"alterLabel"
Use the "alterLabel" action to modify an existing label
The "alterLabel" action modifies an existing label. Include properties you want to modify. Properties that you omit remain unchanged.
Request examples
Minimal
The following example is allowed but does not change any values.
{
"action": "alterLabel",
"params": {
"name": "mylabelName"
}
}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"
}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"
}{
"result": {
"id": 1,
"group": "my group name",
"name": "my 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": "authToken",
"debugInfo": {},
"errorCode": 0,
"errorMessage": ""
}Use the "alterLabel" action to modify an existing label
"params" properties summaryProperty | Description | Default | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|---|
(optional) specifies when a label is deprecated or not |
| Boolean |
| ||||
(optional) describes a label |
| string | 1 to 65,500 bytes | ||||
(optional) assigns an integer number to a label |
| smallint |
| ||||
(optional) assigns a group to a label to create named lookup lists and tag sets |
| string | 1 to 64 bytes | ||||
uniquely identifies each label | Automatically generated by the server | integer |
| ||||
(optional) assigns metadata to a label |
| string | 0 to 65,500 bytes | ||||
names a label. The name must be unique in its group | Required - No default value | string | 1 to 64 bytes | ||||
(optional) provides a new name for renaming a group |
| string | 1 to 64 bytes | ||||
(optional) provides a new name for renaming a label. The new name must be unique in its group |
| string | 1 to 64 bytes | ||||
(optional) specifies the numerical order of labels within a group |
| double | Any floating point or integer number. |
The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false when you do not. It defaults to false. Deprecating a label is similar to marking a label as deleted.
The "description" property optionally provides additional information about a label. You can use it as internal or external documentation about the meaning, purpose, and usage of a label.
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: \".
The "enum" property optionally 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.
The "group" property optionally groups labels into a lookup list or tag set. It is an optional 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 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. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.
The "id" property is the unique identifier of a label. 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.
The "metadata" field optionally allows a customer to add a JSON value to the label. It is typically a JSON object, but may be any JSON value. It defaults to null. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.
The "name" property is the name of a label. It is a required UTF-8 string that is up to 64 bytes long.
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.
The "newGroup" property is available in the "alterLabel" action. It optionally assigns a new group name to an existing label. It defaults to null.
The "newName" property is available in the "alterLabel" action. It optionally assigns a new label name to an existing label. It defaults to null.
The "sequence" property optionally 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.