Fetching and Manipulating Data from Mambu

Mambu Process Orchestrator (MPO) can be used to pull and manipulate data from other services, such as the Mambu Banking Engine, to create custom processes. In this documentation we will primarily deal with fetching and changing data from Mambu, but the same principles apply to any API-enabled service.

Interacting with external services

In order to receive data from a service, it must have an API that you can access. In the case of Mambu, you must authenticate API requests using Basic Auth or with API keys. When possible, we recommend using API keys. For more information, see Authentication in our API Reference.

We recommend keeping the API call process, which fetches or manipulates data, separate from the process that executes the business logic. This allows you to easily reuse fetch logic in other processes, and also simplifies debugging.

Receiving data from an external service in MPO

To make an API call that fetches data from an external service, set up a process with the API Call node. Once you have collected any necessary authentication keys and so forth, a typical process for adding an API call would look like this:

1. Read the API reference documentation to be sure you are formatting your requests correctly.
2. Test the endpoint using a tool like Postman or Insomnia. For more information about the basics of working with the Mambu API, see our API Reference.
3. Create the API call process in the MPO UI by creating a process with an API Call node. To do so, open the info box by selecting the node. Enter the URL for the API call and make sure that the Request Format, Request Method (usually GET for fetching data), and the Content-Type (usually application/json) are set correctly.

To add headers, go to the Additionally section, select the checkbox next to Header Parameters, and add the parameters.

When this process is deployed and tasks are created, the returned object with the data will be stored in the data store of the process.

Example: Get all clients from Mambu

In this example, you will set an API Call node to fetch a JSON object from the Mambu API v2 with all the clients in your Mambu instance. This example uses Mambu API keys for authentication. For more information on the call we will use, see Clients in the Mambu API Reference.

In the URL API section use the following settings:

• URL API: https://TENANT_NAME.mambu.com/api/clients
• Request format: Default
• Request method: GET
• Content-Type: Application/json

Enable Header Parameters in the Additionally section and add the following key-value pairs:

• apiKey : Your API key
• Accept : application/vnd.mambu.v2+json (this is required for all Mambu API v2 calls)

To view the returned data, open the process in View mode, upload a new task, and then select the Final node once it has stopped. Under the Archive tab you should see the returned object with all the clients in your Mambu instance.

Using the returned data

The returned data from a GET request is stored in the private data store of the process. When the root of the response is an array, MPO creates an object called __conveyor_api_array__, which contains an array of the request responses. It is available to manipulate in the code block as the data.__conveyor_api_array__ variable. Using dot notation, you can isolate a key-value pair or return the whole JSON object that you would like to access in another process, such as a process where the business logic is applied. Other variables may be added depending on the response. See the API Call node documentation for more on these variable.

Using the Reply to Process node, you can pass this object back to another process for further use.

Manipulating data in an external service from MPO

To manipulate data on an external service you will need API edit rights. For more information about getting the appropriate access rights, see the API Consumers section. Once you have collected what you need to authenticate requests, follow the steps below:

1. Read the API reference documentation and find the external service’s API endpoint that you need. For Mambu, this would be the API Reference documentation at api.mambu.com.
2. Test the endpoint to ensure that your authentication works using a tool like Postman or Insomnia. For more information about the basics of working with the Mambu API, see the API Reference documentation.
3. Create the API call process by going to the MPO UI. Create a process with an API Call node. Open the info box by selecting the node. Enter the URL for the API call and make sure that the Request Format, Request Method (usually the POST, PUT or DELETE methods for manipulating data) and the Content-Type (should always be application/json for Mambu API v2 calls) are set correctly.

For Mambu POST requests, you need to first disable the Send system parameters setting, which can be found in the Additionally section. Then, add header parameters by selecting the checkbox next to Header Parameters and adding the parameters.

To add a body parameter, go to the Parameter section of the settings box, select the Code Editor tab, and add a JSON object.

PATCH operations on Mambu

Performing a Mambu API v2 PATCH request in MPO requires a few extra steps when using the API Call node. MPO treats an HTTP 204 status code as an error, as no response body is received. In order to make a PATCH operation work, you need to do the following in the settings box of the API Call node:

1. Select Raw as the Request Format.
2. Select PATCH as the Request Method.
3. Double click the Condition node that is connected to the API Call node. This will expand the Condition node.

4. In the Condition node’s setting box, select + Add condition.
5. In the Key input, add __conveyor_api_return_http_code__, which sets the HTTP return code as the condition to evaluate.
6. Set the double equal sign (==) as the logic operator.
7. In the Value input, add 204 as the the value.
8. Connect that conditional to the End: Success to ensure that when the HTTP return code is 204, the operation ends successfully.

Example: Create a new client in Mambu

In this example, we will configure a call to the Mambu API v2 /clients endpoint to create a new client.

In the URL API section:

• URL API: https://TENANT_NAME.mambu.com/api/clients
• Request format: Default
• Request method: POST
• Content-Type: Application/json

In the Parameters section under the Code Editor tab add a JSON body with details of the client you want to create:

{
     "addresses": [
          {
               "city": "Stuttgart",
               "country": "Germany",
               "line1": "Invalidenstrasse 130",
               "line2": "Montberg",
               "postcode": "10112",
               "region": "Baden-Wuerttemberg"
          }
     ],
     "birthDate": "1971-09-09",
     "emailAddress": "newclient@email.com",
     "firstName": "Harold",
     "gender": "MALE",
     "homePhone": "0123456789",
     "id": "23452345",
     "lastName": "Schlimmer",
     "middleName": "Norris",
     "mobilePhone": "013571234567",
     "notes": "Opened an account at the Stuttgart branch. Assisted by Petrus Lindhof.",
     "preferredLanguage": "ENGLISH",
     "state": "INACTIVE"
}

For more information, see the create section of Clients in our API Reference.

Enable Header Parameters under Additionally section and add the following key-value pairs:

• apiKey : Your API key
• Accept : application/vnd.mambu.v2+json (this is required for all API v2 calls)

Then deselect Send system parameters for POST requests to the Mambu API. To confirm that a new client was created, go to the Mambu UI and search for the details of the newly created client.