Sync API
The Sync API allows you to make synchronous, blocking calls to the Mambu Process Orchestrator (MPO) by issuing calls to a sync server instead of the standard MPO base URL.
Requests to the standard MPO base URL return confirmation that the call was received, but the call is non-blocking for your application code. The process or state diagram output is returned later as an additional response, or you must make another call to check its status.
When using the Sync API, the output is returned synchronously, and your request will be blocked waiting for the outputs.
Use the API Call node to invoke a sync API request.
We generally recommend using the standard asynchronous API where possible, so that your applications are not be blocked while your request is being handled.
How it works
Every MPO instance has a corresponding sync server with the following base URL:
https://TENANT_NAME-syncapi.mpo.mambu.com/
To make synchronous calls to MPO, you must issue calls to the sync server base URL. You may also issue synchronous calls to your MPO sandbox using the following base URL:
https://TENANT_NAME-syncapi.sandbox.mpo.mambu.com/
Synchronous requests use the sync server as an intermediary to make the request for you. Your request will be blocked until the process or state diagram output is returned or the request times out.
Configuring a sync API request in the UI
To configure a synchronous request, you need to:
- Add the API Call node after the step from which you need an output.
- Provide the {{__callback_url}}.
- Specify the parameters which are to be sent to the task.
Generating a sync API request
Once the process or state diagram is set up to receive a sync API request, send a request to the sync Server to invoke a task. This synchronous request must include a signed hash to ensure that requests are coming from a known sender.
https://TENANT_NAME-syncapi.mambuonline.com/api/1/json/API_USER/GMT_UNIXTIME/SIGNATURE
For more information on how to create a signature, see API Basics.
Request body
The request body must include either the process ID or an alias of the task you want to invoke and any parameters you want to pass into the task. You may provide an optional timeout for the request, in seconds. If you do not specify a timeout, the default value of 60 seconds will be used.
Example using the process ID
{
"timeout": 30,
"ops": [{
"conv_id": 33220,
"company_id": "i123456789",
"type": "create",
"obj": "task",
"data": {
"param": 1
}
}]
}
parameter | type | description | required |
---|---|---|---|
timeout | number | The maximum time to wait for a response. The default is 60 seconds. | No |
ops | JSON Object | A list enclosing all the tasks to run on MPO. | Yes |
ops[].conv_id | number | The ID of the process or state diagram that you want to run. | Yes |
ops[].company_id | string | The 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[].type | string | The type of task. Usually create . | Yes |
ops[].obj | string | An object type. Usually task . | Yes |
ops[].data | JSON Object | An object with key-value pairs of the parameters to pass into the task. | Yes |
Example using an alias
{
"timeout": 30,
"ops": [{
"obj_alias": "an-alias",
"company_id": "i123456789",
"type": "create",
"obj": "task",
"project_id": 27443,
"stage_id": 33164,
"data": {
"param": 1
}
}]
}
parameter | type | description | required |
---|---|---|---|
timeout | number | The maximum time to wait for a response. The default is 60 seconds. | No |
ops | JSON Object | A list enclosing all the tasks to run on MPO. | Yes |
ops[].obj_alias | string | The short name of the alias of the process or state diagram that you want to run. | Yes |
ops[].company_id | string | The 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[].type | string | The type of task. Usually create . | Yes |
ops[].obj | string | An object type. Usually task . | Yes |
ops[].project_id | string | If the alias is in a stage you need to provide a project ID. Without project_id and stage_id the alias is global and can be accessed from any process. Using project_id and stage_id allows you to isolate an alias to a specific project. For more on finding the project ID see the Additional Operations section of the Projects, Stages, and Versions page. | No |
ops[].stage_id | string | If the alias is in a stage you also need to provide a stage ID. Without project_id and stage_id the alias is global and can be accessed from any process. Using project_id and stage_id allows you to isolate an alias to a specific project. For more on finding the stage ID see the Additional Operations section of the Projects, Stages, and Versions page. | No |
ops[].data | JSON Object | An object with key-value pairs of the parameters to pass into the task. | Yes |
You can not use both
obj_alias
and conv_id
in the same API request. Each request should use one or the other.Responses
{
"ops": [
{
"proc": "ok",
"data": {
"info": {
"param_1": "value_1",
"param_2": "value_2",
"param_3": "value_3"
}
}
}
],
"request_proc": "ok"
}
parameter | description |
---|---|
ops | A list enclosing responses from all of the tasks run on MPO. |
ops[].proc | Returns ok if a particular task runs successfully or errors if otherwise. |
ops[].data.info | An object with key-value pairs of the parameters returned from the task. This response can be specified in the API Call node. |
request_proc | Returns ok if all the tasks ran successfully or errors if otherwise. |