Leveraging HubSpot's APIs and Workflows | Developer Day 2021

Next up we have a couple of presentations from the community.

Yep. First up we have Parag from Unifiq talking all about workflow extensions, followed by Ola and Roman from Cohorta, who actually made an app specifically for Dev Day.

Hey everybody, thank you for this opportunity and excited to be here. So yeah, let's get right into it. Today I'm going to be talking about custom workflow actions. We want to learn how to create custom workflow actions and show you a specific use case and app that Unifick has. So we'll cover an introduction to what they are. We'll also cover their example and how to build custom workable actions. And lastly, the things you need to be careful about when you're building those workflow actions. Why listen to us Unifig has been part of the HubSpot Marketplace since 2014. We integrate Shopify, Magento, WooCommerce and BigCommerce with HubSpot. We have four certified integration apps on the HubSpot App Marketplace and four dynamic coupons apps as well. Let's get into it. Here's the introduction. So coupon workflow actions are a system to call external apps or APIs that can perform tasks outside of HubSpot. You know, they're an opportunity for app developers to create their own workflow actions. They're a much better user experience than webhooks. I'm sure as a developer there have been many instances where you've had to explain how to use a webhook to a customer and there are all sorts of issues with copying pasting incorrectly and things like that. There are full substitute for webhooks as well and the developers get their wish to be as creative and impactful as possible and while still making the user experience extremely well for your customers. How do hubsite users benefit? So in today's marketing stack there's an ever growing list of apps that need to work together. The end customer's journey can be just disjointed with too many apps that don't talk to each other and the workflows actions are a way for us to bump to make that easier. Non technical users have a big challenge when you're trying to set up automations, but with custom actions they can get their work done much faster without having to wait from a developer. They can integrate multiple tools as they please. Let's go into the use case. The goal of your use case is to increase abandoned cart conversion rate with a dynamic coupon delivered to the customer at the right time. What we're talking about here is personalization at scale. Once you create a workflow, that workflow will always run unless you turn it off. And we want to use the events in the shopping cart that are happening to trigger the workflow. So it's a very personalized coupon that can be sent. Let's get into it here. We're configuring a coupon rule instead of the Unifiq app. We've created a Halloween abandoned cart discount and there are many configuration options here, as you can see. Now, one reason we did it this way is because custom actions should be very easy to use and have very few options inside of HubSpot workflows. You can add lots of options, but it would be a bad user experience. So we want to keep that part of it minimal. So it's simple on the HubSpot side to use. So we had to show the options in here. Okay, let's build a workflow here. We're targeting abandoned carts with customers who spent less than $50. We want to personalize the value of the coupon to match the needs. So for example, if somebody spent $1,000 with you over their lifetime, you don't need to send them a coupon. Instead you, you should send them engagement emails. But this is a way for again, hubsite user to really customize and personalize how you send discounts. And of course your custom action will have its own values. In our example, we're going to add a custom action here. And on the right side you can see an action that we can choose. Shopify Dynamic Call Coupons is an app and here's an action that we've created. So today we'll be discussing how do we create this option inside of the workflow builder. Once an action is added to the workflow, there's an option to configure it. There's an opportunity to configure it. That Halloween abandoned cart discount that we've created from Unifiq into this coupon section. This is a coupon rule and it's a property that we define when we create the action, which we'll discuss later. Create a coupon action has been added to the workflow. So this means, you know, we fetched options from Unifick and we've also configured the coupon so now it's ready to use and it's, oops, skipped a step. I do want to discuss an additional event we've added here. It's delay until event happens. We want to send an email, but of course we Want to make sure the coupon actually exists in HubSpot before we send it. So property value has changed. This is something called blocking. We don't want to send an empty coupon, of course, because it may take some time to get to Shopify or whichever store you're using and generate the coupon there and sync it back into HubSpot. So this is a blocking action. We'll discuss going to the more details about blocking actions you can you can also block with the API directly. Now let's get into how do we build a coupon workflow action. Some important terms A custom action is actually what we've been talking about. How do we actually add that to a workflow? And a callback is an execution. So every time HubSpot sends your app a request to create the coupon or execute our action, it is assigns a unique callback ID so that you can do some additional work on that callback. We'll discuss that a little bit later. Configuring actions so when the user is adding your action to the workflow, this is an opportunity for the user to configure what that action should do. Field option Fetches these are when your app is actually fetching those options from your app to display to be configured on the action. For example, that Halloween example I used action execution requests, the request to app to perform the actually useful tasks. When a workflow triggers our action, this is the execution of that action. There are two types of API calls if we break it down. Field option fetches and action execution requests. These allow you to separate out what your app does, but there is also customizing payload functions. We won't cover these today, but they're very complex ways to that HubSpot allows you to customize what should happen when these requests happen. Now let's get into defining the action. Mainly we want to define what the action should look like, what labels they should have, and it's explainable to the user and understandable to the user. And also we want to define what properties we want to show. So if there are dropdowns on the action. So for example, we selected a coupon rule id in our example we need to select a specific Halloween coupon code to run. This is the request to fetch option. So showing by example, we want to populate this dropdown so there's an opportunity for when the customer adds your action to the workflow. An API call is made to your app to request these options. Of course, now your app needs to respond with those options. In our example, I'VE responded with Halloween abandoned card discounts and demo 10% off. These are the two options to display, and the customer can configure those. Now, when your app receives an execution request, we need to of course sync that, actually run that request. We need to generate the coupon, send it to create it in Shopify or whichever store you have, and then sync it back into HubSpot. For you to do that, we need to know the what portal ID it is. Ideally, if you're an app, you're supporting multiple portals. Which action definition is it? Specifically which object it is and what is the object? The contacts email address. So if you're running with this for contacts, what is the email address? And of course input fields. So you need the value that the customer selected. In an example, it was the Halloween discount codes. Blocking actions now, this is the if your app receives a coupon. Sorry request to generate a coupon, it needs to decide if first we should wait for your action to complete before continuing or should we continue anyway? You can specify an expiration time as well. So the workflow can just continue. If your workflow is running and your app does not respond for a long time, the customer could be stuck in that workflow. So we don't want that. And you can customize this as you need. So here's some gotchas. If an update we want to update existing custom actions. If there's an already instance installed for a particular portal in a workflow, then we cannot update that one. You have to create a new action before we can do that. Blocking calls so as we discussed before, you can allow the user to block or you can block it yourself, the action from running. So when your app receives it, as we saw, there are some API calls that we can resume a block call or actually allow blocking by the user. In our case, we allow blocking by the user because we waited for a property to be updated before we continue the workflow. We of course want to verify the request source. So if you get a API request from HubSpot, we need to know it's actually from HubSpot. If it's from some other source, we don't want to run that. So we want to make sure that that signature matches scalability and reliability. Last thing we'll talk about is better make sure that your app can handle the load. So if a customer can load in as many enroll as many contacts as they want into a workflow, you may receive thousands or hundreds of thousands of request very quickly from HubSpot. Of course, if your apps crashes in that period of time, then the workflow will stop or may not continue depending how you set up blocking. But if you can build it scalably and reliably, there should be no issue. Workflows are very often time sensitive and your application should always respond quickly, so you'll have to build some engineering some way to handle the load. Quick Summary and Overview we discussed how custom workflow actions are powerful and why they're valuable to users. HubSpot users don't need to write any code to run them. HubSpot has made it very easy to build custom workflow actions. There's just a few API calls you need to create and you have to make sure that of course your systems are reliable. We have, like I said, four different diamond coupons app available from Magento, Shopify, BigCommerce and WooCommerce. I've also created a use case page just different ways you can use diamond coupons. You can visit that on our website unifiq.com you can also search for UNIFIK on the HubSpot App Marketplace and you can find me on the Slack channel for developers for HubSpot. With that I will hand off the presentation to Ola and Roman. They're going to be discussing building integrations that enhance the HubSpot CMS. Thank you very much.

Thanks Parag. In a minute we will share our screen.

Hello everybody. Thanks for having us here today. A special thank you to HubSpot team for inviting us this year. We are super excited to have the chance to talk at HubSpot Developer Day 2021. Let's start by introducing ourselves. I am Olya Goza, Designer, Developer and Design Partner at Cohorta and my co presenter Roman.

Thanks Olya. I'm Roman Kozak, Full Stack Developer and Managing Partner at cohorta. Today we are going to talk about how to enhance the HubSpot CMS experience. Our talk is particularly relevant to HubSpot teams creators. For that we are going to present new HubSpot integration. Let's get started. Olya, would you mind over your presentation?

Sure. We have organized this talk in the following way. First a few words about us as a team. How we have come up with an app for this presentation and how the app works. Then guide on how to build such HubSpot app and finally some time to answer your questions before getting into code. Let me say a few more words about us. We are a team of two who builds websites and integrations for the HubSpot marketplace. We also enjoy working with clients on challenging solutions Overall, we each have 10 years of experience in design and development with numerous projects. Before we were working on themes and templates for Shopify and WordPress, but now we are into HubSpot development for more than two years. Both of us love working with it and our latest HubSpot products are web Push and Simple. The first one is a listed HubSpot integration for marketers to send push notifications and the Second is the HubSpot theme for content creators. So what we have prepared for the audience today?

Roman Just for this event we have created a brand new integration called Theme. It streamlines the process of content creators setting up a demo of HubSpot themes. With this app, HubSpot developers will be able to distribute demos way more easily. Integration reduces the number of steps needed for clients to check out themes inside their own accounts. Theme can be used as a tool for marketing purposes for theme developers to gather email and feedback on the installation process. Let's now take a look at how the app works. Olya, would you mind to tell us about it?

Sure. In short, Theme combines CMS and API to transfer the theme files from the developer side to the authenticated user account. Before going into details of development, let's watch a quick screen recording to grasp a full picture of what we can build together.

The screen recording of the demo takes less than a minute. Check it out. You may see that end user authorization through the HubSpot API. And now you may see the App Success page, the link to the demo page created at the user's HubSpot account on this slide. Here's the demo link of the app itself deployed on Firebase. Check this out on your own. Interact with the app after the presentation. Dennis, could you please pin this link in the chat, please?

I've added it to the chat after.

Seeing the app in the action. Let me tell you how to build something like that. We are going to share all the programming logic behind this.

But before that it's worth mentioning that the full code base is on GitHub. There you can find the readme file with installation guide and comments in the code files which explain all their main programming steps. Also, the code is free to use. As you see it fit back to.

The process of building the app. Here are three main steps we are going through to build this integration. How did you start it?

Danola on this slide there is a code that creates a Node JS server using popular JS Framework Express. Once we have a server, we need HubSpot API credentials to authenticate end users and use API to stop demo theme for that we need to register a new HubSpot app. In order to create a HubSpot app, you'll need to have an app developer account. You can create HubSpot apps only from these accounts. This process is pretty simple. To create an app, all you need is a name and redirect URL. So what's next? Roma?

Next we can move to build an app logic. On this slide you may see ExpressRoute where all AppLogic is placed. First step is to authenticate the end user. Once the authorization is done and we get an access token, we can go to uploading the theme.

Yes, we can upload a zip archive of the theme to the HubSpot account of the authenticated user. We'll need to use the CMS source code API endpoint shown on this slide. This new API which allows uploading different files to the design manager. More details on this API in HubSpot documentation and link included. Once the theme archive is uploaded, it's ready to be extracted. We are going to use the CMS source code API endpoint shown on the slide. This API allows extracting a zip file in the user's design manager. For uploading and extracting, we have used a single post request for each which is possible with a new version of API. More on this read in HubSpot documentation so finally we can create a demo page for end user, right Roman?

Yeah, we are creating a demo page once the archive is successfully extracted. For this we need the CMS Pages API endpoint shown on the slide. This API allows creating and publishing site pages in the user's account. Currently this API in beta, however we hope it will be officially released shortly. From what we may say, for now, it's worked pretty smoothly. More on this read on HubSpot documentation link included after all the work on the server side, we may display something to the end users. So it's time for them to look at the demo page that our code has created for them in their own HubSpot accounts. Looks like that is it, right?

Olya Pretty yes, these were the main steps to building something like themy. These recently released APIs really make life easier and make such an app possible to build. At this point our app has done its job. If we have time, let's have a look at few edge cases.

There are three different content types in request handlers. Each of these content types requires a specific data format, so we need to format the data accordingly. Also be cautious of name duplication conflicts when we create something via API and such File or page already exists in a user account, it leads to errors that need to be foreseen in the app beforehand.

Also, here are the links we have been referring to during our talk. The presentation will be shared with all the attendees, so we will get a chance to get into details.

Thank you for everyone for being with us today.

In case you would like to connect, you may find us@horta.com to talk HubSpot development and more. So, ready to answer your questions.

Thank you guys. This is good stuff. Nicole, let's go to the Q and A. What do you say?

Let's do it. Anything to you, Chris.

I'm just going to start from the top right here. Okay. So Sandra asked a while back. This is going to be for Parag, I believe. Can we go back to blocking actions? Do they make it more dynamic for the user? What kind of actions could be created?

Yeah, so blocking actions are a tricky thing. If your app is blocking the action, of course the workflow will wait. There are ways to get around that. Of course, if we can allow the user to define through HubSpot functionality how to wait, that is the preferred method. Because when an action waits, the user has really no indication of what's happening other than that the action is waiting. So as developers, we have to take care of edge cases of what can happen and yes. Are they dynamic? Of course, because your action is dynamic, it should be dynamic. But depending on what your app does, the answer could be different how you block. So take a look at the documentation. It's very clear there's a callback ID as well. That's very important for unblocking actions.

And let's go with Ola and Rome on this one. What were your biggest challenges? Challenges, blah blah in building these apps? Anything you learned in the process?

Biggest challenges?

That's a good question.

Yeah, I would say that the biggest challenge to start when you start in the flow, there are no challenges like steps after steps after steps and this get more excited, more excited and the more you head into the finish. So biggest challenge is to start.

Parag. I'd ask the same question of you. Challenges or you know, go for it.

Yeah, challenges. I mean reliability is the biggest one that everybody needs to worry about. Have a plan for how you deal with that, you know, a queue based system to receive those requests and respond to them quickly or how do you actually in regards to those blocking calls? I think that's probably the most difficult thing for every app. How would you deal with that? If there's app has to Respond back. Then of course customer support, you have to help your customers hubs that users understand how it works and you have to really great job of putting a knowledge base together and be able to respond at scale because if many if your app is popular you could have thousands of customers. And if you are a developer, especially if a single developer, you have a good process to provide the support.

Cool.

And Roman, this one I think is for you from Ronald. He's asking why are you not using the Node JS library from HubSpot?

I was using it on purpose to make clear request and see in details how it works and to make it possible for educational reason to experiment so you can see all jsons, all errors, all is transparent. So it's educational purpose.

And moving on over to you again Parag, Andre asks can we use HubSpot serverless functions to build custom workflow actions?

You could because the custom actions are really. So there's actually multiple ways to talk about serverless in this context I believe you're talking about HubSpot serverless so there's actually a custom code actions which is a different type of workflow action and that's probably the better method to work with serverless but actually it doesn't take anything away, it's just a different way to do it.

Kieran also asked of you Parag, what field types are supported in workflows?

I believe it's string or options. I'm not sure if specifically the documentation doesn't say about different types other than those, but it's up to you to try it. It's fairly easy to try it and see what works.

And there's this guy named John McLaren who asked a question here and we'll start with parags. I believe Ola and Roman answered this, but how long have you been building.

Integrations with HubSpot 2014? Very long time. Know the API very well and have gone through the different changes in the API. But I love the new API. You guys are doing an awesome job on the new version. Version three and learning and just trying to use it. Especially with some of the some of them have postman access. I think that really makes it easy for developers.

I would like to add my two cents to it please. I think that it's a bit frustrating that API changes in the process when we are working on it, but still the changes are great and we are loving it.

Yeah, I will take that.

Well the worst version of that is there are no API changes.

If I don't know much about just the APIs in general, where do you guys suggest I get started on learning about this? What's my baby steps? What would you guys suggest?

I would suggest to go to HubSpot.

Documentation this new feature to play with different APIs on the site. When you can put portal EPIC API key and just send the request and get JSON in the response, it's very cool and intuitively easy to understand what's going on. So this HubSpot documentation with interactive tools, pretty much what is needed.

Cool. John McLaren character asked one more question. If you could ask for anything from the HubSpot team to make your work easier, what would it be? And that's not a loaded question. Get it out there. Prav, you've been here for 2014, so we'll start with you.

Well, I mean, you guys are already doing a great job. I mean the cli, especially for CMS development is awesome. You know, some of the postman. I think all of the action, sorry, all the endpoints should have a postman capability. So, you know, just click a button, enter the postman requests and that will get us much faster getting started. Much faster. And I would say migrating more of the old documentation to the new or specifying. Exactly. Okay, which version should we follow? Because if you're on the old version, the custom example custom workflow actions used to be named workflow extensions. A good connection between those would be good so that developers don't accidentally develop the old version.

Ola Roman, you got anything to add to that?

Oh yeah.

I'll start. I work a lot with CMS right now and I'm using CLI in the process of. I'm very grateful for all the improvements to local development and for great documentation and especially helpful error messages. They are more informative than you get, for example in Design Manager in HubSpot. So I love working with it.

I would ask a new endpoint which allows us to to post something in head tag or at the body closing body tag. Because we can post for the page individually, but we have not such endpoint for global posting.

Sounds good. Nicole, I think we can wrap it up here. What do you think?

I think so. Thank you to our presenters today and to the audience. We will see you in the next session.

See you.

Thank you.