Integration Setup

Jump to Section

MPO

Importing the connector

Log in to your Mambu Process Orchestrator (MPO) UI environment. Select Create from the left-hand menu and click From file.
Upload the JSON file for the AML connector with the pre-integration templates. A new AML Screening and Monitoring vX.X (YYYY-MM-DD) folder will be available in your workspace.
Upload the JSON file for the Configurable Callback with the pre-integration templates. A new AML Entity Translator folder will be available in your workspace.
Navigate to Aliases tab and press the Create button.
Create a new Alias and link the process from the AML Entity Translator folder.
Open the MPO process from AML Entity Translator folder and add JavaScript code based on the client business for Client and Group code node.
Add JavaScript support for the rest of the parameters as in the table below:

Parameter Name	Entity	Details
`data.client.fullName`	Client	Format = string; concatenates `data.client.firstName`, `data.client.middleName`, `data.client.lastName`
`data.client.birthYear`	Client	Format = 4 digits.
`data.client.countryCodes`	Client	Format = 2 letters.
`data.client.searchVersion`	Client	Field stores the criteria on which the last search was made for a client.
`data.group.groupName`	Group	Format = string; remove white spaces.
`data.group.countryCodes`	Group	Format = 2 letters.
`data.group.entityType`	Group	Extracted value from Mambu custom field or from Mambu group entity type; allowed values: `Company` or `Organisation`.
`data.group.searchVersion`	Group	Field stores the criteria on which the last search was made for a group.

Please Note

You can add validation for the input data and generated fields in the Code node to avoid errors in downstream processes. Any errors thrown from the Code node will be logged in the connector. This may help with troubleshooting. For more information visit our additional settings for complex nodes support article.

Configuration

Open the Setup process from the AML Screening and Monitoring vX.X (YYYY-MM-DD) folder, switch to View mode and select New task. Fill all the parameters and click Add task. Wait until the task moves to the final node, indicating all steps have been processed.

MPO. Setup

Alternatively, the following JSON data can be used. Modify it accordingly and paste into the Code editor tab.

{
    "customUpdatesClientConfig": {
        "blacklistedStatus": [
            "potential_match"
        ],
        "blacklistedSources": [
            "matched_source_PEP",
            "matched_source_AMedia",
            "matched_source_sanctions"
        ],
        "whitelistedStatus": [
            "false_positive",
            "no_match",
            "true_positive_approve"
        ],
        "monitoredStatus": [
            "no_match",
            "potential_match"
        ],
        "stopMonitoringOnEvent": [
            "exitedClient",
            "blacklistedClient",
            "rejectedClient"
        ],
        "reportStatus": [
            "potential_match",
            "true_positive_approve"
        ],
        "createUpstreamBlacklistedClient": true // applicable only for Upstream Onbording flow
    },
    "customUpdatesGroupConfig": {
        "monitoredStatus": [
            "no_match",
            "false_positive",
            "unknown"
        ],
        "reportStatus": [
            "potential_match",
            "true_positive_reject",
            "true_positive_approve"
        ],
        "stopMonitoringOnEvent": [
            "exitedGroup"
        ]
},
    "cfMappingData": {
        "clientUsedFields": [
            {
                "source": "id",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_searchId"   // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "search_version",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_clientSearchVersion"    // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "share_url",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_sharedUrl"  // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "pep",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_pep"    // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "sanctions",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_sanctions"  // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "adverseMedia",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_adverseMedia"   // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "match_status",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_matchStatus"    // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "risk_level",
                "targetPath": "_ComplyAdvantage_AML_Clients.aml_riskLevel"  // represents the customSet.customFieldId created in Mambu environment
            }
        ],
        "groupUsedFields": [
            {
                "source": "id",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_searchIdGroup"   // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "share_url",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_sharedUrlGroup"  // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "pep",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_pepGroup"    // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "sanctions",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_sanctionsGroup"  // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "adverseMedia",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_adverseMediaGroup"   // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "match_status",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_matchStatusGroup"    // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "search_version",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_groupSearchVersion"  // represents the customSet.customFieldId created in Mambu environment
            },
            {
                "source": "risk_level",
                "targetPath": "_ComplyAdvantage_AML_Groups.aml_riskLevelGroup"  // represents the customSet.customFieldId created in Mambu environment
            }
        ],
    },
    "groupState": {
        "targetPath": "_ComplyAdvantage_AML_Groups.aml_stopMonitoring" // represents the customSet.customFieldId created in Mambu environment
    },
    "complyAdvantageAccessKey": "njV5SXDZGGdAgcRwApFBCRQ8g533YMi3",
    "complyAdvantageExactMatch": false,
    "complyAdvantageFuzziness": 0.7,
    "complyAdvantageRemoveDeceased": 0,
    "complyAdvantageShareUrl": 1,
    "complyAdvantageSearchProfile": "5222e25c-167e-4078-6981-20f866c7f861", 
    "complyAdvantageUrl": "https://[CAInstance].complyadvantage.com",
    "entityDataPreparationCallBack": "ca-aml-entity-data-preparation",	// this is the MPO Alias name for the linked callback process developed based on the client business
    "mambuUrl": "https://mambuecosystem.sandbox.mambu.com",
    "mambuUser": "Mambu user",
    "mambuPassword": "Mambu password",
    "retryInterval": 30,    // applicable for Retry Mechanism [number of seconds]
    "retryLimit": 5,    // applicable for Retry Mechanism [number of tries]
    "notificationChannel": "task",  // available values; task / zenDesk / URL
    "defaultTaskAssigneeKey": "8a19a9b6727f4fd001727ff5c5ec011d",
    "createClient": true,
    "createSearch": true,
    "matchStatusAnalyser": true,
    "getClientDetails": true,
    "getGroupDetails": true,
    "getSearchDetails": true,
    "startStopMonitoring": true,
    "updateClientState": true,
    "updateCustomField": true,
    "updateSearch": true,
    "webhookAPIKey": "",
    "webhookUrl": "",
    "zenDeskAPIKey": "",
    "zenDeskGroupId": "",
    "zenDeskLogin": "",
    "zenDeskSubdomain": ""
}

`ComplyAdvantage` setup field description

Name	Type	Value
`complyAdvantageRemoveDeceased`	number	`0` or `1`. When set to `1` deceased people are removed from search results
`complyAdvantageShareUrl`	number	`0` or `1`. When set to `1` a shareable URL to access search publicly is included and populated to a Mambu custom field.
`complyAdvantageFuzziness`	number (float)	Between `0.0` - `1.0`. Determines how closely the returned results must match the supplied name. For example, `0.0` fuzziness disables 1 letter typo matching but keeps all other standard and optional matching behaviors. Can be overridden by setting `complyAdvantageExactMatch` to `true`.
`complyAdvantageExactMatch`	boolean	When set to `true` all standard and optional matching behaviors including honorifics, affixes, initials, glued name, name variation, equivalent names, extra words in entity and so on are ignored. In other words, the `complyAdvantageFuzziness` property is not applied.
`complyAdvantageSearchProfile`	string	This is an optional field. The ID for search profile can be found in the Comply Advantage UI once created. If not stated (and there are no types under filters), all listing types will be screened. More details on the search profile can be found underComplyAdvantage Search Profile.

`customUpdatesClientConfig` and `customUpdatesGroupConfig` setup field descriptions

`blacklistedStatus` array

Object name	Value
`customUpdatesClientConfig`	`no_match`, `false_positive`, `unknown`, `true_positive`, `potential_match`, `true_positive_reject`, `true_positive_approve`

`blacklistedSources` array

Object name	Value
`customUpdatesClientConfig`	`matched_source_PEP`, `matched_source_AMedia`, `matched_source_sanctions`

`monitoredStatus` array

Object name	Value
`customUpdatesClientConfig` and `customUpdatesGroupConfig`	`no_match`, `false_positive`, `unknown`, `true_positive`, `potential_match`, `true_positive_reject`, `true_positive_approve`

`stopMonitoringOnEvent` array

Object name	Value
`customUpdatesClientConfig`	`exitedClient`, `blacklistedClient`, `rejectedClient`
`customUpdatesGroupConfig`	`exitedGroup`

`reportStatus` array

Object name	Value
`customUpdatesClientConfig` and `customUpdatesGroupConfig`	`no_match`, `false_positive`, `unknown`, `true_positive`, `potential_match`, `true_positive_reject`, `true_positive_approve`

`notification` setup field descriptions

Name	Value	Description
`notificationChannel`	`task` / `zenDesk` / `URL`	The system of choice for receiving notifications.
`defaultTaskAssigneeKey`	`encodedKey`	The encoded key of the default Mambu user for task notification. Required if you select `task` as `notificationChannel`.
`webhookAPIKey`	`apiKey`	The API key of the system used to receive notifications via webhook. Required if you select `URL` as `notificationChannel`.
`webhookUrl`	`url`	The URL of the selected `URL` system. Required if you select `URL` as `notificationChannel`.
`zenDeskAPIKey`	`apiKey`	The API key of the `zenDesk` system. Required if you select `zenDesk` as `notificationChannel`.
`zenDeskGroupId`	`groupId`	The group ID of the `zenDesk` system. Required if you select `zenDesk` as `notificationChannel`.
`zenDeskLogin`	`login`	The login ID of the `zenDesk` system. Required if you select `zenDesk` as notificationChannel.
`zenDeskSubdomain`	`subdomain`	The subdomain of the `zenDesk` system. Required if you select `zenDesk` as notificationChannel.
`createClient`	`true` / `false`	When this value is set to `true` and an error occurs while creating the client in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`createSearch`	`true` / `false`	When this value is set to `true` and an error occurs while creating a search for client or group in ComplyAdvantage, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`matchStatusAnalyser`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a client or a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`getClientDetails`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a client in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`getGroupDetails`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`getSearchDetails`	`true` / `false`	When this value is set to `true` and an error occurs while updating a client or a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`startStopMonitoring`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a client or a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`updateClientState`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a client in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`updateCustomField`	`true` / `false`	When this value is set to `true` and an error occurs while creating or updating a client or a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.
`updateSearch`	`true` / `false`	When this value is set to `true` and an error occurs while updating a client or a group in Mambu, a notification will be sent. If set to `false`, the error will only be stored in MPO, in the `Error Handling` state diagram.

Please Note

When notifications are set to false, or are set to true but creation of the Mambu or Zendesk ticket fails, the responses are stored in the Error Handling -[AML] state diagram for further analysis.

Mambu user setup

We strongly recommend using a role to assign permissions. This makes it easier to update permissions when more than one user account must share the same set and allows you to grant access to custom fields, transaction channels, and other parts of Mambu via the role. For more information on the differences and benefits, read our support article on understanding users, roles, and permissions.

The Mambu user will need Mambu and API access rights. You will not be able to grant API access when creating the user. To grant API access, you will have to first save the user, then open it again for editing to add API access.

To configure user permissions in the Mambu UI, go to the Administration tab, then Access, then open the Users section and click Actions > Edit for the user you want to edit. Copy the username and password, these will be needed later.

For more information, see permissions in our user guide. For managing permissions and roles via API, we also have a configuration as code endpoint. See the configuration as code for user roles article in our user guide for more information.

Necessary permissions

The minimum required user permissions for the user are:

Entity	Permissions
`Clients`	View Client Details Create Clients Edit Clients Approve Clients Reject Clients Exit Clients Blacklist Clients Undo Client State Changed Change Client Type Manage Client Association Edit Custom Field Values For Blacklisted Clients
`Groups`	View Group Details Create Groups Edit Groups Change Group Type Manage Group Association
`Tasks`	Create Tasks
`Custom Fields`	View Custom Fields Edit Custom Fields
`Branches`	View Branch Details
`Users`	View User Details

Mambu custom fields

Custom fields are used to store the results of searches as well as the search criteria used for the last search. Keeping a copy of the search criteria makes it possible for the connector to pick up any changes to a group or client so that a new search can be created in ComplyAdvantage.

Required custom fields

Create new custom fields for Clients and Groups entities to hold ComplyAdvantage AML data. You can add these custom fields to any existing standard custom field set or you can create a new one for this integration. For more information on creating custom fields via the Mambu UI, visit the custom fields article in our user guide.

Custom fields can also be created using our configuration as code APIs. This can be helpful when transferring your custom field configuration from a sandbox to production environment or vice versa. For more information on managing custom fields via API visit the custom fields configuration article in our user guide.

Create searchId, sharedUrl and clientSearchVersion/groupSearchVersion custom fields as regular text fields (Free Text).
Create matchStatus and riskLevel custom fields as selection fields (Selection).
Add the following possible values for matchStatus field:
- unknown
- no_match
- potential_match
- false_positive
- true_positive
- true_positive_approve
- true_positive_reject
Add the following possible values for riskLevel field:
- unknown
- low
- medium
- high
Add the following possible values for stopMonitoring field:
- EXITED Copy the ID of the fields and also grant access to the role created or used for your API user.

Please be Aware

When creating these custom fields you must check the Edit checkbox for the role assigned to the API user created for this connector so that data can be read and written.

Edit Rights role

Optional custom fields

If you want to store extra details about the categorization of potential_match searches in Mambu, you will need to create three additional, free text custom fields for Clients and Groups named sanctions, adverseMedia and pep. All three custom fields must be created as Standard free text fields with the Long Field option enabled.

Optional Custom Fields

After you have created the fields, copy their IDs and grant access to the role assigned to the API user created for this connector.

Client type configuration

For groups, there are two ways to provide information on the group type, depending on whether you want to use custom client types or the default ComplyAdvantage definitions of company and organisation.

If using custom group types, you will need to set up an extra custom field to hold the values expected by ComplyAdvantage. For more information on setting up client types, visit the creating a group - group types article in our user guide.

Using ComplyAdvantage default client types

If using default ComplyAdvantage values, you will need to create two new client types for the Group entity with the following ID’s: company and organisation. Group: Entity Type Group: Company Type Group: Organisation Type

Using custom client types

If using custom client types, you will need to set up an additional entityType custom field to hold the default ComplyAdvantage type definitions.

Create new client types for groups.
Create new selection custom field for groups under the same AML Standard custom field set. Copy the ID of this field and also grant access to your API user (via its role).
Add the following possible values for entityType field:
- company
- organisation

Please Note

Grant view access for all custom fields. Ensure that no roles are given edit access so that only a user with the administrator type will be able to edit these fields.
Make the entityType custom field available for custom client types for the group entity except for client types with company or organisation as the ID.

Mambu webhooks configuration

Client or group creation

Create a new Opt-Out Client/Group Created Webhook for the corresponding Target. Webhook setup:

Target	On Event	Conditions
`Clients`	Client Created	When: `searchId`, `matchStatus` and `riskLevel` are Empty
`Groups`	Group Created	When: `Group Type` equals `Company` or `Organisation` And: `searchId` and `matchStatus` are Empty
`Groups`	Group Created	When: `entityType` is Not Empty

Please Note

Only one Group Created webhook must be configured. If custom client types are added for the groups entity, then you must set up a Group Created webhook with entityType custom field. Otherwise you must create a Group Created webhook with default ComplyAdvantage values for client types. See the required JSON body for each webhook below.

Client Created webhook body:

{
    "clientId": "{RECIPIENT_ID}",
    "clientFirstName": "{RECIPIENT_FIRST_NAMES}",
    "clientLastName": "{RECIPIENT_LAST_NAME}",
    "clientEncodedKey": "{ENCODED_KEY}",
    "clientFullName": "{RECIPIENT_NAME}",
    "clientBirthYear": "FORMAT_DATE{CLIENT_BIRTH_DATE,datePattern=yyyy}",
    "clientCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}"
}

Client Created Webhook

Group Created with Entity Type custom field webhook body:

{
    "groupId": "{RECIPIENT_ID}",
    "groupEncodedKey": "{ENCODED_KEY}",
    "groupName": "{RECIPIENT_NAME}",
    "groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}",
    "aml_entityType":"{CF:GROUP:AML_ENTITYTYPE}"
}

Group Created with EntityType Webhook

Group Created webhook body:

{
    "groupId": "{RECIPIENT_ID}",
    "groupEncodedKey": "{ENCODED_KEY}",
    "groupName": "{RECIPIENT_NAME}",
    "groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}"
}

Group Created Webhook

Client or group activity

Create a new Opt-Out Client/Group Activity Webhook for the corresponding Target. For more information, please read Defining a new webhook. Webhook setup:

Target	On Event	Conditions
`Clients`	Client Activity	When: `clientSearchVersion`, `searchId` and `matchStatus` are Not Empty
`Groups`	Group Activity	When: `groupSearchVersion`, `searchId` and `matchStatus` are Not Empty And: `Group Type` equals `Company` or `Organisation`
`Groups`	Group Activity	When: `entityType` and `groupSearchVersion`, `searchId` are Not Empty

Please Note

Only one Group Activity webhook must be configured. If custom Client Types are added for Groups, then you must set up a Group Activity webhook with entityType custom field. Otherwise a Group Activity webhook with default ComplyAdvantage values for Client Types must be created. See the required JSON body for each webhook below.

Client Activity webhook body:

{
    "clientId": "{RECIPIENT_ID}",
    "clientFullName": "{RECIPIENT_NAME}",
    "aml_searchId": "{CF:CLIENT:AML_SEARCHID}",
    "clientBirthYear": "FORMAT_DATE{CLIENT_BIRTH_DATE,datePattern=yyyy}",
    "clientCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}"
}

Client Activity Webhook

Group Activity with Entity Type custom field webhook body:

{
    "groupId": "{RECIPIENT_ID}",
    "groupName": "{RECIPIENT_NAME}",
    "aml_searchIdGroup": "{CF:GROUP:AML_SEARCHID}",
    "aml_entityType": "{CF:GROUP:AML_ENTITYTYPE}",
    "groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}",
    "aml_matchStatusGroup": "{CF:GROUP:AML_MATCHSTATUS}"
}

Group Activity with EntityType Webhook

Group Activity webhook body:

{
    "groupId": "{RECIPIENT_ID}",
    "groupName": "{RECIPIENT_NAME}",
    "aml_searchIdGroup": "{CF:GROUP:AML_SEARCHID}",
    "groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}",
    "aml_matchStatusGroup": "{CF:GROUP:AML_MATCHSTATUS}"
}

Group Activity Webhook

Stop monitoring webhook

Create a new Opt-Out Client Activity Webhook for the corresponding Target. For more information, please read Defining a new webhook. Webhook setup:

Target	On Event	Conditions
`Clients`	Client Activity	When `Client State` equals `Blacklisted`, `Exited` or `Rejected` And `searchId` is Not Empty

Client Activity Stop Monitoring webhook body:

{
    "clientId": "{RECIPIENT_ID}",
    "aml_matchStatus": "{CF:CLIENT:AML_MATCHSTATUS}",
    "aml_searchId": "{CF:CLIENT:AML_SEARCHID}",
    "clientFullName": "{RECIPIENT_NAME}",
    "stopMonitoringReason": "{TRANSACTION_COMMENT}",
    "activityType": "{ACTIVITY_TYPE}",
    "clientEncodedKey":"{ENCODED_KEY}"
}

Client Activity Stop Monitoring Webhook

ComplyAdvantage search profile

More information about creating a search profile can be found in the ComplyAdvantage documentation (a password is required to access this resource).

In order to obtain a search profile ID, you can create a search profile in the ComplyAdvantage UI, and then retrive the ID as shown in the following image.

Search Profile Id

ComplyAdvantage webhooks configuration

Create a new Search Status Updated ComplyAdvantage webhook.

Search Status Updated Webhook

Two other webhooks are available in ComplyAdvantage: Match Status Updated and Monitored Search Updated. These two webhooks can also be created and enabled in ComplyAdvantage using the same endpoint as the Search Status Updated webhook.

If enabled, Match Status Updated and Monitored Search Updated webhooks will trigger the Entity Management Router process which will update aml custom fields in Mambu.

Apply Search Version

Integration Setup

MPO

Importing the connector

Configuration

ComplyAdvantage setup field description

customUpdatesClientConfig and customUpdatesGroupConfig setup field descriptions

blacklistedStatus array

blacklistedSources array

monitoredStatus array

stopMonitoringOnEvent array

reportStatus array

notification setup field descriptions

Mambu user setup

Mambu custom fields

Required custom fields

Optional custom fields

Client type configuration

Using ComplyAdvantage default client types

Using custom client types

Mambu webhooks configuration

Client or group creation

Client or group activity

Stop monitoring webhook

ComplyAdvantage search profile

ComplyAdvantage webhooks configuration

`ComplyAdvantage` setup field description

`customUpdatesClientConfig` and `customUpdatesGroupConfig` setup field descriptions

`blacklistedStatus` array

`blacklistedSources` array

`monitoredStatus` array

`stopMonitoringOnEvent` array

`reportStatus` array

`notification` setup field descriptions