About this integration

Integration Summary

This integration is used to retrieve all available information from your UserVoice domain using the UserVoice REST API (GET method).

SAS_ConventionAPIRequests_OnlyEN

API Detailed Dscription

Item	Comments
About the software and company	UserVoice is a San Francisco based Software-as-a-Service (SaaS) company creating customer engagement tools.
Information about the REST API	Date on which the information was retrieved from the software company's website: June 2016 Last known REST API name/version/date: V1
Main useful links to software company information about REST	Getting Started with User Voice REST API UserVoice API References API Technical Details & OAuth 1.0a Authentication Mapping UserVoice data to your own    Link UserVoice suggestions/tickets to EasyVista tickets/incidents API Rate Limiting
Format and sample of API resources/endpoints	https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500 When documenting a resource, UserVoice uses keywords in orange for identifiers. In this documentation we are using curly braces { } for identifiers and our convention for API Requests. Replace {subdomain} in the URI with your subdomain name provided by UserVoice.
API assets	UserVoice REST API provides a way to map your system’s data to its own. This through mappings that are called External Ids.    You might want to link suggestions to and let UserVoice provide easy links back to your system. See Mapping UserVoice data to your own
API recommendations (limitations, advice, tips)	API calls: This API is “rate limited”. Only a certain number of requests per minute are allowed. As an API consumer, you should expect to be able to make at least 120 requests per minute (with All Helpdesk Plans). If a request takes longer than 1 second to compute then another “request” is counted for every whole second after the first. Pagination: By default, most list endpoints return a maximum of 10 records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request URL parameters. However, you cannot exceed 500 records per page for most endpoints.    per_page=50 When the response exceeds the per-page maximum (i.e. 500), you can request for a specific page of records. By default Page returned is Page 1.    page=3
Comments	N/A

Step-by-step Integration Process

UserVoice can be integrated with  in 4 easy steps:

• Step 1: Check the list of requirements
• Step 2: Start the process for creating the REST data source
• Step 3: Authenticate to UserVoice
• Step 4: Create a query string using UserVoice documentation

Step 1: Check the list of requirements

• This documentation assumes that you already have an UserVoice domain.
• To use the UserVoice Personal API Key/Token Access Authentication, you must enable it in the Admin console of your UserVoice domain. You must add at least one token. The token will be required in the REST data sources you create in an  app.
  See the procedure
  How to enable the UserVoice Personal API Key

  To find out more, see the Getting Started with User Voice REST API

  1. In the UserVoice Admin Console, select Settings > Integrations > UserVoice API Keys.

  

  2. Click [ ADD API KEY ].

  

  3. Enter a name for the API Client.

  4. Decide if you want the client to be trusted or not. Some endpoints require a trusted client. However, DO NOT check this if your API Key will be stored in an insecure environment.

     A Javascript client application that end-users download

Step 2: Start the process for creating the REST data source

     For details about the creation, see the wiki page REST data source

• Click  in the Objects pane. 
• Open the Online category and select the REST data source .
• Name the data source.
             UserVoice_List of published suggestions

Step 3: Authenticate to UserVoice

 Authenticate to UserVoice with the UserVoice Personal API Key/Token Access Authentication

• Select the type of authentication: Authentication Type = None.

Step 4: Create a query string using UserVoice documentation

          See the UserVoice API documentation
         See Examples of use cases

• Create a query string as a data source, i.e. a resource to access, in the URL field.

Best Practice

          See Best Practice for the REST data source

• By default, UserVoice list endpoints return a maximum of 500 records per page. Therefore, to keep the number of records as low as possible, we recommend that you define as many parameters as possible. These parameters can include the category (authorized values: all, uncategorized,category_id), status_id, filter (authorized values for comments endpoints type: all, published, deleted, spam; authorized values for suggestions endpoints type: all, published, inbox, active, closed, deleted, spam, merged, updated_after), etc.

• You must not share the personal API token. You must keep this token and all information on credentials secure.

• Note:
  • Status ID “288277” = “under review”
  • Status ID “288278” = “Planned”
  • Status ID “288279” = “started”
  • Status ID “288280” = “Completed”
  • Status ID “288281” = “Declined”

Use case

You might want to have in an app a list of all suggestions (called also ideas) with their creator name and with the number of associated voices. To get this list, you can create a Composite data source to merge information from UserVoice and  using the email address as a unique key.

Notes: 

• We assume that users use their professional email for UserVoice. So that email will be the same than in . On the contrary users may use nicknames for UserVoice. So using a composite data source will also enable you to get the accurate last and first name in a Data Viewer widget.

• In January 2016, it was not possible to extract in UserVoice such list as indicated in the UserVoice suggestion about UserVoice below:
           

1. Create the REST data source  (Standard category) - called for example UserVoice_Suggestions - with following parameters.
         

2. Create the EasyVista data source  (Application category) - called for example Easyvista_Employees - with following parameters. Note: It depends on your  configuration.
         

3. Create the Composite data source  (Standard category) - called for example UserVoice & EVSM Link - with following parameters.
         

     Notes:

• Such data source must use a key having common values in the two data sources used (REST and EasyVista). In our case we are using emails that have common values in  UserVoice and in our  environment.
• Watch not to create data sources which base themselves on views of  which have an excess large number of recordings.
• Use filters which allow you to have the minimum of recordings and the views which contain the minimum of columns to answer your need.

Samples of most relevant use cases and resources

Note: Replace {subdomain} with the name of your UserVoice domain and {Personal_API_Key} by the API Key you want to use

Method: GET

SAS_IntegrationRESTAboutTheUse_OnlyEN