This is our first post in “How’d They Do That?”, a series where we’ll be looking at work done by both engineers and non-engineers to accomplish specific goals. Sometimes these posts will involve using Shortcut, sometimes they won’t. We simply want to show you a useful thing and then walk you through how it was made so that you can potentially make a similar useful thing of your own.

Elizabeth Toy had a problem:

Our Zendesk integration wasn’t as robust as she and her team needed it to be.

Specifically, they couldn’t automatically generate or update Shortcut Stories from within Zendesk Tickets, and, as you might expect, they also couldn’t do the reverse of this and automatically update Tickets from within Stories. The functionality that was there required manual selections to be made, and manual processes always have the potential for human error.

What was Elizabeth's solution?

Build something herself using our APIs and Zapier webhooks, creating her own more powerful integration.

Now, it’s possible that you may not be using Zendesk and so don’t particularly care about using Zendesk with Shortcut. That’s totally reasonable. But many of the steps Elizabeth describes below can apply to using our APIs in many other situations.

We’ll let Elizabeth tell the story from here. And note that you can see her original version of this post on Medium.

Disclaimer: so I refer to myself as a non-engineer. And I am not one, in the truest sense. But I do work with a bunch of them and have learned enough to get by. I also took some classes in college but have not retained any of it, nor is it even something I’d use (VBA, ha).

I work on the Support team at Gloo. Our Engineering team decided to make the switch to Shortcut (editor’s note: very smart and cool of them). It promised Zendesk integration—great! I didn’t have time to check it out in depth, but my manager told me to trust him, that it was better than our last system’s Zendesk integration.

Fast forward to all our engineers clamoring to use the new tool and wondering when we’d be sending bugs their way from Zendesk. Time to set this up. Should be easy right?

Nope. Wrong.

The integration consists of a Zendesk app. Nothing in Zendesk apps is trigger-able, action-able, filter-able, etc. in Zendesk or Zapier (the two tools I can usually count on to make things do what I want). We would have to manually select to add a card to Shortcut. Manual processes have the potential for human error.

So I checked Zapier. Shortcut has some actions available there (by invite). But no triggers (no bueno) and the only action is to Create a Story. So that was actually worse than our last system’s Zendesk integration.

What to do? APIs and Webhooks!

Replace any non-bold text above with your own inputs. (You need to generate a Shortcut API Token.)

5. Add an action using Webhooks by Zapier to fire a Custom Request.

Replace any non-bold text above with your own inputs. Or check out Shortcut’s Create Story API documentation for available parameters and make a custom request to fit your needs. To get the Project ID, I recommend a quick GET request using the List Projects API endpoint.

6. Continue on through and test the Zap.

7. Add an action using Zendesk to Update a Ticket. Use the ticket ID from the Trigger step in the Zap and have it post a private note to say the card was added and include a link to the card.

1. Set the Zap’s trigger using Webhooks by Zapier and a Catch Hook trigger.

2. Add an action using Formatter by Zapier to work with Text to Split Text to separate the Actions data from the Webhook to new lines using [:newline:] with the Segment Index of All (as Separate Fields).

3. Add a Filter step to only continue if the Actions data does not contain the string story-task.

4. Add an action using Formatter by Zapier to work with Text to Extract Pattern in a specified value in a given input.

5. Add a Filter step to only continue if Output from the previous step Exists.

6. I set up different paths based on the type of update (Lane Changes, Comments, and Archived/Deleted) but for my own sanity, will only explain how I set up Comments. But if you want to do it similar to how I did, add your paths now.

7. Set up a filter (or path rule) to only continue if the Catch Hook “Actions” portion of the response contains entity_type: story-comment and the “Actions” does not contain action: delete

8. Add an action using Webhooks by Zapier to fire a Custom Request.

9. Add a Filter step to only continue if Output from the previous step Exists.

For an Archive/Delete path, you should omit steps 10/11 as it will error (there’s no card to get). And in the steps following, you would use the story ID rather than the external ID. (You could technically omit steps 10/11 for all paths, but the external ID is a more reliable source of the ID of the ticket to update.) Also for the Archive/Delete path, make sure to filter if the “Actions” portion of the response does not contain story-comment. Comment deletions would otherwise cause a false positive for a Story being deleted.

10. Add an action using Zendesk to Find a Ticket. For the Query, use the External ID item from the Custom Request in step 8.

For an Archive/Delete path, you would use the Query “https://app.clubhouse.io/[ShortcutProject]/story/[storyID]” or, if you have a custom field to capture the URL (see step 6 in Zendesk→Shortcut above) then you should use the Query fieldvalue:“https://app.clubhouse.io/[ShortcutProject]/story/[storyID]”

11. Add a Filter step to only continue if ID of the ticket from the previous step Exists and the Status of our ticket from the previous step Does not exactly match Closed

12. Add an action using Webhooks by Zapier to fire a Custom Request.

This gets the profile information for the commenter.

13. Add an action using Webhooks by Zapier to fire a Custom Request.

This gets the comment information.

Have it post a private note that says something like this:

[commenterName] commented on Shortcut card [storyID]: [commentText]

Fill in the commenterName using the Custom Request in step 12 “Profile Name” portion of the response.

Fill in the storyID using the output from step 3.

Fill in the commentText using the Custom Request in step 13 “Text” portion of the response.

If you made it to this point, kudos to you. What I explained above is a pretty specific use-case, but it’s meant to show you that with awesome APIs and a little webhook magic, you can do a whole lot.

Maybe you want to have comments on Shortcut cards post directly to a Slack channel. Easy! Take the Shortcut→Zendesk steps and omit step 5–7 and change step 11 to post to a Slack channel instead of updating a ticket.

Once you get one thing set up, you’ll realize all the data you have to work with and will want to keep going. Especially in Shortcut’s case, with so many APIs available, you can GET and POST until you’re blue in the face.