TIBCO Scribe® Online Connector For HubSpot
Use the TIBCO Scribe® Online Connector for HubSpot to create HubSpot source or target Connections in Integration and Migration Solutions. You can also use the HubSpot Connector to integrate Contact, Company, Deal, and Task data between HubSpot and other datastores, synchronize List and Email Campaign data, and submit Form data.
Possible use cases for the HubSpot Connector include:
- Integrate your HubSpot marketing contacts with other contact management systems in your organization.
- Update HubSpot contact life cycle stages with input from other business applications.
- Export marketing lists from HubSpot to any other business application or data endpoint.
- Integrate HubSpot company and associated contacts into your CRM application.
- Report on Company revenue based on associated HubSpot closed won Deals.
- Create a client in a project management system when a HubSpot Deal is marked as closed won.
- Synchronize HubSpot Deals with your CRM application.
- Update calendar events in another application when a HubSpot Task is created, updated, or deleted.
- Submit contact data based on the fields contained in a Form.
Connector Specifications
Supported | |
---|---|
Agent Types |
|
On Premise | X |
Cloud | X |
Replication Services |
|
Source | |
Target | |
Integration Services |
|
Source | X |
Target | X |
Migration Services |
|
Source | X |
Target | X |
Maps |
|
Integration | X |
Request-Reply | X |
Message |
Note: This Connector is available from the TIBCO Scribe® Online Marketplace. See Marketplace TIBCO Scribe® Certified Connectors for more information.
Supported Entities
TIBCO Scribe® Online currently supports the following entities and operations for the HubSpot connector. Select a linked entity name for additional information on using that entity with TIBCO Scribe® Online. For a list of additional operations by entity see Special Operations.
Standard Operations
Entity | Query | Create |
Update | Delete | Upsert |
---|---|---|---|---|---|
X |
X |
X |
X |
|
|
X |
X |
X |
X |
|
|
X |
X |
X |
X |
X |
|
X |
X |
X |
X |
|
|
|
|
|
|
|
|
|
X |
|
X |
|
|
X |
X |
|
X |
|
|
X |
X |
X |
X |
|
|
X |
|
|
|
|
|
X |
X |
X |
X |
|
|
X |
|
|
|
|
|
X |
|
|
|
|
|
X |
|
|
X |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
X |
|
|
|
|
X |
X |
X |
X |
|
|
|
|
|
|
|
|
X |
X |
X |
X |
|
|
X |
X |
X |
X |
|
|
X |
|
X |
|
|
|
X |
|
|
|
|
|
X |
X |
X |
X |
|
Special Operations
Entity | Operations |
---|---|
Update/Insert |
|
OptOut Update/Insert |
|
Add Remove |
|
Update/Insert |
|
Submit |
|
Update/Insert |
|
Request |
-Send -Add |
The connector supports two Add blocks that are used in different circumstances.
-
There is an Add block that only supports the ContactListMember entity. That block is used to add leads to lists.
-
The second Add block is used in conjunction with the Send block to support Hierarchical data allowing you to add multiple nested records in a single parent record. The hierarchy can extend down multiple levels, for example, a record containing a Country or parent, States or children, and Cities within each state or grandchildren.
Setup Considerations
To use the HubSpot Connector, you need a trial, paid HubSpot Professional, or Enterprise account. For more information, see the HubSpot website.
In addition, to create and use a HubSpot Connection, you need your own HubSpot user account. If needed, ask your HubSpot Administrator to create a user account for you. Refer to How to add users to your HubSpot account in the HubSpot Knowledge Base.
Note: HubSpot OAuth tokens can become invalid if any one of the configurations below is used. Best practice is to use a single HubSpot user account and only one HubSpot Connection in TIBCO Scribe® Online per TIBCO Scribe® Online Organization.
- Using more than one HubSpot user account from the same HubSpot organization to create multiple connections in a single TIBCO Scribe® Online Organization.
- Creating multiple HubSpot Connections in a single TIBCO Scribe® Online Organization using the same HubSpot user account and credentials.
Scopes
A scope provides access to a specific set of HubSpot API endpoints. Following are the default scopes that are currently supported. To include additional scopes to access other API endpoints, use the Additional Scopes field in the Edit Connection window as described in Connecting To HubSpot.
- automation
- content
- crm.lists.read
- crm.lists.write
- crm.objects.contacts.read
- crm.objects.contacts.write
- crm.objects.companies.read
- crm.objects.companies.write
- crm.objects.deals.read
- crm.objects.deals.write
- crm.objects.owners.read
- crm.schemas.companies.read
- crm.schemas.companies.write
- crm.schemas.contacts.read
- crm.schemas.contacts.write
- crm.schemas.deals.read
- crm.schemas.deals.write
- forms
- sales-email-read
- social
- timeline
Additional information about all available scopes can be found in the HubSpot documentation.
Selecting An Agent Type For HubSpot
Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.
Connecting To HubSpot
Note: Best practice is to create Connections with credentials that limit permissions in the target system, following the principle of least privilege. Using Administrator level credentials in a Connection provides Administrator level access to the target system for TIBCO Scribe® Online users. Depending on the entities supported, a TIBCO Scribe® Online user could alter user accounts in the target system.
- Select More > Connections from the menu.
- From the Connections page select Add to open the Add a New Connection dialog.
- Select the Connector from
the drop-down list in the Connection Type field, and then enter the following information for this Connection:
- Name — This can be any meaningful name, up to 25 characters.
- Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
- Account Number — Your HubSpot account number, which you can find under My Profile in the HubSpot Settings pane.
- Additional Scopes — Several default scopes are provided with the connector. If access to an API that is not supported by the default scopes is required, use this field to add the scope to the connection. Multiple scopes may be added using a comma between the scope names (other delimiters are not allowed). Names are case-sensitive. Additional information about all the available scopes can be found in the HubSpot documentation.
- Select Authenticate to open the HubSpot authorization page:
- If you are not already logged into HubSpot, the HubSpot login page displays. Enter your email address and password, and select Log in.
- If this is the first time you are creating a HubSpot Connection, the HubSpot Authorization page displays. Select Authorize to allow HubSpot to use the data specified.
A page with the following message displays:
- Select Close to return to the TIBCO Scribe® Online page.
Tip: Do not test the Connection until the message at the top of the Connection dialog reads Authentication complete. Note that it may take a few minutes for this message to display.
- Select Test to ensure that the Agent can connect to HubSpot. Be sure to test the Connection against all Agents that use this connection. See Testing Connections.
- Select OK/Save to save the Connection.
Metadata Notes
Naming
Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.
Picklists
- Picklist or check box fields in HubSpot require specific values. When mapping to a picklist field, select the field and refer to the description for details on the expected values. For example, the Contact entity field singleon_off_checkbox expects either true or false when creating a contact in HubSpot.
- If your source data contains NULL values for any picklist field, you must use a formula to transform the NULL before the record is sent to HubSpot. You can use a formula, such as the following: IF(ISNULL(sourcefield),"false","true")
- When using HubSpot as a source, HubSpot returns a NULL for picklist fields where the check box is not selected.
Reserved Fields
Some HubSpot fields have reserved names that cannot be used as custom field names. Using one of these field names as a custom field name generates errors.
Contact
- is-contact
- portalid
- HubspotContactTimelineUrl
- HubspotContactUrl
HubSpot Connector As IS/MS Source
Using changedate To Filter Records
When using HubSpot as a source, if you use the Most Recent Record Processed feature or filter on the changedate field in the Query Block, HubSpot may return multiple contact records for each HubSpot Contact. These records are tracked with the vid field, HubSpot contact ID. When TIBCO Scribe® Online queries the HubSpot API for records that are filtered on changedate, HubSpot returns a contact record for each unique changedate.
If you use changedate as a filter in the Net Change tab or you use no filters at all on the Filters tab, the value of changedate displays in the Preview tab and is included in the Query results. If you use any filter on the Filters tab for Contact, the value of the changedate field is blank on the Preview tab and is not included in Query results.
Note: The changedate field is called addedat in HubSpot.
Filtering On HubSpot Data
When a datetime is configured on the Query Block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Scribe® Online builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.
Some Connectors for TIBCO Scribe® Online only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.
Note: The Net Change date is ignored when previewing data on the Preview tab. Filters on the Block Properties Filters tab are used to filter the data on the Preview tab.
- Data can be filtered:
- From the Filter tab, Lookup Criteria tab, or Matching Criteria tab in Integration Maps.
- Only supported fields display in the Field drop-down list for any filter.
- Complex filters using AND and OR are not supported. See Block Properties Filter Tab.
- Supported Boolean values for HubSpot custom properties are only true and false in lowercase letters.
- Using both the Most Recent Record Processed option on the Net Change tab of the Query Block and a filter is not supported.
- Timestamps entered in the HubSpot User Interface are in local time. In TIBCO Scribe® Online, timestamps in the Net Change Most Recent Record Processed option and on the Query Preview tab are UTC time.
Relationships
- Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.
- Parent/Child relationships are supported where noted for some entities. Review the Notes On Standard Entities section for details on specific entities.
Note: For this Connector, only one level of relationship, Parent/Child, is supported for the entity selected in the Query or Fetch Block. For records with multiple levels of relationships, such as Parent, Child, Grandchild, only the selected Parent entity and related Child entities can be retrieved. Additional levels beneath Child entities, such as Grandchildren, cannot be accessed for this Connector using the Include tab. See Block Properties Include Tab — Relational Data.
HubSpot Connector As IS/MS Target
Special Operations
The following additional target operations are available in Integration Maps for this Connector:
- Add and Remove target operation Blocks are available for the ContactListMember entity.
- OptOut target operation Block is available for the Contact entity.
- Submit target operation Block is available for the Form entity.
- Update/Insert target operation Block is available for Company, Contact, ContactList, Deal, and Task.
Note: These operations may behave differently depending on the entity. Refer to Notes On Standard Entities below for additional information.
Send Operation
-
The Send operation is used to make API calls to the HubSpot API. It can be used to support custom calls to the HubSpotREST APIs.
-
Send supports the Request entity used to build the HTTP calls to the API.
-
Send works in conjunction with the Add Block to include Headers, Cookies, or Query Parameters.
-
The Send and Add operations support the use of the following variables or tokens to make configuring customized API calls easy and robust:
Name Example Value [endpointUrl] https://api.hubspot.com [authToken] CJSP5qf1KhQEYs-gDIIIpuIFEavB2-qYAGQsF4
- endpointUrl — The Connector derives the value of the [endpointUrl] from the HubSpot Organization associated with the Connection configuration. This is the Custom Domain URL for your HubSpot organization. Use the [endpointUrl] to construct the Uri for the Send block. Note that the value of the variable includes https://. The value of endpointUrl is https://api.hubspot.com.Note: You can provide [endpointUrl] in the Uri field of the Request Entity.
- authToken — The Connector derives the value of the [authToken] variable from the authentication token configured in the Connection. This token is used to perform the POST, GET, and any other HTTPVerb calls using the Request entity.Note: The [authToken] must be provided in the Request Header for any HTTP request.Note: If the Authorization Token is provided explicitly, instead of using the [authToken] variable, and the token is refreshed, an error similar to the following is generated:
Operation failed. Label: Send Request, Name: RequestSend, Message: Forbidden: Error in calling Operation Send Http call failed with StatusCode 403 - Forbidden. Response Body: Bad_OAuth_Token.
- endpointUrl — The Connector derives the value of the [endpointUrl] from the HubSpot Organization associated with the Connection configuration. This is the Custom Domain URL for your HubSpot organization. Use the [endpointUrl] to construct the Uri for the Send block. Note that the value of the variable includes https://. The value of endpointUrl is https://api.hubspot.com.
- The Send block, the Add block, and the Request entity are based on the functionality in the HTTP Connector. For more details see the HTTP Connector help.
Notes On Standard Entities
Call
- This entity represents only the call component of a HubSpot calendar event or engagement.
- Filtering is available for the following fields:
- id — Can be used with the equals operator.
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- When querying Calls, the Call id is required as a filter. If no filter is used, no records are returned and an error is generated.
Company
- Custom HubSpot properties are supported.
- Query —
- Filtering — Available on the following fields:
- companyId — Can be used with the equals operator.
- createdate — Can be used with is greater than or is greater than or equal to operators.
- domain — Can be used with equals operator.
- hs_lastmodifieddate — Can be used with is greater than or is greater than or equal to operators.
- Net Change — Only the createdate or hs_lastmodfieddate fields can be used for Net Change to return only new and updated records. See Most Recent Record Processed.
- DateTime Filters — If you include a datetime field either on the Net Change tab or on the Filters tab, note the following:
- Only records from the last 30 days are available.
- If there are more than 10,000 records in the time span specified, only the most recent 10,000 records are returned. To retrieve more records, remove the datetime filter.
- Filtering — Available on the following fields:
Contact
- Filtering is available on the following fields:
- changedate — Can be used with is greater than or is greater than or equal to operators to return updated records. See Using changedate To Filter Records.
- createdate — Can be used with is greater than or is greater than or equal to operators to return only new records.
- contactlistid — Can only be used with the equals operator.
- is-contact — Boolean field that determines whether or not the Contact record can be edited.
- email — Can only be used with the equals operator.
- UserToken — Can only be used with the equals operator. This Token is generated and stored when a Contact submits information through a HubSpot Form hosted by HubSpot.
For Forms that are not hosted by HubSpot, the token is generated by inserting the correct HubSpot JavaScript Tracking Code into the page that contains the Form. When a Contact accesses the Form, the HubSpot JavaScript Tracking Code places a "hubspotutk" cookie in the user's browser. The value of this token can be retrieved programmatically and stored with the Contact, but not through TIBCO Scribe® Online. Creating your own UserToken values when creating a Contact is not recommended.
- vid — Can only be used with the equals operator.
If you specify record criteria on the Lookup tab that can return more than one record, such as contactlistid, TIBCO Scribe® Online only returns the first record that meets the criteria. See Block Properties—Lookup Criteria Tab.
- DateTime Filters — If you include a datetime field either on the Net Change tab or on the Filters tab, note the following:
- createdate — The first time you retrieve records and write them to a target database, all records are returned. On subsequent synchronizations, only new records are returned based on the datetime selected.
- changedate — Only records from the last 30 days are available.
- Query —
- Using Preview when configuring a Query on the Contact entity occasionally causes timeout errors to be returned from HubSpot. However, at run time, the Query is processed correctly.
- The changedate or the createdate field can be used for Net Change to return only new and updated records. If createdate is used, only new records are returned, not changed records. See Using changedate To Filter Records.
- Delete — Only vid and email are supported as fields for Matching Criteria. For better performance TIBCO recommends using Id.
- OptOut Operation Block — Enables the opt out of emails option on a contact in HubSpot. Supported fields for Matching Criteria are: vid and email. The changedate and contactlistid fields display in the match fields drop-down, but are not supported as match fields for this operation.
- Upsert — HubSpot Upsert operations process records asynchronously. Updated and inserted Contact records may take some time to display in the HubSpot user interface.
- Create, Update, and Upsert —
Note: Mapping the Contact associatedcompanyId field can degrade performance and use additional API calls. If you experience a degradation in performance or exceed your API limits, try breaking the process up into separate Solutions that execute on different days. For example, Create your Contacts on Day 1 and Update those Contacts with an associatedcompanyId on Day 2 using the new CRMAssociations entity.
- Virtual Fields — Virtual fields on the Contact entity used to access contact information via a URL.
- profileurl — Contains the URL for the associated public Contact Record. HubSpot is deprecating access to this URL. TIBCO Scribe® recommends using the HubspotContactUrl or the HubspotContactTimelineUrl instead.
Note: When the profileurl field is deprecated, if a Null value is received from HubSpot, the Connector provides the URL for the HubSpot Contact Timeline embed record with an & appended. For existing Maps where a / parameter was appended to the profileurl, the & indicates that the / should be ignored. This will prevent errors in existing Maps that used the profileurl + /embed to generate the Contact Timeline URL. Otherwise, the & is ignored. Accessing the Contact record using this URL requires the user to be logged into HubSpot to view the record.
- HubspotContactURL — Contains the URL for the associated Contact record. Logging into HubSpot is required to access the Contact record via this URL.
- HubspotContactTimelineUrl — Contains the embed URL used to integrate Contact Timeline information into another application. Logging into HubSpot is required to access the Contact record via this URL.
- profileurl — Contains the URL for the associated public Contact Record. HubSpot is deprecating access to this URL. TIBCO Scribe® recommends using the HubspotContactUrl or the HubspotContactTimelineUrl instead.
ContactList
- Filtering is available on the following field:
- listId — Can only be used with the equals operator.
- Query —
- An unfiltered query returns all active lists and excludes all deleted lists. A filtered query returns both active and deleted lists. When a list is deleted in HubSpot it is marked as deleted, but the record is not removed.
- Retrieve ContactListMembers by selecting the ContactListMember entity on the Query Block Properties Include tab when querying the ContactList entity.
- Using Net Change to filter for new and updated records is not supported for this entity.
- Returns both Static Lists and SmartLists.
- Create —
- Only Static Lists are supported.
- Name is the only field that can be mapped. All other fields are read only.
- Update — Name is the only field that can be mapped. All other fields are read only.
- Delete — Only listId is supported for Matching Criteria.
ContactListMember
- Only Static Lists are supported for Add and Remove operations.
- Add Operation Block — Requires either the vid or the email value. If both vid and email values are provided, the vid value supersedes the email value.
- Remove Operation Block — To remove a ContactListMember from a ContactList, the lookup condition for delete must be in this format.
- 1st condition: listId = xx
AND
- 2nd condition: either vid = xx or email = xx, but not both.
- 1st condition: listId = xx
ContactsDeals
- Represents the one-to-one relationship between Contacts and Deals.
- Delete —
- Use the Delete operation with this entity to remove the association between a Contact and a Deal.
- Match criteria for the Delete operation requires two match fields, such as dealId and contactId.
CrmAssociations
- Represents associations between objects in HubSpot, such as the association between a deal and a company.
- Filtering — Only supports the equals (=) operator for Query filters and match criteria.
- Query —
- Requires filtering by the Category, fromObjectId, and definitionId fields.
- Deals merged via the HubSpot User Interface have been assigned new IDs. If you are querying for associations based on those IDs, associations for merged Deals are not returned. See Merged Deals for additional information.
- Create — Requires mapping the Category, toObjectId, fromObjectId, and definitionId fields.
- Delete — Requires using the Category, toObjectId, fromObjectId, and definitionId fields as match criteria.
Note: The HubSpot API returns a success message whether the association is found and deleted or not. To verify whether the association exists before deleting it, you can use a Lookup Block. However using a Lookup consumes additional API calls.
Note: For Category information and ID lists refer to the following HubSpot API documentation pages:
- CRM associations overview
- Get associations for CRM object provides additional information on the Query operation.
- Associate CRM objects - Provides additional information on the Create operation.
- Delete an association
Deal
- Custom HubSpot properties are supported.
- Filtering is available on the following fields:
- createdate — Can be used with is greater than or is greater than or equal to operators.
- dealId — Can be used with the equals operator.
- hs_lastmodifieddate — Can be used with is greater than or is greater than or equal to operators.
- DateTime Filters — If you include a datetime field either on the Net Change tab or on the Filters tab, note the following:
- Only records from the last 30 days are available.
- If there are more than 10,000 records in the time span specified, only the most recent 10,000 records are returned. To retrieve more records, remove the datetime filter.
- Query — When using HubSpot as a source, only the createdate or hs_lastmodfieddate fields can be used for Net Change to filter for new and updated records. See Most Recent Record Processed.
- To remove an associated Company from an existing Deal, use a NULL or empty string ("") value in the companyId field of the Deal record.
- Create — If an invalid companyId is used when creating a Deal in HubSpot, the Deal is assigned an empty company and HubSpot does not generate an error. The Deal can be reassigned a valid company either through the HubSpot user interface or using the Update operation in a TIBCO Scribe® Online Map.
- Create and Update —
Note: Mapping the companyId field can degrade performance and use additional API calls. If you experience a degradation in performance or exceed your API limits, try breaking the process up into separate Solutions that execute on different days. For example, Create your Deals on Day 1 and Update those Deals with a companyId on Day 2 using the new CRMAssociations entity.
- Merged Deals — HubSpot supports merging Deals via the HubSpot UI. Merged Deals are assigned a new dealId. For example, if you merged Deal A and Deal B, HubSpot creates Deal C to represent the merged Deals. If you request a Deal using the old dealId, HubSpot returns the new merged Deal. However, if you are working with records associated with Deals, such as associated Contacts, you cannot use the old dealId to retrieve those associated records. HubSpot does not return any associations when using the old dealId.
To work around this issue, use a Lookup or Fetch Block with the old dealId as matching criteria to locate the new dealId. Use the new dealId to get the correct associated records.
Note: If you are using HubSpot dealId values as external IDs in another system, such as a CRM system, and your Maps use those dealIds to work with associated records, best practice is to create a Map that updates those external IDs with the new merged dealIds before using the dealIds to synchronize HubSpot and the CRM system.
DealPipeline
- Query —
- Filtering is not supported.
- Using Net Change to filter for new or changed records is not supported.
- This entity represents only the email component of a HubSpot calendar event or engagement.
- Filtering is available for the following fields:
- id — Can be used with the equals operator.
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- When querying Emails, the Email id is required as a filter. If no filter is used, no records are returned and an error is generated.
EmailCampaign
- This entity represents only the email component of a HubSpot campaign.
- Filtering is available on the following field:
- Id — Can be used with the equals operator.
- Query — Using Net Change to filter for new and updated records is not supported for this entity.
EmailEvent
- Filtering is available on the following fields:
- created — Can be used with is greater than operator.
- emailCampaignId — Can only be used with the equals operator.
- recipient — Can only be used with the equals operator.
- type — Can only be used with the equals operator.
The type field lists enumeration values in the field description. Enumeration values represent a fixed set of constants, such as days of the week.
- Query —
- When using HubSpot as a source, only the created field can be used for Net Change to filter for new and updated records. See Most Recent Record Processed.
- EmailEvent records that are not associated with any campaign are included in the records returned unless an emailCampaignId is included as a filter.
Engagement
- HubSpot Engagement types are represented as separate entities. Types include:
- Query —
- When querying the Engagement entity, only the fields that are common to all Engagement types are returned.
- To retrieve all Engagements, do not use any filters on the Filter tab or dates on the Net Change tab. Depending on the number of Engagement records, this may take a considerable amount of time.
- Net Change — When filtering for new and updated records on the Query Block Net Change tab, only the lastUpdated datetime field on the Engagement entity is supported for Net Change.
- DateTime Filters — If you include a datetime field either on the Net Change tab or on the Filters tab, note the following:
- Only records from the last 30 days are available.
- If there are more than 10,000 records in the time span specified, only the most recent 10,000 records are returned. To retrieve more records, remove the datetime filter.
Form
Using the HubSpot Connector you can submit form data to HubSpot. Forms are used in HubSpot to populate a subset of Contact fields. To use the Forms entity, enable the Marketing module in HubSpot.
- Form Names —
- Form entity names display in the format Form_<formname>. For example, if you have a Form named Address, the entity for that Form is named Form_Address.
- Form names longer than 50 characters are truncated in TIBCO Scribe® Online. For example, if the Form name in HubSpot is 100 characters long, the entity name for that Form in TIBCO Scribe® Online is Form_<first 50 characters of name>.
- Use only alphanumeric characters in Form names. All other characters are removed when the Form name is displayed in TIBCO Scribe® Online.
- If two Forms have the same name, a number is appended to the name in TIBCO Scribe® Online. Form names could be unique in HubSpot, but the same in TIBCO Scribe® Online due to the removal of special characters. Be sure to use unique Form names.
- Submit — HubSpot requires either email address or UserToken when submitting Form data. If the email address field is empty or the data is invalid, the Submit operation is successful, but the Contact does not display in the HubSpot User Interface. Use a formula to check for valid values in the email address field and only submit records with an email address. See ISEMAILADDRESS and ISREGEXEXACTMATCH for additional formula information.
If you have added a Contact without an email address, you can use the UserToken as a match field to locate and update the Contact with an email address.
- Fields marked as required on the Form are not necessarily required by the HubSpot API. Required Form fields display as required in TIBCO Scribe® Online and generate warnings if they are empty, but the records are accepted by the HubSpot API.
- Default Values — You can set default values for Form fields when creating them in HubSpot. The HubSpot Connector does not include default values when submitting form data because it does not determine whether the Submit operation is updating an existing Contact or creating a new one. If the Submit operation were to include default values when updating a Contact, existing Contact data could be overwritten.
- UserToken — Either leave this field blank or retrieve the value by doing a Lookup on the Contact record for the Contact associated with this Form. This is a value generated by HubSpot when a user completes a Form. Populating this field with other data may cause reporting issues in HubSpot. See Contact for additional information.
- Fields — The fields below are not displayed on Forms in the HubSpot User Interface, but are available in the HubSpot Connector and can be submitted with Form data:
- pageUrl — Used to submit the Source URL for the Form. If blank, the field defaults to the TIBCO Scribe® Online URL.
- pageName — Used to submit the name or the title of the page containing the Form. If blank, the field defaults to "Scribe Online".
FormSubmissionInfo
- There are no operations supported for this entity. This entity is supported only in a Query operation of the Contact entity as a child of the Contact entity.
- Only outer Joins are supported for the relationship between Contact and FormSubmissionInfo. Errors are generated if you use an inner join.
HubSpotEvent
Use this entity to track if and when an event was triggered by a Contact.
Note: If the Contact in the Event record does not exist in HubSpot, TIBCO Scribe® Online creates an empty Contact record with only an email address. Use the Contact entity to create new Contacts before creating Events or to update new Contacts after creating Events.
- EventId, ContactEmailAddress, and ContactRevenue are the only fields available for the Event entity when using the HubSpot Connector.
- When using HubSpot as a target, the ContactEmailAddress and EventId fields are required to add an Event to a Contact.
- Create — The EventId field accepts numeric ID or string values.
- If source record data mapped to EventId contains the EventId of an existing event in HubSpot, the event is added to the Contact.
- If source record data mapped to EventId contains only the event name and it can be resolved to an existing event in HubSpot, the event is added to the Contact.
- If source record data mapped to EventId contains only the event name and it cannot be resolved to an existing event in HubSpot, a new event is created in HubSpot, and that event is added to the Contact.
- Events created by the HubSpot Connector in HubSpot can be viewed in the Contact's time-line via the HubSpot User Interface.
IncomingEmail
- This entity represents only the incoming email component of a HubSpot engagement.
- Query — Only outer Joins are supported for the relationship between Company and IncomingEmail or Contact and IncomingEmail. Errors are generated if you use an inner join.
- Fetch — Only outer Joins are supported for the relationship between Company and IncomingEmail or Contact and IncomingEmail. Errors are generated if you use an inner join.
- Update — When updating an IncomingEmail record, the entire record is updated. Any values not provided are written as NULL.
ListMembership
- There are no operations supported for this entity. This entity is supported only in a Query operation of the Contact entity as a child of the Contact entity.
- Only outer Joins are supported for the relationship between Contact and ListMembership. Errors are generated if you use an inner join.
Meeting
- This entity represents only the meeting component of a HubSpot calendar event or engagement.
- Filtering is available for the following fields:
- id — Can be used with the equals operator.
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- When querying Meetings, the Meeting id is required as a filter. If no filter is used, no records are returned and an error is generated.
Note
- This entity represents only the note component of a HubSpot calendar event or engagement.
- Filtering is available for the following fields:
- id — Can be used with the equals operator.
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- When querying Notes, the Note id is required as a filter. If no filter is used, no records are returned and an error is generated.
SubscriptionStatus
- Filtering is available on the following field:
- Email — Can be used with the equals operator.
- Query —
- When querying SubscriptionStatus, the Email field is required. If you filter for an email address that does not exist, multiple records are returned.
- Using Net Change to filter for new and updated records is not supported for this entity.
- Update —
- Matching Criteria requires both the SubscriptionStatus_Id and Email. If there is a match on id but not email, the record is not updated and no error is generated.
- The SubscriptionStatus_Subscribed field is the only field that can be updated and only supports the string value false. Using false unsubscribes someone from a subscription. Setting this field to true to subscribe someone to a subscription is not supported.
SubscriptionType
- Filtering is not supported for this entity.
- Query — Using Net Change to filter for new and updated records is not supported for this entity.
Task
- This entity represents only the task component of a HubSpot calendar event.
- Filtering is available on the following field —
- id — Can be used with the equals operator.
- The Timestamp field for a task is a combination of two HubSpot User Interface fields, Due Date and Time. When querying a task, if no time value is entered in the HubSpot User Interface, the HubSpot API returns a time of 11:59:59 pm displayed in UTC. For example, if your time zone is Eastern Standard Time, the time returned is 3:59:59 am. Depending on your time zone, the date returned could be the next or the previous day.
- The active field for a task is always set to true by the API when creating or updating a task, regardless of the value sent in the task record.
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- When querying tasks, the task id is required as a filter. If no filter is used, no records are returned and an error is generated.
- Update — When updating a task, if the status field is empty, the task's status setting is set to the default Not Started setting, erasing the prior setting. If the body field is empty, the value for the body field on the task is erased. Use a Lookup operation to retrieve and map the existing values for status and body fields if the source values are NULL.
- Create —
- Contacts, companies, and deals do not appear in the Relates To column of the Task table in the HubSpot User Interface if the associated Tasks were created by the HubSpot Connector, using the HubSpot API. To display the associated items, open the task in HubSpot and save it again.
- The createdby field is read only and is not populated when a task is created using the HubSpot Connector via the HubSpot API. If the new task record is queried, a NULL value is returned for the createdby field.
- When creating tasks, invalid field values cause the following:
- companyId — No error is generated by the API and the task is created.
- contactId, dealId — An error is generated indicating that one or more associations were invalid, but it does not specify which association and the task is not created.
TIBCO Scribe® Online API Considerations
To create connections with the TIBCO Scribe® Online API, the HubSpot Connector requires the following information:
Connector Name |
HubSpot |
Connector ID |
84DDC45D-675E-4EBA-A781-AB1FF24985B1 |
TIBCO Scribe® Online Connection Properties
In addition, this Connector uses the Connection properties shown in the following table.
Note: Connection property names are case-sensitive.
Name | Data Type | Required | Secured |
---|---|---|---|
PortalId |
String |
Yes |
No |
AdditionalScope | String | Yes | No |
See Create Or Modify An OAuth Connection in the API Help.
PortalId
When creating or updating a HubSpot Connection with the TIBCO Scribe® Online API you must include the property PortalId, with the value of your HubSpot Account Id.
Example:
"Properties": [ { "Key": "PortalId", "Value": "2648825" } ]
AdditionalScope
The AdditionalScope property holds the default scopes along with any optional scopes added by the user. In the example below, the default values are shown in red. Optional user-added scopes are appended to the default list and are shown in blue. Note that the scopes must be separated by a URL encoded space, %20.
Example:
"Properties": [ { "Key": "AdditionalScope", "Value": "automation%20content%20timeline%20forms%20social%20e-commerce%20crm.import" } ]
License Agreement
The TIBCO Scribe® Online End User License Agreement for the HubSpot Connector describes TIBCO and your legal obligations and requirements. TIBCO suggests that you read the End User License Agreement.
More Information
For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.