The Cheat Sheet I Wish I had before Building our Zapier Integration
Imagine explaining how to use Instagram to your 30-something’s co-worker. Now imagine explaining Instagram to your 80-something’s grandmother.
Documentation is mission critical to the success of a new developer product, but finding the sweet spot for maximizing audience engagement is no trivial task. Lucky for you, my loss (of time) is your gain. I hope this blog post will save you a ton of time, effort, and that you’ll be building on this reliably awesome tool faster than grandma can say “Snapchat”.
Vocabulary
First off, the Zapier docs do not have a dedicated glossary of keywords and terms. You can get the gist from their individual category sections, but having a dedicated reference list certainly would have softened the slope of my own learning curve.
Another benefit of a dedicated glossary is being able to compare the keyword definitions for developers and non-technical end-users side by side. The Zapier documentation does do this to an extent (hats off, Zapier!) but still assumes a level of knowledge above what I had as a developer just beginning to work on Zapier.
App
- End User Definition — The singular and only way to ever interact with your company’s data/API/integration.
- Developer Definition — The current version of the code/scripting you’re working on. An app may be public, private, or invite only, but scripting for public/invite only apps can only be updated through a deploy of private apps. You are going to have a lot of private apps and that’s OK.
Action
- End User Definition — The thing that automagically happens after the trigger occurs.
- Developer Definition — The `POST` request (body comes from the Action Fields) made to the url I specify (Note: I am considering actions very separate from ‘Searches’ or other Zapier features that transform data mid-Zap).
Action Field
- As a new developer to Zapier, this term took me an inexplicably long time to comprehend, perhaps because there are so many places in the Zapier documentation where “Action Field” is described, used, defined, and expanded on.
- An Action Field is an input field for the user while they’re creating their Zap. It makes sense if you break down the words — it’s a field (that the user fills in) on the user-facing action part of a Zap. An Action Field represents the value of a key that becomes input to your scripting. Action Fields get passed as the body of the POST request made to your API endpoint when a Zap runs.
Parts of an Action
- Name: Not used in scripting. User-facing value for the way they identify an action available through your app.
- Noun: Not used in scripting. User-facing value for the object they’re working to create/update.
- Key: Used in scripting! Used as a prefix to identify this action in code.
- Help Text: Not used in scripting. Help text that the user will never read, because users rarely read anything, but Zapier still requires.
Trigger
- End User Definition — The event that starts my Zap.
- Developer Definition — Whether by polling or webhook, Zapier ends up with a JSON object to splice up. Values from specific keys of this object will be sent to the next step of the zap.
Trigger Fields
- Much like Action Fields, these are the fields available on the user-facing Trigger setup for user input. Unlike the previously described action, the trigger fields are used for filtering / determining if a Zap should continue.
Parts of a Trigger
- Use the same definitions found for Name, Noun, Key, and Description as described above for actions.
- Bundle: The bundle is only ever referenced in the context of scripting — this is purely a developer-side keyword. The bundle is the object that is being updated; some of the data in the bundle might be sent as values to other API endpoints. The bundle contains headers for the request Zapier makes to any API endpoint you specify in your app, including any Auth information. Knowing where this Auth information lives is particularly useful if you’d like to make an additional request as part of your scripting logic.
Draw me a picture
In general, I feel there is a lack of pictures in technical documentation. I understand the reason for this — pictures are not easily updated, and even more so than text, should be geared towards a specific audience. However, I find them obscenely useful for getting a big picture context when I’m starting to learn something, so here is my (crude) picture of how Zapier works, specifically geared towards beginners:
Printing and Logs
Console.log()
You’re working on your scripting and you’d like to print something to confirm your suspicions and advance your code. How do you do this? Where does it print?
Step 1: Open the Scripting for your app.
Step 2: Under Quick links (top right corner), click on Bundle Logs
Step 3: The bundle logs are divided up by the functions that ran and a section for “The logs”. This is where you’ll find anything you’ve console.log()-ed.
Check out this sweet gif to see these steps in action!
Task History
The Bundle Logs (described above) will show you errors and are most useful while you’re working on the scripting portion of your Zapier app. However, they’re not great for getting a bird’s-eye view of a Zap that involves another app or even one of your own apps that is public.
For your first stop when debugging a Zap you’ve created (remember debugging a Zap is distinct from debugging your scripting), I suggest visiting the Task History. This will give you the `data in` and the `data out` for each step, even for steps belonging to different apps. The Task History will even give you some error messages.
Check this out if you prefer your information in video format.
Inspecting a Single Request
Basically Task History (described above) but with more detail. If you’d like to see the headers, the method, the request url, or the response content while debugging a Zap, this is the tool for you.
Step 1: From your app, find the category for the Request Log.
Step 2: Click on the original viewer.
Step 3: On the far right, click the buttons for More Details.
Step 4: Profit.
A note about the Original Viewer vs the New Log Viewer: You have two options for your log-viewing-pleasure in Zapier. The two viewers are very similar, but the new one has more options for you to filter on. At first I was partial to the Original Viewer but as time has gone on I’ve come to appreciate the diminished scrolling of the New Viewer. Examples of both the original and the new log viewers are below:
Check out how to access the Original Viewer through the power of gif.
Super Important “Gotchas” that will save you oodles of time
- If you use console.log() with anything too large, any logs prior will not show — only the logs after will appear.
- You can return an empty array to stop a Zap (instead of throwing an error, which might potentially pause the Zap for the user if the error is thrown too many times).
- Datetime: Zapier’s standard datetime format is an ISO-8601 formatted string. This means that if you receive a date from Zapier for a user’s action and your API expects a UNIX timestamp, you’ll need to use moment.js (thankfully a library Zapier Scripting allows access to) or `new Date()` to convert it via scripting before passing it to your API.
- You can access information in the user’s Zapier profile via scripting! For instance, `bundle.zap.user.timezone`will give you the timezone the user entered on their Zapier profile.
- Pre’s and Posts in Scripting: There are a lot of suffixes you can put on a key (that’s the thing from the trigger or the action that identifies which action/trigger you’re scripting about) — pre_poll, pre_read_resource, post_search, pre_write, etc. The myriad of options were really overwhelming for me when I first started developing features on our Zapier app. I wish someone has summed it up like this: pre_stuff is for before Zapier makes the request to your API. As a result, it’s mainly going to be used for things like adjusting the request url, or the headers of the request. The post_stuff is used after the request for data has been made, and so is mainly for adjusting the data you receive in the response to the request.
Streak’s integration with Zapier has enabled our users of varying technical capacity to really make the most out of our API. It’s been a fantastic tool to engage and create efficiency for our users through automation, and it’s all taken care of in a user-facing UI that’s friendlier than a border collie. A further plus is that Zapier’s support — both for developers and users — is top notch. I’ve been impressed with both the speed and quality of the support they consistently offer. As with any new technology tool, the learning tool can be steep. But the good news with Zapier is that you’re not going it alone.
