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 OAuth connection. You'll then use the connection to authenticate requests in the integration's ZIS flow.

OAuth connections are a type of connection in the ZIS Connections Service. For more information about other connection types, see Understanding connections.

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 ZIS OAuth token for the integration. See Obtaining a ZIS OAuth token.

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 an OAuth connection named "zendesk".

   In a typical setup, an admin uses a private Zendesk app to create OAuth connections. For this tutorial, you'll create the "zendesk" connection without an app.

   To create the "zendesk" connection, follow the steps in Creating an OAuth connection for Zendesk. Then return here.

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

   You'll define the custom action, ZIS flow, and job spec 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",
         "connectionName": "zendesk",
         "headers": [
           {
             "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 uses the "zendesk" connection.

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

6. Replace the TicketStatusChangedJobSpec placeholder with the following job spec 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 job spec 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",
             "connectionName": "zendesk",
             "headers": [
               {
                 "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"
                 },
                 "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}/token:{api_token} \
     -H "Content-Type: application/json" \
     -d @my_zis_bundle.json

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

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}/token:{api_token} \
     -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}/token:{api_token} \
     -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}/token:{api_token}

   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 uses an OAuth connection to make authenticated API requests. For a more complex example, see the Zendesk app as an admin interface tutorial series.