search string side menu

Modules > Custom modules > Business process activities / Binding variables for activities in business processes

Binding variables for activities in business processes

After creating an activity in a custom module, it becomes available in the business process designer.

For the activity to work correctly, you need to pass input data to it and save the result. For this purpose, use activity variables:

  • Input variables. They contain the data from the business process context required for the activity to work. The values that are written into them are determined during the process before the activity is executed.
  • Output variables. They contain the result of the activity execution. Their values can be passed:
    • To the business process context, e.g. to show them in a user task.
    • To app fields from the process context to save the information on the item page.

You can configure data transfer with the help of binding — mapping activity variables to a process or app context. Binding is performed when modeling the process in the activity settings.

To configure data transfer:

  1. Add input and output variables when creating or editing an activity in the module.
  2. Create a custom binding form if when mapping additional information needs to be displayed for the user.
  3. Add an activity to the business process diagram and map activity variables to process or app properties.

Add variables to configure an activity

You can create activity variables in two ways:

Create variables for binding manually

To add a constant set of variables:

  1. Go to the module settings to the Business Process Activities tab. Add a new activity or open an already created one by clicking its name.
  2. In the activity settings on the Context tab, create variables by clicking + Add in the upper right corner. Read more about variable types in the System data types article.
  3. In the list of variables, select the checkboxes to indicate which variables are input and output variables, and also specify if they are required.
  4. Save and publish the activity.

You can then add the activity to the business process diagram and perform variable mapping.

Configure adding variables for binding using a script

For a Script activity, you can create a set of variables automatically while configuring the activity in the process. For example, when integrating with an external service, you can get an up-to-date list of fields from it and create variables for binding based on it.

Please note, to request data from an external service, it must provide a method to retrieve a description of its API. For example, OpenAPI, WADL, or SOAP can be used.

The basic steps for configuring dynamic variable addition:

  1. Create a custom binding form for the activity.
  2. In the settings of the binding form, add a script that generates activity variables using data from an external service. They are written to the Arbitrary type property.
  3. Place the Dynamic Binding widget on the binding form to display the created variables.
  4. Customize the start of the variable creation script, for example, bind it to a button.
  5. Provide an error message when a request to an external service fails.
  6. Write an activity script. For example, it can request data from an external system and transfer it to output variables.

Let's see how to configure binding.

For example, you need to create an activity to retrieve data about companies from an external service. The activity variables for mapping should be automatically added on the basis of field descriptions received from the service. To do this:

  1. On the Business Process Activities tab of the custom module, go to the settings of the Script activity or add a new one.
  2. Open the Context tab and click Create Form.
  3. In the binding form settings that open, click the Context tab. Add variables of the following types:
  • Arbitrary type to store the created activity variables.
  • Yes/No switch to indicate the presence of an error.
  • String to record the error text.
  1. On the Template tab, place the Dynamic Binding widget on the form. In its settings, in the Dynamic fields* option, select the created Arbitrary type property and click Save.
  2. Go to the Scripts tab and write a client or server script that creates activity variables based on data from an external service. They should be stored in the Arbitrary type property. Also customize the recording of error information when the script is executed.

For more details about description of variables for binding in the script, see BRIX TS SDK.

Example of a script for creating variables

// Intermediate structure for transferring a list of fields and their types from an external service
interface FieldDescription {
  code?: string;
  type?: string;
}
 
// Structure for comparing data types between an external service and BRIX
const TypeMapping = new Map<string, DynamicFieldType>([
  ["STRING", DynamicFieldType.String],
  ["FLOAT", DynamicFieldType.Float],
  ["BOOLEAN", DynamicFieldType.Boolean],
  ["DATETIME", DynamicFieldType.Datetime]
]);
 
// Function for retrieving data from an external service
async function getFields(): Promise<FieldDescription[] | undefined> {
  // Obtaining data on the required fields
  ...
}
 
// Function for creating activity variables
async function FillBindings(): Promise<void> {
  ViewContext.data.is_error = false;
  ViewContext.data.error_text = '';
  // Call a function to retrieve data from an external service
  const fields = await getFields();
  if (fields) {
      const bindings = {} as any;
      // Add a variable that will be used to obtain contractor data
      bindings["__name"] = { name: '__name', type: DynamicFieldType.String, input: true } as DynamicBindingField;
      for (var item of fields!) {
          if (TypeMapping.has(item.type!)) {
              // Checking for output variables that are named the same as input variables
              // They are marked as input and output
              if (bindings[item.code!]) {
                  if ((bindings[item.code!] as DynamicBindingField).type == TypeMapping.get(item.type!)) {
                      (bindings[item.code!] as DynamicBindingField).output = true;
                  }
              } else {
                  bindings[item.code!] = { name: item.code!, type: TypeMapping.get(item.type!), output: true } as DynamicBindingField;
              }
          }
      }
      ViewContext.data.bindings = bindings;
  } else {
      ViewContext.data.is_error = true;
      ViewContext.data.error_text = " An error occurred while receiving data from an external service";
  }
}
 
  1. Bind the script launching to the button. To do this, place the Button widget on the form, select the Script activity in its settings and specify the function where the variables are added.
  2. To make the user see a notification in case of a script execution error, add the Information Box widget to the form. On the Main tab, for the Text field, set a link with a String type variable, where the error text is written.
  3. Customize the visibility of the information box so that it is displayed only in case of an error during script execution. To do this, go to the System tab and select the Show conditionally option. Click <Not defined> and link the widget display to a Yes/No switch variable where the error occurrence is recorded.
  4. Save and publish the binding form.
  5. Variables that are created dynamically can now be accessed in the activity script. This allows you to use the information from the input variables in the activity and assign values to the output variables.
     
    To do this, go back to the activity settings and select the Script tab. In our example, the input data is used to generate a query to retrieve company information.

Activity script example

 
// Function for obtaining data about companies from an external service
async function getContractorData(name: string): Promise<Map<string, any> | undefined>
{
  // Obtaining data on contractors from an external service
  // and their recording in an array for transfer to the output parameters of the activity
  // ...
}
 
// Function for obtaining data from input activity variables,
// their use for requesting an external service
// and storing data in output variables
async function action(): Promise<void>
{
   // Recording the name of the contractor from the activity input variable to the `name` variable
   const name = Context.data['bindings.__name'];
   // Referring to an external service to obtain data about a contractor
   const contractor:Map<string, any> | undefined = await getContractorData(name);
   // If data is received, it is recorded in the output variables of the activity.
   if (contractor)
   {
      for (var item of contractor.keys())
      {
         Context.data['bindings.' + item] = contractor.get(item);
      }
   }
}
  1. Save and publish the activity.

Now the activity can be added to the business process diagram. In its settings on the Activity Settings tab, the user will click the button to make a request to the external system. After that, they will see the automatically generated variables and can map them.

Configure a custom binding form

You can create a custom variable binding form. It will be displayed to the user when modeling the business process in the activity settings. To do this:

  1. In the activity settings on the Context tab, click Create Form.
  2. In the interface designer that opens, place fields and widgets on the form, for example, add an information box with tooltips.
  3. Save and publish the form.

After that, in the activity settings, instead of the Inputs and Outputs tab, the Activity Settings tab with the created form will appear.

Map variables in a business process

To use an activity from an enabled module in a business process:

  1. On the right panel, open the Integrations tab and add the activity to the flow chart. Its settings will open.
  2. On the Main tab, in the Bind output attributes to field, specify where to write the result of the activity execution:
  • Into the context variables of the business process.
  • To the fields of the app added to the business process context.
     
    For more information about customizing the activity in the business process designer, see the Business Process Activity article.
  1. Go to the Inputs and Outputs tab. If a custom binding form is configured, the tab is called Activity Settings.

The binding form will open. Select:

  • For input activity variables — properties of the process from which you want to get data for the activity execution.
  • For output activity variables — properties of the process or app to which the result of the activity execution will be written.

Please note that only variables of the same type can be mapped.

To complete the configuration, click Save.

delegated-activities.html extention-processes.html