API Response Mapping
Purpose
The purpose of API Response Mapping is to enable the automated enrichment of ticket attributes within Puzzel Case Management. This feature allows the content returned from an outbound webhook API call to be efficiently mapped to specific category or form field ticket attributes, facilitating streamlined workflow and enhanced data management. The returned response must be in JSON type in order for this feature to function correctly.
How to Use API Response Mapping
Below are the steps to create, implement, and utilise the API Response Mapping feature:
1. Creating a Response Mapping Schema
To create a new Response Mapping schema:
- Navigate to Settings -> Integrations -> Outbound Integrations -> Response Mappings in your Puzzel Case Management interface.
- Click on the option to create a new Response Mapping schema.
- In the schema creation interface, define the mappings using JSON Path to define the link between the expected JSON response attributes and the corresponding ticket attributes (categories or form fields).
Example Response Mapping:
{
"Categories": [
{
"Category": "Internal Customer Key",
"JsonQuery": "$.response.base.internalCustomerKey"
},
{
"Category": "Anonymous Customer Key",
"JsonQuery": "$.response.base.anonymousCustomerKey"
},
{
"Category": "Country",
"JsonQuery": "$.response.base.country"
}
],
"Form": {
"JsonQuery": "$.response.base.formSample"
},
"FormFields": [
{
"Field": "Free Text",
"JsonQuery": "$.response.base.formSample..freeText"
},
{
"Field": "Dropdown",
"JsonQuery": "$.response.base.formSample..dropdown"
},
{
"Field": "Nested Dropdown",
"JsonQuery": "$.response.base.formSample..nestedDropdown.field",
"NestedFields": [
{
"Field": "Free Text 1",
"JsonQuery": "$.response.base.formSample..nestedDropdown.fields..freeTextNested1"
},
{
"Field": "Free Text 2",
"JsonQuery": "$.response.base.formSample..nestedDropdown.fields..freeTextNested2"
},
{
"Field": "Nested Options",
"JsonQuery": "$.response.base.formSample..nestedDropdown.fields..nestedOptions"
}
]
}
]
}
Here you would typically define how each attribute in your JSON response corresponds to a specific field in your ticketing system. This might include mapping a 'customer_email' from the JSON to the 'Email' field in a ticket form, or mapping a 'issue_type' to a specific category in your system.
Response Mapping Schema breakdown
Categories
Property |
Type |
Description |
Constraints/Notes |
---|---|---|---|
Category |
String |
Defines the category name. |
Must be at least 3 characters long. |
JsonQuery |
String |
A query string to fetch data. |
Optional. Must be at least 3 characters long. |
Form
Property |
Type |
Description |
Constraints/Notes |
---|---|---|---|
JsonQuery |
String |
A query string to fetch form data. |
Optional. Must be at least 3 characters long. |
FormFields
Property |
Type |
Description |
Constraints/Notes |
---|---|---|---|
Field |
String |
The name of the field. |
Required. |
JsonQuery |
String |
A query string to fetch field data. |
Optional. Must be at least 3 characters long. |
NestedFields |
Array of Objects |
Nested fields within a field. |
Follows the same structure as FormFields. |
Overview of Response Mapping in Webhook Processing
During the webhook sending process, the received response is compared against the pre-defined response mapping, if one is selected. This mapping directs how data from the response is extracted and stored in the corresponding categories, forms or form fields on a ticket.
Basic Mapping Example:
Consider the following response mapping configuration:
{
"Categories": [
{ "Category": "CustomerID", "JsonQuery": "$.Customer.ID" },
{ "Category": "CustomerAPI", "JsonQuery": "$.Customer.href" }
]
}
When applied, this mapping instructs the system to:
-
Extract
Customer.ID
from the response and store it in theCustomerID
category on the ticket, assuming theCustomerID
category exists. -
Extract
Customer.href
and store it in theCustomerAPI
category on the ticket, assuming theCustomerAPI
category exists.
Example Response:
{
"Customer": {
"ID": 12345,
"href": "<https://System.com/API/V1/Customers/12345>"
}
}
Result:
-
CustomerID
category value:12345
-
CustomerAPI
category value:<https://System.com/API/V1/Customers/12345
>
Advance Mapping Example - Arrays:
When we point the webhook to retrieve an array of data, maybe the <https://System.com/API/V1/Customers>
endpoint, which returns a list of customers on the system.
{
"Categories": [
{ "Category": "CustomerAPI", "Jsonquery": "$.Customer[N]"}
]
}
Considering the array is zero-indexed, substitute 'N' with the position in the array of the desired result. If you aim to fetch the first item, 'N' should be 0; for the second item, 'N' becomes 1, and so forth. For retrieving the last item, 'N' becomes -1.
2. Editing an Existing Webhook
To apply a Response Mapping schema to an existing webhook:
- Go to Settings -> Integrations -> Outbound Integrations -> Webhooks.
- Select and edit the webhook you wish to modify.
- In the webhook settings, select one of the available response mapping schemas from a dropdown menu or similar selector. This schema will be applied to process responses when the webhook is triggered.
3. Setting up a Business Rule
To automate the triggering of the webhook:
- Define a new business rule (this can be a productivity rule or an event rule) within the system.
- Within the rule's action settings, specify the action to trigger a webhook and send a schema request to an external endpoint.
How It Works
When the configured webhook is triggered (via the conditions set in your business rule), the response mapping schema will automatically process the returned JSON response from the external endpoint. It will search for values contained within the JSON and map them to the predetermined form or category fields in your ticketing system. This process allows for the automatic update and enrichment of ticket attributes based on external data sources, streamlining your workflow and improving ticket information accuracy.
By integrating API Response Mapping into your workflow, you can significantly reduce manual data entry, improve response times, and ensure that ticket information is comprehensive and up-to-date.