Integration Setup

Business Central setup

After following the steps in this section you will have the necessary credentials for connecting to Microsoft Dynamics 365 Business Central.

Retrieve credentials

Log in to your Azure Portal and navigate to the registered app for the Microsoft Dynamics 365 Business Central connector. Take note of the corresponding values for:

  • Application (client) ID

  • Directory (tenant) ID

  • Redirect URI

  • Client Secret

    client/tenant id redirect uri client secret

Request authorization code

To request an authorization code, create a link as in the example below, filling in your values for tenantId, clientId and redirectUri and open it in a browser:

https://login.windows.net/[tenantId]/oauth2/authorize?client_id=[clientId]&response_type=code&redirect_uri=[redirectUri]&response_mode=query&resource=https://api.businesscentral.dynamics.com

Note: When accessing the link, input the necessary Microsoft credentials in order to complete the authentication.

Once successfully authenticated and granted consent, the authorization code will be generated and displayed in the address bar of the browser. Take note of the code value (between code= and &session_state).
code

MPO setup

After following the steps in this section you will have imported the connector processes into the Mambu Process Orchestrator and synchronized existing entities and their dimensions between Mambu and Microsoft Dynamics 365 Business Central.

Import connector

Log in to your MPO environment and import the connector file. Once the upload is complete, a new Microsoft Dynamics 365 Business Central connector folder will be visible in the workspace.

Initial configuration

In the MPO environment, open the Common setup process (found within the Connector Setup folder), switch to View mode and select New task. Fill in all the required parameters and click Add task. Wait until the task is processed.

common setup process

Alternatively, the following JSON can be used. Copy, modify and then paste it into the Code editor tab.

{
    "accountDimensionCode": "",
    "assignedUserKey": "",
    "branchDimensionCode": "",
    "businesscentralPrefix": "",
    "clientDimensionCode": "",
    "code": "",
    "companyName": "",
    "generalJournalName": "",
    "limitSizeBatchSearch": "",
    "limitSizeCollectionOfBatches": "",
    "mambuNoOfRetries": "",
    "mambuPassword": "",
    "mambuUrl": "",
    "mambuUser": "",
    "msdClientId": "",
    "msdClientSecret": "",
    "msdNoOfRetries": "",
    "msdUrlV2": "",
    "notificationChannel": "",
    "productDimensionCode": "",
    "redirectURI": "",
    "syncLimitSizeBatch": "",
    "tenantId": "",
    "timezone": "",
    "webhookAPIKey": "",
    "webhookAuthorizationType": "",
    "webhookPass": "",
    "webhookURL": "",
    "webhookUser": ""
}
ParameterDescription
accountDimensionCodeThe exact name of the Dimension found in Business Central which corresponds to the Mambu Account entities (Loan and Deposit).
assignedUserKeyThe encoded key of the designated Mambu user who will receive notifications in case of errors.
branchDimensionCodeThe exact name of the Dimension found in Business Central which corresponds to the Mambu Branch entity.
businesscentralPrefixBusiness Central environment endpoint prefix (e.g. https://api.businesscentral.dynamics.com/v2.0/<user domain name>/<environment name>;https://api.businesscentral.dynamics.com/v1.0/<user domain name>).
clientDimensionCodeThe exact name of the Dimension found in Business Central which corresponds to the Mambu Client entities (Client and Group).
codeThe authorization code specific to the OAuth2 process, used as an exchange for the access token. The value is retrieved in the Request authorization code section.
Note that the code has a short lifespan and after it is generated it can be used only once.
companyNameThe exact value of the Name of the company used in Business Central (not to be confused with Display Name). See the notes on how to retrieve the value.
generalJournalNameThe name of the General Journal in Business Central, where the Journal Lines will be posted. See the notes about pre-existing General Journals.
The length of the name must not exceed 10 characters.
limitSizeBatchSearchThe maximum size of Journal Lines to be retrieved from Mambu in a single batch.
It accepts values between 1 and 1000 (inclusive).
limitSizeCollectionOfBatchesThe maximum number of Entity Item batches processed simultaneously in MPO during the Initial sync phase.
Simultaneous processing of up to 250 batches is recommended.
mambuNoOfRetriesThe maximum number of attempts (in case of errors) to make a Mambu API request.
mambuPasswordMambu user password.
mambuUrlMambu tenant URL address (e.g. https://organizationName.mambu.com).
mambuUserMambu username (with API access).
msdClientIdBusiness Central client ID. The value is retrieved in the Retrieve credentials section.
msdClientSecretBusiness Central client secret. The value is retrieved in the Retrieve credentials section.
msdNoOfRetriesThe maximum number of attempts (in case of errors) to make a Business Central API request.
msdUrlV2The Business Central OData V4 URL for API V2 - POST Dimension Values. See the notes below on how to retrieve the value.
notificationChannelChannel used to send error notifications (i.e. task or webhook).
productDimensionCodeThe exact name of the Dimension found in Business Central which corresponds to the Mambu Product entities (Loan and Deposit).
redirectURIBusiness Central redirect URI. The value is retrieved in the Retrieve credentials section.
syncLimitSizeBatchThe maximum size of Entity Items to be retrieved from Mambu in a single batch.
It accepts values between 1 and 1000 (inclusive).
tenantIdBusiness Central tenant ID. The value is retrieved in the Retrieve credentials section.
timezoneMambu tenant Time Zone. (e.g. Europe/Berlin)
webhookAPIKeyThe API key used to authenticate the request.
Required if the notificationChannel is webhook and webhookAuthorizationType is APIkeyAuth.
webhookAuthorizationTypeWebhook URL authentication type.
Allowed values: NoAuth, BasicAuth, APIkeyAuth.
Required if the notificationChannel is webhook.
webhookPassUser password used to authenticate the request.
Required if the notificationChannel is webhook and webhookAuthorizationType is BasicAuth.
webhookURLThe URL of the target destination that will receive notification details.
Required if the notificationChannel is webhook
webhookUserUser name used to authenticate the request.
Required if the notificationChannel is webhook and webhookAuthorizationType is BasicAuth.

Notes for Setup parameters:

  • For each company created in Business Central, there is a Name and a Display Name field. To retrieve the value for the companyName parameter, find and access the Companies page using the Search function in Business Central then copy the value from the Name field.
  • The generalJournalName parameter is used to first search for an existing General Journal in Business Central with that name. If not found, it will create a new one with the provided value.
  • The msdUrlV2 will be in the form https://api.businesscentral.dynamics.com/v2.0/tenantId/environmentType/ODataV4/Company(‘CompanyName’)/DimensionValues. To retrieve this value, find and access the Web Services page using the Search function in Business Central, then filter the list by “Dimension” and copy the OData v4 URL value for the Dimension Values object. Dimension Values OData v4 URL
  • limitSizeBatchSearch and syncLimitSizeBatch are API query parameters which specify the maximum number of records to return per batch. They are each used in combination with an offset parameter to paginate the retrieved sets of records.

Initial sync configuration

This configuration is meant to copy existing Mambu entities (Branches, Products, Clients, Accounts) information into their corresponding Dimension Values within Business Central.

In the MPO environment, navigate through its folders to Connector Setup \ Dimension Values - Initial sync and open the Initiate the initial sync between Mambu entities and the equivalent Business Central dimensions process. Switch to View mode and press New task, then Add task and wait until the task is processed.

initial sync process

Retrieve webhook URLs

In your MPO environment, navigate to the main connector folder. Take note of the corresponding values for:

  1. CRON trigger Webhook
    • Select the Webhook receiver (CRON trigger) process, click the View details button, switch to the Webhook tab on the right-hand side, then select Copy webhook via JSON.
      cron trigger webhook
  2. Create dimensionValues Webhook
    • Follow the same steps as before, this time selecting the Webhook receiver - create dimensionValues for client, deposit account, loan account process, instead.

Mambu setup

After following the steps in this section you will have configured a number of webhooks in Mambu which will trigger processes in the connector when certain events take place, including client or loan account creation and completion of End of Day processing. At the end of this section you should have a total of 11 webhooks configured in Mambu for this connector.

End of day processing webhook

In your Mambu environment create a webhook notification with the following configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - End of day processing)
  • Target: End of day processing
  • On Event: Accounts Updated
  • Web Hook URL: the CRON trigger Webhook URL retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "Mambu message": "Process triggered on FORMAT_DATE{CURRENT_DATE_TIME,datePattern=dd-MM-yyyy}"
    }
    

    end of day webhook notification

Client created webhook

Create a webhook notification (similar to previous step) with the following configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Client created)
  • Option: Opt-out
  • Target: Clients
  • On Event: Client Created
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[clientDimensionName]",
      "dimensionValueCode":"{RECIPIENT_ID}",
      "dimensionValueName":"{RECIPIENT_NAME}"
    }
    

    Note: Replace the [clientDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

    end of day webhook notification

Group created webhook

Create a webhook notification with the following configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Group created)
  • Option: Opt-out
  • Target: Groups
  • On Event: Group Created
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[groupDimensionName]",
      "dimensionValueCode":"{RECIPIENT_ID}",
      "dimensionValueName":"{RECIPIENT_NAME}"
    }
    

    Note: Replace the [groupDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

Loan Account created webhook

Similar to instructions from Client created and Group created, create two webhook notifications, one targeting Clients and the other, Groups, using following the configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Loan account created (Client) / Business Central - Loan account created (Group))
  • Option: Opt-out
  • Target: Clients / Groups
  • On Event: Loan Account Created
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[accountDimensionName]",
      "dimensionValueCode":"{ACCOUNT_ID}",
      "dimensionValueName":"{ACCOUNT_NAME}"
    }
    

    Note: Replace the [accountDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

Loan Account refinanced webhook

Similar to instructions from Client created and Group created, create two webhook notifications, one targeting Clients and the other, Groups, using the following the configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Loan account refinanced (Client) / Business Central - Loan account refinanced (Group))
  • Option: Opt-out
  • Target: Clients / Groups
  • On Event: Loan Account Refinanced
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[accountDimensionName]",
      "dimensionValueCode":"{ACCOUNT_ID}",
      "dimensionValueName":"{ACCOUNT_NAME}"
    }
    

    Note: Replace the [accountDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

Loan Account rescheduled webhook

Similar to instructions from Client created and Group created, create two webhook notifications, one targeting Clients and the other, Groups, using the following configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Loan account rescheduled (Client) / Business Central - Loan account rescheduled (Group))
  • Option: Opt-out
  • Target: Clients / Groups
  • On Event: Loan Account Rescheduled
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[accountDimensionName]",
      "dimensionValueCode":"{ACCOUNT_ID}",
      "dimensionValueName":"{ACCOUNT_NAME}"
    }
    

    Note: Replace the [accountDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

Deposit Account created webhook

Similar to instructions from Client created and Group created, create two webhook notifications, one targeting Clients and the other, Groups, using the following configuration:

  • Name: choose a unique value to describe the webhook notification (e.g. Business Central - Deposit account created (Client) / Business Central - Deposit account created (Group))
  • Option: Opt-out
  • Target: Clients / Groups
  • On Event: Deposit Account Created
  • Web Hook URL: the Webhook URL for the Create dimensionValues process retrieved in the Retrieve webhook URLs section
  • Request Type: POST
  • Authorization: No Authorization
  • Content Type: application/json
  • Body of request:
    {
      "dimensionCode":"[accountDimensionName]",
      "dimensionValueCode":"{ACCOUNT_ID}",
      "dimensionValueName":"{ACCOUNT_NAME}"
    }
    

    Note: Replace the [accountDimensionName] in the Body of request field value with the related Dimension name used in Business Central.

Warning:
If migrating existing data into Mambu using the Import function, the Dimension Values will not be created automatically in Business Central as the required webhooks cannot be triggered by import.