Triggering Tasks

There are five ways to trigger a task in Mambu Process Orchestrator (MPO):

• Manually trigger a task in the MPO UI. Generally used only for testing during the development stage.
• Use a direct URL, when you need to trigger a task from an external service.
• Via the MPO API.
• Via Sync API, when you need a task response to be handled synchronously.
• Import a CSV file to trigger multiple tasks at once in the MPO UI.

Manually trigger a task in the MPO UI

To manually trigger a task in the UI, go to the View tab of the MPO process editor by opening a process from the Workspace and selecting View in the menu bar.

To trigger a new task, select the + New Task button to open the settings box. Here, you can create a new task and you can add parameters to the task by selecting + Add “key-value” or by opening the Code editor tab and adding parameters in JSON.

Once you are done, select Add task.

Trigger a task using a direct URL

A direct URL allows you to add a new task using only a link. To get the link, open a process in Edit mode and select the Start node. In the info box that pops up on the right-hand side, you will see options to Copy webhook via JSON, Copy webhook via XML, or Copy webhook via NVP. Select one of these to copy the link to your clipboard.

We recommend using Copy webhook via JSON.

Triggering a task with the MPO API

MPO API requests use the following URL template:

BASE_URL/api/API_VERSION/json/API_LOGIN/GMT_UNIXTIME/SIGNATURE

For more information about the parts of an API call URL, see API Basics.

JSON request body

{
    "ops": [
        {
            "type": "create",
            "obj": "task",
            "company_id": "i123456789",
            "conv_id": 66305,
            "ref": "3159895014223541328",
            "data": {
                "parameterName1": parameterValue1,
                "parameterName2": parameterValue2,
                "parameterName3": parameterValue3
            }
        }
    ]
}

Response

The response body returns an error if the task was not added, and returns ok for tasks added successfully. The response body does not include the task’s output, which is received asynchronously.

{
    "request_proc": "ok",
    "ops": [
        {
            "id": "",
            "proc": "ok",
            "obj": "task",
            "ref": "3159895014223541328",
            "obj_id": "5f4d39e0513aa0094458adc9"
        }
    ]
}

Triggering a task with the Sync API

The Sync API allows you to use synchronous, blocking calls to make requests to MPO, including triggering requests. When using the Sync API, your calling process must wait for a response from MPO. For more information, see Sync API.

Sync API calls use the following URL template:

https://TENANT_NAME-syncapi.mpo.mambu.com/api/1/json/API_LOGIN/GMT_UNIXTIME/SIGNATURE

For more information about the parts of an API call URL, see API Basics.

Request body JSON

{
    "timeout": 30,
    "ops": [
        {
            "type": "create",
            "obj": "task",
            "conv_id": 66305,
            "company_id": "i123456789",
            "ref": "3159895014223541328",
            "data": {
                "parameterName1": parameterValue1,
                "parameterName2": parameterValue2,
                "parameterName3": parameterValue3
            }
        }
    ]
}

Response

When the task creation API is successfully called using the Sync API, it waits for a response from the task before returning a 200 status code and a JSON object:

{
    "ops": [
        {
            "proc": "ok",
            "data": {
                "info": {
                    "parameterName1": parameterValue1,
                    "parameterName2": parameterValue2,
                    "parameterName3": parameterValue3
                }
            }
        }
    ],
    "request_proc": "ok"
}

Status codes for API-triggered tasks

For all successfully triggered tasks the HTTP status code is 200 and for tasks with errors 400 or 500.

Trigger multiple tasks using a CSV in the UI

In certain cases, you may want to trigger more than one task for batch operations. Instead of manually creating a new task each time, you can import a CSV file that will add multiple tasks. Each row in the CSV file specifies a separate task to be added. If you have four rows, excluding the header row, four tasks will be added.

Requirements for the CSV file:

• The CSV file must be encoded in UTF-8 or Windows-1251 (for Cyrillic script).
• The parameter names must be in the first row.
• Parameter names must not have any spaces.
• You may use commas (,), semi-colons (;), or pipes (|) as delimiter values.

Format

parameterName1;parameterName2;parameterName3
parameterValueA1;parameterValueA2;parameterValueA3
parameterValueB1;parameterValueB2;parameterValueB3
parameterValueC1;parameterValueC2;parameterValueC3
parameterValueD1;parameterValueD2;parameterValueD3
parameterValueE1;parameterValueE2;parameterValueAE3

The first task in this format is:

parameterValueA1;parameterValueA2;parameterValueA3

The equivalent specification for that task in JSON is:

{
     "parameterName1":parameterValueA1,
     "parameterName2":parameterValueA2,
     "parameterName3":parameterValueA3
}

Importing the CSV file

To add tasks, go to the View tab and select Import from CSV. Select the CSV in the resulting pop-up dialog and choose the delimiter and encoding format of the file.

In the next window, make sure to check Parameter names are in the first row and then select Import. The tasks will be added immediately.