Integration Setup

Data Dictionary

The Mambu-Xero connector’s business flow consists of extracting from Mambu, at midnight, all Journal Lines created in the previous day and sending them as balanced batches of Journal Lines to Xero.

The dictionary of terms below will help reconcile the names of entities and parameters which may be referred to differently between Xero and Mambu.

General terms

The mapping of terms between the Mambu Journal Line and Xero Journal Line is found in the table below.

Mambu parameterXero elementDescriptionNotes
n/aNarrationDescription of manual journal being posted.The format is: “Mambu journal data with creation date: creation_date”, where creation_date is the Mambu Journal Line creationDate.
bookingDateDateThe date when an entry is posted to an account on the account servicer’s accounting books.The format is: yyyy-mm-dd.
n/aJournalLinesA batch of balanced Journal Lines (total Debit amounts are equal to total Credit amounts), grouped by booking dateSee table Array of JournalLines below.

Array of JournalLines:

Mambu parameterXero elementDescriptionNotes
glCodeAccountCodeCustomer defined numeric account code.Each account has an account code of up to 10 characters.
Any code can be used for any account as long as it’s unique.
amount
type
LineAmountAmount of the Journal Line.Debits are positive, credits are negative value.
entryID
transactionId
DescriptionDescription for Journal Line.The format is: EntryID: {entryID}, TransactionID: {transactionId}, where {entryID} is the Mambu Journal Line ID while the {transactionId} is the Mambu ID of the transaction (e.g. repayment, disbursement) that generated the Journal Line.

Example of raw Journal Lines retrieved from Mambu:

      [
         {
            "encodedKey": "8a19bd517945f2d4017955ad7a70387d",
            "entryID": 4519,
            "creationDate": "2021-05-10T12:48:23+03:00",
            "bookingDate": "2021-05-10T12:48:22+03:00",
            "transactionId": "6407",
            "accountKey": "8a19d41a790debe001790e18afea0ec8",
            "productKey": "8a19a9b6727f4fd001727fcbb85700cf",
            "productType": "LOAN",
            "amount": 100,
            "glAccount": {
                "encodedKey": "8a19befc78a1360c0178a1a0bdde0269",
                "creationDate": "2021-04-05T13:43:38+03:00",
                "lastModifiedDate": "2021-04-05T13:43:38+03:00",
                "glCode": "11504",
                "type": "ASSET",
                "usage": "DETAIL",
                "name": "Transaction Source",
                "activated": true,
                "description": "",
                "allowManualJournalEntries": true,
                "stripTrailingZeros": true,
                "currency": {
                    "code": "EUR"
                }
            },
            "type": "DEBIT",
            "userKey": "8a19a25978c97f040178c9da6c2d07fe"
        },
        {
            "encodedKey": "8a19bd517945f2d4017955ad7a70387e",
            "entryID": 4520,
            "creationDate": "2021-05-10T12:48:23+03:00",
            "bookingDate": "2021-05-10T12:48:22+03:00",
            "transactionId": "6407",
            ...
            "amount": 69.92,
            "glAccount": {
                ...
                "glCode": "11503",
                ...
            },
            "type": "CREDIT",
            "userKey": "8a19a25978c97f040178c9da6c2d07fe"
        },
        {
            "encodedKey": "8a19bd517945f2d4017955ad7a70387f",
            "entryID": 4521,
            "creationDate": "2021-05-10T12:48:23+03:00",
            "bookingDate": "2021-05-10T12:48:22+03:00",
            "transactionId": "6407",
            ...
            "amount": 30.08,
            "glAccount": {
                ...
                "glCode": "11310",
                ...
            },
            "type": "CREDIT",
            "userKey": "8a19a25978c97f040178c9da6c2d07fe"
        }  
      ]  

Example of processed Journal Lines sent to Xero:

    {
        "Date": "2021-05-10",
        "Narration": "Mambu journal data for creation_date 2021-05-10 ",
        "JournalLines": [
            {
                "LineAmount": 100,
                "AccountCode": "11504",
                "Description": "EntryID: 4519, TransactionID: 6407"
            },
            {
                "LineAmount": -69.92,
                "AccountCode": "11503",
                "Description": "EntryID: 4520, TransactionID: 6407"
            },
            {
                "LineAmount": -30.08,
                "AccountCode": "11310",
                "Description": "EntryID: 4521, TransactionID: 6407"
            }

        ]
     }

Installation and Configuration

Installation of the connector requires a few steps to be carried out in Xero, MPO and Mambu.

Xero environment

Communication between the connector and Xero is secured using OAuth 2.0, an industry-standard protocol for authorisation of users and third-party applications. Read more about OAuth for custom integrations and apps with Xero on their dedicated support page.

Creating an OAuth 2.0 App

  1. Access your dedicated Xero environment

  2. Select New app create new app in Xero

  3. Fill in the mandatory fields:

    • Name
    • Company or application URL;
    • OAuth 2.0 redirects URIs.
    • Select Auth Code as OAuth 2.0 grant Type. OAuth app settings in Xero Select Create app.
  4. Select Generate a secret. generate an OAuth client secret in Xero

  5. Take note of the Client id and Client secret as these values will be used during MPO setup client ID and secret for Xero OAuth app

    The Client Secret is private and should not be shared. We recommend storing it in a password vault or keychain as you will not be able to access it again through the Xero user interface.

Retrieving the Authorization Code

The AuthorizationCode is ephemeral, may only be exchanged once and expires 5 minutes after it has been generated. So you may want to hold off on generating it until you are ready to run the setup process for the connector.

  1. Create an authorization link like the example below and open it in a browser.
  • https://login.xero.com/identity/connect/authorize?response_type=code&client_id=xeroClientId&redirect_uri=xeroRedirectURI&scope=offline_access+accounting.transactions&state=state
    The following query parameters should be included:
    • xeroClientId: client id retrieved when creating your OAuth 2.0 app
    • scope: use offline_access in order to receive a refresh_token and accounting.transactions for Accounting APIs;
    • xeroRedirectURI: the URL of your server to redirect back to;
    • state: a unique string to be passed back on completion. calling the authorization URL in your browser
  1. You will be prompted to log in and once you have, should allow access to the OAuth app created above authorise access for the OAuth app
  2. Take note of the code from the URL as it will be used as a value for parameter xeroAuthorizationCode when setting up the connector in MPO. retrieving the authorisation code from the Xero OAuth app

MPO environment

MPO contains the connector and its component processes. You will need to provide values such as Xero and Mambu credentials as well as details of your timezone and settings for the size of the Journal Entry batches the connector will be sending to Xero.

Importing the connector

  1. Access your MPO environment.
  2. Select Create - From File and add the .json file from the GitLab repository. MPO create process from file Once the upload is complete, you will see the Xero VX.X folder in your workspace, where X.X represents the current version.

Configuring the Connector

  1. Go to the Setup folder and open the Common setup process process.
    setting configuration parameters in MPO
  2. Switch to View mode, and click New task. Fill in all the parameters with required values and press Add task. Wait until the task is processed. running the connector setup process in MPO
    ParameterDescription
    limitSizeBatchSearchThe URL parameter limit that specifies the number of records to return (Journal Lines), used in combination with the offset parameter. These parameters are utilized to retrieve the records in batches, as a paginated set.
    Taking into account the Xero API Rate Limits number 50 it is recommended as value for this parameter.
    limitSizeBatchXeroThe minimum number of balanced Journal Lines that can be sent to Xero.
    Taking into account the Xero API Rate Limits number 50 it is recommended as value for this parameter.
    limitSizeCollectionOfBatchesThe maximum number of batches processed simultaneously in MPO.
    Simultaneous processing of up to 250 tasks is recommended.
    mambuNoOfRetriesThe number of retries for a Mambu API call in case of errors.
    mambuPasswordMambu user password.
    mambuUrlOrganization’s Mambu URL address (e.g. https://{{tenantName}}.mambu.com).
    mambuUserMambu user (with API access).
    notificationChannelNotification channel, ex. task - in this case, if an error occurs, a task is created in Mambu.
    notificationUserThe encoded key of the assigned Mambu user who will receive notifications in case of errors.
    timezoneOrganization’s Time Zone.
    xeroAuthorizationCodeThe verification code parameter specific for OAuth2.0. This is a temporary code that may only be exchanged once and expires 5 minutes after issuance. See Retrieving the authorization code
    xeroClientIdXero Client id. Retrieved at step 5 of Creating an OAuth 2.0 App
    xeroClientSecretXero Client secret. Retrieved at step 5 of Creating an OAuth 2.0 App
    xeroNoOfRetriesThe number of retries for a Xero API call in case of errors.
    xeroRedirectURIXero redirect URI (the URL to redirect back to).
    xeroURLXero URL (e.g. https://api.xero.com/api.xro/2.0).

Alternatively, you can use the following JSON. Modify it and paste into the Code editor tab.

{
    "limitSizeBatchSearch": 0,
    "limitSizeBatchXero": 0,
    "limitSizeCollectionOfBatches": 0,
    "mambuNoOfRetries": "",
    "mambuPassword": "",
    "mambuUrl": "",
    "mambuUser": "",
    "notificationChannel": "",
    "notificationUser": "",
    "timezone": "",
    "xeroAuthorizationCode": "",
    "xeroClientId": "",
    "xeroClientSecret": "",
    "xeroNoOfRetries": "",
    "xeroRedirectURI": "",
    "xeroURL": ""
}
  1. Open the Main process, click View details (the i icon), open the Webhook tab and select Copy webhook via JSON. retrieving the webhook URL from MPO Take note of the URL, as as it will be needed when creating webhooks in Mambu.

Mambu environment

The final step is to configure the webhook which will trigger the connector to push Journal Entries to Xero Accounting after End of Day processing has been run for your Mambu system. You can read more about what jobs are included in Mambu End of Day processing in our dedicated support article.

Creating a webhook

  1. Log in to your Mambu environment.
  2. Go to Administration and select the Webhooks menu. creating a new webhook in Mambu
  3. Create a new Webhook with the following settings:
    • Target: End of day processing
    • On Event: Accounts Updated
    • Web Hook URL: paste the webhook URL retrieved in step 4 of configuring the connector
    • Request Type: POST
    • Authorization: No Authorization
    • Content Type: application/json
    • Body of request:
    {
      "startType":"automatic"
    }
    

    creating a webhook in Mambu