listLabels

Retrieve a filtered list of label names

If you provide no filtering criteria, the server returns all labels.

 

How to find labels

The "idFilter" property filters all labels matching the specified "id" values. When using the "idFilter" property, 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. Each filter property is combined with the other filter properties using a logical AND operation. The values within the array of a filter property are combined using an OR 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.

The "includeDescription" and "includeMetadata" are set to true to include these properties in the results.

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

 

Request examples

Minimal

This example returns all labels.

{
  "action":    "listLabels",
  "params":    { },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

This example returns all labels that match the filters. 

{
  "api":        "admin",
  "action":     "listLabels",
  "params":     {
    "partialGroupFilter": "product/color/",
    "nameFilter":         [ "my label 1", "myLabel2" ],

    "deprecatedFilter":   false,
    "enumFilter":         [ 0, "1" ],
    "sequenceFilter":     [ 3.2, "4.4" ],

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

Return all labels

This example returns all labels.

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

Return labels matching specified "id" values

This example returns two labels with "id" values 1 and 2. Notice how you can embed an "id" value in a string.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "idFilter": [ 1, "2" ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Return all labels that match the partial group filter

This example uses a partial group filter to find one or more matching groups. It returns all labels in those groups.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "partialGroupFilter": "product/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Return specific labels in a specific group hierarchy

This example uses a partial group filter to find one or more matching groups. It returns 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":    "listLabels",
  "params":    {
    "partialGroupFilter": "product/",
    "nameFilter":         [ "my label 1", "myLabel2" ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Return all deprecated labels

This example returns all deprecated labels.

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

Return all labels that match specific group names

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

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

Return labels in specific groups that match a partial name filter

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

Return labels that match the partial name filter

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

 

Response examples

Maximal

{
  "result": {
    "labels": []
  },
  "requestId": "2",
  "debugInfo": {
    "request": {
      "authToken": "authToken",
      "api": "admin",
      "action": "listLabels",
      "params": {
        "partialGroupFilter": "product/color/",
        "nameFilter": [
          "my label 1",
          "myLabel2"
        ],
        "deprecatedFilter": false,
        "enumFilter": [
          0,
          "1"
        ],
        "sequenceFilter": [
          3.2,
          "4.4"
        ],
        "includeDescription": true,
        "includeMetadata": true
      },
      "apiVersion": "1.0",
      "requestId": "2",
      "debug": "max"
    }
  },
  "authToken": "authToken",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Request properties ("params")

Property Description Default Type Limits (inclusive)

partialGroupFilter

The "partialGroupFilter" property filters the results of the action. 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. 

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 Default Type

labels

The "labels" property can assign 1 or more labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 

When using tag actions, the optional "labels" property assigns zero or more labels to a tag. You can use it to do lookups and filtering. You can display a list of existing stages, add new ones, rename them, and deprecate them.

 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

Was this article helpful?

Give feedback about this article

Related Articles