Connectors are used by certain types of data sources to:

• Define connection settings to databases used by Service Apps apps.
• Retrieve dynamic content from services (websites or third-party products) using URIs (Uniform Resource Identifiers) or endpoints.
• Log in to Self Help.
• Use a Service Bots virtual agent.

    See the different types of connectors.
 

Data sources can point to the connector itself or to an alias.
     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

• Create a connector that provides access to a Service Apps app using a virtual agent:
  • Service: The Service Apps app

Different types of connectors

Connectors for accessing a database

• Access a Service Manager database
  • EasyVista IT Service Manager connectors.  See the description.
  • Data sources: EasyVista and EasyVista KPI

• Access a MySQL database
  • MySQL connectors.  See the description.
  • Data sources: MySQL

• Access an MS SQL Server database
  • MS SQL Server connectors.  See the description.
  • Data sources: MS SQL Server

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.  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 a Self Help domain

• Self Help connectors.  See the description.
• Widget: Self Help
• Data source: EasyVista Self Help
   

Note: 

• You can define single sign-on via an API key. This enables authenticated users to access content on the Self Help portal using their Service Apps credentials. A Self Help account will automatically be assigned to users if they do not have an existing one.
• To restrict access to a given Self Help project within the domain, you can specify the project reference in the connector.
• If you want to specify several Self Help projects, you must create one Self Help connector for each project.

Connectors for using a Service Bots virtual agent

• Service Bots connectors.  See the description.
• Widget: Virtual Agent
• Data source: EasyVista Virtual Agent
   

Note: 

• You can define a public account to authorize users who are not authenticated in Service Apps to access the virtual agent.
• You can define single sign-on via an API key. This enables authenticated users to access virtual agent content on the Self Help portal using their Service Apps credentials. A Self Help account will automatically be assigned to users if they do not have an existing one.
• To restrict access to a given virtual agent within the domain, you can specify the virtual agent reference in the connector.
• If you want to specify several virtual agents, you must create one Service Bots connector for each virtual agent.

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.  See User management.
  • 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  > 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

    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  >  

List of connectors

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

• 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 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  option) or only by the app creator (Private  option).

MySQL and MS SQL Server connectors

Used to configure access to MySQL and MS SQL Server databases.

    See How to configure an MS SQL Server connector.

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  option) or only by the app creator (Private  option).

REST connectors

Used to retrieve dynamic content via a service.

    See:

• REST (Connector) data source
• How to configure a REST connector

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  next to the field to display the list of services available and select the one you want.
         

• 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.
           
  
• For None and Basic authentication, you can click  to create a service.
           

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}

Note : Do not include a possible BOM (Byte-order Mark) in the JSON body sent, it is recommended to use the "Content-type" key with the value "application/json; charset=utf-8" so "Content-type: application/json; charset=utf-8"

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  to enter the information.
   

Default Resource: Resource proposed by default for the service when a REST (Connector) data source is created. Click  next to the field to display the list of resources defined for the service.
         

• Click Add Resource to create a new resource.
           

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  option) or only by the app creator (Private  option).

Self Help connectors

Used to configure access to a Self Help domain.
         

Connector Name: Connector name.

Type: Type of connector = Self Help.

Domain: Location of the Self Help server.

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.

Project ID or Alias: ID (GUID or full alias) of the Self Help project to be run.

• The full alias will have the following format, <Self Help domain alias> / <Self Help project alias>. Caution: The name is case-sensitive.

Connection Account : Public account that authorizes users who are not authenticated in Service Apps to access Self Help.

• If you do not specify a public account, Self Help access will only be allowed to authenticated users. The authentication method depends on whether or not you enabled an API key by ticking the Cross Service Authentication box.
• You must have previously created the public account in Self Help and selected the Connection without password option in order to authorize users to connect without a password.  See admin mode in the Desktop Studio > Writers and Users > Info tab.
• If SSO is used, the public account must be specified.
   

Cross Service Authentication: Used to indicate whether authentication via an API key is enabled for accessing Self Help (box is checked) or not (box is not checked). If it is enabled, you will be required to specify the parameters for the API key.

• If authentication via an API key is not enabled, authenticated users will access Self Help via the public account. Otherwise, they can access using their Self Help credentials, provided they have an account in Self Help.
• If authentication via an API key is enabled, and delegated to a Trusted Provider, authenticated users can access Self Help using their Service Apps credentials. A Self Help account will automatically be assigned to users if they do not have an existing one.

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  option) or only by the app creator (Private  option).

Service Bots connectors

Used to access to a Service Bots virtual agent.
         

Connector Name: Connector name.

Type: Type of connector = Service Bots.

Domain: Location of the Self Help server.

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.

Agent Reference: Identifier of the virtual agent in Self Help.

Public Account: Public account that authorizes users who are not authenticated in Service Apps to access the virtual agent.

• If you do not specify a public account, virtual agent content will only be accessible to authenticated users. The authentication method depends on whether or not you enabled an API key by ticking the Cross Service Authentication box.
• You must have previously created the public account in Self Help and selected the Connection without password option in order to authorize users to connect without a password.  See admin mode in the Desktop Studio > Writers and Users > Info tab.
• If SSO is used, the public account must be specified.
   

Cross Service Authentication: Used to indicate whether authentication via an API key is enabled for accessing the virtual agent (box is checked) or not (box is not checked). If it is enabled, you will be required to specify the parameters for the API key.

• If authentication via an API key is not enabled, authenticated users will access virtual agent content via the public account. Otherwise, they can access this content using their Self Help credentials, provided they have an account in Self Help.
• If authentication via an API key is enabled, and delegated to a Trusted Provider, authenticated users can access virtual agent content in Self Help using their Service Apps credentials. A Self Help account will automatically be assigned to users if they do not have an existing one.

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  option) or only by the app creator (Private  option).

List of aliases

Aliases identify the services interfacing with Service Apps apps.
         example  Service Manager, SAP, Finance or Outlook

• Click one of the aliases to display its details.

• Add Alias: Used to add a new alias.
      

List of execution contexts

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

• Click one of the execution contexts to display its details.

• Add Execution Context: Used to add a new execution context.
      

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.

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. 

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.
           

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

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

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

1. Click  next to the Service URL field.
The list of existing services will appear.
         

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 .
             
  • Specify the properties of the service.  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  next to the Default Resource field.
For a service defined by EasyVista, the list of all predefined resources will appear.
         

2. Click Add Resource.
         

3. Specify the properties of the resource.  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  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.
             
  • 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.

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.  See the description.

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

• : Public connector
• : 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  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.  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.
          Table

2. Complete the table using your own elements in order to facilitate the next steps in the configuration.  See the use case.
          

Step 2: Configure connectors, aliases and execution contexts.

1. Click 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  in the app toolbar to open the app.

3. Modify the current execution context of the app.

• Click  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  to test the app.
The current execution context will automatically search for the connectors to be used with each alias.

    See the use case.

Step 5: Configure step 2 in the deployment process.

1. Click  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  to run the app.

    See the use case.

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.

    See the use case.

Step 7: Define access rights to the app.

1. Go to the App Gallery.

2. Click  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.

Connectors, aliases and execution contexts used by the app
       

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

      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.