You have the option to upload specific user and account data into your dataset using the Interaction Studio API. This is useful if you want to add a custom field to many users or accounts at once, or add them to a dataset instead of waiting for them to log into your app. This data must be constructed very precisely and submitted to Interaction Studio in the form of a .CSV (Comma Separated Value) file. These files can be created in any spreadsheet program (Excel, Google Spreadsheet, etc.).
Interaction Studio Classic Only
- The contents of this article are intended for customers using Interaction Studio (formerly Evergage Classic). Do not adjust your beacon version to downgrade or upgrade.
- If you are a Campaigns & Templates customer, please refer to the CSV Feed Requirements in this knowledge base, or the Feeds article in developer.evergage.com.
- The Visual Editor Chrome Extension will no longer be available starting January 1, 2023. For more information, see this knowledge article.
This Article Explains
This section details how to upload specific user and account data into your dataset using the Interaction Studio API.
Sections in this Article
Construct the .CSV file
Interaction Studio has the ability to upload just users, just accounts, or users with their associated accounts into your dataset, as well as any custom field. However there are many rules to ensure the process goes smoothly. This section details how the spreadsheet data is supposed to look for each of these three scenarios:
In all cases, each individual entity will occupy one row in the spreadsheet. Also, the first row of the spreadsheet should detail the field being upserted.
User-only upserts
For user-only upserts, construct your data as shown in the screenshot at the right so that the first cell, A1, has the word "name" in it. This is the API term for userID. Below this (in the first column) list userID of each user that you would like to upsert. Across the 1st row, list the names of the custom fields you want to upsert. Below each column, list the values for the custom fields for each of the users designated by name in the first column.
NOTE
With user-only upserts, only the name (userId) field is required
Account-only upserts
Account upserts are very similar to user upserts, the only difference is you'll want to make sure that the designated fields you submit are custom fields that are attributes of the account. The value for A1 should be accountName. As shown in the screenshot at the right, the first column includes the account name of each account that you would like to upsert. Across the 1st row, list the names of the custom fields you want to upsert. Below each column, list the values for the custom fields for each of the accounts designated by the accountName in the first column.
NOTE
With account-only upserts, only the accountName (accountID) field is required
User and account upserts
This is a combination of the user and account upserts. The "name" value will still occupy A1, with the userIDs below it. In B1 you'll have the accountName and the accounts below it. The rest of the columns will be custom fields associated with the user or account. The screenshot at the right shows an example of how to include the data.
NOTE
With upserts including both users and accounts, only the userID (name) and accountName fields are required
Check for Completeness
Confirm exact string matches
It is very important that the userIds and company fields that you upsert are exact string matches to what we'll naturally see as events in Interaction Studio. What this means is that if the userId being tracked by the beacon (or Visual Editor) is "testuser@evergage.com," and in the .CSV file you submit "testuser" for the name, it will not update the current user but instead create a new one. This is true for the account field as well. If you submit "evergage" in the .CSV file but you're passing us "evergage (0001)" with an ID # appended to it through the beacon, it will not upload correctly and create a new account.
Use the correct field names
For Interaction Studio to know which value to assign and where, you have to use the field names recognized by the Interaction Studio API. The two most important ones are for the userId and account:
userId = name
account = accountName
Interaction Studio also has built in defaults for the display name, email and account type:
User's display name = userName
User's email = userEmail
Account Type = accountType
Account Name = displayName
Create and assign custom fields
If you choose to upsert custom fields with a .CSV file, you need to make sure these custom fields are assigned as an attribute of the user or account before you upsert. To do this, select your dataset and navigate to Settings > Attributes. From here you can set the custom fields as an attribute of the user or account. Make sure the Attribute value is an exact match to the field name that will appear in the first row of your .CSV file.
Use the proper date format
A common use case for upserting is to submit a registration date as a custom field with an account or user. The intention is to be able to create a segment of (and possibly message) users that have registered before or after a certain date. If this is the case, the date field must be constructed such that Interaction Studio can create a numerical KPI that will be used to create a segment. The format is: YYYYMMDD. This format creates a number that increases as the days progress. For example, you can create a segment that filters out users with registration dates greater than January 1st, 2017 by finding all values greater than 20170101. If you submit a date in any other format, including 01/01/2014, 2014/01/01, 01012014, Interaction Studio won't be able to resolve it into a segment.
Remove hyperlinks from e-mails
Spreadsheet programs have a tendency to hyperlink email addresses. If you notice this happening, select the addresses, then right click to remove the hyperlink, otherwise they will be saved in your .CSV file with a "mailto: " appended before the email address.
Overview
Content Tools