In Building your first integration - Part 3: Creating a ZIS Flow, you learnt how to create your first ZIS Flow which described making external HTTP calls using a ZIS Action to https://webhook.site/. In this tutorial, you’ll focus on an action’s ability to make authenticated HTTP calls using an OAuth access token.

You’ll create a ZIS Flow that uses ZIS Action to add a tag called “has_attachment” to a Zendesk ticket when a comment is added with an attachment.

First, let’s take a look at the action definition and state.

Action definition

The Action definition takes the form:

{   "type":"ZIS::Action::Http",   "properties":{      "name":"",      "definition":{         "method":"",         "url":"",         "headers":[            {               "key":"",               "value":""            }         ],         "query":[            {               "key":"",               "value":""            }         ],         "requestBody":{}         }      }   }}

An action contains the following properties:

Name Type Description
type string The name of the resource
properties.name string The unique name for your Action, you will be using this in the Action state. The action name can be a maximum of 20 characters [a-z,A-Z,0-9,_]
properties.definition.method string The HTTP method for the call. Available methods are GET, POST, PUT, PATCH, DELETE
properties.definition.url string (optional*) External target URL. When the target system is Zendesk this property should be omitted and properties.definition.path should be used instead.
properties.definition.path string (optional*) Zendesk URL path. Defines a path following the inferred Zendesk URL 'https://<subdomain>.zendesk.com/'.
properties.definition.headers Array of property value pairs (optional) The request headers. Property representing the header and value representing its value
properties.definition.query Array of property value pairs (optional) The query parameters attached to the end of the url. Property representing the query parameter key and value representing its value
properties.definition.requestBody Object (optional) The request body

Note the following information:

  • The action name is unique for an integration
  • All actions referenced in the flow should be present in the same bundle as the flow
  • Depending on the endpoint and the method used, headers or requestBody may be required
  • One of url or path is required. path should be used when the target system is Zendesk, and url should be used for external systems.

Available system variables

The following system variables can be used in the url, headers, or in the requestBody:

  • $.subdomain: The subdomain of the Zendesk account the flow is run for
  • $.integration: The integration the flow belongs to

ZIS substitutes the corresponding values when executing the flow.

When using a system variable or other user-defined variable in the action definition, it needs to be interpolated. For example, in order to use $.input.ticket_id in the path, you would do the following:

{  "type": "ZIS::Action::Http",  "properties": {    "name": "myaction",    "definition": {      "method": "GET",      "path.$": "/api/v2/tickets/{{$.input.ticket_id}}"    }  }}

Notice the .$ suffix in the path object property. If the value is a JSON path (for example, $.input.comment) or a JSON path interpolated in a string (for example, “/api/v2/tickets/{{$.input.ticket_id}}”), the property must carry a .$ suffix.

Named connection

Actions support named connections. The named connection refers to the use of OAuth access by its name in a custom action. Named connections come in handy when making requests to services that support bearer token based authentication such as OAuth from a flow. See Using ZIS to obtain Zendesk OAuth token to set up a named connection.

The following example shows a named connection used inside an action:

{   "type":"ZIS::Action::Http",   "properties":{      ...      "definition":{         ...         "headers":[            {               "key":"Authorization",               "value.$":"Bearer {{$.connections.zendesk.access_token}}"            }         ]      }   }}

If you had named the connection as mysystem when starting the OAuth flow, you would refer to the access token as $.connections.mysystem.access_token in the flow.

Note: The name zendesk for a connection is reserved and can only be used for Zendesk connections. When initiating an OAuth flow for Zendesk, the resulting connection is named "zendesk" by default. Third party system connections cannot be named "zendesk".

Action state

The action state is where you reference the custom action definition in a flow. It takes the form:

{  "Type": "Action",  "ActionName": "",  "Parameters": {},  "ResultPath": "",  "Next": ""}

It has the following properties:

Name Type Description
Type string The name of the resource
ActionName string The name of your action definition
Parameters object The parameters to pass to the action definition
ResultPath string The json path where the response of the HTTP call is stored
Next String The name of the next state to execute
End boolean The value should be “true”. Either Next or End should be present

Create and upload a ZIS Bundle

The bundle to add a tag to tickets that contains attachments consists of three resources:

  • A JobSpec
  • A ZIS Flow
  • A ZIS Action

The job spec’s event_type is the trigger that informs ZIS to execute the flow identified by flow_name. In the following example, when there’s a ticket attachment event for the Zendesk account, the job spec is enabled.

The flow contains a simple one state workflow with ticket_id as the input. A call to the Zendesk ticket API to add a tag in the action uses the OAuth access token by referencing its name as $.connections.zendesk.access_token.

To upload the ZIS bundle

  1. Create a bundle file named tutorial_custom_action.json and paste the following content:

    {  "zis_template_version": "2019-10-14",  "name": "Add a tag to tickets with attachment",  "description": "Add a tag to a ticket that contains comments with attachment",  "resources": {    "AddTagJobSpec": {      "type": "ZIS::JobSpec",      "properties": {        "name": "AddTagJobSpec",        "event_source": "support",        "event_type": "ticket.AttachmentLinkedToComment",        "flow_name": "zis:<YOUR_INTEGRATION_NAME>:flow:AddTagFlow"      }    },    "AddTagFlow": {      "type": "ZIS::Flow",      "properties": {        "name": "AddTagFlow",        "definition": {          "StartAt": "AddTagState",          "States": {            "AddTagState": {              "Type": "Action",              "ActionName": "zis:<YOUR_INTEGRATION_NAME>:action:AddTagAction",              "Parameters": {                "ticket_id.$": "$.input.ticket_event.ticket.id",                "access_token.$": "$.connections.zendesk.access_token"              },              "End": true            }          }        }      }    },    "AddTagAction": {      "type": "ZIS::Action::Http",      "properties": {        "name": "AddTagAction",        "definition": {          "method": "PUT",          "path.$": "/api/v2/tickets/{{$.ticket_id}}/tags",          "headers": [            {              "key": "Authorization",              "value.$": "Bearer {{$.access_token}}"            },            {              "key": "Content-Type",              "value": "application/json"            }          ],          "requestBody": {            "tags": ["has_attachment"]          }        }      }    }  }}
  2. Replace <YOUR_INTEGRATION_NAME> with your integration name and save the file.

  3. Upload the bundle by making an API request to the Upload or Update Bundle endpoint:

    curl \--request POST \--url https://<YOUR_SUBDOMAIN>.zendesk.com/api/services/zis/registry/<INTEGRATION_NAME>/bundles \--user '<EMAIL>:<PASSWORD>' \--header 'content-type: application/json' \-d @tutorial_custom_action.json
  4. Replace <EMAIL> and <PASSWORD> with your basic authentication credentials.

Enable the JobSpec

Make an API call to the Install JobSpec endpoint that installs the respective JobSpec and enables a flow on a Zendesk account:

curl \  --request POST \  --url https://<YOUR_SUBDOMAIN>.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:<INTEGRATION_NAME>:job_spec:AddTagJobSpec \  --user '<EMAIL>:<PASSWORD>'

Testing the integration

You can test the integration in Zendesk by uploading an attachment to a comment in a ticket. The tag has_attachment getting added by ZIS.

Next: Extending your first integration: Conditional branching