UserVoice Integration


About this integration
SAS_IntegrationRESTIntroduction_OnlyEN

You can integrate third-party systems with Product name - ev sas.png in many ways. The method you select will depend on business requirements, architectural and security constraints as well as the characteristics specific to each third-party application or service. You can use the REST, CSV, Online CSV data sources as well as the HTML Script widget.

This document describes a standard integration process with the REST data source that has already been implemented in a customer context. It provides only a few examples of HTTP queries for manipulating resources (i.e. endpoints) using the REST API in the third-party application. You can discover more about the possibilities of this API and consult the relevant documentation on the website of the third-party software company.

To find out more about this integration, please contact the Logo - EasyVista.png Consulting & Professional Services team, the Logo - EasyVista.png Support team, or your service provider and integrator.

Integration Summary

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

      Example documentation icon EN.png  Retrieve and display a list of suggestions in an Product name - ev sas.png app

Integration Data Feed (direction) Authentication Type Integration Connector Options

Product name - ev sas - big.png

Up arrow.png

Logo - UserVoice.png

Check icon.png   Personal API Key/Token Access Authentication

REST data source   Apps - Datasource - JSON Online icon.png

SaaS Version of Third-Party Product

On-premise Version of Third-Party Product

Check icon.png

Not check icon.png


SAS_ConventionAPIRequests_OnlyEN

Convention for the API requests

Curly brackets { } indicate values you have to supply. 

In most of the cases, we draw your attention with:

  • in green and bold, the important and mandatory values to be replaced;
  • in green, certain important and/or optional values (often choice of parameters).

Example documentation icon EN.png  https://{subdomain}.uservoice.com  ==> replace {subdomain} with the name of your UserVoice domain

API Detailed Dscription

Item Comments
About the software and company

Logo - UserVoice.png

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

Example documentation icon EN.png    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.

Example documentation icon EN.png    You might want to link suggestions to and let UserVoice provide easy links back to your system.

Open url.png 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.

    Example documentation icon EN.png    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.

    Example documentation icon EN.png    page=3

Comments N/A

Step-by-step Integration Process

UserVoice can be integrated with Product name - ev sas.png in 4 easy steps:


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 Product name - ev sas.png app.
    Open url.png See the procedure
    How to enable the UserVoice Personal API Key

    Open url.png 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.

    Prerequisites - Get Personal API Key (0).png

    2. Click [ ADD API KEY ].

    Prerequisites - Get Personal API Key (1).png

    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.

    Example documentation icon EN.png    A Javascript client application that end-users download


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

  Open url.png  For details about the creation, see the wiki page REST data source

  • Click Apps - Add datasource icon.png in the Objects pane
  • Open the Online category and select the REST data source Apps - Datasource - JSON Online icon.png.
  • Name the data source.
             Example documentation icon EN.png  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.

Note: Contrary to other REST data sources for third-parties products requiring Personal API Key/Token Access Authentication, you must not select Authentication Type = Basic. Rather you will have to add the API Key you want to use in the query strings.


Step 4: Create a query string using UserVoice documentation

       Open url.png  See the UserVoice API documentation
       Open url.png  See Examples of use cases

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

Example documentation icon EN.png  You want to create a data source that will retrieve a list of published suggestions  ==>  Enter the following text in the URL field. Note: Replace {subdomain} with the name of your UserVoice domain and {Personal_API_Key} by the API Key you want to use -  Open url.png  See Step 1

https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500&filter=all

Best Practice big icon.pngBest Practice

       Open url.png  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 Product name - ev itsm.png 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 Product name - ev itsm.png. 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:
             UserVoice - Use case - Example.png

1. Create the REST data source Apps - Datasource - JSON Online icon.png (Standard category) - called for example UserVoice_Suggestions - with following parameters.
         UserVoice - Use case - REST data source.png

URL = https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500&filter=all

2. Create the EasyVista data source Apps - Datasource - EasyVista icon.png (Application category) - called for example Easyvista_Employees - with following parameters. Note: It depends on your Product name - ev itsm.png configuration.
         UserVoice - Use case - EasyVista data source.png

3. Create the Composite data source Apps - Datasource - Composite icon.png (Standard category) - called for example UserVoice & EVSM Link - with following parameters.
         UserVoice - Use case - Composite data source.png

    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 Logo - EasyVista.png UserVoice and in our Product name - ev itsm.png Logo - EasyVista.png environment.
  • Watch not to create data sources which base themselves on views of Product name - ev itsm.png 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

Use Case Sample Endpoint
Retrieve the list of published suggestions for all our UserVoice forums and for our UserVoice domain
  • filter = published (default)
  • sort = votes (default)

Authentication Type: Personal API Key (Token Access Authentication) - Using in REST data source Authentication type = None
Basic Authentication Parameters: N/A
URI: https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500
Selector: .Suggestions
Retrieve the list of all suggestions for all our UserVoice forums and for our UserVoice domain
  • filter = all
  • sort = votes (default)

Authentication Type: Personal API Key (Token Access Authentication) - Using in REST data source Authentication type = None
Basic Authentication Parameters: N/A
URI: https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500&filter=all
Selector: .Suggestions
Retrieve the list of all suggestions except those with the status Declined for all our UserVoice forums and for our UserVoice domain
  • sort = votes (default)

Authentication Type: Personal API Key (Token Access Authentication) - Using in REST data source Authentication type = None
Basic Authentication Parameters: N/A
URI: https://{subdomain}.uservoice.com/api/v1/suggestions.json?client={Personal_API_Key}&per_page=500&filter=all
Selector: :has(.status .id:expr(x!=288281))
Retrieve the list of published suggestions for a specific forum and for our UserVoice domain
  • filter = published (default)
  • sort = votes (default)

Authentication Type: Personal API Key (Token Access Authentication) - Using in REST data source Authentication type = None
Basic Authentication Parameters: N/A
URI: https://{subdomain}.uservoice.com/api/v1/forums/{forum_id}/suggestions.json?client={Personal_API_Key}&per_page=500
Selector: .Suggestions
Retrieve the list of published comments for all our UserVoice forums and for our UserVoice domain
  • filter = published (default)
  • sort = newest (default)

Authentication Type: Personal API Key (Token Access Authentication) - Using in REST data source Authentication type = None
Basic Authentication Parameters: N/A
URI: https://{subdomain}.uservoice.com/api/v1/comments.json?client={Personal_API_Key}&per_page=500
Selector: .comments
SAS_IntegrationRESTAboutTheUse_OnlyEN

About the use of the third-parties REST API

Please note that numerous software companies limit the access to the REST API of their software, generally by basing itself on a number of calls by hour/day/month.
Moreover, only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
Finally, some software companies set up plans (for example Classic, Professional, Enterprise, etc.) for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.

The possible cost of the use of the third-parties API by means of Product name - ev sas.png is not taken care by Logo - EasyVista.png.

Tags:
Last modified by Unknown User on 2017/04/24 15:58
Created by Administrator XWiki on 2016/07/11 15:23

Shortcuts

Recent Updates

Haven't been here in a while? Here's what changed recently:

-   Product name - ev itsm.png
-   Product name - ev sas.png

Interesting Content

How to Automate Integration
Add a Shortcut to an App
History
Quick Dashboard
Full text search - Stop Words

Powered by XWiki ©, EasyVista 2018