It’s that time of year again, though it may not quite feel it. The leaves have taken their time falling from the trees, department stores are playing “Happy Holidays” on a loop to almost entirely empty rooms, and I’m wearing a big pink hat I bought on Etsy last month because it makes not leaving my house feel slightly more festive.
To celebrate, Shortcut is highlighting twelve of our integrations with a detailed write up alongside their own little digital snow globes. We hope you return every day to enjoy these posts alongside your tinglers and fuzzles, your dafflers and wuzzles, and your delicious pot (or Beyond meat) roasts
Our twelve featured integration is not an integration but instead a way for you to build your own. The Shortcut API.
On our Twelfth Day of Integrations Shortcut gives to you: A REST API in a Shortcut. You really need to sing that line to make it work.
Why stop stop at using integrations that other organizations have built, when you can also build your own?
The Shortcut API provides a greater amount of control over your Shortcut data than what is possible in the web app alone. You can use the API to build custom integrations or automate more of your workflow.
You can read detailed documentation about our API right here.
In some cases you're even able to take one of our existing integrations and build a personal version that's even better. That's what one of our customers, Elizabeth Toy from Gloo, did for our Zendesk integration. It was missing some of the features her team needed and she used our APIs alongside our Zapier integration to build her own.
To show off this example, we’ll let Elizabeth tell the story from here. 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?
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.)
Python code to get Shortcut member ID
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).
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
Setting up Catch Hook rules in Zapier
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.
Nothing to see here...