HubSpot Workflow Connector 

Overview

Send and receive workflow data directly to HubSpot from within the HubSpot Workflow Connector.

Requirements

To use the HubSpot Workflow Connector, a FormAssembly user must:

• Be part of a Team plan or higher
• Have Content Management and HubSpot user permissions enabled for their login
• Have a HubSpot account
• Use the connector on a FormAssembly Workflow

Add the HubSpot Connector to your Workflow

To add the HubSpot Workflow Connector to a workflow:

• Select Add Step and choose Connector
• Select HubSpot

Set up the Connector Properties

Description Tab

Use the Description tab to add a Step Name and Step Description.

Authorization Tab

The Authorization dropdown lists all saved authorizations from all workflows owned by your user account. Select an existing authorization from the list or scroll to the bottom to create a New Authorization.

Create a New Authorization

• Select New Authorization from the Authorization dropdown list
• Enter a Name for the authorization
  • We advise using an easily recognizable name so that you’ll know which HubSpot environment and login credentials the authorization belongs to
• Click Authorize

Grant access to HubSpot

• Sign in with your HubSpot account credentials in the authorization modal
• Click Connect App in the authorization modal
• Click Save in the Authorization tab to store and apply this authorization to the connector

Edit an Existing Authorization

• Select a saved authorization from the Authorization dropdown list
• Click Edit to modify authorization settings
• When complete, click Save to apply the changes to the saved authorization, or click Save as New to save the modified authorization as a new entry in the Authorization dropdown list.

Manage or Delete Authorizations

• Click Manage to view the Authorizations page
• From the Authorizations page, an authorization can be revoked. When revoked, the authorization is deleted from all connectors. Ensure an authorization is not used in a live workflow before it is revoked, to prevent connector errors.

Configuration Tab

The Configuration Tab is where you define connector actions. Each HubSpot Workflow Connector can support multiple actions with the ability to pass HubSpot data between actions.

To start configuring the HubSpot Workflow Connector, start by selecting an Action and Record Type.

• Supported actions: 
  • Create a Record: create a new record in HubSpot
  • Update a Record: locate and update an existing record in HubSpot
  • Lookup a Record: locate an existing record in HubSpot
  • Upload a File: add a file to a HubSpot record
• Supported Record Types
  • All standard and custom object types
  • To show recently created custom objects, click Refresh Lists located at the bottom of the action cards

Create a Record

Create a new record in your HubSpot account.

Parameters

Configure an action to create a new record in HubSpot.

• To create a record in HubSpot, start by selecting Create a Record in the Action field within the Parameters section
• Select the type of record you want to create in the Record Type field
• When both Action and Record Type fields have selections, the Mapping and Return Variables sections are available within the action card

Mapping

Define which HubSpot fields should receive FormAssembly data for the selected record type when the record is created.

• Add additional HubSpot fields to be mapped with form data by selecting the Add Another button
• Optionally, select the Add all standard fields button to add all standard form fields contained in workflow forms
• In the Source field, select the FormAssembly data to be added to the selected HubSpot field
  • Form Field: data entered into a form field by a respondent
  • Value or Formula: static text, aliases, formulas, or calculations
  • Variable: custom variables created in other Workflow-native Connectors
• In the Destination field, select the HubSpot record’s field to receive FormAssembly data
• Delete mapped rows by selecting the red trashcan icon

Return Variables

Optionally capture the ID or URL of the newly created HubSpot record to be used in other HubSpot Workflow Connector actions or Workflow-native Connectors within the same workflow.

• In the Result From field, select ID or URL
  • ID: the ID number of the newly created record
  • URL: the URL of the newly created record
• In the Destination field, open the value dropdown to select Form field or Variable
  • Form field: assign the ID or URL value to a field in a workflow form
  • Variable: save the ID or URL as a custom variable to be used later in a HubSpot Workflow Connector action step or other Workflow-native Connectors within the same workflow
• Select Add Variable to add additional rows to save both ID and URL or save them with different Destination options

Update a Record

Locate a record in your HubSpot account and update the record’s fields.

Parameters

Configure an action to update an existing record in HubSpot.

• To update a record in HubSpot, start by selecting Update a Record in the Action field within the Parameters section
• Select the type of record you want to create in the Record Type field
• When both Action and Record Type fields have selections, the Lookup Query, Mapping, and Return Variables sections are available within the action card

Lookup Query

Set conditions to identify a matching record in HubSpot.

• Click Add Condition to create the first Lookup Query row
• In the lefthand dropdown, select the HubSpot field to inspect for a matching value
• In the middle dropdown, select the logical operator used to compare the HubSpot field to query value
• In the righthand dropdown, enter the value to be used to find a matching record. Select Form field, Value or Formula, or Variable to select the value type.
  • Form Field: data entered into a form field by a respondent
  • Value or Formula: static text, aliases, formulas, or calculations
  • Variable: custom variables and return variables created in other Workflow-native Connectors
• Add additional search criteria by selecting the Add Condition button
  • When more than one condition is present, select an option:
    • All conditions must be satisfied: all conditions entered in the Lookup Query section must be true in the matching record
    • Any condition must be satisfied: Only one condition entered in the Lookup Query section must be true in the matching record
    • Custom: Use boolean logic to customize the logical operation
• In the field If no records found, select what the connector should do if a match is not found using the above conditions
  • Skip this action: the remainder of the action is skipped and the next action or workflow step is started
  • End execution and return an error: the connector stops all actions, writes an error to the connector log, and error handling preferences are employed
  • Continue with dependent actions: the connector continues with dependent actions as if this action had been completed

• In the field If multiple records found, select what the connector should do if multiple matches are found using the above conditions
  • Skip this action: the remainder of the action is skipped and the next action or workflow step is started
  • End execution and return an error: the connector stops all actions, writes an error to the connector log, and error handling preferences are employed
  • Pick most recently modified record: the record most recently modified among the matching results is selected for the record update action

Example:  Updating a record and creating a new record if no match is found

Step 1: Configure the update record action and return the record ID as a variable.

Step 2: Configure a subsequent create record action using the variable as a precondition. If the variable is blank, then the record doesn’t exist and the precondition will be met. The create record action will then execute.

Mapping

Define which HubSpot fields of the identified record should be updated.

• Select the Add Another button to add a row to the Mapping section
• Optionally, select the Add all standard fields button to add all standard form fields contained in workflow forms
• In the Source field, select the FormAssembly data to be added to the selected HubSpot field
  • Form Field: data entered into a form field by a respondent
  • Value or Formula: static text, aliases, formulas, or calculations
  • Variable: custom variables created in other Workflow-native Connectors
• In the Destination field, select the HubSpot record’s field to receive FormAssembly data
• Delete mapped rows by selecting the red trashcan icon

Return Variables

Optionally capture the ID or URL of the newly created HubSpot record to be used in other HubSpot Workflow Connector actions or Workflow-native Connectors within the same workflow.

• In the Result From field, select ID or URL
  • ID: the ID number of the updated record
  • URL: the URL of the updated record
• In the Destination field, open the value dropdown to select Form field or Variable
  • Form field: assign the ID or URL value to a field in a workflow form
  • Variable: save the ID or URL in a custom variable to be used later in a HubSpot Workflow Connector action step or other Workflow-native Connectors within the same workflow
• Select Add Variable to add additional rows to save both ID and URL or save them with different Destination options

Lookup a Record

Look up a record in your HubSpot account and capture the record’s data.

Parameters

Configure an action to lookup an existing record in HubSpot.

• To lookup a record in HubSpot, start by selecting Lookup a Record in the Action field within the Parameters section
• Select the type of record you want to create in the Record Type field
• When both Action and Record Type fields have selections, the Lookup Query and Mapping section are available within the action card

Lookup Query

Set conditions to identify a matching record in HubSpot.

• Click Add Condition to create the first Lookup Query row
• In the lefthand dropdown, select the HubSpot field to inspect for a matching value
• In the middle dropdown, select the logical operator used to compare the HubSpot field to query value
• In the righthand dropdown, enter the value to be used to find a matching record. Select Form field, Value or Formula, or Variable to select the value type.
  • Form Field: data entered into a form field by a respondent
  • Value or Formula: static text, aliases, formulas, or calculations
  • Variable: custom variables created in other Workflow-native Connectors
• Add additional search criteria by selecting the Add Condition button

• In the field If no records found, select what the connector should do if a match is not found using the above conditions
  • Skip this action: the remainder of the action is skipped and the next action or workflow step is started
  • End execution and return an error: the connector stops all actions, writes an error to the connector log, and error handling preferences are employed
  • Continue with dependent actions: the connector continues with dependent actions as if this action had been completed
• In the field If multiple records found, select what the connector should do if multiple matches are found using the above conditions
  • Skip this action: the remainder of the action is skipped and the next action or workflow step is started
  • End execution and return an error: the connector stops all actions, writes an error to the connector log, and error handling preferences are employed
  • Pick most recently modified record: the record most recently modified among the matching results is selected for the record update action
  • Select all records: select all of the HubSpot records that match the above conditions

Mapping

Capture HubSpot field data of the matching record(s) to be placed in a form field (prefill) or stored as a variable.

• Select the Add Another button to add a row to the Mapping section
• In the Source field, select the HubSpot field within the matched record(s) to bring into the workflow
• In the Destination field, select the FormAssembly data to be added to the selected HubSpot field
  • Form Field: prefill a field in a workflow form with the selected HubSpot data
  • Variable: capture the selected HubSpot data as a custom variable to be used in a HubSpot Workflow Connector action or other Workflow-native Connectors
• Delete mapped rows by selecting the red trashcan icon

Upload a File

Upload a file to a HubSpot record.

Parameters

Configure an action to upload a file to a record in HubSpot.

• To upload a file to a HubSpot record, start by selecting Upload a File in the Action field within the Parameters section
• Select File in the Record Type field
• When both Action and Record Type fields have selections, the Send file field and Return Variables section are available within the action card
• In the Send file field, select a file upload field contained within workflow forms
• When the file upload field has been selected in the Send file field, the Mapping section is available within the action card

Mapping

Define the destination and details of the uploaded file in HubSpot.

• The field Destination folder path is required and will appear as the first mapping row by default
  • Files will be uploaded to HubSpot’s File Library
  • In the Source field, select ValueorFormula and enter the name of the desired destination folder within the File Library
  • To target nested folders, enter the path (i.e. parent folder/sub-folder/sub-folder)
  • A folder will be created if a matching folder name does not exist
• Add additional HubSpot fields to be mapped with form data by selecting the Add Another button
• In the Source field, select the FormAssembly data to be added to the selected HubSpot field
  • Form Field: data entered into a form field by a respondent
  • Value or Formula: static text, aliases, formulas, or calculations
  • Variable: custom variables created in other Workflow-native Connectors
• In the Destination field, select the HubSpot record’s field to receive FormAssembly data
• Delete mapped rows by selecting the red trashcan icon

Example: Associate file upload to object by using Notes

Step 1: Configure an Upload a File action and save the ID as a variable in the Return Variables section.

Step 2: Configure a subsequent action to create a Note. Map the ID variable to the field Attached File IDs and return the Note ID as a variable.

Step 3: Configure a third action to create or update a record and map the Note ID variable to an association parameter, OBJECT_TO_NOTE

Return Variables

Optionally capture the ID or URL of the uploaded file to be used in other HubSpot Workflow Connector actions or Workflow-native Connectors within the same workflow.

• In the Result From field, select ID or URL
  • ID: the ID number of the updated record
  • URL: the URL of the updated record
• In the Destination field, open the value dropdown to select Form field or Variable
  • Form field: assign the ID or URL value to a field in a workflow form
  • Variable: save the ID or URL in a custom variable to be used later in a HubSpot Workflow Connector action step or other Workflow-native Connectors within the same workflow
• Select Add Variable to add additional rows to save both ID and URL or save them with different Destination options

Action Preconditions and Dependencies

Determine when actions should run and chain actions together by using action preconditions and dependencies.

Action Preconditions

Preconditions determine whether a connector action runs or is skipped. They replace the skip-if formulas of the form-level HubSpot Connector, and they work inversely. In the form-level HubSpot Connector, if a skip-if formula returns true, the connector step is skipped. If the skip-if formula returns false, the connector step executes. Alternatively, with Preconditions in the Workflow-native HubSpot Connector, if there are no preconditions added, the action will always execute. If preconditions are added, then the action will only execute if the defined preconditions are met.

To add a precondition to an action:

• Open the action menu by clicking on the down arrow next to the Close button
• Select Add Precondition
• Select a Form field, enter a Value or Formula, or select a Variable value
  • The action will only run if the selected or entered condition is True. 
  • If multiple conditions are added, you may specify whether you want the action to run if all conditions are satisfied, any condition is satisfied, or by using custom boolean logic. For more information about custom logic, refer to the Set Condition section of our Conditional Ruleset article.

Action Dependencies

Actions with preconditions can be linked to dependent actions by setting action dependencies. Dependent actions run if the prerequisite action runs, and dependent actions are skipped if the prerequisite actions are skipped.

To add a dependency to an action:

• Open the action menu by clicking on the down arrow next to the Close button
• Select Set Dependencies

• In the Run after field, select the action(s) that are the prerequisites for this action to run. 

Repeated Content

When repeated fields are mapped in the HubSpot Workflow Connector, the connector can be configured to properly handle the repeated values.

When a repeated field is mapped in the HubSpot Workflow Connector’s mapping section, the Repeated Content section is available. 

• Add a record for every submitted field tells the connector to repeat the action for each repeatable section or once for the workflow response
  • Select Workflow to have the action run a single time regardless of the repeated content.  Values will be concatenated.
  • Select a repeatable section to have the defined action repeat as many times as the respondent repeated the section

When a repeatable field is mapped in the HubSpot Workflow Connector’s Lookup Query section, the option Select all records in the field If multiple records found can be used to update all repeated values that are matched in HubSpot.

Prefill and Variables

HubSpot data can be passed to forms or stored in variables to use elsewhere in the workflow.

Prefill

Using a Lookup a Record action, HubSpot record data can be retrieved and placed in a form field within the same workflow.

To prefill a form using the HubSpot Workflow Connector:

• Configure a Lookup a Record action to locate a desired record
• In the Lookup a Record action’s Mapping section, select the HubSpot data you wish to retrieve from the matching record in the Source field and the form field you wish to prefill in the Destination field

Variables

HubSpot data can be stored in variables and passed to additional HubSpot Workflow Connector steps and other Workflow-native Connectors.

To store HubSpot data as a variable and use it in the workflow:

• Configure a Lookup a Record action to locate a desired record
• In the Lookup a Record action’s Mapping section, 
  • Select the HubSpot data you wish to retrieve from the matching record in the Source field 
  • Create a variable in the Destination field by selecting Variable from the value type dropdown and entering a custom variable name

Example: Create a new lead and associate the lead with a contact

Step 1: Lookup a contact and save the contact’s Record ID and email as variables.

Step 2: Create a Lead and map the email to the Lead Name and contact ID to LEAD_TO_PRIMARY_CONTACT

Action Name and Description

Each action can be given a custom name and description.

Action Name

Click on the action name to customize the name of the action.

Action Description

To add a custom description of the action for ease of reference, open the Action Menu by clicking on the down arrow next to the Close button, and select Add Description.

Copy and Delete an Action

Actions can be copied and deleted using the action menu.

Copy Action

Actions can be quickly duplicated with the Copy Action button.

To copy an action: 

• Click on the down arrow next to the Close button
• Select Copy Action

All configuration details are copied into a new action within the connector’s Configuration tab.

Delete Action

Actions can be deleted with the Delete Action button.

To delete an action: 

• Click on the down arrow next to the Close button
• Select Delete Action

Error Handling Tab

By default, if the connector encounters an error, the workflow terminates. To override this behavior, you can configure the error to redirect the workflow to another step by making a selection in the Upon Connector Error, Go To This Step… dropdown menu within the Error Handling tab.

You may also create a custom error message to display to your respondent. If a custom message is not added, the default connector error displays. To include the default message with your custom message, select the checkbox.

Connector Logs

Each time the HubSpot Workflow Connector runs, logs are published to describe the details of the connector actions.

To review HubSpot Workflow Connector logs:

• While in the workflow builder, click on the Responses link on the left-hand navigation menu
• Select a response and click View under the Actions column
• In the upper right-hand corner of the response details page, click View Logs