Integrating Umbraco with Zapier

From the studio that brought you Once Upon a Time in Hollywood, one of the longest movies of 2019, comes one of the most challenging Umbraco integrations so far… But wait, this is not a Tarantino movie, it’s just a new blog post covering the latest Umbraco package released, the integration with Zapier, delivered to you from the team that brought you a suite of integrations for Umbraco CMS or Umbraco Forms (Shopify and Google Search Console).

All joking aside, it has been quite a journey, but the final result is totally worth it! Bear with me for the length of this post while I walk you through the steps we took to integrate Umbraco CMS with Zapier.

Zapier Overview

Save time by automating your work → this would highlight the purpose of Zapier, a workflow automation platform that supports more than 4000+ apps, ranging from Microsoft Outlook, Excel, and Dynamics CRM, to Google suite, Slack, Shopify, HubSpot, Trello, Dropbox and many more. 

In the words of Wade Foster, the CEO of Zapier: one of the biggest advantages of automation in the workplace is time savings. Through automated processes, worker productivity will boost and businesses can save time and money.

Zapier automates the use of web applications together, acting as a translator between web APIs, helping to increase productivity by saving time through automation of recurring tasks, and business processes such as leads management.

If you want to read more about Zapier’s mission, you can check out their website for more information.

Automation through Zaps

Automation is the process of getting something up to run automatically. Automation is all around us, even if we don’t realize it.

The heart of any automation boils down to a simple command: “WHEN and DO” → “WHEN this happens, DO that …”.

Chances are you’ve automated something without even realizing it:

• Have you received an automatic email before a calendar event is set to start? That’s automation.
• Did you get a text alert when it’s almost time to renew a subscription or to remind you of an upcoming appointment? Automation again!

And the list can go on; Zapier is on a mission to make automation incredibly easy and accessible to everyone at work. 

The processes are managed through automated workflows called Zaps, offered by Zapier through an interface in which users can set up rules to orchestrate the flow of data between tools and online services that wouldn’t otherwise communicate with one another. The intuitive interface lets users set up “IF THIS, THEN THAT” (IFTTT) rules that govern how automation functions work. 

A Zap consists of a “trigger” and one or more “actions”. A trigger is an event that starts a Zap, and an action is what your Zap does for you. When a Zap runs, each action it completes counts as one task.

In essence, Zapier aims to make it easier for workers to connect workflows across web apps using code-less automation, regardless of technical expertise. The no-code approach is also designed to lighten the load on IT staff. Users can create multi-step Zaps that perform several actions, this flexibility opening the door to a variety of automation - most of the popular use cases in Zapier center around sales and marketing.

With the free version the users can create five single-step Zaps, with a limit of 100 tasks; more complex Zaps require a monthly fee. 

Zapier offers five pricing plans with access to various features at different levels.

Umbraco in the Zapier ecosystem

We are now happy to announce that Umbraco is part of the Zapier App Directory, we encourage you to explore and use it to create your custom workflows:

The app is currently in a beta version, so we would really appreciate your help and feedback testing it with your use cases;  reaching 50 Zaps using our app will validate our integration and cement our place in Zapier’s marketplace. 

H5YR!

How can you do that?

First, make sure you've signed up for a Zapier account: https://zapier.com/sign-up/ . It’s free to start!

Then you just need to follow these steps:

1. Select the Umbraco App
2. Pick one of the events:
   1. New Content Published → when the assigned content type of the Zap gets published, then the defined workflow actions are executed.
   2. New Form Submitted → when the assigned form of the Zap is submitted, then the defined workflow actions are executed.
3. Define the set of actions

Umbraco Integration

At the beginning of the blog post, I mentioned that this integration was challenging and had to overcome a series of blockages. Here is what happened and how we got to the end result …

Every Zap starts with a trigger, powered by either a webhook subscription that watches for new data as it comes in or polling GET API calls to check for new data periodically. The polling option was not a viable solution for our integrations so we took the webhook subscription approach. You can read more about triggers in the documentation available here.

With this setup in mind, the initial technical approach followed these patterns, covering CMS and Forms components of Umbraco through individual and independent packages:

1. CMS Package - Umbraco.Cms.Integrations.Automation.Zapier - would deliver a dashboard interface where the user could map content types against webhooks provided from Zapier’s interface when a new Zap was set. When the mapped content type would be published, a POST request with the published content would be sent to the webhook, causing the Zap to run and execute the actions. 

1. Forms Package - Umbraco.Forms.Integrations.Automation.Zapier - would deliver a workflow that users could include in a form, and choose which fields of the form they would like to send to Zapier along with the characteristics of the form. When that form would get published, a POST request would be sent to the webhook with the included details of the form, causing the Zap to run and execute the actions.

At this point, the Umbraco app was in development mode, private, and accessible only through an invitation. While setting up the triggers I missed a couple of optional parameters that did not ring a bell (Subscribe/Unsubscribe and Polling endpoints):

On the final stretches of the integrations and while preparing for the public listing of the Zapier App, we encountered a major blockage caused by app validation errors. The public listing of the app requested we fill out the fields above, which affected the existing integration, not being able to gain the webhook URL from the Zap interface and use it in the Umbraco backoffice.

After discussions with the support team - and a big thumbs up to them for helping me unblock the situation quickly, the reason behind this was the fact that “webhooks URLs are shown only when the REST hooks aren’t configured. This is no longer allowed for apps that would like to go public. This is because it makes it easier for users that they don’t have to do additional setup between both apps and it makes it seamless when everything happens on the backend.” 

This sent us back to the drawing board and eventually turned around the integration.

As a result, most of the functionality was condensed in the CMS package, leaving the Forms package to act as an extension to the CMS package, handling the form submissions.

Contents of the CMS package:

• API endpoints for:
• Handling authentication from Zap
• Handling subscriptions for content and forms
• Polling for content and forms
• Get list of content types
• Get forms
• Handling saved hook configurations for content and forms
• Backoffice Dashboard
• Db operations service
• Migration plans for content subscription hooks and form subscription hooks
• Components for handling published content

Content of the Forms package:

• Components for handling form submissions
• Db operations service

CMS package is the principal one and mandatory, Forms act like an extension with less functionality. Forms-related use cases will be executed only if the Forms extension is installed.

Data flow between Umbraco and Zapier

As you can see in the above diagram the data flows mainly from Zapier, offering the user more flexibility by working primarily with one application, and a great improvement from the original plan that would have required jumping between the two applications.

Diagram walkthrough:

• Choose Umbraco App
• Choose Event: New Content Published or New Form Submitted
• Choose an account or pick an existing one - if this is the first time you create Zaps, you will be prompted to enter the username, password, base URL (URL of your website, without /umbraco ), and API key in case you would prefer the access to be handled using a key. The URL will, later on, be used for future requests.

• Choose a content type or form you want to add a subscription for
• Test trigger and create an action - based on the selected content type alias or form Id, a mock-up object with the matching properties will get displayed:

The properties will be available for embedding into the action steps you will define.

When a Zap is turned on, the subscription hook will be saved into the database and will be viewable in the Zapier Integrations backoffice dashboard:

Some key aspects to take into consideration:

• Identifier column refers to the entity - either content alias, or form’s Id.
• Entity Type column holds the “category” of the entity: Content or Form.

This structure is flexible and can be extended in the future with additional entities.

Turning off the Zap will remove the subscription hook registration from Umbraco. 

When content for a content type is published, or a form is submitted, the subscription hooks are looked up in the configuration tables, either by content type or form name. If matching record(s) is(are) found, a POST request will be sent to the attached hook URL with details of the published content or submitted form.

The subscriptions are stored in a single table called zapierSubscriptionHook with the following columns:

• EntityId → content type name or form Id
• Type → 1/2 values, where 1 = Content, 2 = Form
• HookUrl → Zapier webhook the subscription is using

One important thing worth mentioning is that in the case of an API key-based authorization approach, each package references a different configuration record in the website’s settings:

• CMS package: Umbraco.Cms.Integrations.Automation.Zapier.ApiKey
• Forms package: Umbraco.Forms.Integrations.Automation.Zapier.ApiKey

Conclusions

I would like to thank you for the patience and curiosity you’ve proven by reading this newly released integration. Hopefully, you will benefit from it in the future and take advantage of the full potential of automation using Umbraco and Zapier!

The minimum requirements for the packages are:

• Umbraco CMS 8.5.4 and Umbraco Forms 8.9.1
• Umbraco CMS 9.0.1 and Umbraco Form 9.1.0

You can find the packages by searching for "Zapier" in the backoffice package section or head over to the respective download pages for Zapier: Umbraco CMS Integration and Zapier: Umbraco Forms Integration - Enjoy!