onValidateAssociatedRecords
This callback allows you to specify a validation procedure for associated CRM records with interaction which would be linked with the activity record. When interaction is about to be completed, Communicator Widget sends this event in order to validate a set of CRM records associated with that interaction (agent can select any visited records in the widget's UI for activity). If your integration requires specific rules for a set of records to be valid for activity history, you will want to implement that logic in this callback handler. If you don’t provide a handler for this event, then any set of CRM records will be accepted as valid.
The handler must return a RecordsValidationResult object: if valid is true, the set of records will be accepted and the process of interaction completion will continue; if valid is false, the process will be aborted and the agent will be asked to change the selection.
Request
Syntax
| on('ON_VALIDATE_ASSOCIATED_RECORDS', handler: OnValidateAssociatedRecordsHandler): void
type InteractionAssociatedObjectsData = { list: InteractionAssociatedObject[] selected: string[] } type InteractionAssociatedObject = { id: string type: string displayName: string displayType: string customFields: Record<string, string> } type RecordsValidationResult = { valid: boolean message?: string } |
Parameters
| Parameter | Parameter Values | Data Type | Optional/Required | Description |
| interactionId | string | Required | ID of the interaction which these records are associated with. | |
| records | object | Required | Data about visited and selected CRM records | |
| list | object[] | Required | List of all visited CRM records during the interaction | |
| selected | string[] | Required | List of CRM records ID (selected from the list above) which the agent selected as associated for activity history records. This is a set of records which needs to be validated. | |
| InteractionAssociatedObject | object | Optional | Data about one object associated with that interaction | |
| id | string | Required | Record's unique ID | |
| type | string | Required | Type of the record (contact, case, task, etc.) | |
| displayName | string | Required | Display name of the record | |
| displayType | string | Required | Display type of the record | |
| customFields | object | Required | Any additional information about the record |
Example Request
// Example validation by rules that valid selection is 1 case + 1 contact or nothing selected.
adApi.on("ON_VALIDATE_ASSOCIATED_RECORDS", (interactionId, records) => {
// It’s valid if nothing is selected
if (!records.selected.length) {
return { valid: true }
}
// If not 2 records are selected - not valid
if (records.selected.length !== 2) {
return { valid: false, message: "Please select exactly one case and one contact." }
}
const firstRecord = records.list.find(record => {
return record.id === records.selected[0]
})
const secondRecord = records.list.find(record => {
return record.id === records.selected[1]
})
// Check just for type-safety
if (!firstRecord || !secondRecord) {
return { valid: false, message: "Selected records not found." }
}
// Final check: one record should be "case", one record should be "contact"
if (
(firstRecord.type === "case" && secondRecord.type === "contact") ||
(firstRecord.type === "contact" && secondRecord.type === "case")
) {
return { valid: true }
} else {
return { valid: false, message: "Please select exactly one case and one contact." }
}
})
Return Value
| Object | Object Values | Data Type | Optional? (Y/N) | Value Description |
| RecordsValidationResult | object | Validation result | ||
| valid | boolean | Indicates the result of validation procedure | ||
| message | string | Y | If validation is not passed, you can provide an explanation message which will be displayed in the widget UI |