Extending your first integration: Conditional branching

In Building your first integration, the flow logic steps through the states in the same sequence every time the corresponding trigger occurs. However, sometimes this logic doesn’t address our needs. If you want a flow that can branch between different states conditionally (example: if state A succeeds go to B; if it fails go to C), you’ll want to use the Choice state type in your flow.

In this tutorial, you’ll use the Choice state to create a flow that posts a message to webhook.site when a ticket status is solved.

Understanding Choice states

The Choice state type lives alongside your other action state types in our flow. Example:

{
   ...
   "pickChoice":{
      "Type":"Choice",
      "Choices":[
         {
            "Variable":"$.input.config",
            "StringEquals":"choice1",
            "Next":"ProcessChoice1"
         },
         {
            "Variable":"$.input.config",
            "StringEquals":"choice2",
            "Next":"ProcessChoice2"
         }
      ]
   },
   ...
}

Choice states require a Variable and conditional expression such as StringEquals and Next properties. In the above example:

• Variable is the input value
• The conditional expression StringEquals defines which conditions the input value leads to one state or another state
• The Next state is executed after the choice has been made

Having a default value for the next state is also a logical choice. If the conditions described are not met, it falls back to the Default value instead. Example:

{
   ...
   "CheckDeployResult":{
      "Type":"Choice",
      "Choices":[
         {
            "Variable":"$.deploy_result.deploy_error",
            "StringGreaterThan":"",
            "Next":"PatchConfigFailure"
         }
      ],
      "Default":"PublishSuccess"
   },
   ...
}

Creating and uploading the ZIS Bundle

1. In your text editor, create a file named tutorial_bundle.json and paste the following code:

   {
     "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": "PostToWebhook"
                   }
                 ],
                 "Default": "End"
               },
               "PostToWebhook": {
                 "Type": "Action",
                 "ActionName": "zis:{integration_name}:action:PostToWebhook",
                 "Parameters": {
                   "ticket_id.$": "$.input.ticket_event.ticket.id",
                   "ticket_status.$": "$.input.ticket_event.current"
                 },
                 "Next": "Finish"
               },
               "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:

   • {integration_name} is the integration name when you register your integration. See Building your first integration
   • {webhook_site_path} with the unique webhook URL identifier by creating an external webhook target by visiting https://webhook.site/. It looks something like https://webhook.site/21ae2ed2-4ee3-44f3-b716-7bd934a50a56

2. Save the file.

3. From your command line tool, run the curl command to upload the bundle using the ZIS Registry API.

   curl \
   --request POST \
   --url https://{subdomain}.zendesk.com/api/services/zis/registry/{integration_name}/bundles \
   --user '{email}:{password}' \
   --header 'content-type: application/json' \
   -d @tutorial_bundle.json

4. Replace the following {email} and {password} with your Basic Auth credentials. From the command line, run the curl command to enable the Job Spec.

   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": 7,
    "status": "solved"
  }
}

Next: Extending your first integration: Data transformation