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.

Uploading a task

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.

Getting the Direct URL from MPO

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
            }
        }
    ]
}
ParameterTypeDescriptionValuesRequired
opsJSON ObjectA list enclosing all the tasks to run on MPO.Yes
ops[].typeStringThe type of task.This should always be ‘create’Yes
ops[].objStringAn object type to run the tasks on.This should always be ‘task’Yes
ops[].company_idstringThe ID of the company. This can be retrieved from your MPO URL when you are logged into the MPO UI (e.g https://TENANT_NAME.mpo.mambu.com/i123456789/workspace/).Yes
ops[].conv_idNumberThe ID of the process, which you can find by selecting the Start node to open the info panel.Yes
ops[].refNumber or StringAny unique, alphanumeric identifier of up to 255 characters long that identifies the task externally. Useful if you want to keep track of tasks.No
ops[].dataJSON ObjectAn object with key-value pairs of the necessary parameters.Yes, if the process has required parameters.

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"
        }
    ]
}
ParameterDescription
request_procReturns ok if all the tasks ran successfully or errors if otherwise.
opsA list enclosing responses from all of the tasks run on MPO.
ops[].idThe request ID.
ops[].procReturns ok if a particular task runs successfully or errors if otherwise.
ops[].objAn object type. Always task.
ops[].refThe reference identifier of the task. Matches the reference sent in the API call.
ops[].obj_idAn internal system ID of the task.

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
            }
        }
    ]
}
ParameterTypeDescriptionRequired
timeoutnumberThe maximum time to wait for a response. The default is 60 seconds.No
opsJSON ObjectA list enclosing all the tasks to run on MPO.Yes
ops[].typeStringThe type of task. This should always be create for this type of request.Yes
ops[].objStringAn object type to run the tasks on. This should always be task for this type of request.Yes
ops[].conv_idNumberThe ID of the process, which you can find by selecting the Start node to open the info panel.Yes
ops[].refNumber or StringAny unique, alphanumeric identifier of up to 255 characters long that identifies the task externally. Useful if you want to keep track of tasks.No
ops[].company_idstringThe ID of the company. This can be retrieved from your MPO URL when you are logged into the MPO UI (e.g https://TENANT_NAME.mpo.mambu.com/i123456789/workspace/).Yes
ops[].dataJSON ObjectAn object with key-value pairs of the necessary parameters.Yes, if the process has required parameters.

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"
}
ParameterDescription
opsA list enclosing responses from all of the tasks run on MPO.
ops[].procReturns ok if a particular task runs successfully or errors if otherwise.
ops[].data.infoAn object with key-value pairs of the parameters returned from the task. Data specified for response in the API Call node.
request_procReturns ok if all the tasks ran successfully or errors if otherwise.

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.

HTTP Status Coderequest_procprocdescriptionCause
200okokThe task has been successfully triggered.
400errorBad request. Reason: callback_hash_errorThere is an error in the request signature or the body is missing.
500An internal server error that may be caused by using the incorrect API login details.

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.

The settings popup to import CSVs

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.

Previewing the task list