Custom integration hub for API and events

This article explains how to use the custom integration hub for configuring settings that are essential for using the Lightico API and consuming events.

For full documentation of Lightico API and events, see Lightico developer center.

You can find the Custom hub on the Built-in integrations tab of the Integrations page in the Lightico admin center.

Note

If you are looking to create a custom integration with an external service, please go to Build a custom integration.

Overview

The main sections in this article are as follows:

• Set up a custom integration hub

• Generate API credentials

• Map fields in your app to Lightico Attributes

• Define event destinations (webhooks)

Set up a custom integration hub

1. In the admin center left navigation panel, click Integrations.
   
   The Integrations page opens.

2. Under Add New Integration, click Custom.
   
   
   The Custom integration hub opens.

3. Enter a Name (only lower case letters and underscores) and a Description for this hub.

4. Click Save.
   The Lightico Integration hub is set up and activated.

Generate API credentials

Before sending an endpoint from your system to Lightico, you’ll need to generate credentials for authorization purposes.

To generate API credentials:

1. In the custom integration hub, click Generate API Credentials.
   
   You are prompted to enter your Lightico login credentials.

2. Enter your Lightico Username and Password and click Apply.
   
   
   The API credentials appear.

3. Click Save.
   

Note

Take note of the Client ID and API Key, for authenticating API calls.

Tips

• To see the API Key, you'll need to provide your Lightico login credentials.

• For the API Password, you'll need to click the refresh button, enter a new password, and use this new one in your system.

Map fields to Attributes

Mapping fields from your app/platform to Lightico Attributes enables you to do the following:

• Fill in digital forms and PDFs with pre-existing data from your platform.

• Use your data to affect conditional actions in Workflows.

• Update fields in your app with the data obtained during a session.

• Enhance intelligent document analyzing.

Note

Field mapping is only supported when creating a session using the API and not with a session initiated by an agent from the collaboration room. See Defining a data source below.

Methods of field mapping

There are two ways to map fields. You can choose one or the other, depending on your needs:

• Dynamic mapping - for collaboration session endpoints.

• Schema mapping - for Document Analyzer endpoints.

Defining a data source

By default, Lightico identifies data in a session by its Attribute name. If you have mapped your fields to Lightico Attributes, you need to let Lightico know that you want your field names to be the source of the data/field names. Lightico will then translate data coming from your app into Attribute names that can be used in the session.

This is done using one of the following API endpoints, depending on what type of action you are performing:

• Adding Dynamic Workflow v28.1 - in the Set Attributes for a session endpoint, enter the custom hub name in the source parameter
  

• Adding Workflow template - In the Create new session endpoint enter the custom hub name  in the sourceName parameter
  

• Starting document analysis - In the Create document analysis endpoint enter the custom hub name in the sourcename parameter

Define the value of the source or sourceName parameter as the name of the custom integration hub where you configured the field mapping.

For example:

"sourceName": "my_custom_mapping_hub"

Define event destinations

Events are Lightico's way of letting you know when something significant occurs in your Lightico account and providing you with information about that occurrence. See Events in the Lightico developer center for an explanation of all events. Each type of event notification can be sent to a different destination URL (webhook). In the integration hub, you can  define a URL for each of the different events.

Warning

Lightico permits the use of client-controlled endpoints for integration purposes. Please be aware that Lightico reserves the right to remove any endpoints that utilize free or open webhook site services. This measure is in place to ensure the security of callback data.

To configure event destinations:

1. Open the Events tab in your API integration hub. This tab shows all supported Lightico API events.

2. Click Expand All and enter a URL and, where applicable, a Username and Password for each event.

3. You can click Test Connectivity to verify that each event URL is valid.
   

   Event destinations are configured.

Send events to multiple destinations

If you need to send events to multiple URLs, you can create more than one API integration hubs and define different webhooks for each one.  Each event will be sent to all defined URLs.

Send events to specific destinations

If you need events for a session to be sent to the webhooks in only one of your configured hubs, you can do so using one of these endpoints:

• For a session - v21.1 Create new session
  

• For dynamic Workflows - v28.1 Create new session

• For Workflow templates - v21.3 Add Workflow template to a session
  

In the hubs object, define events and the name of the hub with the relevant webhooks.

For example,

"hubs": {

   "events": "hub_2"

}