Connectors


Connectors are used by certain types of data sources. Depending on the type of data source, they enable you to:

  • Define connection settings to databases used in different steps in the deployment process of a Product name - ev sas.png app.
    Example documentation icon EN.png Access the MySQL database during the development and production steps
  • Retrieve dynamic content from services (websites or third-party products) using URIs  (Uniform Resource Identifiers) or endpoints.
    • Services offer different types of content and data via resources.

      Example documentation icon EN.png  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 documentation icon EN.png Content read in Google Calendar, Google Contacts, Twitter 

       

Data sources can point to:

  • The connector itself, that identifies a combined database/deployment process step.

    Example documentation icon EN.png  SAP database in the development step ==> Connector A; SAP database in the production step ==> Connector B

  • An alias, that identifies one of the services interfacing with the app.

    Example documentation icon EN.png  Product name - ev itsm.png, SAP, Finance, Outlook

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

Examples

  • 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

Different types of connectors

Connectors for accessing a database
Access a Product name - ev itsm.png database Access a MySQL database Access an MS SQL Server database
easyvista IT Service Manager connectors

Open url.png See the description

MySQL connectors

Open url.png See the description

MS SQL Server connectors

Open url.png See the description

Data sources: EasyVista and EasyVista KPI Data sources: MySQL Data sources: MS SQL Server
Connectors for retrieving content

REST connectors

Open url.png See the description

Data sources: REST (Connector)

Access public data Access private data
Authentication: None Authentication: Basic, OAuth 2.0

How to use connectors and aliases

    Open url.png See the use case

Creation rules

  • A connector is defined for each combined database/deployment process step.
  • An alias is defined for each app service, irrespective of the deployment process step.
  • Each execution context identifies a step in the deployment process.
     

Method 1: Data sources pointing to connectors

  • Each time the app is run in a new step, all data sources must be modified to point to the connectors defined for this step.

    Example documentation icon EN.png  SAP database in the development step ==> Connector A; SAP database in the production step ==> Connector B

Method 2: Data sources pointing to aliases

  • Each time the app is run in a new step, the step must be defined in the current execution context.
    • You select this context in the general properties of the app from the execution contexts available for all deployment process steps.
    • You are not required to modify data sources before running the app. The alias linked to the data source will automatically detect the appropriate connector to be used in the current execution context.

Notes

  • Connectors, aliases, and execution contexts are defined in the App Gallery or graphic editor. They are available to all apps.
  • The current execution context is specific to the app and is defined in the general properties of the app.
  • Connectors are linked to access management in the App Gallery and to the profile of the logged-in user.
    • App Center Manager: Users can create connectors other than easyvista IT Service Manager connectors. They can also create aliases and execution contexts.
      App Creator: Users can create connectors other than easyvista IT Service Manager connectors. They can also list execution contexts but cannot see their details.
      Registered User: Users are not authorized to modify connectors, aliases or execution contexts.
  • Depending on the type of connector, the information to be specified will vary.
  • EasyVista IT Service Manager connectors:
    • They are defined by Logo - EasyVista.png during the setup of Product name - ev sas.png. You cannot create a new one or modify an existing one.
    • Product name - ev sas.png They are always shipped with a sandbox connector (account 50005) and a production connector (account 50004).
    • To create a connector with an email address, you must submit a request to Logo - EasyVista.png. You should provide the relevant email address. It must be unique in the corresponding Product name - ev itsm.png database.
  • REST connectors:
    • A list of services is defined by Logo - EasyVista.png.
      • Those using None or Basic authentication can be modified or deleted. You can also add new ones.
      • Those using OAuth 2.0 authentication cannot be modified or deleted. You cannot add new ones.
    • A REST (Connector) data source pointing to a REST connector enables you to access a service and all of the resources defined for it.
    • For services using OAuth 2.0 authentication, users can access the personal information in their accounts via their user information zone Apps - Authentication zone.png > Manage my External Accounts.
  • The number of execution contexts is specific to each customer and depends on the customer's app deployment strategy. 
  • Access to a connector linked to a sensitive database (e.g. accounting database) can be restricted using the Keep it Private property in the connector. The connector will be a private one.

Caution

  • When you change the connector of an EasyVista or EasyVista KPI data source, you must specify its components again (query, view and filter).
  • When you change the current execution context of an app, you should ensure that the components (query, view and filter) of each data source exist for the new execution context so that the associated widgets can work correctly.
  • If you want to delete a connector, an alias or an execution context, you should first ensure that they are not being used by any app because this app will no longer run correctly.

Best Practice big icon.pngBest practice

  • Define an execution context for each step in the deployment process, e.g. development, acceptance and production.
  • Define an alias for each service interfacing with Product name - ev sas.png. Associate a default connector that will be used when the app is run in cases where the current execution context is not specified.
  • Use an alias to associate a data source with a database. You should point the data source to a connector when the database does not change, regardless of the step in the deployment process.

Screens description

Access: Via the App Gallery or graphic editor > Apps - Gallery - Connectors icon.png  

List of connectors

Connectors enable you to define connection settings to databases. REST connectors indicate how dynamic content will be retrieved.
         Apps - Connectors - Connectors tab.png

  • Click one of the connectors to display its details.
  • Add Connector: Used to add a new connector.
    • You cannot add a new easyvista IT Service Manager connector.
    • The fields to be specified depend on the type of connector.

easyvista IT Service Manager connectors

Used to access Product name - ev itsm.png databases.
         Connector Type - EasyVista.png

Connector name: Connector name.

Type: Type of connector = easyvista IT Service Manager.

URL: Link for accessing the Product name - ev itsm.png database.

Account: Account in the Product name - ev itsm.png database.
         Example documentation icon EN.png  Account 40000 for the test database

Email: Email address for accessing the account.

  • By default, the email address is not specified.
  • Logged-in users can access the specified account and view only the data for their domain, e.g. Europe Incidents
  • To restrict or extend access to a specific domain, you must create a connector with an email address for this domain. Note: You should submit a request to the Logo - EasyVista.png Support team and provide an email address that is not already used for the corresponding account.
             Example documentation icon EN.png  Access to the Incidents Canada domain is required

Keep it private: Used to indicate, in edit mode, if the type of connector can be used by all users authorized to create apps (Public Public icon.png option) or only by the app creator (Private Private icon.png option).

MySQL and MS SQL Server connectors

Used to configure access to MySQL and MS SQL Server databases
         Connector Type - MySQL and MS SQL Server.png

Connector Name : Connector name.

Type: Type of connector = MySQL or MS SQL Server.

Hostname: Name of the machine hosting the data server.

Port: Port number for accessing the data server.

  • As a general rule, we use port 3306.

User: Name of the user with access rights to the data server.

Password: User password.

Keep it private: Used to indicate, in edit mode, if the type of connector can be used by all users authorized to create apps (Public Public icon.png option) or only by the app creator (Private Private icon.png option).


REST connectors

Used to retrieve dynamic content via a service.
         Connector Type - REST.png

    Open url.png See:

Connector Name: Connector name.

Type: Type of connector = REST.

Authentication method: User authentication method for accessing the service. Depending on the authentication method, the information to be specified will vary.

  • None: No authentication required because the REST API is open or public.
  • Basic: The authentication parameters specified are sent to the service in the header of the HTTP request.
  • OAuth 2.0: Authentication specific to the data owner is performed using the service. Authentication is based on the authorization delegation protocol.
     

Service URL: URL of the service interfacing with the app. Click REST - Select URL icon.png next to the field to display the list of services available and select the one you want.
         Apps - Connectors - Connectors tab - REST choose service.png

  • For None and Basic authentication (Note: Except for services defined by Logo - EasyVista.png), you can modify or delete a service. To do so, move your cursor over the name to display the contextual menu.
             Apps - Connectors - Connectors tab - REST contextual menu service.png
  • For None and Basic authentication, you can click Apps - Add icon.png to create a service.
             Apps - Connectors - Connectors tab - REST create service.png

Service Name: Name of the service.

URL: Link for accessing the service.
Note: You can add variables in the main section of the URL using the following format: {variableName}. You can also add parameters at the end of the URL prefixed by the ? or & character.
         Example documentation icon EN.png  https://{hostname}/api/v1/{account}/

Icon: Icon associated with the service.

  • By default, the icon is Wheel icon.png.
  • Click Upload icon.png to download another icon..
  • Click Apps - Remove uploaded file icon.png to return to the default icon.

 

Key / Value: Used to customize the HTTP header of queries run by a third-party REST API, by passing a password, API token or static API key, etc.
         Example documentation icon EN.png  Key = Authorization; Value = {Your Authorization Token}

ACCOUNT / subdomain (Note: Only for Basic authentication): Account and domain name provided by the service.

User name / Password authentication (Note: Only for Basic authentication): Login and password for accessing the service.

Instance (Note: Only for OAuth authentication):

Authentication parameters (Note: Only for OAuth authentication): Required parameters for accessing the service.

  • Click Edit icon.png to enter the information.
     

Default Resource: Resource proposed by default for the service when a REST (Connector) data source is created. Click REST - Select URL icon.png next to the field to display the list of resources defined for the service.
         Apps - Connectors - Connectors tab - REST resources list.png

  • Click Add Resource to create a new resource.
             Apps - Connectors - REST create resource.png

Label: Name of the resource.

URI: URI for accessing the resource.
Note: You can add variables in the main section of the URI using the following format: {variableName}. You can also add parameters at the end of the URI prefixed by the ? or & character.
         Example documentation icon EN.png  request?max_rows={maxrows}/

Default Selector: Default selector of the resource. It extracts the relevant data from the JSON file.

  • You can specify the tag directly.
  • You can also click Apps - Edit icon.png to use the Selector tool. See the procedure.

Description: Description of the resource contents.

Keep it private: Used to indicate, in edit mode, if the type of connector can be used by all users authorized to create apps (Public Public icon.png option) or only by the app creator (Private Private icon.png option).

List of aliases

Aliases identify the services interfacing with Product name - ev itsm.png apps.
         Example documentation icon EN.png  Product name - ev itsm.png, SAP, Finance, Outlook

         Apps - Connectors - Aliases tab.png

  • Click one of the aliases to display its details.
  • Add Alias: Used to add a new alias.
        Apps - Connectors - Aliases tab - Create.png

Alias Name: Name of the alias.

Type: Type of connector.

Default connector: Default connector associated with the alias, used when the app is run in cases where the current execution context is not specified.

  • Only connectors belonging to the selected type of connector will appear.

List of execution contexts

Execution contexts identify the steps in the deployment process. Open url.png See the use case.

         Apps - Connectors - Execution contexts tab.png

  • Click one of the execution contexts to see its details.
  • Add Execution Context: Used to add a new execution context.
        Apps - Connectors - Execution contexts tab - Create.png

Name: Name of the execution context.

Alias Name Associated: List of all existing aliases (services). 

Connector to be Used: The name of the connector to be used with the alias for the selected execution context.

  • If the connector is not specified for an alias, then the default connector defined in the Alias tab is used when the app is run.

Procedures

How to create a REST connector

Note: Only for users with the App Center Manager profile

REST connectors are used to retrieve dynamic content from websites or services (third-party products).

Step 1: Create a new REST connector.

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. Name the connector.

4. Select the REST connector type.
The fields specific to the type of connector will appear.

5. Select the authentication method.
The fields specific to the authentication method will appear.
         Connector Type - REST.png
 

Step 2: Select the service associated with the new connector.

1. Click REST - Select URL icon.png next to the Service URL field.
The list of existing services will appear.
         Apps - Connectors - Connectors tab - REST choose service.png

2. Specify the service.

  • Select one of the services from the list.
    You will return to the window for creating the connector. The service URL will be specified.

      or

  • Create a new service (Note: Only for None or Basic authentication).
    • Click Apps - Add icon.png.
               Apps - Connectors - Connectors tab - REST create service.png
    • Specify the properties of the service. Open url.png See the description.
    • Click OK to save the service.
      You will return to the list of services. The new service will appear.
    • Select the new service from the list.
      You will return to the window for creating the connector. The service URL will be specified.



Step 3: Configure the resources associated with the service.

1. Click REST - Select URL icon.png next to the Default Resource field.
If it is a service defined by Logo - EasyVista.png, the list of all predefined resources will appear.
         Apps - Connectors - Connectors tab - REST resources list.png

2. Click Add Resource.
         Apps - Connectors - REST create resource.png

3. Specify the properties of the resource. Open url.png See the description.

4. Specify the selector of the resource. The selector will be used for extracting data from the JSON file.

  • Specify the tag of the JSON file in the Default Selector field.

      or

  • Use the Selector tool.
    • Click Apps - Edit icon.png next to the Default Selector field.
      • The Selector tool window will appear. 
      • The contents of the resource will appear in a JSON table.
    • You can select 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. Click Save.
You will return to the list of resources.

6. Repeat the same procedure to create all of the resources to be accessed by the service.

7. Click Save.

  • All resources will be saved.
  • You will return to the window for creating the connector.

Step 5: Complete the configuration of the REST connector.

1. Select the resource proposed by default when a new REST (Connector) data source is created from the Default Resource drop-down list.

2. Specify the fields specific to the selected authentication method. Open url.png See the description.

3. In the Keep it private field, indicate whether you want a public or private connector.

  • Public icon.png : Public connector
  • Private icon.png: Private connector

4. Click OK to save the connector.
 

Step 6: Create a REST (Connector) data source pointing to the new REST connector.

1. Go to the App Gallery.

2. Click Apps - Application properties icon.png in the toolbar of the app that will use the new connector.
The graphic editor will appear.

3. Create a new REST (Connector) data source.

  • Point it to the new connector.
    The new data source will be able to access the associated service and all of the resources configured for the connector.
  • Specify the other properties. Open url.png See the procedure.

 

How to deploy an app

Step 1: Prepare the configuration of aliases, connectors and execution contexts.

1. Download the document below. It contains the template of a pivot table for aliases, connectors and execution contexts.
         Download icon.png Table

2. Complete the table using your own elements in order to facilitate the next steps in the configuration. Open url.png See the use case.
         Table for Preparing the Configuration - EN.png 

Step 2: Configure connectors, aliases and execution contexts.

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. Create all of the connectors to be used in the deployment process.

  • Click Add Connector.
  • Specify a new connector for each database to be used by services (third-party products).

3. Create all of the aliases corresponding to services (third-party products) to be used in the deployment process.

  • Select the Aliases tab.
  • Click Add Alias.
  • Define an alias for each service (third-party product) interfacing with Product name - ev sas.png.

4. Create all execution contexts corresponding to all of the steps in the deployment process.

  • Select the Execution Contexts tab.
  • Click Add Execution Context.
  • Specify the connector to be used for connecting to each of the aliases displayed.
     

Step 3: Configure step 1 in the deployment process.

1. Go to the App Gallery.

2. Click Apps - Application properties icon.png in the app toolbar to open the app.

3. Modify the current execution context of the app.

  • Click Apps - Application properties icon.png to display the general properties.
  • Select the execution context corresponding to step 1 in the deployment process from the Choose an execution context field.
  • Click Save.

4. Go to each data source and specify the alias (third-party product or service) to which it should point.

5. Click EVApps - GUI - Execute icon.png to test the app.
The current execution context will automatically search for the connectors to be used with each alias.

    Example documentation icon EN.png  Open url.png  See the use case.

  • Current execution context = development (step 1 in the deployment process) 
  • Data sources that are used by Dashboards widgets point to the EasyVista alias ==> When they are run, the EasyVista ITSM SBox connector will automatically be used.

 

Step 5: Configure step 2 in the deployment process.

1. Click Apps - Application properties icon.png to display the general properties of the app.

2. Select the current execution context corresponding to step 2 in the deployment process from the Choose an execution context field.

3. Click Save.

4. Click EVApps - GUI - Execute icon.png to run the app.

    Example documentation icon EN.png  Open url.png See the use case.

  • Current execution context = acceptance (step 2 in the deployment process)
  • Data sources that are used by Dashboards widgets point to the EasyVista alias ==> When they are run, the EasyVista ITSM Test connector will automatically be used.

 

Step 6: Configure the next steps in the deployment process.

1. Repeat the procedure in step 5 up to the final step to deploy the app in your production environment.

    Example documentation icon EN.png  Open url.png  See the use case.

  • Current execution context = production (last step in the deployment process)
  • Data sources that are used by Dashboards widgets point to the EasyVista alias ==> When they are run, the EasyVista ITSM Prod connector will automatically be used.

 

Step 7: Define access rights to the app.

1. Go to the App Gallery.

2. Click Apps - Application rights.png in the app toolbar.

3. Assign rights for running the app to the relevant users.

 

Use case

Dashboard displaying:

  • (1) Product name - ev itsm.png information, in four Dashboards widgets pointing to EasyVista data sources.
  • (2) Financial charts, in three Dashboards widgets pointing to MySQL data sources linked to a Finance database.

       Apps - Connectors - Example.png

Connectors, aliases and execution contexts used by the app
       Apps - Connectors - Example table - EN.png

  • One connector for each database used by the app in each deployment process step.
  • One alias for each service interfacing with the app, e.g. EasyVista, Finance
  • One execution context for each deployment process step, e.g. development, acceptance and production.
     

How to build the app in the development environment before switching to the two other environments, i.e. acceptance and production

    Method 1: Data sources pointing to connectors

  • Create the app. Point each data source to the connector to be used in the development step. 
  • Perform acceptance for the app. Point each data source to the connector to be used in the acceptance step.
  • Deploy the app. Point each data source to the connector to be used in the production step.

==> Disadvantage: You must modify all data sources and point them to the new connector for each step of the process.

   Best Practice icon.png Method 2: Data sources pointing to aliases

  • Specify the current execution context of the app in the general properties corresponding to the first step in the deployment process = development execution context.
  • Create the app. Point each data source to the alias that identifies the service.
    • EasyVista: Data sources linked to Product name - ev itsm.png.
    • Finance: Financial data sources.
  • Test the app. The connectors that will be used are those defined for each service in the development execution context.
  • Perform acceptance for the app (step 2 in the process). Modify the current execution context = acceptance execution context.
  • Test the app. The connectors that will be used are those defined for each service in the acceptance execution context.
  • Deploy the app (step 3 in the process). Modify the current execution context = production execution context.
  • Users run the app. The connectors that will be used are those defined for each service in the production execution context.

==> Advantage: You only need to modify the current execution context of the app for each step of the process.

Tags:
Last modified by Unknown User on 2019/04/01 20:15
Created by Administrator XWiki on 2014/09/02 12:21
Powered by XWiki ©, EasyVista 2019