Integration Setup
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
andGroup
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.
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
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.
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
andclientSearchVersion
/groupSearchVersion
custom fields as regular text fields (Free Text
). - Create
matchStatus
andriskLevel
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.
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.
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
.
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 AMLStandard
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 withcompany
ororganisation
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}"
}
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
webhook body:
{
"groupId": "{RECIPIENT_ID}",
"groupEncodedKey": "{ENCODED_KEY}",
"groupName": "{RECIPIENT_NAME}",
"groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}"
}
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 EmptyAnd: 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}"
}
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
webhook body:
{
"groupId": "{RECIPIENT_ID}",
"groupName": "{RECIPIENT_NAME}",
"aml_searchIdGroup": "{CF:GROUP:AML_SEARCHID}",
"groupCountryCodes": "{RECIPIENT_ADDRESS_COUNTRY}",
"aml_matchStatusGroup": "{CF:GROUP:AML_MATCHSTATUS}"
}
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}"
}
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.
ComplyAdvantage webhooks configuration
Create a new Search Status Updated
ComplyAdvantage 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.