☰

Integration Setup

Jump to Section

Connector Installation and configuration

  1. Log in to your Mambu Process Orchestrator (MPO) UI environment. Press the Create button and select the From file option. MPO. File import
  2. Upload the JSON file for the AML connector with the pre-integration templates. 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. 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

  • 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 based on which the last search was made;
data.group.groupNameGroupformat = string; remove white spaces
data.group.countryCodesGroupformat = 2 letters;
data.group.entityTypeGroupshould be extracted from Mambu Custom Field or from Mambu Group Entity Type; allowed values: Company or Organisation
data.group.searchVersionGroupfield stores the criteria based on which the last search was made;

Notes: You may validate the input data and generated fields in the code node to avoid errors in downstream processes and any thrown errors from the code node will be logged in the connector and may help with troubleshooting.

  1. Open the Setup process from AML Screening and Monitoring vX.X (YYYY-MM-DD) folder, switch to View mode and press New task. Fill all the parameters and click Add task. Wait until the task is processed (moves to the final point).
    MPO. Setup
    Alternatively, the following JSON data can be used as Setup. 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"
        ]
},
    "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
            }
        ]
    },
    "complyAdvantageAccessKey": "njV5SXDZGGdAgcRwApFBCRQ8g533YMi3",
    "complyAdvantageExactMatch": false,
    "complyAdvantageFuzziness": 0.7,
    "complyAdvantageRemoveDeceased": 0,
    "complyAdvantageShareUrl": 1,
    "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,
    "createUpstreamBlacklistedClient": true,
    "matchStatusAnalyser": true,
    "getClientDetails": true,
    "getGroupDetails": true,
    "getSearchDetails": true,
    "startStopMonitoring": true,
    "updateClientState": true,
    "updateCustomField": true,
    "updateSearch": true,
    "webhookAPIKey": "",
    "webhookUrl": "",
    "zenDeskAPIKey": "",
    "zenDeskGroupId": "",
    "zenDeskLogin": "",
    "zenDeskSubdomain": ""
}
  • Possible values and meaning for ComplyAdvantage Setup fields:
NameTypeValue
complyAdvantageRemoveDeceasednumber0 or 1 => when set to 1 = Removes deceased people from search results
complyAdvantageShareUrlnumber0 or 1 => when set to 1 = Includes a shareable URL to access search publicly (Mambu custom field is populated with the URL)
complyAdvantageFuzzinessnumber (float)Between 0.0 - 1.0 => Determines how closely the returned results must match the supplied name (overridden by complyAdvantageExactMatch). For example, 0.0 fuzziness disables 1 letter typo matching but keeps all other standard and optional matching behaviours
complyAdvantageExactMatchbooleantrue or false => when set to true = Disables all standard and optional matching behaviours (Honorifics, affixes, initials, glued name, name variation, equivalent names, extra words in entity,…). In other words, when set to true, the complyAdvantageFuzziness property is disabled.
  • Possible values and meaning for customUpdatesClientConfig and customUpdatesGroupConfig Setup fields:
    • 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
      customUpdatesClientConfigexistedClient,
      blacklistedClient,
      rejectedClient
    • reportStatus array
      Object nameValue
      customUpdatesClientConfig and customUpdatesGroupConfigno_match,
      false_positive,
      unknown,
      true_positive,
      potential_match,
      true_positive_reject,
      true_positive_approve

Notes:

  • A notification is sent only if the value is set to true in the Notification Setup.
  • When notifications are set to false or are set to true but the Mambu or Zendesk ticket fails, the responses are stored in Error Handling -[AML] state diagram in order to be analyzed.

Mambu Setup

User permissions

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.

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

Note:
The Mambu user should have Mambu and API access rights.

The minimum required user permissions to use the connector 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
  1. Log in to your Mambu UI environment. Create a user for MPO and grant necessary permissions or a role. Copy username and password.

Custom fields

  1. Create new custom fields for Clients and Groups entities for storing ComplyAdvantage AML data.

    • Create searchId, sharedUrl and clientSearchVersion/groupSearchVersion custom fields as regular text fields (Free Text). You can add these custom fields to any existing Standard Custom Field Set or you can create a new one (Standard type). Copy the ID of these fields and also grant access to your API user (via its role).
      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


    Edit Rights role

  2. [Optional] In case you want to store in Mambu details regarding the categorization of potential_match search, create three additional custom fields as Free Text for Clients and Groups: sanctions, adverseMedia and pep. All three custom fields should be created as Standard text fields (Free Text) with Long Field option enabled. Copy the ID of these fields and also grant access to your API user (via its role).
    Optional Custom Fields

  3. Only for Groups

    i. Configuration for Client Types with entityType custom field

    • Create new Client Types for Group entity.
      Client Types for Groups
    • Create new selection custom field for Groups entity 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
      Group: Entity Type Custom Field

    Notes:

    • Grant View access for all custom fields (only an Admin user should be able to edit these fields);
    • Custom field entityType should be available only for custom Client Types for Groups entity (exception: client types with ID’s: company and organisation);

    ii. Configuration for Client Types with ComplyAdvantage default values

    • Create two new Client Types for Group entity with the following ID’s: company and organisation. Group: Entity Type Group: Company Type Group: Organisation Type

Mambu Webhooks Configuration

  1. Create new Opt-Out Client/Group Created Webhook for the corresponding Target. Wehbook 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

Note: Only one Group Created webhook must be configured based on the chosen configuration from Step 4. If custom Client Types are added for Groups entity, then Group Created webhook with entityType custom field should be set up, otherwise Group Created webhook with default ComplyAdvantage values for Client Types should be created.

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 (applies for Configuration 4.1):

{
"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 (applies for Configuration 4.2):

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

Group Created Webhook

  1. Create new Opt-Out Client/Group Activity Webhook for the corresponding Target. 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

Notes: Only one Group Activity webhook must be configured based on the chosen configuration from Step 4. If custom Client Types are added for Groups entity then Group Activity webhook with entityType custom field should be set up, otherwise Group Activity webhook with default ComplyAdvantage values for Client Types should be created.

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 (applies for Configuration 4.1):

{
"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 (applies for Configuration 4.2):

{
"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

  1. Create new Opt-Out Client Activity Webhook for the corresponding Target. Webhook setup:
TargetOn EventConditions
ClientsClient ActivityWhen: Client State equals: Blacklisted, Existed 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 Webhooks Configuration

Create new Search Status Updated ComplyAdvantage webhook .

Search Status Updated Webhook

Notes:

  • Two other webhooks are available in ComplyAdvantage: Match Status Updated and Monitored Search Updated. These two webhooks can also be created and be enabled in ComplyAdvantage using the same Endpoint as for Search Status Updated webhook.
  • If enabled payload for Match Status Updated and Monitored Search Updated webhooks will be just stored in a MPO state diagram.