Purpose

With the variable labeling endpoint, variable labels can be added, updated and deleted from Optimize.

Functionality

The variable labeling API allows users to add, update and delete batches of variable label data, which Optimize stores in a dedicated index. All variable label data includes a reference to the process definition each variable belongs to, which allows Optimize to display a variable’s label instead of its original name, anywhere the given process definition is being used. Some examples of that would be in reports, configuring filters, report grouping, dashboard filters and Event Based Processes.

Limitations

Please note that this feature is currently not supported in outlier analysis. This means that during Outlier Analysis, the original name of a variable will be displayed.

Authorization

Every request requires Authorization.

Method & HTTP Target Resource

POST /api/public/variables/labels

Request Headers

The following request headers have to be provided with every variable labeling request:

Request Body

The request body should contain a reference to the process definition using its key, as well as an array of variable labels. Each variable label object in the array must specify the name and type of the variable for which a label is being added, as well as the value of the label itself.

Result

This method returns no content.

Response Codes

Possible HTTP Response Status codes:

Example 1

Insert three labels for three variable for a given process definition
Note: If the label exists already in the index, then its value will be overridden.

Request

POST /api/public/variables/labels

Request Body:

    {
      "definitionKey": "bookrequest-1-tenant",  
      "labels" : [
        {
          "variableName": "bookAvailable", 
          "variableType": "Boolean", 
          "variableLabel": "book availability" 
        },
        { 
          "variableName": "person.name", 
          "variableType": "String",
          "variableLabel": "first and last name" 
        },
        { 
          "variableName": "person.hobbies._listSize", 
          "variableType": "Long",
          "variableLabel": "amount of hobbies" 
        }
      ]
    }

Response

Status 204.

Example 2

Delete a label for a variable belonging to a given process definition by inputting an empty String for its value. If there is no label for the given variable in Elasticsearch then no operation is being conducted.

Request

POST /api/public/variables/labels

Request Body:

  {
    "definitionKey": "bookrequest-1-tenant",  
    "labels" : [
      { 
        "variableName": "bookAvailable", 
        "variableType": "Boolean", 
        "variableLabel": ""
      }
    ]
  }

Response

Status 204.

Example 3

Insert and delete labels for two variables belonging to a given process definition. The following example adds a label for the variable with name bookAvailable and deletes a label for the variable with name person.name.

Request

POST /api/public/variables/labels

Request Body:

  {
    "definitionKey": "bookrequest-1-tenant",  
     "labels" : [
       {
         "variableName": "bookAvailable", 
         "variableType": "Boolean", 
         "variableLabel": "book availability" 
       },
       { 
         "variableName": "person.name", 
         "variableType": "String",
         "variableLabel": "" 
       },
     ]
   }

Response

Status 204.

Example 4

Attempting to insert multiple labels for the same variable will result to a 400 response code.

Request

POST /api/public/variables/labels

Request Body:

  {
    "definitionKey": "someProcessDefinitionKey",  
    "labels" : [
      {
        "variableName": "bookAvailable", 
        "variableType": "Boolean", 
        "variableLabel": "book availability" 
      },
      {
        "variableName": "bookAvailable", 
        "variableType": "Boolean", 
        "variableLabel": "is book available" 
      },
    ]
  }

Response

Status 400.