Integrations

Configure integrations to receive data from external systems and use it on your B2B CRM instance.

An example of such an integration is the integration with the DaData service that allows to receive full legal name of a company after specifiying its TIN.

To configure an integration, complete the following steps:

1. Create an integration.
2. Create integration parameters.
3. Create mappings.
4. Use the data received from the integration

tip

Role required: admin, crm_admin.

Create an integration

---

To configure an integration, you need to create its record in the CRM Integration (crm_integration) table and create an integration script. To do so, complete the following steps:

1. Navigate to CRM → Parameters → Integrations.
2. Click New and fill in the fields.
3. Click Save or Save and exit.

CRM Integration form fields

Field	Mandatory	Description
Name	Y	Specify the integration name.
Table	Y	Specify the table for applying the data received from the integration. The value of this field is a unifying marker used by the system when it checks the integration responses through the handler when more than one integration is configured for a single table.
Login	N	Specify a login to authenticate in the API provider system.
Access token	N	Specify a unique user authentication key generated by the API provider.
Active	N	Select the checkbox to make the integration active.
Integration URL	N	Specify a link to the external service to be used by the system for sending the requests.
Password	N	Specify a password to authenticate in the API provider system.
Order	N	Specify the order for running this integration compared to other integrations. The lower the order, the earlier the system attempts to receive the integation parameter value through this integration compared to other integrations. It is relevant if there are mappings for the same integration parameter created for different integrations. If the integration response does not contain the required information, the system proceeds to the next integration according to the order.
Integration script	Y	Specify an integration server script.

note

The Login, Access token, Integration URL, Password fields are not mandatory since the integration mechanism may vary for different external services. Use the parameters required by your API provider.

Important information for creating the integration script:

• The current object in this context refers to the current integration record. Reference it to retrieve values from the record fields instead of hard-coding them into the script. For example, use current.getValue('integration_url') to access the Integration URL field value.
• An object called integrationOptions is passed to the integration script. It must contain the data required to make a request to the external API. The integrationOptions object is generated and sent when the new CRMIntegrationHandler handler is called in other scripts to receive the data from the integration:

  new CRMIntegrationHandler(
      'tableName' – the name of the table in which you are going to apply the data received from the integration; this value is a unifying marker for the system to check the integration responses when there is more than one integration for a single table, 
      ['full_name', 'short_name'] – the integration parameters from the crm_integration_parameter table, 
      { request_data: 'request information'} – the integrationOptions object
  );
• All potential errors occuring during an HTTP request to the external service must be considered in the integration script. You can add error descriptions for them to be displayed in the Main Log. If no errors are specified, and the integration returns an empty object or nothing, the handler will continue executing the next integration without adding a record to the Main Log.
• The integration must always return an object even if it is empty.

You can find an example of a configured integration and a working script in the DaData integration available on your instance by default.

The Mappings related list is located in the integration form and contains all mappings created for the current integration.

caution

When you delete an integration record, related mappings are deleted as well.

Create an integration parameter

---

After creating an integration, you must create parameter records in the Integration Parameter (crm_integration_parameter) table. These parameters store the data received from the integrations. To do so, complete the following steps:

1. Navigate to CRM → Parameters → Integration Parameters.
2. Click New and specify a unique Name of the parameter using which you will be able to address it in scripts.
3. Click Save or Save and exit.

Repeat steps 1-3 for each parameter that you want to receive through the integration.

Create a mapping

---

After defining the parameters, add records to the Mapping (crm_mapping) table to associate external API properties with the corresponding parameters. To do so, complete the following steps:

1. Navigate to CRM → Parameters → Mappings.
2. Click New and fill in the fields.
3. Click Save or Save and exit.

Mapping form fields

Field	Mandatory	Description
External API property	Y	Specify a key from the integration API response to which the selected integration parameter corresponds.
Integration parameter	Y	Specify an integration parameter for which you create the mapping.
Active	N	Select the checkbox for the system to use this mapping.
Use processing script	N	Select the checkbox to create a script that will process the data received from the external API. Use this option if you need to change the format of the received data before using it on your instance.
Processing script	N	Create a server script for the system to process the data. The script must return a processed value.
Integration	Y	Specify an integration for which you create the mapping. Note that the same parameter may be mapped through more than one integration. In this case, create a separate mapping record for each integration.

Use integrations

---

Once the integration is configured, you can use the data received from it in your scripts. To do so, call the CRMIntegrationHandler handler.

The script below sets logic for the business rule that automatically completes the Full name field of the Customer Company table when the TIN value is specified:

Example of a script using an integration

  (function executeRule(current, previous = null /*not null only when action is update*/) {
    /*global CRMIntegrationHandler: readonly*/
    ss.importIncludeScript('CRMIntegrationHandler');
    const integrationHandler = new CRMIntegrationHandler('crm_customer_company', ['full_name'], { tin: current.getValue('inn') });
    const integrationsData = integrationHandler.getData();

    if (Object.hasOwn(integrationsData, 'full_name')) {
        current.setValue('full_name', integrationsData.full_name);
        return;
    }

    current.setValue('full_name', '');
  })(current, previous);