@bpmn-io/variable-resolver

An extension for bpmn-js that makes the data model of the diagram available to other components.

[!NOTE] As of version v3 this library exposes both written and consumed variables, you can filter them via options.

Usage

To add the variable resolver to you application, add it to your bpmn-js configuration:

import BpmnModeler from 'bpmn-js/lib/Modeler';
import ZeebeModdle from 'zeebe-bpmn-moddle/resources/zeebe.json';

import {
  ZeebeVariableResolverModule,     // For Camunda 8 diagrams
  // CamundaVariableResolverModule // for Camunda 7 diagrams
} from '@bpmn-io/variable-resolver';

const modeler = new BpmnModeler({
  container: '#canvas',
  additionalModules: [
    ZeebeVariableResolverModule
  ],
  moddleExtensions = {
    zeebe: ZeebeModdle
  }
});

Retrieving variables

Retrieve the variables from a diagram using the variableResolver service:

const variableResolver = modeler.get('variableResolver');
const elementRegistry = modeler.get('elementRegistry');

// retrieve variables relevant to an element
const task = elementRegistry.get('Task_1');

// default: variables relevant to <task> in its visible scopes
await variableResolver.getVariablesForElement(task);

// variables read by <task> only
await variableResolver.getVariablesForElement(task, {
  read: true,
  written: false
});

// all variables written by <task>
await variableResolver.getVariablesForElement(task, { written: true, read: false });

// local variables only (scope === queried element)
await variableResolver.getVariablesForElement(task, {
  local: true,
  external: false
});

// non-local variables only (scope !== queried element)
await variableResolver.getVariablesForElement(task, {
  local: false,
  external: true
});

// retrieve all variables defined in a process
const processElement = elementRegistry.get('Process_1');

// returns all variables for the process (unfiltered), for local processing
await variableResolver.getProcessVariables(processElement);

getVariablesForElement(element, options) supports five filter switches:

Adding a variable extractor

To add your own variables, extend the variableProvider class in your extension. It only needs to implement the getVariables method, which takes an element as an argument and returns an array of variables you want to add to the scope of the element. The function can be asynchronous.

// MyExtension.js
import VariableProvider from '@bpmn-io/variable-resolver/lib/VariableProvider';

class MyCustomProvider extends VariableProvider {
  getVariables(element) {
    const variables = [
      {
        name: 'myVariable',
        type: 'String',
        info: 'This is a global variable'
      }
    ];
      if (is(element, 'bpmn:Process')) {
      return variables;
    }
  }
}

export const MyExtension = {
  __init__: [
    'myCustomProvider',
  ],
  myCustomProvider: [ 'type', MyCustomProvider ],
};

Advanced use-cases

By default, getVariablesForElement and getProcessVariables merge variables with the same name and scope into one - entry structure and types are mixed in the merged representation.

Merged variables additionally expose variants, one per writing element. Each variant is shaped like a variable and describes only the value contributed by its single origin:

/**
 * variable = {
 *   name: 'myVariable',
 *   type: 'Number|String',
 *   origin: [ 'Task_1', 'Task_2' ],
 *   variants: [
 *     { name: 'myVariable', type: 'String', origin: [ 'Task_1' ], ... },
 *     { name: 'myVariable', type: 'Number', origin: [ 'Task_2' ], ... }
 *   ],
 *   ...
 * }
 */

In some cases, you might want access to the raw data, e.g. to run lint rules to detect potential schema mismatches between providers. For this, you can use getRawVariables:

const variableResolver = modeler.get('variableResolver');

const raw = await variableResolver.getRawVariables();

/**
 * raw = {
 *  'Process_1': [
 *    {
 *     name: 'myVariable',
 *     type: 'String',
 *     scope: 'Process_1',
 *     origin: [ 'Task_1' ]
 *    },
 *    {
 *     name: 'myVariable',
 *     type: 'Number',  // Same Variable with different types
 *     scope: 'Process_1',
 *     origin: [ 'Task_2' ]
 *    }
 *  ]
 * }
 */

Development

Prepare the project by installing all dependencies:

npm install

Then, start the example with:

npm start

License

MIT