This type of activity allows passing data from BRIX to an external service, processing it, and receiving a response.
Delegated activities are passed to an external microservice via standardized Web API (HTTP REST). A single service can implement multiple activities that are separated by code.
This activity does not use scripts, so it is configured only on the Settings and Context tabs.
Settings tab
Fill in the fields on the Settings tab:
- Name. The name of the activity in the module settings and in the business process designer.
- Default name. The name of the item displayed when it is added to the process diagram.
- Activity color. The color of the activity on the process scheme.
- Description. The description of the functionality of the activity and its features.
- Outdated. This option allows you to hide the item from the business process designer so that users cannot add it to new process schemes. Outdated activities will continue to work without changes in already created processes. For example, you can enable the option for an activity after a module update.
- URL for delegating. The address of an external service specifying the code of a particular activity in the following form:
schema://domain:port/base/path/action-code. Click the {+} icon in the field to use the variables created in the custom module on the Settings tab in the address. Use the f(x) icon to add DateTime() function to the address. - Number of retries in case of error. The number of attempts to execute the activity.
- Retry delay (sec)*. Frequency of attempts to execute the activity when an error occurs.
Context tab
Add variables that will be used in the item settings on the business process diagram. The context can be requested from an external executor service or created manually by clicking + Add for each variable. Read more about variable types in System data types.
Mark which variables are input and output variables. This will allow you to map the context of the activity to the process in which it is used. For more information on variable bindings, see Binding and other aspects of business process activities.
After entering data on the tabs, click Save and Publish in the top panel of the activity settings window. With the module enabled, the activity will be available in the business process designer, on the Integrations tab. You can add the graphical element on the process flow chart and configure the settings for its execution.
How the activity works
The delegated activity is performed according to the following algorithm:
- The URL for delegating, specified in the activity settings, is read by the processor service and its
/requestsmethod is called. In the body of the request, the Executors and Context are transferred as the values of the input context variables from the activity settings. - When a request for
/requestsis sent to the executor service, one of the following actions occurs:
- The activity is executed and the result is displayed;
- Additional data is requested from the processor service;
- If all data is available but simultaneous execution of the activity is impossible, the information is stored, for example, in a database. The response that the activity is accepted for execution is sent to the processor service and the URL of the method that sends the recovery point identifier is transferred;
- If an error occurs, a notification about it is returned.
- Depending on the response received from the executor service, one of the following activities is performed on the processor service side:
- When the activity is executed, the result is written to the output variables configured in the context of the activity. Execution of the business process continues;
- If it is necessary to request additional data, a custom task is created. After its execution, the
/requestsmethod is called. - If the activity was accepted for execution, a restore point is created. Its identifier is passed to the executor service using the received URL;
- In case of an error, the error is analyzed. A new request is sent, according to the settings specified in the activity. You can also use a gateway to configure an additional branch in the process, which will be used in case of an error.
Request additional data in a task
To perform an activity, the executor service may require additional data from the user, for example, an electronic signature. Then the executor service returns the code 201 in response to the /requests request. The initiator of the process receives a task, which specifies: executors, context (data), description of the form fields for the task, and a list of allowed transitions.
The user specifies the required information. Then the processor service requests the /requests method again and passes the form data, the selected transition, and the task executor identification to the executor service. After that, the executor service performs the activity again
Await activity execution
If a restore point is created, the process stops until the delegated activity is executed by the executor service. If a timer intermediate event is configured in the process scheme after the activity, the expecting will be interrupted after the set time has elapsed.
After the executor service has received the recovery point identifier, it is saved, for example, in the database. Then the activity is executed.
At the end of the activity, the processor service receives information about the need to continue the business process from the recovery point. The Web API method is used to transfer the result to the delegated activity:
POST /pub/v1/bpm/restore-point/{id}/restore
The updated activity context is passed in the request body.
The received data is written by the processor service to the output variables configured in the item, and the process continues.
Interrupt the execution of the activity
Interrupting or canceling a delegated activity occurs:
- When a business process is interrupted.
- At escalation by timer.
The initiator of activity interruption is the processor service. It deletes the created restore point and informs the executor service about the need to cancel the activity with a request:
Executor service API
A detailed description of the executor service interface can be found in the OpenAPI-scheme:
openapi: 3.0.0 info: title: perfomer-service description: Executor service for a delegated activity version: 1.0.0 servers: - url: schema://domain:port/base/path paths: /{action-code}/context: get: summary: Get context description description: The method is intended for loading the context description from the executor service into the delegated activity item at the stage of its creation operationId: getContext tags: - Context parameters: - name: action-code in: path description: activity code required: true schema: type: string responses: '200': description: Description of the activity context as an array of properties content: application/json: example: [ { "code": "firstName", "type": "STRING", "searchable": false, "indexed": false, "deleted": false, "array": false, "required": false, "single": true, "defaultValue": null, "calcByFormula": false, "formula": "", "data": null, "view": { "name": "Name", "tooltip": "Name without abbreviations", "data": { "input": true } } }, { "code": "lastName", "type": "STRING", "searchable": false, "indexed": false, "deleted": false, "array": false, "required": false, "single": true, "defaultValue": null, "calcByFormula": false, "formula": "", "data": null, "view": { "name": "Surname", "tooltip": "Surname without abbreviation", "data": { "input": true } } }, { "code": "fullName", "type": "STRING", "searchable": false, "indexed": false, "deleted": false, "array": false, "required": false, "single": true, "defaultValue": null, "calcByFormula": false, "formula": "", "data": null, "view": { "name": "Full name", "tooltip": "Full name without abbreviations", "data": { "output": true } } } ] /{action-code}/validate: post: summary: Check bindings operationId: validateBingings tags: - Validation parameters: - name: action-code in: path description: Activity code required: true schema: type: string requestBody: description: "" content: application/json: schema: $ref: '#/components/schemas/Bindings' responses: '200': description: Successful validation content: application/json: schema: $ref: '#/components/schemas/ValidationResult' '400': description: Validation error /{action-code}/requests: post: summary: Execute activities operationId: runActionRequest tags: - Action parameters: - name: action-code in: path description: Activity code required: true schema: type: string - name: x-company-alias in: header required: true schema: type: string - name: x-user-id in: header description: Current user in case of custom task execution required: false schema: type: string - name: x-correlation-id in: header description: CorrelationID in case of a custom task required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAction' responses: '200': description: Task is completed content: application/json: schema: $ref: '#/components/schemas/Result' '201': description: The task is accepted for processing. It is necessary to assign the task to the user and repeat the request after its execution content: application/json: schema: $ref: '#/components/schemas/CreateActionCreateTaskResponse' '202': description: Task is accepted for processing content: application/json: schema: $ref: '#/components/schemas/CreateActionResponse' '400': description: Error in request format content: application/json: schema: $ref: '#/components/schemas/BadRequest' '422': description: Error in request data content: application/json: schema: $ref: '#/components/schemas/BadRequest' '429': description: It is necessary to repeat the request later '500': description: Internal error of the executing service, the activity cannot be continued /{action-code}/requests/{id}: delete: tags: - Action summary: Cancel the request operationId: cancelAction parameters: - name: action-code in: path description: Activity code required: true schema: type: string - name: id in: path description: Activity ID (correlationID) required: true schema: type: string responses: '204': description: Activity is successfully canceled /{action-code}/requests/{id}/restore-point: put: summary: Save breakpoint operationId: saveRestorePointID tags: - Action - RestorePoint parameters: - name: action-code in: path description: Interagency code required: true schema: type: string - name: id in: path description: Activity ID (correlationID) required: true schema: type: string requestBody: required: true content: plain/text: schema: type: string format: uuid description: ID Breakpoint ID responses: '200': description: Code is saved '409': description: ID is already saved '400': description: Error in request format content: application/json: schema: $ref: '#/components/schemas/BadRequest' components: schemas: Result: type: object properties: context: type: object example: { "context": { "fullName": "Jenna Smith" } } Bindings: type: object properties: bindings: type: array items: type: object ValidationResult: type: array items: type: object BadRequest: type: object properties: errors: type: array items: type: object properties: source: type: string description: Pointer to the item in the request where the error occurred title: type: string description: Brief error description detail: type: string description: Detailed error description code: type: string description: Machine readable error code required: - code - title CreateAction: type: object properties: id: type: string format: uuid description: Request ID, must be unique for each request. It is used to control repeated requests performers: type: array description: Executors items: type: string format: uuid context: type: object description: Serialization of step context or form data exitID: type: string description: Selected transition required: - id - performers - context CreateActionResponse: type: object properties: id: type: string format: uuid description: uniqye Correlation ID restorePointURL: type: string format: url description: The address to which the restore-point-id is sent CreateActionCreateTaskResponse: type: object properties: performers: type: array description: Task executors items: type: string format: uuid context: type: object description: Field descriptions and data formFields: type: array description: Form template items: type: object description: FormField structure exitIDs: type: array description: List of allowed transitions items: type: string format: uuid required: - performers - context - exitIDs
|