HubSpot Module Basics - Steps
  • 03 Jun 2022
  • 6 Minutes to read
  • Dark
    Light

HubSpot Module Basics - Steps

  • Dark
    Light

Article summary

Overview

The HubSpot Module in Decisions allows users to access and update HubSpot data using steps in a Flow that hides the complexities of working with the HubSpot API directly.  

In order to use the HubSpot steps, the HubSpot Module will need to be installed. To learn how to install modules, click here. Also, an Authentication Token needs to be configured. Learn how to set up HubSpot for use in Decisions here.

The HubSpot Module provides steps for working with Contacts and Companies. It also provides Advanced steps that allow users to send API calls to HubSpot and receive JSON that can be processed.

If a user receives an authentication error during any of the steps, the HubSpot OAuth token that was created may have an expired Access Token.  To correct this, under System > Integrations > OAuth > Tokens, select the HubSpot Token and choose the Refresh Access Token action.

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, 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 A: Displaying Companies

  1. In the Designer Project, click CREATE FLOW on the Global Action Bar and select Flow. Name the Flow and click CREATE.
  2. On the Start step, click the Done path and navigate to Integrations > All Integrations > HubSpot. Select the Get All Companies step and click ADD.
  3. Under the INPUTS category on the Properties panel, set the Count, Extra Properties To Get, and Offset fields to Null. Click Unknown next to Token Id and select Constant. Click the dropdown list and select HubSpot Token.
  4. Click the Done path on the Get All Companies step. Select Show Form and click ADD.
  5. Click PICK OR CREATE FORM from the Properties panel. Then, click CREATE.
  6. Click Form. Name the Form (Display Companies) and click CREATE.
  7. Configure the Form to have a Data Grid component and Button component. In the Type field under INPUT DATA, enter "company" and select Company [Decisions.HubSpot...]. Click Save to save changes and close the Form Designer.
  8. With the Form selected, click Edit Input Mapping.
  9. Click and drag on the Get All Companies_ Output {Company[]} and connect it to Data Grid. Then, click OK.
  10. Connect the Close path to the End step. Click Save to save changes.







Connect the Close path to the End Step.

HubSpot_Steps6.png



Running the Flow will display a list of the companies that are defined in the HubSpot account.


Example B: 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 additional properties are required, they can be specified 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 run, each of the Contact results will contain the lifecycle stage value in the Properties Array for that result. 

HubSpot_Steps9.png

Example: 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 would be better if the entities being processed were in a form that allows the user 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 needed Properties, including any extra custom ones. Then click SAVE. This Data Structure is useful because it contains the exact wanted Properties without the need to include an extra step or look them up through an Array.


Next, from a Designer Folder, 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, and the Run Flow For List step's Done path to the End step. 

Though similarly named, the step referenced above is 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.

The Input Type should be "Contact [Decisions.HubSpot.Datatypes]"

The Output Type should be the custom Defined Data Structure created in steps 1 and 2.


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. 

From its Properties tab, click Show Editor under the Data Definitions.

Define an object for the Defined Data Structure that will be returned from the Flow, by Constant mapping values.  CLOSE the panel to save the object and return to the Flow Designer. 


Next, add a Data Pair To Object step; connect the Done path to the Data Pair To Object step, and the Data Pair To Object step to the End step. 

Set up the Properties for the Data Pair To Object step as follows: 

  • 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 a user wants to be copied into the output entity.
  • The Destination Names are the property names in the Defined Data Structure that a user wants copied into.  The order must match the order in the Source Names.

Next, Save and Close the Flow.


From the Previous Flow's Flow Designer, Edit 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 those items. If more than that number is required, then any objects 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 in retrieving large amounts of data.

The Count Property

The Count property establishes the number of results that HubSpot will return. In the previous examples, setting the Count property to Null or Ignore causes 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.

If more information is needed than HubSpot's set maximum of 250 Companies and 100 Contacts from a single API call, users must 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.


Was this article helpful?

What's Next