Vitally

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Connect to Vitally

Go to the Destinations overview page and click the Add destination button. Select Vitally and click Continue. You can then authenticate Hightouch to by entering the following fields into Hightouch:

• Region: Either EU or US.
• Analytics API Token: This is required for syncing analytics objects and events.
• REST API Token: This is required for the REST endpoints.

Follow these instructions to generate tokens.

1. Log into your Vitally account, click the wheel icon on the bottom sidebar.

   

2. Under Data Management, select the Integrations option.

   

3. For the Analytics API Token, select the Vitally Analytics API card. Otherwise, skip to step 6 for the REST API Token.

   

4. Toggle on the integration.

   

5. Click the Integrate via HTTPS API tab and copy the API KEY. This is the Analytics API Token you need to enter in Hightouch.

   

6. For the REST API Token, select the Vitally REST API card.

   

7. Toggle on the integration and click to generate the API Key.

   

8. Copy the Basic Auth Header once it's generated to use in Hightouch. This is the REST API Token you need to enter in Hightouch.

   

Once you've entered the relevant token or tokens, click Continue and enter a descriptive name for your destination to complete setup.

Sync configuration

Once you've set up your Vitally destination, have a model to pull data from, and have a clear idea of the data you want to sync, you can set up your sync. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Vitally destination you want to sync to.

Syncing REST objects

Hightouch supports syncing to account, organization, and user objects in Vitally.

Record matching

To match rows from your model to objects in Vitally, you need to select the model column that contains values that match the External ID field in Vitally. When syncing users, you can also match on Email.

Refer to the record matching docs for more information.

Field mapping

Hightouch lets you sync object fields via field mapping. You can map data from any of your model columns to any of an object's default fields. Ensure the data type of your model column matches the data type of field you want to sync to in Vitally. For example, a Vitally text field expects a model column with the string data type.

When using Upsert or Update mode to sync users, if you match on Email, you need to map both the External ID and either Account IDs or Organization IDs. Otherwise, Hightouch displays a Required field error and a Must specify at least one of: accountIds or organizationIDs error.

If you match users on External ID, you only need to provide either Account IDs or Organization IDs. Otherwise, Hightouch displays a Must specify at least one of: accountIds or organizationIDs error.

Vitally accounts, organizations, and users objects contain an editable traits attribute to store custom key/value pairs. This is useful for storing information like a customer's plan, number of licenses, name, etc.

To properly sync traits to Vitally, you need to format the traits field as an object data type rather than a string. You can create an object of all the fields you want to update, and then map them to traits. An example traits attribute for an organization object could look like this:

{
	"organizationId": "Id_value",
	"organizationName": "Name_value"
}

You can use template mapping to create objects like this in your sync configuration. In the following example screenshot, the template uses this Liquid function

{{ | json_construct : 'organizationName', row['organizationName'] }}

to create an object where the key's name is organizationName and the value is the row's organizationName column.

For more information, refer to the Vitally's API documentation.

Delete behavior

The delete behavior you select dictates what to do when a row no longer appears in your model's query results. You have the following options:

Syncing analytics objects

Hightouch supports syncing to account, organization, and user objects in Vitally with the analytics API.

Record matching

To match rows from your model to objects in Vitally, you need to select a model column that contains the corresponding ID for each supported object.

• Account ID for account objects
• Organization ID for organization objects
• User ID for user objects

Field mapping

Hightouch lets you sync analytics object fields via field mapping. You can map data from any of your model columns to the default object fields. Ensure your model columns data types match the data types of the fields you want to sync to.

Traits mapping

Hightouch allows you to map traits for the analytics objects. Any mappings from this section will be synced as additional attributes in the traits parameter.

Syncing events

Hightouch supports syncing product events in Vitally. Vitally's API requires the following event parameters:

• event: the name or type of event
• timestamp: the time the event was generated
• message_id: a unique ID for the event

And at least one of:

• user_id: the ID of the user that 'owns' the event
• account_id: the ID of the account that 'owns' the event

The sync configuration form ensures all these are set and provides some additional options.

Event name

Providing an event name is required to send an event to the Vitally's API. You can either provide a static value or select to use a column from your model. Hightouch syncs the static or column value as the event parameter the API requires.

Event timestamp

You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Hightouch uses the time the event arrives at the server. Hightouch syncs the timestamp as the timestamp parameter the API requires.

Field mapping

Field mapping is where you select which event parameters you want to send to the Vitally's API. The API requires you to map at least one of the following fields in order to save your sync.

• Account ID
• Organization ID
• User ID

You can also include data to sync as custom event fields in Vitally.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

Must specify at least one of: accountIds, organizationIDs, user_id

You may receive an error like this in the Hightouch UI if you don't include all necessary values in your sync. Consult the field mapping section of your relevant sync type to learn more.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.