Enumeration fields or optionsets would need to be well handled in migration scenarios. And it's easy to not have an option in a target system, which was a legacy option in your Source data set. One such example would be currency options. Currency abbreviations can easily be missed, incomplete, or need to be changed to better reflect the destination system. In this business case, we are working with an old database system and have now been tasked to create the contact information in HubSpot. One of our source fields ‘Currency’ lets you know what type of currency the contact will be working in, so this field is a dropdown select where there are many options and you may select one. The first problem is that in your source system, some of the fields must be changed (ex. US to USD for the accurate United States currency), and the second problem is you may have additional currency types in your source system that are not present in your HubSpot environment (ex. ARS for Argentinian currency is missing in destination property). With the help of our KingswaySoft HubSpot component, we can resolve both problems in the same process with the help of enumeration option mapping.
In this scenario we will be using the components below:
- Data Spawner Component: emulating our source database which we are pulling data from.
- HubSpot Connection Manager: establish a connection to our HubSpot instance.
- HubSpot Destination Component: writing our data to our HubSpot instance.
Design and Configuration
The setup in this scenario will be using a HubSpot custom property, in our case we have a dropdown-select of currency abbreviations. Note the ‘US’ value in the screenshot below, we would like this to be updated to the official value of ‘USD’.
Your data flow will look similar to the below screenshot. The Data Spawner component will act as our source database, and we are pulling data from this source. The HubSpot Destination component will be the destination where our data will be stored. The data viewer in the path between the two components is optional but recommended if you need to see a snapshot of the data at that moment in the data flow.
On the General page, we will be working with the Create action where we will be creating Contacts with some basic information about them.
On the Columns page, we have created a basic mapping for our contacts. If you reference the image below you can see that the component lets you know which fields are available for the Enumeration Mapping, and in our example, this will be the currency field.
Inside the Enumeration Option Mapping Editor, we can create the change in the option to accurately reflect what the currency abbreviation should be. The Input Value is what the current value is in the source system and the Enumeration Option Value is the value we want it changed to in the destination. We can easily handle any changes within the HubSpot component. Secondly, we can also handle when there is no match for a value between the source and destination. There are four options to choose from and for our use case, we will select the Create Option. In our case, the HubSpot environment has an incomplete set of options for currencies and we can easily add these so they can become new additions to the Currency properties. Not only will they be added as new properties, but they can be used in the same data flow.
We will go over the other options for handling non-matched values:
- Replace as an existing option: If you have a default value when no match is found it will set the value as default. This is useful when you have an intended default value, and that value cannot be empty or NULL.
- Set as empty (NULL): when the field can have a nullable value, useful for when you intend to re-process the fields later.
- Raise an error: If there is no match found for the input value component will fail with an error. May be useful when the row has a mandatory field, and you would like to redirect the error rows to re-process them. This would be used in combination with the Error Handling page in the HubSpot destination component and selecting the Redirect Rows to Error Output as shown below.
When executing the package our data viewer shows us how the data looks coming from the source, and you can see highlighted in yellow the contact Gregg Cartwright with a currency abbreviation that does not exist in the HubSpot Currency property as well as Alda Gerlach which has an abbreviation, we would like changed to better reflect the Currency property.
Post Execution Observations
After execution is complete, we can verify the changes and additions by going into the HubSpot instance and looking at the two Contacts referenced before. We can also verify the currency option has been updated and additions were included as well.
Conclusion
A Few limitations you will have to keep in mind for the HubSpot environment:
- The supported objects for enumeration mapping are Contact, Company, Deal, Ticket, Product, Line_Item.
- HubSpot does not allow you to change the enumeration option mapping on their standard fields.
- The dropdown select option type has a limit of 5,000 options and 3,000-character limit including label, value, and description. Other option types may have different limitations.