REST (Connector) Datasource

Last modified on 2022/11/08 13:22
Contents

Apps - Datasource - REST Connector icon.png This data source belongs to the Online category in the data source library. It is used to access, via a connector, the resources of a service (websites or third-party products) in order to retrieve dynamic content.

REST_ServiceResourceAuthentication
  • Services offer different types of content and data via resources.

    example  Twitter  ==> Timeline or followers

  • Data may be public and accessible to everyone (no user authentication required) or private. In this case, user authentication is required before the resource can be accessed.

    example  Content read in Google Calendar, Google Contacts, Twitter 

  • Data is read in the resource and sent to Service Apps) in JSON format.
    • This data can be displayed using widgets. The Selector tool integrated in the data source is used to extract only the data you want.
    • Data is then automatically refreshed each time that the data source is modified.

Examples

REST_Examples
  • No user authentication:
    • The http://api.open-notify.org website publishes public data in real-time from the ISS (International Space Station).

      ==> Thanks to REST architecture, the position of the ISS can be displayed using a Google Maps widget without requiring user authentication.

  • Using Basic authentication: * Creation of a timeline customized by each Twitter user.

    ==> Thanks to 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.

    • Salesforce 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.

Notes

     Open url.png See General remarks on data sources.

  • All services that use a REST API and that offer access to resources without user authentication or using Basic authentication can interface with Service Apps using a REST data source. Open url.png See Best practice.
  • For each service, EasyVista provides a list of predefined resources. You cannot modify it.
    • You can add other resources by defining a URI. Open url.png See the REST API documentation of the resource.
              Example documentation icon EN.png  Google YouTube API V3
  • The type of authentication that can be used depends on the API set up by each service and is described in the API documentation of the service.
REST_AuthenticationNotes
  • Authentication supported by Service Apps:
    • Access to public data: Service Apps Can interface with all resources without requiring user authentication.
    • Access to private data: Only two authentication methods are supported, Basic (authentication using a login and password) and OAuth 2.0.
  • OAuth authentication:
    • The list of services interfacing with Service Apps is defined by EasyVista. You cannot add to them.
    • The login information required depends on the service. Users can access either public data (e.g. general corporate data) or their own data (e.g. user-specific calendar).
  • To find out more about the JSON table structure, please consult http://www.json.org.
        Open url.png  To find out more about:

Best Practice

  • If different authentication methods are available for a given service, we recommend that you use OAuth 2.0 authentication whenever possible.
REST_DataSourcesRESTComparizon

How to choose between a REST data source and a REST (Connector) data source

  •  You should use a REST (Connector) data source to:
    • Reuse a service and its resources.
    • Access any type of resource for a REST service defined in the app.
       
  • You should use a REST data source to:
    • Define and access a REST resource.
    • Access resources without user authentication or resources using Basic authentication.
    • Use a given resource from a service occasionally (resource not intended for reuse in another app).

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 them. Note: In this case, users must authenticate when requesting access to the resource.
  • List of fields:
    • ACCOUNT / subdomain: Account and domain name provided by the service.


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.
    • Once you have validated, the *** symbols will appear in the OAuth 2.0 Authentication Parameters field.
  • List of fields:
    • Resource Owner: User account of the data owner of the service. To add a new user, click [ + ] and specify the login information specific to the service.
    • Use these account credentials for all users: Used to indicate if the login information for accessing the service 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, all users will have access to the same data. If it is not, users will have access to user-specific data.

      example  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, i.e. resources predefined by EasyVista and manually added resources.

example Twitter: Timeline or followers

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

Additional Query String: Additional filter criterion, can be used in the exposed properties, which are parameters that can be passed in the app URL in order to apply a filter or view, or to access specific records directly.

example Twitter  ==> Filter all posts for a given user.

Selector

Selector: Tool for extracting the data you want from the JSON file of the resource.

  • The JSON table contains a list of tags surrounding data subsets using curly brackets, { }.
  • You can click the tag you want in the JSON table (2).
    The tag will be highlighted in yellow.
    or
  • You can enter an expression in the search field at the top of the window (1) and click Apply  Open url.png See How to use regular expressions: JSONSelect website
             EVApps - datasource REST - Selector.png
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 not (box is not checked).

NoDataMessage

No Data Message: This message is displayed when the data source does not contain any data.

  • 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 open the field editor that enables you to select data source fields and specify the type of each field, e.g. date, integer, etc. when this is not automatically detected.

  • The Apps - datasources Properties - Preview button.png button below the property shows the number of rows (max. 15) and columns extracted. Click to open the editor.
  • The button will display No data available as long as you have not selected any of the mandatory elements for 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 refreshed 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 EVApps - datasource REST connector - Show URL.png

AutoRefresh

Auto Refresh (Note: Only for dynamic data sources): Used to indicate the automatic refreshment interval for data from the data source in hours/minutes.

  • Data is automatically refreshed each time the app is run and each time the page is redisplayed, regardless of whether it is in execute mode or edit mode.
  • Caution: The updating of data requires additional activity on the Service Apps platform.

     Best Practice icon.png

  • 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 screen.

    example  View dashboard data

  •  You should not specify an automatic refreshment interval if the app is only used for displaying a snapshot of data.

    example  Display a portal where catalogs can be consulted

Master/Detail

SectionMasterDetail

Master Datasource: 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 Service Manager) table.

Detail Field: Name of the EasyVista data source column identifying the key in the Service Manager table.

  • As a general rule, it is the column whose prefix is FK (Foreign Key).

    example  You want to display all actions (detail data source) associated with an incident (master data source):

    • Master Datasource = 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 create and use a REST (Connector) data source

Step 1: Define the REST connector.

Note: Only for users with the App Center Manager profile.

1. Click Apps - Gallery - Connectors icon.png Connector in the App Gallery toolbar or graphic editor toolbar.
The window for configuring connectors, aliases and execution contexts will appear.

2. Click Add Connector.

3. Select the REST connector type. Select the authentication method.

4. Specify all of the fields specific to the selected options.

5. Create the services and resources linked to the new connector.

     Open url.png  See the detailed procedure.
 

Step 2: Create the REST (Connector) data source.

1. Click Apps - Add datasource icon.png Add Data Source in the Objects pane.

2. Select the data source type, Apps - Datasource - REST Connector icon.png REST (Connector) (Online category).
 

Step 3: Define the properties of the new data source.

1. Select the REST connector or alias to which the data source should point.

     Open url.png See How to use connectors and aliases.

2. (optional) Select the authentication method for accessing the service linked to the connector or alias (Note: Only if the authentication method of the connector is not None).
The fields specific to the authentication method will appear.

  • (optional) Click Edit icon.png to modify the information inherited from the connector.
        Open url.png see:
    • Information for Basic authentication
    • Information for OAuth 2.0 authentication

3. Select the resource of the service accessed by the data source.

  • (optional) Click Edit icon.png to display the list of all resources for the service.
             Apps - Connectors - Connectors tab - REST resources list.png
  • You can create a new resource using Add Resource. Open url.png See the description of properties.

4. Select the data of the resource to be displayed.

  • Click Edit icon.png next to the Selector field.
    • The Selector tool window will appear. 
    • The contents of the resource will appear in a JSON table.
  • You can click the tag you want in the JSON table.
    The tag will be highlighted in yellow.
    or
  • You can enter an expression in the search field at the top of the window and click Apply.
             Apps - Connectors - Connectors tab - REST edit selector.png
  • Click OK.

5. Specify the other properties of the data source.
 

Step 4: Add the widget displaying data from the data source.

1. Click Apps - Add widget icon.png Add Widget in the Objects pane.

2. Select the type of widget you want.

3. Configure it to point to the REST (Connector) data source you previously configured.

4. Specify the other properties.
 

Step 5: Test the app.

1. Select the type of device on which you must test the app.

  • Apps - GUI - Desktop view icon.png : Display on a PC
  • Apps - GUI - Mobile view icon.png: Display on a smartphone
     

2. Click EVApps - GUI - Execute icon.png to run the app.
The app will appear in a new web browser tab.

3. Check that the data from the resource is correctly displayed.

SAS_IntegrationRESTAboutTheUse

About the use of the software companies API REST

Note: The possible cost of the use of the third-parties API REST via Service Apps is not taken care by EasyVista.

  • Numerous software companies limit the access to the API REST of their software, generally by basing itself on a number of calls by hour/day/month.
  • Only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
  • Some software companies set up plans, e.g., Classic, Professional, Enterprise, 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.

References and useful links

Examples of integration

Below is a list of the products interfacing with Service Apps using a REST (Connector) data source. See the procedure available in each page.

Tags:
Powered by XWiki © EasyVista 2022