REST (Connector) Datasource


Apps - Datasource - REST Connector icon.png This type of data source belongs to the Online category in the data source library. It is used to access the resources of a REST service defined in the app in order to retrieve dynamic content from websites or third-party products (also known as services) using URIs. URIs are Uniform Resource Identifiers (or endpoints) relying on the REST (Representational State Transfer) HTTP protocol.

Open url.png See  How to choose between a REST data source and a REST (Connector) data source.
SelectDataSourceREST
  • REST data source
    • To define and access a REST resource.
    • Only to access resources without authentication or resources using Basic authentication.
    • To use a given resource from a service occasionally (resource not intended for reuse in another app).

      ==>  The Base URI of the data source is made up of the service and the resource proposed by this service. Note: For Basic authentication, you also need to specify the information required for accessing the service.

      Example documentation icon EN.png
  • REST (Connector) data source
    • To reuse the service and its resources.
    • To access any type of resource for a REST service defined in the app.

      ==>  A REST connector must be created. It must be made up of the service and its resources. Note: For Basic or OAuth 2.0 authentication, you also need to specify the information required for accessing the service.

      Example documentation icon EN.png
      • Create a connector to provide access to the six resources proposed by JSONPlaceholder, a fake REST API with public data used for testing and prototyping:
      • Create a connector to provide access to the resources proposed by Google Calendar:
        • Google Calendar service
        • Resources: By week, by day, by event

 

  • A REST (Connector) data source relies on a connector that identifies all resources accessible for a given service.
ResourcesREST
  • Resources can be as follows:
    • Accessible to all users without requiring authentication, e.g. access to public data.
         ==>  Product name - ev sas.png can interface with all these resources.
    • Restricted to specific users who are first required to authenticate, e.g. access to private data.
         ==>  Product name - ev sas.png can interface with these resources using two authentication methods:
      • Basic: Users must enter their login and password.
      • OAuth 2.0 (Note: Only for the REST (Connector) data source): The login information required depends on the third-party product. Users can access either public data (e.g. general corporate data) or their own data (e.g. user-specific calendar).
  • Once access is authorized, data is read and sent to Product name - ev sas.png in JSON format, a structured text data format.
    • This data can be displayed using widgets. A Selector tool integrated in the data source is used to extract only the data you want.
    • Data is then automatically updated each time that the data source is modified.
  • A REST (Connector) data source also has exposed properties that can be passed as a parameter in the URL link of the app.

Notes

Open url.png See General remarks on data sources.

  • The authentication method used depends on the API set up by each third-party product and is described in the documentation of the API.
  • The list of third-party products interfacing with Product name - ev sas.png via OAuth 2.0 authentication is defined by Logo - EasyVista.png.
    • You cannot add others. 
    • New third-party products will be added progressively once the implementation of the OAuth 2.0 protocol has been integrated and technically validated.
  • For each third-party product, Logo - EasyVista.png provides a list of predefined resources to meet the most common user requirements.
    • They cannot be modified.
    • You can add other resources for specific requirements by defining a URI. Open url.png See the REST API documentation of the resource.
              Example documentation icon EN.png  Google YouTube API V3
  • To find out more about the JSON table structure, please consult http://www.json.org.
  • All websites and third-party products that use a REST API and that offer access to resources without user authentication or using Basic authentication can interface with Product name - ev sas.png via a REST data source.

Best Practice big icon.pngBest practice

  • If a third-party product uses a REST API and offers access via different authentication methods, we recommend that you use OAuth 2.0 authentication whenever possible if supported by Product name - ev sas.png.

Examples

ExamplesREST

1. Third-party products (services) and resources:

  • Examples of services: Gmail, Google Contacts, Google Calendar, Twitter
  • For Twitter, examples of resources: Timeline or followers

         Open url.png  See the other Examples of integration with Product name - ev sas.png

2. Examples based on the authentication method:

  • No authentication required:
    • The http://api.open-notify.org website publishes public data in real-time from the ISS (International Space Station) using REST architecture. The position of the ISS can be displayed using a Google Maps widget without requiring user authentication.
  • Using Basic authentication:
    • Twitter enables users to create their own timelines. Thanks to the REST architecture and the REST API adopted by Twitter, tweets in a user's timeline can be displayed using a Data Viewer widget with prior user authentication.
    • The Salesforce third-party product enables users to have different views of corporate data, e.g. lists of customers, prospects, projects or sales employees. The REST protocol enables you to display these resources using Data Viewer widgets with prior user authentication.
  • OAuth 2.0 authentication: The Google Calendar site enables users to access different resources for managing calendars, e.g. By week, by day, etc. Thanks to a connector linked to the Google Calendar service, these resources can be accessed via a REST (Connector) data source.

List of properties

Content

Alias/Connector: Alias/Connector used by the data source for accessing a service and its resources. The fields to be specified are automatically displayed based on the authentication method associated with the connector.

Basic Authentication Parameters (Note: Only for Basic authentication): Login and password for accessing the resource. 

  • By default, information specified for the connector is displayed. Click Edit icon.png to modify it. Click Apps - Delete icon.png to delete it. Note: In this case, users must authenticate when requesting access to the resource.

ACCOUNT / subdomain (Note: Only for Basic authentication): Account and domain name provided by the third-party product.

OAuth 2.0 Authentication Parameters (Note: Only for OAuth 2.0 authentication): Information required in order to access the resource. 

  • By default, information specified for the connector is displayed. Click Edit icon.png to modify it.
             EVApps - datasource REST - Oauth authentication parameters.png
  • Resource Owner: User account of the data owner in the third-party product. To add a new user, click [ + ] and specify the login information specific to the third-party product.
  • Use these account credentials for all users: Used to indicate if the login information for accessing the third-party product is identical for all users (box is checked) or if users are required to enter their personal login information (box is not checked). If the login information is identical, then all users will have access to the same data. If it is not, then users will have access to user-specific data.

    Example documentation icon EN.png  For the Google Calendar service:

    • To enable all users to view the calendar of events of their company ==> box is checked.
    • To enable users to view their user-specific calendar ==> box is not checked.

Resource: List of resources available for the service. These are Logo - EasyVista.png predefined resources and other additional resources.
        Example documentation icon EN.png  For Twitter: Timeline or followers

  • The default resource defined in the connector is proposed.
  • Click Edit icon.png to modify or add a resource.  Open url.png  See the procedure.

Additional Query String: Additional filter criterion, can be used in the exposed properties.
        Example documentation icon EN.png  For Twitter: Filter all posts for a given user.

Selector

Selector: Access to the tool for extracting the data you want from the JSON table which contains all data retrieved from the resource.

  • The JSON table contains a list of tags surrounding data subsets using curly brackets, { }.
  • You can select the Selector tool using an expression in the search field (1) or by selecting a tag from the JSON table (2).
             EVApps - datasource REST - Selector.png

    Open url.png  To find out more about:

  • The JSON data structure: json.org
  • The use of regular expressions in the search field (1): JSONSelect
SelectFirstRowAsCurrentRecord

Select First Row As Current Record: Used to indicate if the first record of the data source, when displayed in widgets, is selected by default (box is checked) or if no record is selected by default (box is not checked). 

NoDataMessage

No Data Message: Message displayed when no data is returned in the data source. Enter the code directly in the field or click Apps - Edit Html icon.png to open the text editor

Preview

Configure Field Types: Used to display a preview of the structure and data from the data source via a data editor. 

  • The button Apps - datasources Properties - Preview button.png displayed below the property indicates the number of extracted rows (up to a limit of 15) and columns. Click on it to open the editor. Open url.png See the Description.
  • The button will display No data available as long as you have not selected any of the mandatory elements of the data source.
  • In edit mode, only the first 15 data source records are displayed.
  • In execute mode, all of the data source records are displayed.
  • Data in static data sources comes from the last file upload.
  • Data in dynamic data sources is updated when you open the app in edit mode.

Best Practice icon.png  For OAuth 2.0 authentication, click > next to Preview to view the complete URL of the resource. This is especially useful when you want to check the URL after adding variables.
        Example documentation icon EN.png  EVApps - datasource REST connector - Show URL.png

AutoRefresh

Auto Refresh (Note: Only for dynamic data sources): Used to indicate the automatic refreshment interval for a dynamic data source. The frequency is expressed in hours/minutes. The updating of data is done in execute mode or edit mode, each time the app is run and each time the page is redisplayed.

    Best Practice icon.png

  • Because the updating of data requires additional activity on the EasyVista Service Apps platform, you should define an automatic refreshment interval only if the app is required to constantly display  real-time data for long periods of time on a screen.
             Example documentation icon EN.png  Dashboards
  • You should not define an automatic refreshment interval if the app is only used for displaying a snapshot of data for short periods of time.
             Example documentation icon EN.png  A portal for consulting catalogs

Master/Detail

SectionMasterDetail

Master Data Source: In a master-detail relationship, this is the name of the master data source linked to the current data source.

Master Field: Name of the primary key in the master data source used to establish the link with the current data source. As a general rule, it is the PK (Primary Key) column in the Product name - ev itsm.png table.

Detail Field: Name of the EasyVista data source column identifying the key in the Product name - ev itsm.png table. As a general rule, it is the column whose prefix is FK (Foreign Key).

Example documentation icon EN.png You want to display all actions (detail data source) associated with an incident (master data source):

  • Master Data Source = Incidents data source defined using the Operation > Incidents > All Incidents parent query.
  • Master Field = PK identifying the Incident_ID column in the Incidents table.
  • Detail Field = FK_AM_ACTION_REQUEST_ID identifying the action number related to the incident.

Procedure: How to define a REST (Connector) data source

1. If required, define the REST connector to which the new data source will point. Open url.png  See the procedure.

2. Click Apps - Add datasource icon.png in the Objects pane. Open the Online category and select the REST (Connector) data source Apps - Datasource - REST Connector icon.png.

3. Select the alias/connector you want. 

  • The data source will automatically be able to access the associated service and the list of resources defined for it.
  • The fields to be specified are automatically displayed.

4. Enter the user login information required for accessing the service. By default, the data source inherits its information from the connector. Click Edit icon.png to modify it.

  • For Basic authentication:
    • Click Edit icon.png next to the Basic Authentication Parameters field. Enter the login and password.
    • Depending on the third-party product, you may also have to specify the account in the ACCOUNT field and the domain name provided by the third-party product in the subdomain field.
  • For OAuth 2.0 authentication:
    • Click Edit icon.png next to the OAuth 2.0 Authentication Parameters field.
               EVApps - datasource REST - Oauth authentication parameters.png
    • Select the data owner's user account from the Resource Owner drop-down list. To add a new one, click [ + ].
    • Once you have validated, the *** symbols will appear in the OAuth 2.0 Authentication Parameters field.

5. Select the resource to be accessed by the data source from the Resource drop-down list.

  • The list contains all the resources defined for the service. To display their properties, click Edit icon.png.
             Apps - Connectors - Connectors tab - REST resources list.png
  • In this window, you can:
    • Click [ ADD RESOURCE ] to create a new resource. Specify its properties then click [ SAVE ]. You will return to the list of resources.
    • Click one of the resources to modify its properties.
    • Click Apps - Duplicate icon.png to duplicate a resource. Then click the new resource and modify the desired properties.
    • Click Apps - Delete icon.png to delete a resource.
  • Click [ SAVE ]. Warning: All the additions/modifications/deletions made from the list of resources are only saved when you click this button.

6. You can narrow down the data to be displayed using the Selector tool.

  • Click Edit icon.png next to the Selector field.
  • You can click the tag you want in the JSON table (Note: It will appear in yellow). You can also enter an expression in the search field and click [ APPLY ].
  • Click [ OK ].

7. Add the type of widget for displaying the selected data and point it to the REST (Connector) data source that you just configured.

SAS_IntegrationRESTAboutTheUse

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.

References and useful links

Examples of integration

Agile CRM  Logo - Agile CRM.png 

Oracle Marketing Cloud (Eloqua)  Logo - Oracle Eloqua.png

XWiki  Logo - XWiki.png

WordPress  Logo - Wordpress.png

Freshdesk  Logo - FreshDesk.png

Zendesk  Logo - ZenDesk.png

UserVoice  Logo - UserVoice.png

Tags:
Last modified by Unknown User on 2017/09/01 16:50
Created by Administrator XWiki on 2017/01/03 11:46

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