Skip to main content

Variable Extractors

Introduction​

The Variable Extractor editor allows you to create and manage variable extractor definitions. Variable extractors define how variable values are extracted and mapped into custom fields in the search index (Elasticsearch or OpenSearch). This enables advanced search, filtering, and sorting capabilities on variable data that would otherwise not be directly queryable.

A typical use case is extracting values from complex JSON variables into dedicated indexed fields, or mapping variables to fields with custom analyzers for language-specific full-text search.

Creating a Variable Extractor​

To create a new variable extractor model, navigate to the Other tab in Flowable Design and select the Variable extractor filter. Click the Create button to open the creation dialog.

Provide:

  • The display name of the variable extractor.
  • The variable extractor's unique key.
  • An optional description of the variable extractor.

After clicking Create new model, you are redirected to the variable extractor editor where you can configure the extraction rules.

Variable Extractor Editor​

The Variable Extractor editor allows you to define the mapping between variables and custom index fields using a JSON-based configuration. A variable extractor definition consists of the following main sections:

Variable Properties​

The variableProperties section defines the structure of the new fields that are added to the search index. These fields are placed under the variables property in the index mapping. Each field has a type and optionally an analyzer or other Elasticsearch/OpenSearch field configuration.

Variable Extractors​

The variableExtractors section defines how variable values are mapped into the custom fields. Each extractor requires:

PropertyDescription
FilterDefines when the extractor is applied. The filter is matched against variable create, update, or delete events. Filter fields include name (the variable name) and scopeDefinitionKey (the definition key of the process/case). An explicit null value means only instances without that field value match.
ToThe name of the custom field to map the variable value into. This must correspond to a field defined in variableProperties.
TypeThe data type used for mapping the variable value. Supported types are: boolean, date, double, integer, long, short, string, uuid, and null.

Example​

The following example defines a variable extractor that maps the variable customVariable from the oneTaskProcess definition into two custom fields: one with a whitespace analyzer and one as a keyword.

{
  "version": 1,
  "extends": "tasks",
  "key": "example-variable-properties-extractor",
  "variableProperties": {
    "customAnalyzedField": {
      "type": "text",
      "analyzer": "whitespace"
    },
    "customAnalyzedFieldKeyWord": {
      "type": "keyword"
    }
  },
  "variableExtractors": [
    {
      "filter": {
        "name": "customVariable",
        "scopeDefinitionKey": "oneTaskProcess"
      },
      "to": "customAnalyzedField",
      "type": "string"
    },
    {
      "filter": {
        "name": "customVariable",
        "scopeDefinitionKey": "oneTaskProcess"
      },
      "to": "customAnalyzedFieldKeyWord",
      "type": "string"
    }
  ]
}

With this configuration, the custom fields become available in the search index and can be used in queries.

Deployment​

Variable extractor definitions are deployed as part of an app, just like any other model type. They can also be auto-deployed from the classpath using files with the .extractor suffix. See Variable Extractor Auto Deployment for details.

Further Reading​