HubSpot Module Basics – StepsLast Updated: 12/05/2018 Introduced in Version: v4.1
The HubSpot module in Decisions allows you to access and update your HubSpot data using steps in a flow that hide the complexities of working with the HubSpot API directly. Before using these steps, you must install the HubSpot module and set up an authentication token. Instructions on how to do that are listed here: HubSpot Module Basics – Setup.
Supported HubSpot Features
Currently, the HubSpot module provides steps for working with Contacts and Companies.
- Create Contact
- Get All Contacts
- Get Contact By Id
- Get Contact By Email Address
- Get Recently Created Contacts
- Get Recently Modified Contacts
- Update Contact
- Create Company
- Get All Companies
- Get Company By Id
- Get Recently Created Companies
- Get Recently Modified Companies
- Update Company
The module also provides Advanced steps which allow you to send API calls to HubSpot and receive JSON that you can process.
NOTE 1: If you receive an authentication error during any of these steps, the HubSpot OAuth token you created may have an expired Access Token. To correct this, under System > Integrations > OAuth > Tokens, select your HubSpot Token and choose the Refresh Access Token action.
NOTE 2: If the Get Company By Id, Get Contact By Id, or Get Contact By Email Address are passed an Id or Email Address that isn’t in HubSpot, those steps will return the HubSpot error as an exception. For those steps, you can enable the Add Outcome for Exception checkbox under Outcomes and test whether the Exception Full Trace contains the text “contact does not exist” or “company does not exist”.
Example 1: Displaying Companies
- Create a Flow.
- In the Steps browser, locate the HubSpot entry under Integration.
- Under HubSpot, select the Get All Companies step and add it to the flow. Connect the Start step to it.
- In the Properties tab, set the Inputs as follows:
- You can set the Name of the Output to CompaniesList or something similarly descriptive, but this is optional.
- Add a Show Form step to the flow, and connect the Done path of the Get All Companies step to it.
- In the Form, add a Close button and a Data Grid.
- In the properties for the Data Grid, for the Input Data Type, choose All/Search… Then, type “Company” into the search box and select “Company [Decisions.HubSpot.DataTypes]” in the results.
- Save and Close the Form. Edit the Form’s Input Mapping to connect the output of the Get All Companies step to the grid.
- Connect the Close button to the End Step.
Example 2: Custom HubSpot Properties
HubSpot allows the creation of custom properties for Contacts and Companies. By default, the HubSpot steps in Decisions only receive a default set of properties from the HubSpot API for each Contact or Company. If there are additional properties that you require, you can specify them in the Extra Properties To Get input on the appropriate steps. Here is an example of a Get All Contacts step with a Constant list of Extra Properties To Get:When the steps runs, each of the Contact results will contain the lifecyclestage value in the Properties array for that result.
Reading and Writing Extra Properties
The HubSpot module provides a set of steps for reading and writing property values, even custom ones, in a simple fashion. These steps all operate on an individual Contact or Company.
- Get HubSpot Date Property
- Get HubSpot Number Property
- Get HubSpot String Property
- Set HubSpot Date Property
- Set HubSpot Number Property
- Set HubSpot String Property
While the ability to retrieve this extra information is useful, it might be even better if the entities you are working with were in a form that allowed you to easily map their properties between steps in Decisions. This example shows one way to accomplish that.
- In the Datatypes/Integrations menu, choose User Defined Types > Defined Data Structure
- Name it “Contact”, and fill in the various properties that you will need, including any extra custom ones. Then click OK. This data structure is useful because it contains exactly the properties you want without the need to include an extra step or look them up in an array.
- Create a flow, and add a Get All Contacts step from the HubSpot entry under Integration.
- Add a Run Flows For List step to the flow and connect the Done result from Get All Contacts to it. Note: not the “Run Flow For List [Batch Processing]” step.
- In the Data area of the properties for the Run Flow For List step, set the Input Type and Output Type.
- Click the Edit link under the Item Workflow property to set up the flow that will process each Contact.
- In the new flow editor that appears,
- Add a Create Data step.
- In its Properties, click Show Editor under the Data Definitions.
- Define an object of your Defined Data Structure that will be returned from the flow.
- Add a Data Pair To Object step.
- Connect the Create Data step to it and connect it to the End Step.
- Set up the Properties for the Data Pair To Object step
- The Data Pairs value comes from the Properties array of the Input entity for this flow.
- The Target is the entity that the previous Create Data step created.
- The Source Names are the property names as they appear in HubSpot that you want copied into your output entity.
- The Destination Names are the property names in your Defined Data Structure that you want copied into. The order must match the order in the Source Names.
- Save and Close the flow.
- Edit the Input Mappings for the Run Flows For List step and connect the list of Contacts from the Get All Contacts step to the Input List of the Run Flows For List step.
At this point, the output from the Run Flows For List step is a list of entities in an easy to use form, ready for additional processing.
Handling Large Output
By default HubSpot only returns 100 Companies and 20 Contacts when asked for lists of them. If you have more than that number, then any ones past that limit will not appear in the output of the HubSpot module steps. There are two properties on those steps which can help manage retrieval of large amounts of data.
The Count Property
The Count property sets the number of results that HubSpot should return. In the previous examples, we set the Count property to Null or Ignored, which caused the HubSpot steps to request the default result count. Setting the Count to a higher number than the default will cause HubSpot to return additional data.
Note, however, that HubSpot sets a maximum of 250 Companies and 100 Contacts from a single API call. If you need to retrieve more information than that, you will need to request it in batches.
The Offset Property
To request the first batch of results, set the Offset property to Null or Ignored. To request the next batch, set the Offset property to the ID of the last entry in the array that was returned from the previous batch. HubSpot will return the next group of results (an amount equal to the Count value) that occurs after that ID in its database.