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.
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.
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 "firstname.lastname@example.org," 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.