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. You can find out more about the basics of working with the Mambu API in 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 clicking on 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, click the checkbox next to Header Parameters, and add the parameters.

The API Call node settings for fetching data from Mambu

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

Example: Get all clients from Mambu

In this example, you will set an API Call node to fetch a JSON object from the Mambu v2 API 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:

  • 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 MPO task in View mode and click the Final node. 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 process’s private datastore. When the root of the reponse 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. Find our more about getting the appropriate access rights in 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 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. You can find out more about the basics of working with the Mambu API in 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 clicking on 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) are set correctly.

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

Disable sending system parameters for POST requests to Mambu

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 success message as an error 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 part of the API Call block. This will expand the Condition node.

Expand the Conditional node

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

Add conditional for an Mambu PATCH operation

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. For more information, see the create section of Clients in our API Reference.

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": "string",
      "country": "string",
      "line1": "string",
      "line2": "string",
      "postcode": "string",
      "region": "string"
    }
  ],
  "birthDate": "1987-04-26",
  "emailAddress": "string",
  "firstName": "string",
  "gender": "MALE",
  "homePhone": "string",
  "id": "string",
  "lastName": "string",
  "middleName": "string",
  "mobilePhone": "string",
  "mobilePhone2": "string",
  "notes": "string",
  "preferredLanguage": "ENGLISH",
  "state": "INACTIVE"
}

Please be aware:
Your organization may have set a different default state for new clients, if this is the case, you will receive an error message with an errorReason of INVALID_CLIENT_STATE and an errorSource indicating the correct state to use.

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 uncheck 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 client.