Using a ZIS action to make authenticated API requests

In this tutorial, you'll create a ZIS integration that makes authenticated API requests. As part of the tutorial, you'll create an ZIS connection that contains an OAuth access token. You'll then use the connection to authenticate requests in the integration's ZIS flow.

What you'll need

To complete this tutorial, you'll need the following:

Creating the integration

The integration you create listens for Attachment Linked to Comment events in Zendesk. When it detects the event, the integration makes an authenticated request to the Zendesk Support API's Add Tags endpoint. The request adds a "has_attachment" tag to the ticket from the event.

  1. Create a ZIS connection named "zendesk". In a typical setup, an admin uses a private Zendesk app to create ZIS connections. For this tutorial, you'll create the "zendesk" connection without an app. The "zendesk" connection contains an OAuth access token for Zendesk APIs.

    To create the "zendesk" connection, follow the steps in Create a ZIS connection for Zendesk. Then return here.

    Tip: To create a connection for a service other than Zendesk, see Creating a ZIS connection for a third-party service.

  2. Create a JSON file named my_zis_bundle.json.

  3. Add the following bundle skeleton to my_zis_bundle.json:

    {  "name": "ZIS integration with authenticated API requests",  "description": "Add a tag to tickets with attachment",  "zis_template_version": "2019-10-14",  "resources": {    "AddTagAction": {      "_placeholder_": "ZIS custom action definition goes here"    },    "AddTagFlow": {      "_placeholder_": "ZIS flow goes here"    },    "AddTagJobSpec": {      "_placeholder_": "ZIS JobSpec goes here"    }  }}

    You'll define the custom action, ZIS flow, and JobSpec in the next steps.

  4. In my_zis_bundle.json, replace the AddTagAction placeholder with the following custom action definition.

    "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"]      }    }  }},

    When called, the custom action sends a PUT request to the Add Tags endpoint. To authenticate the request, the action requires an OAuth access token.

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

    The flow contains a single Action state, which is highlighted.

    "AddTagFlow": {  "type": "ZIS::Flow",  "properties": {    "name": "AddTagFlow",    "definition": {      "StartAt": "AddTagState",      "States": {        "AddTagState": {          "Type": "Action",          "ActionName": "zis:INTEGRATION:action:AddTagAction",          "Parameters": {            "ticket_id.$": "$.input.ticket_event.ticket.id",            "access_token.$": "$.connections.zendesk.access_token"          },          "End": true        }      }    }  }},

    The state calls the custom action you defined in the previous step. The state uses the "zendesk" connection's access token to authenticate the action's API request. The state accesses this token using the "$.connections.zendesk.access_token" reference path.

  6. Replace the TicketStatusChangedJobSpec placeholder with the following JobSpec definition. In the definition, replace "INTEGRATION" with your integration key.

    "AddTagJobSpec": {  "type": "ZIS::JobSpec",  "properties": {    "name": "AddTagJobSpec",    "event_source": "support",    "event_type": "ticket.AttachmentLinkedToComment",    "flow_name": "zis:INTEGRATION:flow:AddTagFlow"  }}

    The JobSpec tells ZIS to run the ZIS flow when it detects an Attachment Linked to Comment event.

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

    {  "name": "ZIS integration with authenticated API requests",  "description": "Add a tag to tickets with attachment",  "zis_template_version": "2019-10-14",  "resources": {    "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"]          }        }      }    },    "AddTagFlow": {      "type": "ZIS::Flow",      "properties": {        "name": "AddTagFlow",        "definition": {          "StartAt": "AddTagState",          "States": {            "AddTagState": {              "Type": "Action",              "ActionName": "zis:INTEGRATION:action:AddTagAction",              "Parameters": {                "ticket_id.$": "$.input.ticket_event.ticket.id",                "access_token.$": "$.connections.zendesk.access_token"              },              "End": true            }          }        }      }    },    "AddTagJobSpec": {      "type": "ZIS::JobSpec",      "properties": {        "name": "AddTagJobSpec",        "event_source": "support",        "event_type": "ticket.AttachmentLinkedToComment",        "flow_name": "zis:INTEGRATION:flow:AddTagFlow"      }    }  }}
  8. Upload the bundle to ZIS.

    curl -X POST https://{subdomain}.zendesk.com/api/services/zis/registry/{integration}/bundles \  -u {email}:{password} \  -H "Content-Type: application/json" \  -d @my_zis_bundle.json
  9. Install the JobSpec 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:AddTagJobSpec" \  -u {email}:{password}

Testing the integration

To test the integration, create a ticket with an attachment. Then verify the integration added the "has_attachment" tag to the ticket.

  1. Right-click the following image link and save it to your computer as camera-pieces.png:

    [camera-pieces.png]

  2. In your shell, navigate to the folder where you saved the image. For example:

    $ cd ~/Downloads
  3. Use the following request to upload the image as an attachment.

    curl -X POST https://{subdomain}.zendesk.com/api/v2/uploads?filename=camera-pieces.png \  -u {email}:{password} \  -H "Content-Type: application/binary" \  --data-binary @camera-pieces.png

    Save the upload.token value from the response. You'll use the token in the next step.

    {  "upload": {    "token": "abcxyz",    "expires_at": "2099-05-06T00:00:00Z",    ...  }}
  4. Use the following request to create a ticket with the attachment. Replace "TOKEN" with the token you saved in the previous step.

    curl -X POST https://{subdomain}.zendesk.com/api/v2/tickets \  -u {email}:{password} \  -H "Content-Type: application/json" \  -d '{    "ticket": {      "subject": "My homemade camera fell apart!",      "comment": {        "body": "See attached.",        "uploads": ["TOKEN"]      }    }  }'

    Save the ticket.id value from the response. You'll use the id in the next step.

    {  "ticket": {    "url": "https://SUBDOMAIN.zendesk.com/api/v2/tickets/24.json",    "id": 24,    "external_id": null,    ...  },  ...}
  5. Use the following request to fetch the ticket you created. Replace "{ticket_id}" with the id you saved in the previous step.

    curl -X GET https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json \  -u {email}:{password}

    The response should contain "has_attachment" in the ticket.tags property.

    {  "ticket": {    "url": "https://SUBDOMAIN.zendesk.com/api/v2/tickets/24.json",    "id": 24,    ...    "tags": [      "has_attachment"    ],    ...  }}

    You also can verify the ticket's tag in the Zendesk Support agent interface.

Congratulations! You've created a ZIS integration that makes authenticated API requests. For a more complex example of an integration that makes authenticated API requests, see the Zendesk app as an admin interface tutorial series.