changeLabels

Modify sets of labels in bulk

You use "filter" properties to select labels and "new" properties to change values. If you omit a "new" property, such as "newGroup", the action does not change that property. 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.

 

How to modify many labels at once

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.

  • "groupFilter" includes labels that match one group in the specified list.
  • "partialGroupFilter" includes labels that match the specified partial group names.
  • "nameFilter" includes labels that match the specified label names.
  • "partialNameFilter" includes labels that match a partial label name.
  • "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.

Note The "groupFilter" and "partialGroupFilter" properties are mutually exclusive, and the "nameFilter" and "partialNameFilter" properties are mutually exclusive.

 

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": {
    "partialGroupFilter": "product/color/",
    "nameFilter": [
      "my label 1",
      "myLabel2",
      "myLabel3"
    ],
    "deprecatedFilter": false,
    "enumFilter": [ 0,"1" ],
    "sequenceFilter": [ 1, 3.2, "4.4" ],

    "newGroup": "product/color/",
    "newValue": 99,
    "newEnum": 1,
    "newSequence": 4.4,
    "newDeprecated": false,
    "newDescription": "My new label description.",
    "newMetadata": {"myKey": "myValue"},

    "includeDescription": true,
    "includeMetadata": true
  },
  "authToken": "",
  "apiVersion": "1.0",
  "requestId": "00000027",
  "debug": "none"
}
 
 

Maximal deleting labels

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"
}
 
 

Permanently delete labels matching specified "id" values

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"
}
 
 

Permanently delete all labels that match the partial group filter

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"
}
 
 

Permanently delete specific labels in a specific group hierarchy

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"
}
 
 

Permanently delete all deprecated labels

This example deletes all deprecated labels.

{
  "api":       "admin",
  "action":    "changeLabels",
  "params":    {
    "permanentlyDeleteLabels": true,
    "deprecatedFilter":        true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Permanently delete all labels that match specific group names

This example uses a group filter to delete all labels with the matching groups.

{
  "api":       "admin",
  "action":    "changeLabels",
  "params":    {
    "permanentlyDeleteLabels": true,
    "groupFilter": [ "myGroup1", "myGroup2", "" ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Permanently delete labels in specific groups that match a partial name filter

This example uses a group filter to delete all labels with the matching groups.

{
  "api":       "admin",
  "action":    "changeLabels",
  "params":    {
    "permanentlyDeleteLabels": true,
    "groupFilter": [ "myGroup1", "myGroup2" ],
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Permanently delete labels that match the partial name filter

This example uses a partial name filter to delete labels with matching names. The labels may be part of any group.

{
  "api":       "admin",
  "action":    "changeLabels",
  "params":    {
    "permanentlyDeleteLabels": true,
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Response examples

Maximal changed labels

{
  "result": {
    "changedLabels": [
      {
        "id": 1,
        "group": "mylabelGroupName",
        "name": "mylabelName",
        "value": 99,
        "enum": 0,
        "sequence": "3.14",
        "deprecated": false,
        "description": "My label description.",
        "metadata": { "my": "metadata" }
      },
      {
        "id": 2,
        "group": "anotherlabelGroupName",
        "name": "anotherlabelName",
        "value": 99,
        "enum": 0,
        "sequence": null,
        "deprecated": false,
        "description": null,
        "metadata": null
      }
    ]
  },
  "authToken": "authToken",
  "debugInfo": {},
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

idFilter

The "idFilter" property filters the results of the action by the value of the "id" property. It defaults to [], which provides no filtering. The "id" property of a label must match one of the integers in the array to be included in the results.

The "idFilter" property is mutually exclusive to the other filter properties. 

 

 Optional with default of [] array of integers Each array item is an integer from 0 to 2147483647

partialGroupFilter

The "partialGroupFilter" property filters the results of the actions. It defaults to null, which provides no filtering. The string is the partial or full name of a group. A label's group must match the partial or complete value of this property to be included in the results. The empty string "" and null match all groups.

Note The "groupFilter" and "partialGroupFilter" properties are mutually exclusive.

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.

 Optional with default of "" string 1 to 64 bytes

nameFilter

The "nameFilter" property filters the results of the action by the value of the "name" property. It defaults to null, which provides no filtering. It is an array of strings, such as "nameFilter": [ "myName1", "myName2" ]. Each string is the name of a label and may be up to 64 bytes long. A label's name must match one of the names in the array to be included in the results.

Note The "nameFilter" and "partialNameFilter" properties are mutually exclusive.

 

 Optional with default of [] array of strings Each array item is a label string from 1 to 64 bytes

deprecatedFilter

The "deprecatedFilter" property filters the results of the action by the value in the "deprecated" property. When set to null, the response includes deprecated and non-deprecated labels. Set it to true to include only deprecated labels and false to include only non-deprecated labels.

 

 Optional with default of false Boolean

true

false

null

enumFilter

The "enumFilter" property filters the results of the action by the value of the "enum" property. When null, this property provides no filtering. The "enum" property of a label must match one of the integers in the array to be included in the results.

 

 Optional with default of [] array of smallints Each array item is an integer from -32768 to 32767

sequenceFilter

The "sequenceFilter" property filters the results of the action. It defaults to [], which provides no filtering. The "sequence" property of a label must match one of the doubles in the array to be included in the results.

 Optional with default of [] array of doubles Each array item is a floating-point or integer number. 

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

newValue

The "newValue" property updates the "value" property of an existing label. It defaults to null, which means the action does not change the label's value. 

 Optional with default of null JSON 0 to 65,500 bytes

newEnum

The "newEnum" property updates the "enum" property of an existing label with a new integer value. It defaults to null, which means the action does not change the label's enum value.

 Optional with default of null smallint -32768 to 32767

newSequence

The "newSequence" property updates the "sequence" property of an existing label. It defaults to null, which means the action does not change the label's sequence number. 

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

newDeprecated

The "newDeprecated" property updates the "deprecated" property of an existing label. It defaults to null, which means the action does not change the label's deprecated status.

 Optional with default of null Boolean

true

false

null

newDescription

The "newDescription" property updates the "description" property of an existing label. It defaults to null, which means the action does not change the label's description.

 Optional with default of "" string 1 to 65,500 bytes

newMetadata

The "newMetadata" property updates the "metadata" property of an existing label. It defaults to null, which means the action does not change the label's metadata. 

 Optional with default of {} JSON 0 to 65,500 bytes

includeDescription

The "includeDescription" property specifies whether to include the "description" property in the response. 

Optional with default of true

Boolean

 

true

false

null

 

includeMetadata

The "includeMetadata" property specifies whether to include the "metadata" property in the response.

Optional with default of true

Boolean

 

true

false

null

 

Response properties ("result")

Property Description Type Limits (inclusive)

changedLabels

The "changedLabels" property lists an object for each label that has been updated with new values. Each object contains the "id", "group", "name", "value", "enum", "sequence", "deprecated", "description", and "metadata" properties and their new values for the label that was updated.

    "changedLabels": [
      {
        "id": 4,
        "group": "myLabelGroupName",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      }
    ]
 array of objects An object for each changed label.

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 "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.

 

In Key-Value actions, the "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

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.

 

 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. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

Was this article helpful?

Give feedback about this article

Related Articles