The Integration Builder feature allows you to create new custom integrations for products in real-time. Only users with the Global Admin and LMS Admin system roles have access to view and manage the Integration Builder feature.
Note: This feature is available only upon request and currently works only for the LMS Products. The Integration Builder requires a certain level of expertise in coding languages as it is primarily designed for developers.
To access the Integration Builder, go to the Client Management > Setup > Integration Builder section.
The Integration Builder section contains the following information:
ID: The unique identification number of the custom integration.
Name: The name of the integration.
Status: The status of the integration (Active / Disabled).
Product: The name of the Product
Created: The date and time when the integration was created.
Updated: The date and time when the integration was last updated.
You can narrow down the search results by using the following filters:
Name: Enter the name of the integration.
Status: Select the status of the integration (Active / Disabled).
Product: Select the Product.
To create a new custom integration, click the “Add new record” button and fill in the following fields in the pop-up window:
Type: Select the type of integration (New / Import).
Select the “New” option to create a new integration.
Select the “Import” option to upload a file with custom integration created in Integration Builder in JSON format.
Name: Enter the name of the integration.
Product: Select the Product.
Click the “Add” button to create the integration.
To create a new integration based on an existing custom one, click the “Clone” button in the “Actions” column of the corresponding integration. Enter a name for the new integration in the pop-up window and click the “Clone” button to confirm.
To download the integration in JSON format, click the “Export” button in the “Actions” column of the corresponding integration.
To configure the integration, click the “Configure” button in the “Actions” column of the corresponding integration, and the system will redirect you to the “Builder” setup page. Use the following tabs to configure or update the integration.
General Tab
The General tab allows you to view the general information about the integration and change its name and status.
Integration Name: Enter the new name for the integration or leave it as it is.
Product name: The name of the Product for which the integration was created.
Post model: The type of the Product.
Date updated: The date and time of the last update of the integration.
Status: The status of the integration (Active / Disabled).
Save campaign ID to Lead Stash: Check this box to save the campaign ID to the Lead Stash(e.g., for Ping Post Calls flows).
Click the “Save Integration” button to save changes.
Integration Config Tab
The Integration Config tab allows you to configure the integration parameters displayed on the “Integration” tab of the Campaign settings. These parameters can be later configured from the “Integration” tab directly, without updating the integration. You can add an unlimited number of parameters. If you need to remove any of the parameters, at least one parameter should be present. Example: The Redirect integration contains the “Redirect URL” parameter allowing you to add the redirect link on the “Integration” tab.
The Integration Config tab contains the following settings:
Variable Name: The name of the parameter. It should be unique and not match any existing parameter. The first character should be in lowercase.
Label: The name of the parameter displayed on the “Integration” tab.
Type: Select the “String” option to set the field type as string (allows letters, numbers, and special symbols). The “Select” option sets the field type as select with configurable values for selection (Value / Label).
Required: Select the “True” option to set a required field. Select the “False” option to set a non-required field. You cannot perform a Request Test or a Response Test unless you fill out the values for config fields you have indicated as “Required”.
To add more parameters, click the “Add new” button.
Note: Any changes made to the Integration Config fields will affect the running integration. After you apply the changes, you must review and update the integration settings of the previously set-up campaigns to ensure successful processing.
Mapping Tab
The Mapping tab allows you to configure the variable mapping that can be used in the Request mapping. The list contains all the variables available for the mapping based on the selected Product.
Select the variable from the drop-down list and click the “Add Mapping” button to edit the mapping for the selected variable.
Click the “+” button for the selected variable to display the mapping configuration block.
The configuration block contains the following setting fields:
Slug: The name of the parameter. The name should be unique and not match any existing parameters.
Label: The parameter value received. The default value is used if no value is received.
Mapping: The value that will be mapped to the received value and sent in the request. Values are case-sensitive and should match integration requirements.
Once the Mapping is configured, you can refer to this mapping in the Request Mapping tab.
Request Mapping Tab
The Request Mapping tab contains the integration request settings and allows you to configure the request.
If you have selected the Ping Post Product, the block contains the “PING” and the “POST” settings blocks of the same structure.
The following settings are available in the Request Mapping tab:
Request::Url: The post URL. The default {{ config.url }} value corresponds to the variable added by default on the Integration Config tab.
Method Type: Select the posting method type for the request.
For the “GET” type, fill in the additional parameters of the request in the Headers and Query Params blocks.
For the “POST” type, configure the Data Type block of settings.
Select the “Fake Ping” (the REQUEST BUILDER (PING) block only) for the integration builder interface to work as for the direct post integrations.
Headers and Headers/Query Params: If the integration documentation contains Headers or Headers/Query Params, you can configure it here. The value type of the fields is Key:Value.
In the Data Type field, select the data format for the request (XML, JSON, FORM, None). Depending on the selected data type (XML/JSON/FORM), there are different configuration settings available:
The XML data type.
Click the “Import By Sample” button to import the XML sample of the request. The Builder will fetch and add configured fields for further review and editing. The XML configuration:Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
Type: Select the data type (Object / String).
Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Please note that the value field supports Twig.
The JSON data type.
Click the “Import By Sample” button to import the JSON sample of the request. The Builder will fetch and add configured fields for further review and editing. The JSON configuration:Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
Type: Select the data type (Object / Array / Boolean / String Number / NULL).
Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Note: The value field supports Twig.
The FORM data type.The FORM configuration:
Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
Type: The data type (String).
Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Please note that the value field supports Twig.
Depending on the field and API documentation, "Value" fields can be hardcoded, mapped, or passed from the config or lead.
For the Ping Post Integrations, it is possible to reuse the values from the Response PING block for the Request POST block.
The Request Mapping tab allows creating conditions using the “Condition” parameter. The “Condition” allows you to manage the parameters sent in the request. Please note that the “Condition” field supports Twig.
Example: We have a “driver” object, and we do not want to include the “driver1” object into parameters if it doesn’t match the required age. If the condition is {{ lead.driver1Age }} < 18, then the request will not contain the parameters for the “driver1” object as it does not match the requirements. Therefore, if the condition is {{ lead.driver1Age }} > 18, then the request will contain the object’s parameters.
Response Mapping Tab
The Response Mapping tab allows you to configure the response processing. The Response Mapping settings should be based on the response details provided in the integration documentation. The Response Mapping fields support Twig.
To set up the response configuration, fill in the following fields:
Data Type: Select the data processing format (XML / JSON / PLAIN).
Accept::Sign: The condition that defines if the lead was accepted.
Accept::Price: The field that records the offer price (if received).
Sold::Sign: The condition that defines if the lead was sold.
Sold::Price: The field that records the price (if received).
Sold::RedirectUrl: The field for the redirect link (if received).
Reject::Sign: The condition that defines if the lead was rejected. If the condition states the “is defined” option, all statuses will be processed as rejected.
Reject::Reason: The field that records the reason for the reject.
Error::Reason: The field that records the reasons for all other errors.
Note: The response configuration fields support Twig.
If the integration is set for the Ping Post Product, the PING and POST blocks of settings are available.
Note: If you select the “Fake Ping” option on the Request Mapping tab, the RESPONSE BUILDER (PING) settings block is not available.
Both blocks have the same structure, but only the Response PING block can process and reuse the values received in the response. To configure it, in the “Optional Lead Variables” block, fill in the variable name in the “Variable Name” field. Fill in the processed value in the “Expression” field. You can later use this value in the Request Builder for POST - {{ pingResponse.promise_id }}.
Note: The Response Builder setup might require some coding knowledge to analyze the response of the buyer system.
You can find the configured Response Mapping example on the screenshot below:
The example of a JSON response:
The “sold” status is displayed in the global object key “status” with the “sold” value. The “Sold::Sign” field depends on the received status (for example, if we set the response.status == “sold” value, it will define if the lead is sold or not.
For the “price” parameter, we put the value received in the response of the sold lead. As the “price” parameter is inside another object, we put the “response.price.unitValue” value.
For the “redirectUrl” - response.redirectUrl.
An example of a response for an invalid request:
If the lead is rejected, the “status” parameter displays the “400” value. There can also be other responses, including the authorization error or any other error, but the Response Builder provides an option only for the rejected status. That is why we put in the “response.status is defined” value into the “Reject::Sign” field - which means that all the received statuses will be processed as rejected, except for the “sold” status as it already has a condition set up.
Then we set the “response.title” value for the “Reject::Reason” field.
The response might not contain the price, redirectUrl, or errors in some cases. In this case, the corresponding fields should be left blank.
Testing Tab
The Testing tab allows you to emulate the test of the created integration.
The tab contains the fields added on the Integration Config tab. To run the test, first, fill in those fields. Note: Only those fields defined as required must be filled in with dummy data. Optional fields can be left blank.
To check the correct sending of the Request, click the “Perform Test” button in the “Request Preview” block. The Request Test allows checking if the request is formed correctly after Request Builder variables have been configured.
To check the correct processing of the Response, enter the data in JSON or XML format from your Integration Documentation and click the “Perform Test” button in the “Response Check” block. Note: The PING response needs to result in a sale for the test to proceed to the POST response test.
Note: If the integration is set for the Ping Post Product and the “Fake Ping” option on the “Request Mapping” tab is selected, the REPONSE CHECK block will contain the response status fields for the direct post only.
Logs Tab
The Logs tab allows you to view the changes and compare all the previous backup versions of the Integrational Builder events stored in the system.
The list of logs contains the following information:
Created: The date and time when the integration builder event was created.
Name: The name of the integration builder event.
User: The user who initiated the integration builder event.
Type: The type of the integration builder event (Log, Restore).
Diff: The versions comparison.
New Schema: The new code schema.
Old Schema: The old code schema.
You can narrow down the search results by using the following filters:
Created Date: Select the date of creation (Any time, Last six months, Today, Yesterday, This Week, Last Week, This Month, Last Month, Custom Range).
Type: Select the type (Log, Restore).
Integration: Select the integration.
User: Select the user.
To compare the versions of the integration builder event, click the “Diff” button in the “Actions” column. The blocks will be loaded automatically. All the changes are highlighted in yellow, and all the new records are highlighted in green.
To restore the previously saved backup version of the integration builder event, click the “Restore” button. Also, the “Restore” button is available in the corresponding event in the “Actions” column.
In the “Restore to this version” popup window, enter the “Yes” word and click the “Restore” button to confirm the action.
Note: The Restore event will be logged and displayed if “Restore” was done by a user.