linkLabelsToRecords

The "linkLabelsToRecords" action links one or more labels to one or more records in a table. It adds to the links already assigned to the record, if any. It does not return an error if the specified labels are already assigned to the specified records. 

The operation is atomic. If it returns an error, the action does not apply the requested changes. If some or all of the specified labels are already linked to the specified records, the action returns success with a warning: The "Label LLL is already linked to database DDD, owner OOO, and table TTT with primary key PPP".

 

Request examples

Minimal

This example links the label "myLabel1" to records 1 and 2 in the table "my_table" owned by the default account and database .

{
  "action":    "linkLabelsToRecords",
  "params":    
  {
    "labels":  [ { "name": "myLabel1" } ],
    "tableName": "my_table",
    "ids": [1,2]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

This example links the labels "myLabel1" and "myLabel2" in group "myGroup" to records 1 and 2 in the table "my_table" owned by the "db" user in the "faircom" database .

{
  "api":       "db",
  "action":    "linkLabelsToRecords",
  "params":    
  {
    "labels": 
    [
       {
         "group": "myGroup",
         "name": "myLabel1"
       },
       {
         "group": "myGroup",
         "name": "myLabel2"
       }

    ],
    
    "databaseName": "faircom",
    "ownerName": "db",
    "tableName": "my_table",
    "ids": [1,2],

    "verifyLinks": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

labels

The "labels" property specifies 1 or more label objects to be assigned to records. It can assign many labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property is required and must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 

When using tag actions, the optional "labels" property assigns zero or more labels to a tag. It defaults to []. Each label is a string from 1 to 64 bytes. You can use it to do lookups and filtering. You can display a list of existing stages, add new ones, rename them, and deprecate them.

Required - No default value

 

Defaults to

[] when using tag actions

 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

labels

.group

The "group" property groups labels into a lookup list or tag set. It is a namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. A group assigned to the empty string "" is the default group.

The group name may contain up to 64 bytes of UTF-8 encoded characters.

When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. 

 Optional with default of "" string 1 to 64 bytes

labels

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. 

The "id" property also uniquely identifies each label, so you can rename a label's group and name without breaking "id" references to the label.

 

 Required - No default value string 1 to 64 bytes

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. 

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

tableName

The "tableName" property contains the unique, user-defined name of a table.

See table name in System specifications for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

ids

An “id” is a unique identifier automatically generated by the server. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create an object such as a label or thing and stores it in the table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property. You can use the "id" or "thingName" properties to identify and look up a thing.

 

 Automatically generated by the server array of integers Each array item is an integer from 0 to 2147483647

The "verifyLinks" property causes the action to verify that the specified labels, records, and tables exist when set to true. If your application has already validated that the labels, records, and tables exist, it can set "verifyLinks" to false, which provides a performance boost because the action does not need to look up this information.

 Optional with default of true Boolean

true

false

Was this article helpful?

Give feedback about this article

Related Articles