[If you are looking for ticket fields, it is a different feature. Please see this article]
Understanding the Basics
UserVoice User: This is the profile that's created for a user on your UserVoice account automatically when they log in with our default login, interact with the widget or authenticate with SSO. E.g. your end users that are providing feedback.
External Users: Imported user information from your database. Always mapped to the UserVoice user based on the email or UserVoice ID. Required if you want to connect a UserVoice User to an External Account. You can have multiple External Users connected to one UserVoice user.
External Accounts: An Account is a group of users from the same organization. You pass in external accounts, and then connect them to UserVoice users with an external user.
In this article, we'll walk you through the basics of how this feature works.
Standard TraitsURL: Will display a link, must be valid URL format, e.g. http://www.example.com
Standard fields are preset traits that you can use out of the box. External_ID's are always required, but for the other fields you can pick and choose what you need.
Standard User Traits
- External_ID: Required
- Email: Required
- Name: Only seen by admins, and does not update their UserVoice display name
- Created_At: Defaults to the first time you passed in the external user. This field is used to determine auto-prompts for NPS widget.
- IP: Defaults to the IP we have for the user, but you can pass your own. This is used to set a location for the user.
- Type: Could be admin, owner, developer, end user etc...
- External Account ID: Required to connect the external user to an external account.
- External_ID: Required to create an account
- Name: Account name
- Plan: Plan name
- MRR: Monthly recurring revenue. If you pass MRR, we can then aggregate the MRR of accounts that support an idea.
- LTV: Lifetime value of the account.
- Created_At: Defaults to when the account object was first created in our system.
Is an External User Required to connect a UserVoice user to an account? Yes. If you want to connect a UserVoice user to an account, you must pass an external user for that UserVoice user.
Custom traits are traits you create to pass through your own custom data on users and accounts. You have five types of custom traits you can create and pass data for.
- Text: Single line Text, up to 128 characters
- Multi-Line Text: Up to 10,000 characters
- Number: Whole or decimal numbers 15 digits
- Date & Time: RFC3339 timestamp OR YYYY-MM-DD HH:MM:SS
- Boolean: true or false
- URL: Will display a link, must be valid URL format, e.g. http://www.example.com
Create your Custom Traits Fields
Getting Started: If you are passing in custom traits, you must set up the fields before passing through any data. You can do this two ways.
- User's Page: Click the "users" icon in the left-hand menu -> Click the "gear" icon to the right -> You'll see the option to create user and account fields
Staging your data to add to UserVoice
- List out all User and Account traits you would like to see in UserVoice, using the field names you see in your database.
- Match up as many fields as possible to fields that are already found in UserVoice (standard traits). See this article for more information.
- If you have field remaining, these will be your custom fields. Name them using the naming convention 'cf_your_custom_field'.
- Add the datatype to each custom field (from the list of accepted data types).
Import Traits from a CSV
With our CSV import feature, you can import your user and account traits using a spreadsheet. You may get your source data from a salesforce export, your product database, etc.
Pass in Traits with the API
Data sent in via the API will show immediately in the UI. This is the best long-term solution for keeping external user and account information up-to-date.
Getting Started: You will need engineering resources on your end to set this up with the API. We do have this guide for using Postman if you're awaiting engineering resources.
- Guide for Importing Users and Accounts with the API
- External User API Reference
- External Account API Reference
With the UserVoice widget (learn more about the widget here), you can pass User and Account traits through the widget when a user logs in on the page.
- User and Account traits passed via the widget do not show in the UI until the user interacts with your UserVoice site—votes, comments, creates an idea, sends a message, or gives an NPS rating.
- The widget only supports passing one user profile and associated account. If you need to pass in multiple external users or accounts, you will need to use the API or the CSV import.
Q: How do I unlink a user from an account?
A: You will either need to delete the external user, or pass null for the external_account_id for the external user.
You Might Find Helpful:
- Measure the impact of ideas with the analysis export
- How to create and use Accounts in UserVoice
- Use Postman to pass fields for users and accounts