Version: 8.3

Interact with business processes using a request handler

Level: advanced

@creatio-devkit/common includes the ProcessEngineService service that lets you interact with business processes. This ensures context transfer, enabling stable and predictable business logic execution as part of automation and development. Learn more: Service that runs business processes.

Run a business process

note

Creatio forbids running the business process that has output parameters in the background.

To run a business process:

Add a button to run a business process from a Freedom UI page if needed. Instructions: Set up Button components (user documentation).
Add the dependencies. Instructions: Display the value of a system variable (similarly to step 2). Instead of the SysValuesService service, use the ProcessEngineService service that lets you interact with business processes.

Set up how to handle the action executed on button click.

Go to the viewConfigDiff schema section → select required element. For example, SomeButton.
Define the type of the request to run the business process. Creatio lets you run a business process using base crt.RunBusinessProcessRequest request or custom request. We recommend using the base crt.RunBusinessProcessRequest request that has parameters to determine the context to run the business process precisely, based on your business goals. Learn more: Base request handlers.
Bind the sending of base crt.RunBusinessProcessRequest request or custom usr.SomeCustomRequest request to the element event.

View the example that binds the sending of base crt.RunBusinessProcessRequest request to the element event below. The type of business process to run, i. e., the processRunType parameter value, determines the entity with which the business process interacts. Learn more: Base request handlers.

viewConfigDiff schema section (for the selected app page)
viewConfigDiff schema section (without connection to a dedicated app page)
viewConfigDiff schema section (for the selected list records)

viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    /* Button that calls the business process. */
    {
        "operation": "insert",
        "name": "SomeButton",
        "values": {
            ...,
            "clicked": {
                /* Bind the sending of the base request to the "clicked" button event. */
                "request": "crt.RunBusinessProcessRequest",
                /* List of request parameters. */
                "params": {
                    /* Code of the business process schema. */
                    "processName": "CodeOfSomeBusinessProcessSchema",
                    /* Type of business process to run. Run the business process for the selected app page. */
                    "processRunType": "ForTheSelectedPage",
                    /* Save the current record before the business process is run. */
                    "saveAtProcessStart": true,
                    /* Display the notification when the business process is run. */
                    "showNotification": true,
                    /* Name of the process parameter that is received by the record whose ID is specified. */
                    "recordIdProcessParameterName": "SomeBusinessProcessParameter"
                }
            }
        },
        ...
    },
    ...
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    /* Button that calls the business process. */
    {
        "operation": "insert",
        "name": "SomeButton",
        "values": {
            ...,
            "clicked": {
                /* Bind the sending of the base request to the "clicked" button event. */
                "request": "crt.RunBusinessProcessRequest",
                /* List of request parameters. */
                "params": {
                    /* Code of the business process schema. */
                    "processName": "CodeOfSomeBusinessProcessSchema",
                    /* Type of business process to run. Run the business process without connection to a dedicated app page. */
                    "processRunType": "RegardlessOfThePage",
                    /* Save the current record before the business process is run. */
                    "saveAtProcessStart": true,
                    /* Display the notification when the business process is run. */
                    "showNotification": true
                }
            }
        },
        ...
    },
    ...
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    /* Button that calls the business process. */
    {
        "operation": "insert",
        "name": "SomeButton",
        "values": {
            ...,
            "clicked": {
                /* Bind the sending of the base request to the "clicked" button event. */
                "request": "crt.RunBusinessProcessRequest",
                /* List of request parameters. */
                "params": {
                    /* Code of the business process schema. */
                    "processName": "CodeOfSomeBusinessProcessSchema",
                    /* Type of business process to run. Run the business process for the selected list records. */
                    "processRunType": "ForTheSelectedRecords",
                    /* Save the current record before the business process is run. */
                    "saveAtProcessStart": true,
                    /* Display the notification when the business process is run. */
                    "showNotification": true,
                    /* The data source name. */
                    "dataSourceName": "PDS",
                    /* Key-value collection where key is the business process parameter and the value is the data source field. */
                    "parameterMappings": {
                        "SomeBusinessProcessParameter": "Id"
                    },
                    /* Filter selected list records. */
                    "filters": "$Items | crt.ToCollectionFilters : 'Items' : $DataTable_SelectionState | crt.SkipIfSelectionEmpty : $DataTable_SelectionState",
                    /* Sorting of selected records before they are passed to the business process. */
                    "sorting": "$ItemsSorting",
                    /* Track changes of the selected variable in data source. */
                    "selectionStateAttributeName": "DataTable_SelectionState"
                }
            }
        },
        ...
    },
    ...
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

View the example that binds the sending of custom usr.SomeCustomRequest request to the element event below.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    /* Button that calls the business process. */
    {
        "operation": "insert",
        "name": "SomeButton",
        "values": {
            ...,
            "clicked": {
                /* Bind the sending of the custom request to the "clicked" button event. */
                "request": "usr.SomeCustomRequest"
            }
        },
        ...
    },
    ...
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Implement the request handler that you bind to the element event.

Implement the base crt.RunBusinessProcessRequest request handler

Go to the handlers schema section.
Add a custom implementation of the base crt.RunBusinessProcessRequest request handler.
1. Retrieve the instance of the HTTP client from @creatio-devkit/common.
2. Send the base crt.RunBusinessProcessRequest request that runs a business process.
3. Pass the required request parameters.
4. Implement custom business logic that handles result and error of business process running.

View an example of the base crt.RunBusinessProcessRequest request handler that determines context and runs the business process below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "crt.RunBusinessProcessRequest",
        /* Custom implementation of a base request handler. */
        handler: async (request, next) => {
            /* Retrieve the instance of the HTTP client from "@creatio-devkit/common." */
            const handlerChain = sdk.HandlerChainService.instance;
            /* Send the base request that determines context and runs the business process. */
            var result = await handlerChain.process({
                type: 'crt.RunBusinessProcessRequest',
                /* Code of the business process schema. */
                processName: 'CodeOfSomeBusinessProcessSchema',
                /* Type of business process to run. Run the business process for the selected app page. */
                processRunType: 'ForTheSelectedPage',
                /* Save the current record before the business process is run. */
                saveAtProcessStart: true,
                /* Display the notification when the business process is run. */
                showNotification: true,
                /* Name of the process parameter that is received by the record whose ID is specified. */
                recordIdProcessParameterName: 'SomeBusinessProcessParameter'
            });

            /* If Creatio can run the business process, execute custom business logic. */
            if (result.isSuccess) {
                /* Implement custom business logic that handles result of business process running. */
                ...

            } else {
            
                /* Implement custom business logic that handles an error of business process running. */
                ...

            }

            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        },
    },
]

Implement the custom request handler

Go to the handlers schema section.
Implement the usr.SomeCustomRequest custom request handler.
1. Create an instance of the business process service from @creatio-devkit/common.
2. Implement the executeProcessByName() method that runs the business process.
3. Pass the following method parameters:
  - Name (the Code property value) of the business process to run. Pass as a string.
  - Key-value collection of input business process parameters where key is the parameter code (the Code property value) and the value is the parameter value.
  - Collection of output business process parameters. Pass as an array.
4. Retrieve the ID of the business process to run and specify it in the ProcessId attribute.
5. Retrieve output parameters of the business process to run using the resultParameterValues property and specify them in the attributes if needed.

View an example of a custom usr.SomeCustomRequest request handler that runs the business process below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* The implementation of the custom request handler. */
        handler: async (request, next) => {
            /* Create an instance of the business process service from "@creatio-devkit/common." */
            const service = new sdk.ProcessEngineService();
            /* Implement the "executeProcessByName()" method that runs the business process. */
            const result = await service.executeProcessByName(
                /* Name (the "Code" property value) of the business process to run. */
                "SomeBusinessProcessCode",
                /* Key-value collection of input business process parameters where key is the parameter code (the "Code" property value) and the value is the parameter value. */
                {
                    "SomeInputParameter1": SomeInputParameter1Value,
                    "SomeInputParameter2": SomeInputParameter2Value
                },
                /* Collection of output business process parameters. */
                [
                    "SomeOutputParameter1",
                    "SomeOutputParameter2"
                ],
            );
            /* Retrieve the ID of the business process to run and specify it in the "ProcessId" attribute. */
            request.$context['ProcessId'] = result.processId;

            /* Retrieve collection of business process output parameters using the "resultParameterValues" property and specify them in the attributes if needed. */
            const resultParameters = result.resultParameterValues;
            request.$context['SomeAttribute1'] = resultParameters.SomeOutputParameter1;
            request.$context['SomeAttribute2'] = resultParameters.SomeOutputParameter2;

            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        },
    },
]

Complete a business process element

Set up the page UI if needed. Instructions: Element setup examples (user documentation).
Add the dependencies. Instructions: Display the value of a system variable (similarly to step 2). Instead of the SysValuesService service, use the ProcessEngineService service that lets you interact with business processes.

Implement the custom request handler.

Go to the handlers schema section.
Implement the usr.SomeCustomRequest custom request handler.
1. Retrieve the ID of the business process to run.
2. Retrieve the ID of the business process element using process ID and caption of the Freedom UI page.
3. Create an instance of the business process service from @creatio-devkit/common.
4. Implement the completeExecuting() method that completes a business process element using element ID.
5. Pass a list of additional method parameters if needed.

View an example of a usr.SomeCustomRequest request handler that completes a business process element whose Code property value is SomeBusinessProcessElement below.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    {
        request: "usr.SomeCustomRequest",
        /* The implementation of the custom request handler. */
        handler: async (request, next) => {
            /* Retrieve the ID of the business process to run. */
            const processId = await request.$context["ProcessId"];
            /* Retrieve the ID of the business process element using process ID and caption of the Freedom UI page. */
            const sysProcessElementLogModel = await sdk.Model.create("SysProcessElementLog");
            const filters = new sdk.FilterGroup();
            await filters.addSchemaColumnFilterWithParameter(sdk.ComparisonType.Equal, "SysProcess", processId);
            await filters.addSchemaColumnFilterWithParameter(sdk.ComparisonType.Equal, "Caption", "Show page");
            const sysProcessElementLog = await sysProcessElementLogModel.load({
                attributes: ["Id"],
                parameters: [{
                    type: sdk.ModelParameterType.Filter,
                    value: filters
                }]
            });
            const processElementId = sysProcessElementLog[0]["Id"];
            /* Create an instance of the business process service from "@creatio-devkit/common." */
            const service = new sdk.ProcessEngineService();
            /* Implement the "completeExecuting()" method that completes a business process element using element ID. */
            await service.completeExecuting(
                /* Element ID. */
                processElementId,
                /* List of additional method parameters. For example, code of clicked button for "Auto-generated page" element. */
                {
                    "PressedButtonCode": "SomeButtonCode"
                }
            );
            /* Call the next handler if it exists and return its result. */
            return next?.handle(request);
        },
    },
]

Run a business process​

Complete a business process element​

See also​

Run a business process

Complete a business process element

See also