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

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 "labels" property lists all labels that match the filters set by the "listLabels" request.

    "labels": [
      {
        "id": 6,
        "group": "myLabelGroup",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      },
    ]

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.