Hubspot_vtiger_bridge integrates Hubspot and vtigerCRM in order to push leads data from hubspot to vtigerCRM. Hubspot provides the webhooks interface to their leads stream, i.e. Hubspot has the optional feature of pushing their leads data onto whatever URL provided. This script is able of receiving hubspot leads json data, converting it into vtigerCRM leads json format, pushing the data into vTigerCRM. It was developed for internal use at ERA Environmental Consulting Inc., later gladly released to public with the permission of copyright owners.
Hubspot_vtiger_bridge is based on Hubspot webhooks API, which is only available for Hubspot 'Enterprise' plan customers. For now, Hubspot_vtiger_bridge doesn't have any logic to pull leads data from Hubspot, it is only able of receiving what Hubspot emits to it's webhooks.
The script represents a Sinatra web-application, and has to be hosted on a public HTTPS URL. Hubspot webhooks will only push data onto HTTPS url, so pick your hosting accordingly. Heroku hosting can be a good choice for this type of application. After obtaining the URL for application, it has to get registered with Hubspot webhooks. This can be done using scripts/register_hubspot_callback_url.rb
Before the use of script the conversion of lead properties between two systems has to be adjusted. The mapping is specified in file hubspot_webhooks_adapter.rb, HubspotWebhooksAdapter.to_vtiger_lead static method. After examining that file, you'll see that it depends on some field names that are defined in vtiger_lead_custom_fields.rb.
When the script pushes the lead into vtiger, some properties of the lead object are saved into vtiger custom lead properties, and these have to be created in your vtiger installation. This can be done under Settings > Module Manager > Leads > Layout Editor, using the small '+' icon. vTigerCRM will assign a new name to that JSON lead property, which can't be renamed and looks like this: 'cf_620'. The file vtiger_lead_custom_fields.rb is responsible for representation of these custom field names in hubspot_webhooks_adapter.rb. scripts/get_vtiger_lead_structure.rb can be used to determine these custom names. The structure returned should look like scripts/leadStructureVtiger.js.
Adjusting one of the fields is mandatory for correct script operation - hubspotId:
{
"name": "cf_620",
"label": "hubspotId",
}
'cf_620' has to be substituted for your value in vtiger_lead_custom_fields.rb, as this property is used to make a decision if it's a new lead for vtiger, or it already exists, and we only need to update it.
Setting credentials for vtiger is moved out of the code into environment variables. There are 3 envvars to set: VTIGER_ACCESS_KEY, VTIGER_ADDRESS, VTIGER_USERNAME. When hosted on Heroku, setting of envvars can be done this way (in console from a folder where you've checked out the git project):
heroku config:add VTIGER_ACCESS_KEY='your-access-key', VTIGER_ADDRESS='your-installation-url', VTIGER_USERNAME='your-username'
Not only the leads are transmitted to VtigerCRM, but also Hubspot 're-conversion events' (filling the form on tracked website). They are represented in Vtiger as calendar events that happened to lead. This also requires adjustments and setup. The url to Hubspot's filled form is stored in Vtiger's custom field for calendar events. This field has to be recreated on your Vtiger installation. This can be done in Settings > Module Manager > Calendar > Calendar Custom Fields. Create a field called 'Form URL' with type 'URL'. After that you have to substitute the 'Form URL' JSON property name in vtiger_event_custom_fields.rb to the name that got assigned by Vtiger to your 'Form URL' field. scripts/get_vtiger_event_structure.rb can be used to determine it.
Also, the timezone location of your Vtiger server has to be specified with environment variable VTIGER_TIMEZONE. This is done to properly set the 'Event starts at' and 'Event ends at' properties of the Vtiger calendar event, adjusted to Vtiger's installation location. Hubspot transmits the form-filling datetime in UTC and this has to be adjusted to Vtiger's server timezone. When hosted on Heroku:
heroku config:add VTIGER_TIMEZONE='America/Montreal'
The tz database is used to determine locations like 'America/Montreal'. scripts/get_country_timezone_locations.rb can be used to get the list of possible locations corresponding to ISO 3166 country codes.
Web-server logging can be used to check on correct setup. With Heroku hosting it can be done this way (in console from a folder where you've checked out the git project):
heroku logs --tail
- Hubspot Webhooks API
- Hubspot Leads API
- vTigerCRM API tutorials
- vTigerCRM API reference
- Heroku quickstart
- Hosting a sinatra application on Heroku
- Heroku server env vars
- TZInfo README
- Timezone database
Copyright 2011 Vyacheslav Derevyanko of ERA Environmental Consulting Inc., contact slavik2121[at]gmail.com, released under the MIT license