XM Discover Link Inbound Connector

About the XM Discover Link Inbound Connector

You can use the XM Discover Link Inbound Connector to push XM data into XM Discover via a REST API endpoint while leveraging all the capabilities offered by the Connectors framework, such as fields mapping, transformations, filters, job watching, and so on.

Supported Data Formats

The following data types are supported in JSON format only:

• Individual feedback
• Digital interactions
• Call transcripts

Before setting up the connector, create a sample file that represents the fields you’d like to import into XM Discover. See the linked pages above for more information about the required fields and file formats.

There are also template files available to download within the connector for specific data formats:

• Chat
  • Chat (default): Use for standard digital interactions data.
  • Amazon Connect: Use for digital interactions specific to Amazon Connect Chat.
• Call
  • Call (default): Use for standard call transcripts data.
  • Verint: Use for call transcripts specific to Verint.
• Feedback
  • Dynamics 365: Use for Microsoft Dynamics data.

Creating an XM Discover Link Inbound Connector Job

1. In the Jobs tab, click New Job.
   
2. Click the XM Discover Link job.
   
3. Give your job a name so you can identify it.
   
4. Choose the project to load data into.
5. Give your job a description so you know its purpose.
6. Click Next.
7. Choose your authorization mode, or how you’ll connect to XM Discover:
   
   • API Key: Connect using an XM Discover API token.
   • OAuth 2.0: Connect using a Client ID and Client Secret provided by the XM Discover authentication service. Contact your XM Success Manager to request this method.
8. Click Next.
9. Choose your data format: chat (digital), call, or feedback.
   
10. If desired, choose a template and then click the here link to download the template file.
11. Enter the JSON path to a subset of JSON that contains document nodes. Leave this field empty if the documents are located at the root node level.
12. Click the Click To Select File For Upload button and choose the sample file on your computer.
13. A preview of the file will appear. If you see an error message or raw file contents instead of the preview, there may be a problem with the data format options you selected. See the Sample File Errors page for help troubleshooting your file.
14. Click Next.
15. If needed, adjust your data mappings. See the Data Mapping support page for detailed information on mapping fields in XM Discover. The Default Data Mapping section contains guidance specific for this connector.
    
16. Click Next.
17. If desired, you can add data substitution and redaction rules to hide sensitive data or automatically replace certain words and phrases in customer feedback and interactions. See the Data Substituion and Redaction support page for more information.
    
18. Click Next.
19. If desired, you can add a connector filter to filter the incoming data to limit what data is imported.
    
20. Click Next.
21. Choose how duplicate documents are handled. See Duplicate Handling for more information.
    
22. Click Next.
23. Review your setup. If you need to change a specific setting, click the Edit button to be brought to that step in the connector setup.
    
24. The API Documentation link contains your API endpoint, which will be used to send data to XM Discover. See Accessing the API Endpoint for more information.
25. Click Finish to save your setup.

Default Data Mapping

This section contains information on the default fields for XM Discover Inbound Link jobs.

When mapping your fields, the following default fields are available:

• feedback_type: Feedback type helps you to identify data based on its type. This is useful for reporting when your project contains different types of data (for example, surveys and social media feedback). This field is editable. By default, this attribute’s value is set to:
  • “call” for call transcripts
  • “chat” for digital interactions
  • “feedback” for individual feedback
  • You can use custom transformation to set a custom value.
• source: Source helps you to identify data obtained from a specific source. This can be anything that describes the origin of data, such as the name of a survey or a mobile marketing campaign. This field is editable. By default, this attribute’s value is set to “XM Discover Link.” You can use custom transformation to set a custom value.
• richVerbatim: This field is used for conversational data (such as call and chat transcripts) and is not editable. XM Discover uses a conversational verbatim format for the richVerbatim field. This format supports ingestion of dialogue-specific metadata required to unlock conversational visualization (speaker turns, silence, conversational events and so on) and enrichments (start time, duration and so on). This verbatim field includes “child” fields to track the client’s and representative’s side of the conversation:
  • clientVerbatim tracks the client’s side of the conversation.
  • agentVerbatim tracks the representative’s (agent’s) side of the conversation.
  • unknown tracks the unknown side of the conversation.
• Qtip: Transformations are not supported for conversational verbatim fields. The same verbatim cannot be used for different types of conversational data. If you want your project to host several types of conversation, use separate pairs of conversational verbatims per conversation type.
• clientVerbatim: This field is used for conversational data and is editable. This field tracks the client’s side of the conversation in call and chat interactions. By default this field is mapped to:
  • clientVerbatimChat for digital interactions.
  • clientVerbatimCall for call interactions.
• agentVerbatim: This field is used for conversational data and is editable. This field tracks the representative’s side of the conversation in call and chat interactions. By default this field is mapped to:
  • agentVerbatimChat for digital interactions.
  • agentVerbatimCall for call interactions.
• unknown: This field is used for conversational data and is editable. This field tracks the unknown side of the conversation in call and chat interactions.By default this field is mapped to:
  • unknownVerbatimChat for digital interactions.
  • unknownVerbatimCall for call interactions.
• document_date: Document date is the primary date field associated with a document. This date is used in XM Discover reports, trends, alerts, and so on. For document date, choose one of the following options:
  • conversationTimestamp (for conversational data): Date and time for the entire conversation.
  • If source data contains other date fields, you can set one of them as document date by selecting it from the dropdown menu in the Field Name.
  • You can also set a specific date by adding a custom field.
• natural_id: Natural ID serves as a unique identifier of a document and allows processing duplicates correctly. For natural ID, choose one of the following options:
  • conversationId (for conversational data): A unique ID for the entire conversation.
  • Select any text or numeric field from your data in the Field Name.
  • Automatically generate IDs by adding a custom field.
• feedback_provider: Feedback provider helps you to identify data obtained from a specific provider. For XM Discover Link uploads, this attribute’s value is set to “XM Discover Link” and cannot be edited.
• job_name: Job name helps you to identify data based on the name of the job used to upload it. You can modify this attribute’s value in the Job Name box at the top of the page or using the job options menu.
• loadDate: Load date indicates when a document was uploaded into XM Discover. This field is set automatically and cannot be edited.

In addition to the above fields, you can also map any custom fields you’d like to import. See the Data Mapping support page for more information about custom fields.

Accessing the API Endpoint

The API endpoint is used to upload data to XM Discover by sending the data through a REST API request in JSON format.

You can access the endpoint from the Jobs page:

1. Select Summary in the job options menu for your job.
   
2. Click the API Documentation link.
   
3. Click the Print button to download all the information in this window as a printable PDF.
   
4. Your endpoint information includes:
   • API URL: The URL used for the API request.
   • Method: Use the POST method to load data into XM Discover.
   • Job ID: The ID of the currently selected job.
5. An example JSON payload is included in the Request Body section. An API request should contain only 1 document and only include the fields in the example payload.
6. The Responses section lists the possible success and error responses of the API request.
   
7. The Schema section displays the data schema. Required fields are in the required array.

Monitoring an XM Discover Link Job via API

You can monitor the status of XM Discover Link jobs without logging into XM Discover by calling the the status API endpoint. This allows you to get the latest job run status, metrics for a specific job run, or accumulated metrics for a specific time period.

Status Endpoint Information

To call the status endpoint, you’ll need the following:

• API URL: https://na-data.clarabridge.net/v1/public/job/status/<jobID>?apiKey=<apiKey>
  • <jobId> is the ID of the XM Discover Link job you wish to monitor.
  • <apiKey> is the API token.
• Type: Use the REST HTTP
• HTTP Method: Use the GET method to retrieve data.

Input Elements

The following optional input elements can be used to retrieve additional metrics about your job:

• historicalRunId: The ID of the specific upload session. If this element is omitted and no date range is provided, the API call returns the latest job run status. If this element is omitted and a date range is provided, the API call returns accumulated metrics for the specified time period.
• startDate: Define the starting date from which to return data.
• endDate: Define the end date to return data based on the last upload. If this element is omitted and startDate is provided, the endDate is automatically set to the current date.

Output Elements

The following output elements will be returned, provided you entered the required input elements:

• job_status: The job’s status.
• job_failure_reason: If the job failed, the reason for the failure.
• run_metrics: Information about the documents processed by the job. The following metrics are included:
  • SUCCESSFULLY_CREATED: The number of documents created successfully.
  • SUCCESSFULLY_UPDATED: The number of documents updated successfully.
  • SKIPPED_AS_DUPLICATES: The number of documents skipped as duplicates.
  • FILTERED_OUT: The number of documents filtered out by either a source-specific filter or connector filter.
  • BAD_RECORD: The number of digital interactions submitted for processing that did not match the Qualtrics conversational format.
  • SKIPPED_NO_ACTION: The number of documents skipped as non-duplicates.
  • FAILED_TO_LOAD: The number of documents that failed to load.
  • TOTAL: The total number of documents processed during this job’s run.

Error Messages

The following error message are possible for the status API request:

• 401 Unauthorized: Authentication failed. Use a different API key.
• 404 Not Found: A job with the specified ID doesn’t exist. Use a different job ID.

Sample Request

Below is an example request to get the status for a job:

curl --location --request GET 'https://na-data.clarabridge.net/v1/public/job/status/62da736987c9788b830918e0?apiKey=02e7a0e26b592632dd50f623e974fff6'

Sample Response

Below is a sample response of a failed job:
{
"job_status": "Failed",
"job_failure_reason": "{\"problem\":[{\"requestId":"RQ-MOB-f339aa58-71b6-4a1d-a67c-12b8d3439321","severity":"ERROR","description":"Length limit of 900 characters for attribute supportexperienceresp has been exceeded, length is 1043\"}],\"status\":\"ERROR\"}",
"run_metrics": {
"successfully_created": 10,
"failed_to_load": 1,
"total": 11
}
}


Payload Examples

This section contains 1 example JSON payload for each supported type of structured data (feedback, chat, call).

Click here to view the feedback example payload.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e583f9142ae48a1090a76' \
--header 'Content-Type: application/json' \
--data-raw '{
"dataSource": "Standard JSON",
"Row_ID": "id43682",
"store_number": "226,1,1,0,0",
"address": "5916 W Loop 289  Lubbock,  TX 79424",
"phone_number": "806-791-4384",
"reviewer_name": "Mariposa",
"review_rating": 2,
"Review_Date": "03.03.2019",
"Employee_Knowledge": 2,
"Price_value": 3,
"Checkout_process": 1,
"comments": "One of the best experience I'\''ve had at Best Buy in a long time. Keep up the good work.",
"LTR": 10,
"state": "TX",
"Rewards_Member": "MyBestBuy"
}'

Click here to view the chat example payload.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4d77656afa99b0396ef959' \
--header 'Content-Type: application/json' \
--data-raw '{
"conversationId": "37854",
"conversationTimestamp": "2020-07-30T12:42:15.000Z",
"content": {
"contentType": "CHAT",
"participants": [
{
"participantId": "1",
"participantType": "AGENT",
"is_bot": true
},
{
"participantId": "2",
"participantType": "CLIENT",
"is_bot": false
}
],
"conversationContent": [
{
"participantId": "1",
"text": "Hello, how may I help you?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785201"
},
{
"participantId": "2",
"text": "Hi, are you open today?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785202"
},
{
"participantId": "1",
"text": "We are open from 17:00 till 23:00.",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785203"
},
{
"participantId": "2",
"text": "I would like to make a reservation.",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785204"
},
{
"participantId": "1",
"text": "Absolutely! What name can I use?",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785205"
}
]
},
"city": "Boston",
"source": "Facebook"
}'

Click here to view the call example payload.

curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e564d9242ae6e6308ff04' \
--header 'Content-Type: application/json' \
--data-raw '{
"conversationId": "462896",
"conversationTimestamp": "2020-07-30T10:15:45.000Z",
"content": {
"contentType": "CALL",
"participants": [
{
"participant_id": "1",
"type": "AGENT",
"is_ivr": false
},
{
"participant_id": "2",
"type": "CLIENT",
"is_ivr": false
}
],
"conversationContent": [
{
"participant_id": "1",
"text": "This is Emily, how may I help you?",
"start": 22000,
"end": 32000
},
{
"participant_id": "2",
"text": "Hi, I have a couple of questions.",
"start": 32000,
"end": 42000
}
],
"contentSegmentType": "TURN"
},
"city": "Boston",
"source": "Call Center"
}'