Using conditional branching in a ZIS flow

In this tutorial, you'll create a ZIS integration with conditional branching. To create the branching logic, you'll include a Choice state in the integration's ZIS flow. The Choice state transitions to different states based on the value of an input variable.

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

The integration you create listens for Ticket Status Changed events in Zendesk. If the event's current ticket status is "solved", the integration posts the event's ticket data to an external target. This target represents an external application. If the event has another current ticket status, the integration takes no action.

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 conditional branching",
     "description": "Send webhook when ticket status change to solved",
     "zis_template_version": "2019-10-14",
     "resources": {
       "PostToWebhook": {
         "_placeholder_": "ZIS custom action definition goes here"
       },
       "TicketStatusChangedFlow": {
         "_placeholder_": "ZIS flow goes here"
       },
       "TicketStatusChangedJobSpec": {
         "_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",
             "status.$": "$.ticket_status"
           }
         }
       }
     }
   },

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

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

   The flow contains a Choice state, which is highlighted.

   "TicketStatusChangedFlow": {
     "type": "ZIS::Flow",
     "properties": {
       "name": "TicketStatusChangedFlow",
       "definition": {
         "StartAt": "CheckStatus",
         "States": {
           "CheckStatus": {
             "Type": "Choice",
             "Choices": [
               {
                 "Variable": "$.input.ticket_event.current",
                 "StringEquals": "solved",
                 "Next": "PostToWebhook"
               }
             ],
             "Default": "Finish"
           },
           "PostToWebhook": {
             "Type": "Action",
             "ActionName": "zis:INTEGRATION:action:PostToWebhook",
             "Parameters": {
               "ticket_id.$": "$.input.ticket_event.ticket.id",
               "ticket_status.$": "$.input.ticket_event.current"
             },
             "Next": "Finish"
           },
           "Finish": {
             "Type": "Succeed"
           }
         }
       }
     }
   },

   The Choice state checks whether the event's current ticket status is "solved". If so, the flow runs an Action state that calls the custom action you defined in the last step. Otherwise, the flow ends in a Succeed state.

5. Replace the TicketStatusChangedJobSpec placeholder with the following job spec definition. In the definition, replace "INTEGRATION" with your integration key.

   "TicketStatusChangedJobSpec": {
     "type": "ZIS::JobSpec",
     "properties": {
       "name": "TicketStatusChangedJobSpec",
       "event_source": "support",
       "event_type": "ticket.StatusChanged",
       "flow_name": "zis:INTEGRATION:flow:TicketStatusChangedFlow"
     }
   }

   The job spec tells ZIS to run the ZIS flow when it detects a Ticket Status Changed event.

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

   {
     "name": "Example ZIS integration with conditional branching",
     "description": "Send webhook when ticket status change to solved",
     "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",
                 "status.$": "$.ticket_status"
               }
             }
           }
         }
       },
       "TicketStatusChangedFlow": {
         "type": "ZIS::Flow",
         "properties": {
           "name": "TicketStatusChangedFlow",
           "definition": {
             "StartAt": "CheckStatus",
             "States": {
               "CheckStatus": {
                 "Type": "Choice",
                 "Choices": [
                   {
                     "Variable": "$.input.ticket_event.current",
                     "StringEquals": "solved",
                     "Next": "PostToWebhook"
                   }
                 ],
                 "Default": "Finish"
               },
               "PostToWebhook": {
                 "Type": "Action",
                 "ActionName": "zis:INTEGRATION:action:PostToWebhook",
                 "Parameters": {
                   "ticket_id.$": "$.input.ticket_event.ticket.id",
                   "ticket_status.$": "$.input.ticket_event.current"
                 },
                 "Next": "Finish"
               },
               "Finish": {
                 "Type": "Succeed"
               }
             }
           }
         }
       },
       "TicketStatusChangedJobSpec": {
         "type": "ZIS::JobSpec",
         "properties": {
           "name": "TicketStatusChangedJobSpec",
           "event_source": "support",
           "event_type": "ticket.StatusChanged",
           "flow_name": "zis:INTEGRATION:flow:TicketStatusChangedFlow"
         }
       }
     }
   }

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:TicketStatusChangedJobSpec" \
     -u {email}/token:{api_token}

Testing the integration

To test the integration, use the following request to create a ticket with a "solved" status.

curl -X POST https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -u {email}/token:{api_token} \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "subject": "My printer is no longer on fire!",
      "status": "solved",
      "comment": {
        "body": "The smoke has cleared."
      }
    }
  }'

Navigate to your RequestBin dashboard. You should see a JSON payload with the ticket id and status.

Congratulations! You've created a ZIS integration with conditional branching. For a more complex example of a ZIS integration with conditional branching, see the Zendesk app as an admin interface tutorial series.