Creating Standard Hubspot Associations in Syncari

This doc currently only applies to Standard Objects in Hubspot. This doc will be updated shortly to accommodate Custom Objects as well.

Per Hubspot's documentation:

"Associations represent the relationships between objects and activities in the HubSpot CRM. Record associations can exist between records of different objects (e.g., Contact to Company), as well as within the same object (e.g., Company to Company). You can use the associations endpoints to create, retrieve, update, or delete associations between records, or records and activities."

Association Entities

Associations don't just represent relationships between objects - associations, themselves are objects. This means that Syncari treats associations as their own entity, much like we would treat the objects being associated as their own entities.

To use the example in the quote above, both Contact and Company are standard objects in Hubspot and both have their own respective association entities (Contact Associations and Company Associations, respectively). When we want to create associations between Contact and Company records we create a new record in either the Contact Associations or Company Associations entity that contains the Hubspot ID of both the Contact and Company record.

Let's dive in a bit more.

Pulling Associations into Syncari

The first step in creating an association is to pull in the required association entities from Hubspot:

1. Navigate to Sync Studio and click on the Gear Icon next to the Hubspot Sandbox Synapse
2. Check the boxes next to the relevant association entities you want to pull into Syncari
   • Since we're associating Contacts to Companies, we want to import the Contact Associations and Company Associations entities
3. Click on the Create Entities button

Activating the Associations Entities

Once you've created the Syncari entities based on the Hubspot association entities, the next step is to publish these entity pipelines. 

Analyzing Association Records

Hubspot provides a reference sheet for Association Type IDs and what their values represent (link HERE. Bookmark this doc for future usage when building associations in entity and field pipelines.

1. Category: This value will always be hardcoded as HUBSPOT_DEFINED for standard objects.
2. From Object Id: The Hubspot ID of the Company record that's being associated. Since the record above is part of the Contact Association entity, this value will always apply to the Contact record.
3. From Object Type: A Hubspot-defined value that pertains to the entity from which the association originated. Similar to From Object Id the value here will pertain to the Contact record.
4. Label: An optional field that stores the value of the relationship label. In this case, this is association record represents a Primary association so that information is stored here.
5. To Object Id: The Hubspot ID of the Company record that's being associated. Since the record above is part of the Contact Association entity, this value will always apply to the Company record.
6. To Object Type: A Hubspot-defined value that pertains to the entity being associated. In this case, since the From Object Type is contact, the To Object Type is company.
7. Type Id: Where the numerical key pertaining to the association type is stored. Per the Hubspot Association Type IDs doc linked above, a value of 1 represents a Contact to company (Primary) relationship.
   • Note that the value you put in this field when creating the association may affect the value in the Label field. In this case, when setting a Type Id of '1', Hubspot will automatically add the 'Primary' value.

Creating Association Records: High Level Overview

You may notice that the lookup functions in Step 1 and Step 3 only contain the name of the lookup entity in the title. This naming convention makes it easier to reference output from these lookups via token syntax later in the pipeline, but you can use any naming convention you choose.

At this point you should have a good sense of the anatomy of an association record and what each field denotes. Now, we're going to dive into how to create association records within an entity pipeline.

1. [Lookup Function] Company: Identify a foreign key on the Contact record that maps to a Company entity record and perform a lookup against the Company entity to see if such a record exists.
   
   • Given the logic above, the Contact record will not be created in Hubspot if no referenced Company record exists.
2. [Decision Function] Company Exists: Set this function to return 'True' if the previous lookup function returns a record.
3. [Lookup Function] Company Association: Now, perform a lookup against the Company Association entity. You want to check if there's already an existing association record.
4. [Decision Function] Association Exists: Set this function to return 'False' if the Company Association lookup node does not return a record - indicating the association does not yet exist.
5. [Create Syncari Record Action] Create Association: Create the association record within the Contact Association entity and add values to fields like To Object Id, To Object Type, Label, etc.
6. [Hubspot Destination] Sync to Contact: After the association logic completes, create the Contact record in Hubspot.

Step-by-Step Deep Dive

Step 1: Company Lookup Function

1. Display label: The name of the lookup node. We recommend giving the lookup a simple name, in this case, the name of the lookup entity; this makes it easy to refer to this lookup node elsewhere in your pipeline.
2. Syncari Entity: The name of the entity you're performing a lookup against. In this case, we're looking for a record in the Company entity.
3. Filter Conditions: The value on which to match the lookup record. You need to have an explicit foreign key on the Customer record that can be used to find a matching Company record.

Step 2: Company Exists Decision Function

1. Display label: The name of the decision node.
2. Evaluates to True if: Where the conditions that must be met to return a 'True' value are specified. In this example, you want to set Lookup Result from Company - Is Not Empty.

Step 3: Company Association Lookup Function

1. Display label: The name of the lookup node. We recommend giving the lookup a simple name, in this case, the name of the lookup entity; this makes it easy to refer to this lookup node elsewhere in your pipeline.
2. From Object Id: This should be the Hubspot external ID for the current Contact record. You can find this value by clicking the Data token button and selecting from the token picker.
3. To Object Id: This should be the Hubspot external ID for the Company record returned from the lookup previous lookup. You can find this value by clicking the Data token button and selecting from the token picker.

Step 4: Association Exists Decision Function

1. Display label: The name of the decision node.
2. Evaluates to True if: Where the conditions that must be met to return a 'True' value are specified. In this example, you want to set Lookup Result from Company Association - Is Not Empty.
   • In this case we're going to key off of the 'False' return value since we only want to create an association if one does not already exist.

Step 5: Create Syncari Record

1. Syncari Entity: The Syncari entity in which you're creating a new record. In this case, we want to create a new Contact Association record.
2. From Object Id: The Hubspot External ID of the current Contact record.
3. To Object Id: The Hubspot ID of the Company record returned from the Company lookup function.
4. From Object Type: The Hubspot-defined value relating to the entity type of the current record. In this case, the value would be 'contact'.
5. To Object Type: The Hubspot-defined value relating to the entity type of the associated record. In this case, the value would be 'company'.
6. Type Id: The Hubspot-defined numeric value pertaining to the relationship type. In this case, the value 279 signifies a Contact to company relationship.

Step 6: Sync to Hubspot

1. Entity: The Hubspot entity where the Contact record will be synced after the association logic finishes running.

Syncing Associations to Hubspot

Once the association record is created within the Contact pipeline, it will appear as a record in the Contact Association entity in Data Studio. Here, you will also see any historical association records imported from Hubspot in a previous sync cycle.

You'll also notice that the Company Associations entity has 6 records. In the Contact pipeline we only created an association record within the Contact Association entity. Once that entity record is synced to Hubspot, Hubspot will automatically create the reciprocal Company Association record and sync it back to Syncari.

When creating Primary associations you will always see 2 association records, one with a primary association Type Id and one with a standard association Type Id.