Extending your first integration: Data transformation

It's common to use data transformation for converting data to a specific format. For example, an external API may only accept numbers represented as a string. Example: "123".

ZIS supports data transformation using JQ, a popular JSON processing tool. JQ is exposed as an action state in a ZIS Flow. Any valid JQ expression can be executed using the JQ action state.

Be aware that using JQ for data transformation in ZIS has following limitations:

  • JQ modules are not supported
  • Use of $ENV object in the expression is not supported
  • Streaming is not supported

In this tutorial, you’ll convert the ticket_id which is an integer to a string type before sending it to the webhook.site. You'll reuse the same flow from Extending your first integration: Conditional branching with some minor changes to introduce the zis:common:transform:Jq state.

The zis:common:transform:Jq state looks like this:

{  "Type": "Action",  "ActionName": "zis:common:transform:Jq",  "Parameters": {    "expr": "{jq_expr}",    "data.$": "{input_json}"  },  "ResultPath.$": "{output_json}"}


  • expr: The JQ expression. If any part of the expression needs to be interpolated then the .$ suffix applies, that is expr.$
  • data.$: The input data to expr

Creating and uploading a ZIS Bundle

  1. In your text editor, open the tutorial_bundle.json file you previously created in Extending your first integration: Conditional branching, and add the JQ state to the ZIS Flow that converts integer to a string.

    {  "zis_template_version": "2019-10-14",  "name": "Send webhook when ticket status change",  "description": "Send webhook when ticket status change to solved",  "resources": {    "JobSpec": {      "type": "ZIS::JobSpec",      "properties": {        "name": "TicketStatusChangedJobSpec",        "event_source": "support",        "event_type": "ticket.StatusChanged",        "flow_name": "zis:{integration_name}:flow:TicketStatusChangedFlow"      }    },    "Example_flow": {      "type": "ZIS::Flow",      "properties": {        "name": "TicketStatusChangedFlow",        "definition": {          "StartAt": "CheckStatus",          "States": {            "CheckStatus": {              "Type": "Choice",              "Choices": [                {                  "Variable": "$.input.ticket_event.current",                  "StringEquals": "solved",                  "Next": "ConvertTicketIDToStr"                }              ],              "Default": "End"            },            "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_name}:action:PostToWebhook",              "Parameters": {                "ticket_id.$": "$.ticket_id_str",                "ticket_status.$": "$.input.ticket_event.current"              },              "Next": "End"            },            "Finish": {              "Type": "Succeed"            }          }        }      }    },    "PostToWebhook": {      "type": "ZIS::Action::Http",      "properties": {        "name": "PostToWebhook",        "definition": {          "method": "PUT",          "url": "https://webhook.site/{webhook_site_path}",          "requestBody": {            "ticket": {              "id.$": "$.ticket_id",              "status.$": "$.ticket_status"            }          }        }      }    }  }}

    Replace the following placeholders:

  2. From your command line tool, run the curl command to upload the bundle using the ZIS Bundles API](/api-reference/integration-services/registry/bundles/):

    curl \--request POST \--url https://{subdomain}.zendesk.com/api/services/zis/registry/{integration_name}/bundles \--user '{email}:{password}' \--header 'content-type: application/json' \-d @data_transformation.json
  3. From the command line, run the curl command to enable the JobSpec.

    Note: If you already have enabled the JobSpec TicketStatusChangedJobSpec as part of previous tutorials, you can skip this step.

    curl \--request POST \--url "https://{subdomain}.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:{integration_name}:job_spec:TicketStatusChangedJobSpec" \--user '{email}:{password}'

Testing the integration

Test the integration by setting one of the ticket's status as “Solved” in Zendesk. You should see the event displayed in your webhook dashboard. Example:

{  "ticket": {    "id": "22",    "status": "solved"  }}

Notice the id is a string, in this case, "22".

In this tutorial, you have only scratched the surface of what's possible with JQ. See the JQ documentation for a list of capabilities. To experiment with various JQ expressions, you can use the JQ Play site.

Next: Iterating over a collection