"listLabelGroups" (JSON Action)

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 "groupFilter" 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 "groupFilter": [ "myGroup1", "myGroup2", "" ]. Each string is the name of a group and may be up to 64 bytes long. A label's group must match one of the groups in the array to be included in the results. The empty string "" is a valid group name.

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

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

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

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

The "idFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], 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 "idFilter" property is mutually exclusive to the other filter properties. The "listLabels" action returns an error when it is used with other filter properties.

The "includeDescription" property is an optional Boolean that specifies whether to include the "description" property in the response. It defaults to true.

The "includeMetadata" property is an optional Boolean that specifies whether to include the "metadata" property in the response. It defaults to true.

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

The "partialGroupFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is a string, such as "partialGroupFilter": "myGr". The string is the partial or full name of a group and may be up to 64 bytes long. 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.

The "partialNameFilter" 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 "partialNameFilter": "myNa". Each string is the partial or full name and may be up to 64 bytes long. A label's name must partially match this value to be included in the results. The empty string "" and null match all groups.

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

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

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

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

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.

The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false to preserve it. 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. By default, this property is set to 0. You can use this property to assign an application's hardcoded enumerated value to a label.

The "groups" property lists all active label groups.

  "result": {
    "groups": [
      "group1",
      "group2",
      "group3"
    ]
  },

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

The "value" property associates a value with a label. It is an optional JSON value that is associated with a label. It can be any JSON value. It defaults to null. 

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.