Syncing Users

Step 1 - Query

After you've connected to your warehouse, the next step to syncing Users is to configure the query that Vitally will run against your warehouse on each sync.

Once you've entered your query, be sure to click the Preview Query button, which will execute your query against your warehouse and return the first row fetched from your targeted table.

Each column of the result will be presented as an available trait that you can pull into Vitally as a user trait.

You'll be using the previewed query and returned row further along in the configuration below.

Incremental Sync

Incremental sync is a process of syncing warehouse data that has only been added or modified since the last sync cycle, instead of processing the entire dataset each time. This approach is more efficient as it minimizes the amount of data queried and processed during each sync, making the update process quicker and resource-efficient.

Incremental syncs are highly recommended for syncing Users

If you'd like Vitally to incrementally query your data each time, you'll need to add a clause to your query with the variable $LAST_SYNC_TIMESTAMP. We'll fill in that variable with the timestamp of the last sync each time we query the warehouse.

Incremental syncs should compare the $LAST_SYNC_TIMESTAMP with a timestamp that reflects when the data was synced to the data warehouse. This is particularly important when data is synced to the data warehouse in batches.

SELECT
  name, "createdAt", "segmentId", email, avatar
FROM "User"; 
WHERE "updatedAt" > $LAST_SYNC_TIMESTAMP;

Step 2 - Configure

Once you input and preview your query, you'll be presented with a few additional configuration options:

External ID

Vitally will create or update users from each row based on the External ID of the user. This ID should be shared across your other integrations - its significance is described in The Significance of External ID. This is likely the primary key of the user in your warehouse or the primary key of the user in your main data source.

Create vs Update only

Once you select an external ID, you have the option of determining whether your warehouse can create new users in Vitally or only update existing ones (created from another source).

(Optional) Specifying a fallback ID

If you choose to sync Users by their "External ID", you'll see another question asking about a 'fallback ID':

This is optional but useful if there is a delay in the "External ID" being set on your Users. For example, say you have stakeholders that don't necessarily use your product immediately. If your "External ID" is the primary ID of the User in your database, you won't have that ID until their first login, meaning they won't show in Vitally until that occurs. To resolve this, you can specify a 'fallback ID' here (for example, the User's email). The Vitally platform will then create Users using this fallback ID if the primary external ID is not set. Once the primary external ID is set on the User, Vitally will automatically switch the ID over to the primary and merge any duplicate Users created from other systems.

Optional Config

Lastly, you'll have the option to specify which column in your select should be used as the user's associated account id(s) and account name, as well as the user's name and email in Vitally.

Associating a user to multiple accounts

If your users can belong to multiple accounts, simply follow these steps to ensure users are linked to each account in Vitally:

• In your SQL query that fetches users, return a column that is an array of all account external IDs the user belongs to. For example, ensure your returned users has a column like "accountIds": ['account-external-id-1', 'account-external-id-2']

• Then, in question #3 ("Pick the column that contains a reference to the account's external ID"), simply select this column (e.g. select accountIds)

• Vitally will take it from there, as we will detect if the column contains an array (instead of a string), and will create links between the user and every account referenced in the array.

Step 3 - Continue Configuration

If you have other features to sync continue configuring those.

pageConfiguring Sync

OR Step 3 - Enable Sync

pageEnabling Sync