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:

• Familiarity with ZIS. Before you start, complete the Building your first ZIS integration tutorial.

• A registered ZIS integration. You can use the same integration you created in Building your first ZIS integration or register a new one. To register a new integration, see Registering the integration name.

• A free external target URL from RequestBin

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 job spec goes here"
       }
     }
   }

   You'll define the custom action, ZIS flow, and job spec 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 RequestBin endpoint 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 job spec 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 job spec 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}/token:{api_token} \
     -H "Content-Type: application/json" \
     -d @my_zis_bundle.json

8. Install the job spec 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}/token:{api_token}

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}/token:{api_token} \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "subject": "My printer is on fire!",
      "comment": {
        "body": "The smoke is very colorful."
      }
    }
  }'

Navigate to your RequestBin 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.