Connectors


Connectors are used by certain types of data sources to:

  • Define connection settings to databases used in different steps in the deployment process of a Service Apps app.
  • Retrieve dynamic content from services (websites or third-party products) using URIs (Uniform Resource Identifiers) or endpoints.
  • Log in to Self Help.

    Open url.png See the different types of connectors.
 

Data sources can point to the connector itself or to an alias.
    Open url.png See How to use connectors and aliases.

Examples

  • Create a connector that defines the connection settings to the MySQL database that is used during the development and production phases.
  • Create a connector that provides access to the six resources proposed by JSONPlaceholder, a fake REST API with public data used for testing and prototyping:
    • JSONPlaceholder service: http://jsonplaceholder.typicode.com/
    • Resources: posts, comments, albums, photos, todos, users
  • Create a connector that provides 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 MySQL database

Note:

  • The data source points to a connector that identifies a combined database/deployment process step.

    example  SAP database in the development phase ==> Connector A; SAP database in the production phase ==> Connector B

Connectors for retrieving dynamic content

  • REST connectors. Open url.png See the description.
  • Data sources: REST (Connector)
    • Access to public data: Authentication: None
    • Access to private data: Authentication: Basic, OAuth 2.0

Note:

  • Services (third-party products or websites) can 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 

  • The data source points to an alias that identifies one of the services interfacing with the app.

    example  Service Manager, SAP, Finance or Outlook

Connectors for accessing Self Help

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 EasyVista when Service Apps is installed. You cannot create a new one or modify an existing one.
    • Service Apps is 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 EasyVista. You should provide the relevant email address. The email address must be unique in the corresponding Service Manager database.
  • REST connectors:
    • A list of services is provided by EasyVista.
      • 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 can access a service and all 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.

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 step in the deployment process.
  • 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  SAP database in the development phase ==> Connector A; SAP database in the production phase ==> 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 steps in the deployment process.
    • 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.

Best 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 Service Apps. 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 the 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 Service Manager databases.
         Connector Type - EasyVista.png

Connector Name: Connector name.

Type: Type of connector = EasyVista IT Service Manager.

URL: URL for accessing a Service Manager database.

Account: Account in the Service Manager database.
         example  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 EasyVista Support team and provide an email address that is not already used for the corresponding account.
             example  Additional access to Canada Incidents

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.

    Open url.png See How to configure an MS SQL Server connector.

         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.

    Open url.png See:

         Connector Type - REST.png

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 EasyVista), 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  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  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  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).

SelfHelp connectors

Used to configure access to a Self Help domain.
         Connector Type - Self Help.png

Connector Name: Connector name.

Type: Type of connector = EasyVista IT Service Manager.

Domain: Address of the Self Help domain.

SSL: Used to indicate if the connector uses the SSL security protocol (box is checked) or not (box is not checked).

Port: Port number for accessing the data server.

Hostname: Name of the machine hosting the data server.

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 Service Apps apps.
         example  Service Manager, SAP, Finance or 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 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 display 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 configure an MS SQL Server connector

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

An MS SQL Server connector is used to configure access to an MS SQL Server database.

Step 1: Configure the Service Apps server (command line).

1. Install the ODBC and FreeTDS packages on your Service Apps server.

2. Open the odbcinst.ini file and add or modify the [FreeTDS] section as shown below.

Note: The file is usually located in the /etc folder. However, its location may vary depending on your Linux distribution and installation method. You should adapt the paths for the pilot and configuration accordingly.

[FreeTDS]
Description = FreeTDS
Driver = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so
Setup = /usr/lib/x86_64-linux-gnu/odbc/libtdsS.so
FileUsage = 1
CPTimeout =
CPResuse =
client charset = utf-8

3. Open the odbc.ini file and add a section for each MS SQL server you want to access in Service Apps. You should adapt the example shown below.

Note: The file is usually located in the /etc folder. However, its location may vary depending on your Linux distribution and installation method. 

example

[ Nom du serveur MS SQL (ex. : SERVER1) ]
Description = (ex. : "Dev. Database")
Driver = FreeTDS
Server = adresse IP du serveur (ex. : 192.188.2.10)
UID = Nom de l'utilisateur
Port = Numéro du port du serveur (ex. : 1433)

4. Restart the Apache service.

5. Test the connection to the MS SQL server.

  • Isql -v SERVER1 username
    Note: <SERVER1> and the user name are defined in odbc.ini.
  • If required, check the log files.

    example  Location and name of a log file: /var/log/argo/argo_01/com.XXXX/debug-mssql-20180920.log

     

Step 2: Configure the Admin tenant (Web interface).

1. Log in using the Admin tenant and select the tenant to which you want to add the MS SQL Server connector.

2. Enable the MS SQL Server connector.

  • Select the Widgets Management tab.
  • Select the Allowed box in the MS SQL Server row.
             MS SQL - Admin Tenant - Widgets management.png

3. Create an MS SQL Server connector for each server you want to access.

  • Select the Connector tab.
  • Click Add Connector.
  • Select the MS SQL Server connector.
  • Refer to the information in the odbc.ini file to configure the connector.
    • Connector Name = Name of the MS SQL server section.
    • Hostname = Name of the server.
    • User = User name.
    • Port = Port number.
    • Password = Password of the MS SQL user (unavailable in the odbc.ini file).

         MS SQL - Create connector.png
 

Step 3: Use the MS SQL Server connector.

The connector is now configured and can be used in your apps.

How to configure 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.
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.
For a service defined by EasyVista, 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 Service Apps.

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.

    Open url.png See the use case.

  • Current execution context = Development execution context (step 1 in the deployment process).
  • The Dashboards widgets use data sources that 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.

    Open url.png See the use case.

  • Current execution context = Acceptance execution context (step 2 in the deployment process).
  • The Dashboards widgets use data sources that 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.

    Open url.png See the use case.

  • Current execution context = Production execution context (step 3 in the deployment process).
  • The Dashboards widgets use data sources that 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) Service Manager information, in four Dashboards widgets pointing to EasyVista data sources.
  • (2)  (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 step of the deployment process.
  •  One alias for each service interfacing with the app, e.g.EasyVista, Finance.
  • One execution context for each step of the deployment process, 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

  • You should specify the current execution context of the app (in the general properties) corresponding to the first step of 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 Service Manager.
    • 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 2020/01/18 14:05
Created by Administrator XWiki on 2014/09/02 12:21

Shortcuts

Powered by XWiki ©, EasyVista 2020