Transforming data in a ZIS flow

In this tutorial, you'll create a ZIS integration that transforms JSON data. To do this, you'll include a Transform action in the integration's ZIS flow. A Transform action uses a jq expression to change the values, format, or structure of a JSON input. This input can be event data, an API response, or other JSON accessible from the ZIS flow.

What you'll need

To complete this tutorial, you'll need the following:

Creating the integration

It's common to use data transformation to convert data to a specific format. For example, an external application may only accept numbers formatted as a string.

The integration you create listens for Ticket Created events in Zendesk. The event's data includes a ticket id that's formatted as an integer. When it detects the event, the integration converts this ticket id from an integer to a string. The integration then posts the string to an external target representing an external application.

  1. Create a JSON file named my_zis_bundle.json.

  2. Add the following bundle skeleton to my_zis_bundle.json:

    {  "name": "Example ZIS integration with data transformation",  "description": "Send ticket id string to external target on ticket creation",  "zis_template_version": "2019-10-14",  "resources": {    "PostToWebhook": {      "_placeholder_": "ZIS custom action definition goes here"    },    "TicketCreatedFlow": {      "_placeholder_": "ZIS flow goes here"    },    "TicketCreatedJobSpec": {      "_placeholder_": "ZIS JobSpec goes here"    }  }}

    You'll define the custom action, ZIS flow, and JobSpec in the next steps.

  3. In my_zis_bundle.json, replace the PostToWebhook placeholder with the following custom action definition. In the definition, replace "EXTERNAL_TARGET_URL" with your https://webhook.site/ URL.

    "PostToWebhook": {  "type": "ZIS::Action::Http",  "properties": {    "name": "PostToWebhook",    "definition": {      "method": "POST",      "url": "EXTERNAL_TARGET_URL",      "requestBody": {        "ticket_id.$": "$.ticket_id"      }    }  }},

    When called, the custom action sends a POST request to the external target URL. The request body contains a Zendesk ticket id.

  4. Replace the TicketCreatedFlow placeholder with the following ZIS flow definition. In the definition, replace "INTEGRATION" with your integration key.

    The flow contains an Action state that calls a Transform action. The state is highlighted.

    "TicketCreatedFlow": {  "type": "ZIS::Flow",  "properties": {    "name": "TicketCreatedFlow",    "definition": {      "StartAt": "ConvertTicketIDToStr",      "States": {        "ConvertTicketIDToStr": {          "Type": "Action",          "ActionName": "zis:common:transform:Jq",          "Parameters": {            "expr": ".ticket_event.ticket.id | tostring",            "data.$": "$.input"          },          "ResultPath": "$.ticket_id_str",          "Next": "PostToWebhook"        },        "PostToWebhook": {          "Type": "Action",          "ActionName": "zis:INTEGRATION:action:PostToWebhook",          "Parameters": {            "ticket_id.$": "$.ticket_id_str"          },          "End": true        }      }    }  }},

    The Transform action converts the event's ticket id from an integer to a string. The flow then runs another Action state to call the custom action you defined in the previous step.

  5. Replace the TicketCreatedJobSpec placeholder with the following JobSpec definition. In the definition, replace "INTEGRATION" with your integration key.

    "TicketCreatedJobSpec": {  "type": "ZIS::JobSpec",  "properties": {    "name": "TicketCreatedJobSpec",    "event_source": "support",    "event_type": "ticket.TicketCreated",    "flow_name": "zis:INTEGRATION:flow:TicketCreatedFlow"  }}

    The JobSpec tells ZIS to run the ZIS flow when it detects a Ticket Created event.

  6. Save my_zis_bundle.json. The file should now look like this:

    {  "name": "Example ZIS integration with data transformation",  "description": "Send ticket id string to external target on ticket creation",  "zis_template_version": "2019-10-14",  "resources": {    "PostToWebhook": {      "type": "ZIS::Action::Http",      "properties": {        "name": "PostToWebhook",        "definition": {          "method": "POST",          "url": "EXTERNAL_TARGET_URL",          "requestBody": {            "ticket_id.$": "$.ticket_id"          }        }      }    },    "TicketCreatedFlow": {      "type": "ZIS::Flow",      "properties": {        "name": "TicketCreatedFlow",        "definition": {          "StartAt": "ConvertTicketIDToStr",          "States": {            "ConvertTicketIDToStr": {              "Type": "Action",              "ActionName": "zis:common:transform:Jq",              "Parameters": {                "expr": ".ticket_event.ticket.id | tostring",                "data.$": "$.input"              },              "ResultPath": "$.ticket_id_str",              "Next": "PostToWebhook"            },            "PostToWebhook": {              "Type": "Action",              "ActionName": "zis:INTEGRATION:action:PostToWebhook",              "Parameters": {                "ticket_id.$": "$.ticket_id_str"              },              "End": true            }          }        }      }    },    "TicketCreatedJobSpec": {      "type": "ZIS::JobSpec",      "properties": {        "name": "TicketCreatedJobSpec",        "event_source": "support",        "event_type": "ticket.TicketCreated",        "flow_name": "zis:INTEGRATION:flow:TicketCreatedFlow"      }    }  }}
  7. Upload the bundle to ZIS.

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/registry/{integration}/bundles \  -u {email}:{password} \  -H "Content-Type: application/json" \  -d @my_zis_bundle.json
  8. Install the JobSpec to enable the integration.

    curl -X POST "https://{subdomain}.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:{integration}:job_spec:TicketCreatedJobSpec" \  -u {email}:{password}

Testing the integration

To test the integration, use the following request to create a ticket.

curl -X POST https://{subdomain}.zendesk.com/api/v2/tickets.json \  -u {email_address}:{password} \  -H "Content-Type: application/json" \  -d '{    "ticket": {      "subject": "My printer is on fire!",      "comment": {        "body": "The smoke is very colorful."      }    }  }'

Navigate to your https://webhook.site/ dashboard. You should see a JSON payload with the ticket id formatted as a string.

Congratulations! You've created a ZIS integration that uses jq to transform JSON data. To see other example jq expressions, check out the jq cheat sheet.