"changeLabels"
Modify sets of labels in bulk with the "changeLabel" action
The "changeLabels" action bulk modifies a set of labels. You use filter properties to select labels and data properties to change values. You can also deprecate or permanently delete labels.
This action cannot be undone.
The response to this action includes a list of labels that were successfully changed by this action.
Each object in the list contains the original value of the label before it was changed or deleted.
An application can use
"alterLabel"to return each label to its original values.
If you do not configure the filter properties properly, the action may change more labels than you want.
Tip
Use the same filter in
"listLabels"to verify the filter returns the labels you expect.FairCom recommends you deprecate a label rather than permanently deleting it.
To deprecate a label, set its
"deprecate"property to true.When you permanently delete a label, records referencing the deleted label's
"id"property will fail to join the label. This will cause referential integrity problems if records reference the label.Tip
Permanently delete a label only when no records reference it.
If a label doesn't exist when the server attempts to delete it, the server considers the action a success because the label does not exist. It does not return an error. The server only returns an error when it fails to permanently delete an existing label.
If the server cannot process all the requested labels as requested, it returns an error, aborts the transaction, and rolls back all labels back to their previous state. Thus, this action runs in an atomic, all-or-nothing transaction.
The "changeLabels" action modifies labels that match its filter criteria. It uses properties to define the filter.
The "idFilter" property filters all labels matching the specified "id" values. The action returns an error if you include other filter properties.
The remaining filter properties work together to filter labels. Each is optional and does not filter labels when omitted or set to null. The filter combines them using a logical AND operation.
"partialGroupFilter"includes labels that match the specified partial group names."nameFilter"includes labels that match the specified label names."deprecatedFilter"includes labels that are deprecated or not."enumFilter"includes labels that have the specified enum values."sequenceFilter"includes labels that have the specified sequence values.
Request examples
Maximal changing label property values
This example changes labels that match the filters. The filter properties select labels, and the new data properties change values.
{
"api": "admin",
"action": "changeLabels",
"params": {
"idFilter": [ 1, "2" ],
"partialGroupFilter": "product/color/",
"nameFilter": [ "my label 1", "myLabel2" ],
"deprecatedFilter": false,
"enumFilter": [ 0, "1" ],
"sequenceFilter": [ 3.2, "4.4" ],
"newGroup": "myLabelGroupName",
"newName": "myLabelName",
"newValue": 99,
"newEnum": 0,
"newSequence": 1.2,
"newDeprecated": false,
"newDescription": "My label description.",
"newMetadata": { }
},
"authToken": "replaceWithAuthTokenFromCreateSession",
"apiVersion": "1.0",
"requestId": "1",
"debug": "max"
}This example deletes all labels that match the filter properties.
Note
When "permanentlyDeleteLabels" is true, this action permanently deletes the labels matching your filter requirements. When deleting labels, the server ignores the following properties: "newGroup", "newName", "newValue", "newEnum", "newSequence", "newDeprecated", "newDescription", and "newMetadata".
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true,
"idFilter": [ 1, "2" ],
"partialGroupFilter": "product/color/",
"nameFilter": [ "my label 1", "myLabel2" ],
"deprecatedFilter": false,
"enumFilter": [ 0, "1" ],
"sequenceFilter": [ 3.2, "4.4" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example permanently deletes all labels. It cannot be undone.
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example permanently deletes two labels with "id" values 1 and 2. You can embed an "id" value in a string.
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true,
"idFilter": [ 1, "2" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}This example uses a partial group filter to find one or more matching groups. It then deletes all labels in those groups.
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true,
"partialGroupFilter": "product/"
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
This example uses a partial group filter to find one or more matching groups. It then deletes all labels in those groups that exactly match the two specified label names. Different groups may have labels with the same name.
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true,
"partialGroupFilter": "product/",
"nameFilter": [ "my label 1", "myLabel2" ]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
This example deletes all deprecated labels.
{
"api": "admin",
"action": "changeLabels",
"params": {
"permanentlyDeleteLabels": true,
"deprecatedFilter": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Maximal
{
"result": {
"deletedLabels": [
{
"id": 1,
"group": "mylabelGroupName",
"name": "mylabelName",
"sequence": "3.14",
"deprecated": false,
"description": "My label description.",
"metadata": { "my": "metadata" }
},
{
"id": 2,
"group": "anotherlabelGroupName",
"name": "anotherlabelName",
"sequence": null,
"deprecated": false,
"description": null,
"metadata": null
}
]
},
"authToken": "authToken",
"debugInfo": {},
"errorCode": 0,
"errorMessage": ""
}Modify sets of labels in bulk with the "changeLabels" action
"params" properties summaryProperty | Description | Default | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|---|
(optional) includes deprecated labels when true |
| Boolean |
| ||||
(optional) includes label matching one of the specified enum values |
| array of smallints | Each array item is an integer from | ||||
(optional) includes labels specified by |
| array of integers | Each array item is an integer from | ||||
(optional) includes labels specified by name |
| array of strings | Each array item is a label string from 1 to 64 bytes | ||||
(optional) updates the |
| Boolean |
| ||||
(optional) updates the |
| string | 1 to 65,500 bytes | ||||
(optional) updates the |
| smallint |
| ||||
(optional) provides a new name for renaming a label. The new name must be unique in its group |
| string | 1 to 64 bytes | ||||
(optional) updates the |
| object | 0 to 65,500 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) updates the |
| double | Any floating point or integer number | ||||
(optional) updates the |
| string | 0 to 65,500 bytes | ||||
(optional) includes labels in the specified group hierarchy |
| string | 1 to 64 bytes | ||||
(optional) specifies whether to permanently delete a label |
| Boolean |
| ||||
(optional) includes labels matching one of the specified sequence values |
| array of doubles | Each array item is a floating point or integer number |
The "deprecatedFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, to include deprecated and non-deprecated labels; in other words, a value of null provides no filtering. Set it to true to include only deprecated labels and false to include only non-deprecated labels.
The "enumFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of integers with values from -32768 to 32767. The "enum" property of a label must match one of the integers in the array to be included in the results.
The "idFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of integers with values from 0 to 2147483647. The "id" property of a label must match one of the integers in the array to be included in the results.
The "nameFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings. Each string is the name of a label and may be up to 64 bytes long. The "name" property of a label must match one of the names in the array to be included in the results.
The "newDeprecated" property is available in the "alterLabel" action. It optionally updates the "deprecated" property of an existing label. It defaults to null.
The "newDescription" property is available in the "alterLabel" action. It optionally updates the "description" property of an existing label. It defaults to "".
The "newEnum" property is available in the "alterLabel" action. It optionally updates the "enum" property of an existing label with a new integer value. It defaults to null.
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 "newMetadata" property is available in the "alterLabel" action. It optionally updates the "metadata" property of an existing label. It defaults to {}.
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 "newSequence" property is available in the "alterLabel" action. It optionally updates the "sequence" property of an existing label. It defaults to null.
The "newValue" property is available in the "alterLabel" action. It optionally updates the "value" property of an existing label. It defaults to null.
The "partialGroupFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings, such as "partialGroupFilter":["mylabelGroupName","anotherGroupName"]. Each string is the partial or full name of a group and may be up to 64 bytes long. The "group" property of a label must partially match the group in the array to be included in the results.
Warning
When deleting properties, ensure each partial and full group name in the array properly filters the labels; otherwise, the "changeLabels" action will delete more labels than you want.
The "permanentlyDeleteLabels" property is available in the "changeLabels" action. It optionally specifies for the server to permanently delete the labels specified by the label filter properties. It defaults to null.
The "sequenceFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], which provides no filtering. It is an array of doubles. The "sequence" property of a label must match one of the doubles in the array to be included in the results.