createLabel

Create a new label

The "createLabel" action creates a new label with the required property "name" and optional properties "group", "sequence", "description", and "metadata". The server automatically generates an "id" value and uses it internally for referencing the label. If you use labels in your application, you should also use the "id" property to reference the label because it allows you to rename the label without breaking external references to it.

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.

 

Request examples

Minimal

This example creates a label in the empty "group". It is best to create a label in a specific group.

{
  "action":    "createLabel",
  "params":    {
    "name": "myLabelName"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Typical

{
  "api":       "admin",
  "action":    "createLabel",
  "params":    {
    "group": "product/color/",
    "name": "myLabel2",
    "value": 1,
    "enum": 0,
    "sequence": 1,
    "deprecated": false,
    "description": "unknown",
    "metadata": {}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "debug": "none"
}
 
 

Maximal

{
  "api":        "admin",
  "action":     "createLabel",
  "params":     {
    "group":       "myLabelGroupName",
    "name":        "mySecondLabelName",
    "value":       99,
    "enum":        0,
    "sequence":    1.2,
    "deprecated":  false,
    "description": "My label description.",
    "metadata":    { }
  },
  "authToken":  "replaceWithAuthTokenFromCreateSession",
  "apiVersion": "1.0",
  "requestId":  "3",
  "debug":      "max"
}
 
 

 

Response example

Minimal

{
  "result": {
    "id": 1,
    "group": "mylabelGroupName",
    "name": "mylabelName",
    "value": 99,
    "enum": 0,
    "sequence": 1.2,
    "deprecated": false,
    "description": "My label description.",
    "metadata": {}
  },
  "authToken": "authToken",
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo": {}
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

deprecated

 The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false to preserve it. Deprecating a label is similar to marking a label as deleted. Optional with default of false Boolean

true

false

null

description

 The "description" property describes objects such as code packages, labels, or things. The server indexes this field with a full-text index so that you can search for any word or phrase. You cannot use this property for filtering in the Thing API.

Optional with default of "".

"unknown" for Thing API 

 string

0 to 65,500 bytes

1 to 512 bytes for the Thing API 

enum

The "enum" property assigns an integer from -32768 to 32767 to a label. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 Optional with default of 0 smallint -32768 to 32767

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. 

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.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

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

id

The "id" property 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 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

name

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

The "group" and "name" properties combined uniquely identify each label. An error is returned if the "group" and "name" properties do not create a unique label name.

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

value

 The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records. Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

sequence

The "sequence" property assigns an order to the labels in a group. You may embed the number in a JSON string. It defines the order of labels in a group. It is a double to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 Optional with default of 0 double Any floating point or integer number.

 

Response properties ("result")

Property Description Default Type

id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label 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.

 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API 

group

The "group" property groups labels into a lookup list or tag set. It is an optional namespace for a set of labels that identifies their purpose. 

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.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

When you assign a group name to a label, the server automatically checks whether the group name exists in the list of groups returned by the "listLabelGroups" action. If the group name does not exist, the server adds it 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. 

 

 string 1 to 64 bytes

name

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

The "group" and "name" properties combined uniquely identify each label. Returns an error if the "group" and "name" properties do not create a unique label name.

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.

 

 string 1 to 64 bytes

value

 The "value" property associates a value with a label. It can be any JSON value that is associated with a label. JSON 0 to 65,500 bytes

enum

The "enum" property optionally assigns an integer from -32768 to 32767 to a label. By default, this property is set to 0. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 smallint -32768 to 32767

sequence

The "sequence" property assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 float Any floating point or integer number.

deprecated

The "deprecated" property deprecates a label. Set it to true to deprecate a label and false to preserve it. Deprecating a label is similar to marking a label as deleted.

 Boolean

true

false

null

description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

 string 1 to 65,500 bytes

metadata

The "metadata" field allows a customer to add a JSON value to an object, such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc.

 JSON 0 to 65,500 bytes

Was this article helpful?

Give feedback about this article

Related Articles