alterLabel

Modify an existing label

Only include properties you want to modify. Properties that you omit remain unchanged.

 

Request examples

Minimal

{
  "action": "alterLabel",
  "params": {
    "name": "mylabelName"
  } 
}
 
 

Typical example changing all properties except "group" and "name"

{
  "api": "admin",
  "action": "alterLabel",
  "params": {
    "group": "product/color/",
    "name": "myLabel2",
    "value": 99,
    "enum": 1,
    "sequence": 3.2,
    "deprecated": false,
    "description": "My label description.",
    "metadata": {"myKey": "myValue"}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "2",
  "debug": "none"
}
 
 

Maximal using "group" and "name"

The "group" and "name" properties identify the label. The "newGroup" property renames the group, and the "newName" property renames the label. 

This example changes all values of a label, including "enum", "sequence", "deprecated", "description", and "metadata". It deprecates a label by setting "deprecated" to true.

{
  "api":        "admin",
  "action":     "alterLabel",
  "params":     {
    "group":       "myLabelGroupName",
    "name":        "mySecondLabelName",

    "newGroup":    "new group name",
    "newName":     "new label name must be unique in the label's group",

    "enum":        1,
    "sequence":    "3.14",
    "deprecated":  true,
    "description": "new label description",
    "metadata":    { "new": "metadata" }
  },
  "authToken":  "replaceWithAuthTokenFromCreateSession",
  "apiVersion": "1.0",
  "requestId":  "3",
  "debug":      "max"
}
 
 

Using "id"

The "id" property identifies the label. The "newGroup" property renames the group, and the "newName" property renames the label. It undeprecates a label by setting "deprecated" to false.

{
  "api":       "admin",
  "action":    "alterLabel",
  "params":    {
    "id":         1,
    "newGroup":   "my group name",
    "newName":    "my label name must be unique in the label's group",
    "deprecated": false
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response example 

Minimal

{
  "result": {
    "id": 1,
    "group": "my group name",
    "name": "my label name must be unique in the label's group",
    "value": {
      "new": "metadata"
    },
    "enum": 1,
    "sequence": "3.14",
    "deprecated": true,
    "description": "new label description",
    "metadata": { "new": "metadata" }
  },
  "authToken": "authToken",
  "debugInfo": {},
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

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

newGroup

The "newGroup" property assigns a new group name to an existing label. It defaults to null, which means the action does not change the label's group. 

 Optional with default of null string 1 to 64 bytes

newName

 The "newName" property assigns a new label name to an existing label or table. It defaults to null, which means the action does not change the label's or table's name.  Optional with default of null string 1 to 64 bytes

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. The "createLabel" and "alterLabel" actions return 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.

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 JSON 0 to 65,500 bytes

Was this article helpful?

Give feedback about this article

Related Articles