Integration Setup

MPO

Importing the connector

  1. Log in to your Mambu Process Orchestrator (MPO) UI environment. Select Create from the left-hand menu and click From file. MPO. File import
  2. 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.
  3. 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.
  4. Navigate to Aliases tab and press the Create button. MPO. Aliases tab
  5. Create a new Alias and link the process from the AML Entity Translator folder. MPO. Create alias
  6. Open the MPO process from AML Entity Translator folder and add JavaScript code based on the client business for Client and Group code node. MPO. Update code node
  7. Add JavaScript support for the rest of the parameters as in the table below:
Parameter NameEntityDetails
data.client.fullNameClientFormat = string; concatenates data.client.firstName, data.client.middleName, data.client.lastName
data.client.birthYearClientFormat = 4 digits.
data.client.countryCodesClientFormat = 2 letters.
data.client.searchVersionClientField stores the criteria on which the last search was made for a client.
data.group.groupNameGroupFormat = string; remove white spaces.
data.group.countryCodesGroupFormat = 2 letters.
data.group.entityTypeGroupExtracted value from Mambu custom field or from Mambu group entity type; allowed values: Company or Organisation.
data.group.searchVersionGroupField 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

NameTypeValue
complyAdvantageRemoveDeceasednumber0 or 1. When set to 1 deceased people are removed from search results
complyAdvantageShareUrlnumber0 or 1. When set to 1 a shareable URL to access search publicly is included and populated to a Mambu custom field.
complyAdvantageFuzzinessnumber (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.
complyAdvantageExactMatchbooleanWhen 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.
complyAdvantageSearchProfilestringThis 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 nameValue
customUpdatesClientConfigno_match,
false_positive,
unknown,
true_positive,
potential_match,
true_positive_reject,
true_positive_approve

blacklistedSources array

Object nameValue
customUpdatesClientConfigmatched_source_PEP,
matched_source_AMedia,
matched_source_sanctions

monitoredStatus array

Object nameValue
customUpdatesClientConfig and customUpdatesGroupConfigno_match,
false_positive,
unknown,
true_positive,
potential_match,
true_positive_reject,
true_positive_approve

stopMonitoringOnEvent array

Object nameValue
customUpdatesClientConfigexitedClient,
blacklistedClient,
rejectedClient
customUpdatesGroupConfigexitedGroup

reportStatus array

Object nameValue
customUpdatesClientConfig and customUpdatesGroupConfigno_match,
false_positive,
unknown,
true_positive,
potential_match,
true_positive_reject,
true_positive_approve

notification setup field descriptions

NameValueDescription
notificationChanneltask / zenDesk / URLThe system of choice for receiving notifications.
defaultTaskAssigneeKeyencodedKeyThe encoded key of the default Mambu user for task notification. Required if you select task as notificationChannel.
webhookAPIKeyapiKeyThe API key of the system used to receive notifications via webhook. Required if you select URL as notificationChannel.
webhookUrlurlThe URL of the selected URL system. Required if you select URL as notificationChannel.
zenDeskAPIKeyapiKeyThe API key of the zenDesk system. Required if you select zenDesk as notificationChannel.
zenDeskGroupIdgroupIdThe group ID of the zenDesk system. Required if you select zenDesk as notificationChannel.
zenDeskLoginloginThe login ID of the zenDesk system. Required if you select zenDesk as notificationChannel.
zenDeskSubdomainsubdomainThe subdomain of the zenDesk system. Required if you select zenDesk as notificationChannel.
createClienttrue / falseWhen 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.
createSearchtrue / falseWhen 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.
matchStatusAnalysertrue / falseWhen 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.
getClientDetailstrue / falseWhen 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.
getGroupDetailstrue / falseWhen 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.
getSearchDetailstrue / falseWhen 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.
startStopMonitoringtrue / falseWhen 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.
updateClientStatetrue / falseWhen 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.
updateCustomFieldtrue / falseWhen 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.
updateSearchtrue / falseWhen 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

Log in to your Mambu UI environment. Create a user for MPO and grant necessary permissions or a role.

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:

EntityPermissions
ClientsView 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
GroupsView Group Details
Create Groups
Edit Groups
Change Group Type
Manage Group Association
TasksCreate Tasks
Custom FieldsView Custom Fields
Edit Custom Fields
BranchesView Branch Details
UsersView 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). Client Custom Fields
    Group Custom Fields
  • 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.

  1. Create new client types for groups. Client Types for Groups
  2. 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).
  3. Add the following possible values for entityType field:
    • company
    • organisation Group: Entity Type Custom Field

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:

TargetOn EventConditions
ClientsClient CreatedWhen: searchId, matchStatus and riskLevel are Empty
GroupsGroup CreatedWhen: Group Type equals Company or Organisation
And: searchId and matchStatus are Empty
GroupsGroup CreatedWhen: 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:

TargetOn EventConditions
ClientsClient ActivityWhen: clientSearchVersion, searchId and matchStatus are Not Empty
GroupsGroup ActivityWhen: groupSearchVersion, searchId and matchStatus are Not Empty
And: Group Type equals Company or Organisation
GroupsGroup ActivityWhen: 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:

TargetOn EventConditions
ClientsClient ActivityWhen 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.