Best Practices

Constructing easy to follow Mambu Process Orchestrator (MPO) processes is a key part of keeping your flows maintainable, readable, and debuggable. For most processes we suggest the following general principles:

  • Extract separate business flows into subprocesses that are called by the main process. In the same way one could use functions in certain programming languages.
  • Adopt a numbering system to keep track of subprocesses. For example:
      1. Main process (which calls the subprocesses when needed)
        • Subprocesses:
          • 1.1. Client creation
          • 1.2. Order placement
          • 1.3. Order confirmation
  • Avoid passing the configuration object from the main process to subprocesses. Each subprocess should only read the configuration data it uses directly.
  • Visually design your processes in a way that follows the logic. A top-to-bottom, or left-right, layout that tracks the progression of the process is easier to follow than one with nodes in random locations.
  • Any additional logic, such as constructing the payload for an API call, should be done outside the method. The API methods should be clean and easy to call from different flows of the connector.

Additional login outside the API Call node

  • For usability purposes, we recommend that API calls are built with Request format = Raw. This allows you to send payloads from multiple flows of the process without modifying the API call.

Using the RAW format for the API Call node

  • Use descriptive names for your variables and be careful where you have similar names. For example, the variable accountId may mean different things and it would be preferable to name a variable loanAccountId or depositAccountId to avoid confusion.
  • As connectors work with multiple systems, when you have similar variable names make sure you name your variables according to the system that uses it. For example, instead of using client as a variable name, use mambuClientId or ncinoClientId to better differentiate variables.
  • Avoid overwriting and renaming variables within a process.
  • All nodes should have a short descriptions, especially End:Success and End:Error final nodes, to help you debug processes when they fail.

Beyond these principles there are development areas that require special attention when building flows.

Data security

Sensitive data - such as passwords, authentication keys, secret keys, and IBANs - should always be hidden within MPO processes and configuration state diagrams. Add sensitive data as Task Parameters > Local parameters and enable Auto-clear. This hides the values in the process.

Adding local parameters with autoclear

Performance improvements

In some areas you may get small performance improvements from these tips and tricks. In most cases the system is designed for best performance, but there are ways to squeeze out more.

Reading configuration data from state diagrams

Although it is possible to read configuration data from a state diagram by using a Call Process node, it is quicker and less error-prone to read configuration data from a state diagram using the following snippet:

{{conv[{{state diagram id or alias}}].ref[{{reference}}]}}.parameter

Limiting task payload size

The payload of a task is the JSON object that travels through nodes inside an MPO process. Larger payloads can cause performance issues for the process as a whole. There is a size limit in place for posting data to MPO, but the task payload can be modified and increased once it has entered a process and this can cause performance and stability issues. We recommend keeping task payload sizes lower than 128KB, where possible.

You can do following to keep your payloads small:

  • Use shorter field names.
  • Split JSONs into smaller chunks by using pagination.
  • Avoid using big data structures - such as big arrays and lists - in the Code node.
  • Minimise the use of temporary variables that store duplicated data in the task.
  • Explicitly define the data fields to be added to the task body from responses in API Call nodes.

Error handling

You can handle errors in the following ways:

  • You can choose to handle errors in a different subprocess.
  • You can handle errors in the same process.
  • You can copy the errors to an errors state diagram for future reference.
  • You can send notifications through your preferred channels when errors occur.

Handling errors in subprocesses

Use the Reply to Process node to pass on errors in subprocesses to the main process, where you can define conditions to take actions depending on the error received. When an error is returned to the main process, the error parameters can be directly stored in the errors state diagram without any further manipulation.

Handling errors that occur in calling a subprocess

Additional actions are needed when an error occurs in the Call Process node and the task does not even hit the subprocess. The conveyor parameter __conveyor_rpc_return_description__ is returned by MPO and contains the error caused by the task not having the necessary data to enter the called subprocess. Adding this parameter to the error condition node allows you to exit the Call Process node through a specific path and handle this type of error separately.

For example, a Set parameter node can be used to capture error messages that are specific to this type of failure. The condition to use is: __conveyor_rpc_return_description__ != null and it should be the last condition in the block of conditions (operator = OR).

Handling errors from race conditions when calling subprocesses

When two or more tasks enter a subprocess at the same time and MPO cannot handle the creation of two unique IDs at the same time for the tasks in the subprocess a unique error is thrown. To handle this situation do the following:

  1. Extend the Condition node attached to the Call Process node.
  2. Add the __conveyor_rpc_return_type_tag__ == not_unical_ref condition at the end.
  3. Link the Condition node to the Delay node attached to the Call Process node.

Handling errors with race conditions when calling subprocesses in MPO