@bpmn-io/variable-resolver
A bpmn-js extension to add and manage additional variable extractors in bpmn diagrams.
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';
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
To retrieve the variables from a diagram, use one of the following methods of the variableResolver
service:
const elementRegistry = modeler.get('elementRegistry');
const variableResolver = modeler.get('variableResolver');
const task = elementRegistry.get('Task_1');
const process = elementRegistry.get('Process_1');
await variableResolver.getVariablesForElement(task); // returns variables in the scope of the element
await variableResolver.getProcessVariables(process); // returns all variables for the process, not filtering by scope
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
will attempt to merge variables with the same name and scope into one. Entry structure and types are then mixed.
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
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