Configuration of REST Action Types

Last modified on 2023/02/09 10:13
Contents

Service Manager can call the REST APIs of third-party apps to access external data.

  • The third-party Web services must be declared in Service Manager and the associated services, connections and resources must be defined. Open url.png See the description

Services, connections and resources

Description

Service

A service identifies the third-party product that authorizes access to certain data via its REST API.

  • Each service is reached via a URI that uses the REST (Representational State Transfer) HTTP protocol.
  • The data of the service can be public and accessible to everyone or restricted to certain users (authentication required). Open url.png See Authentication methods

  Service Manager can also provide REST Web services that enable third-party apps to access data.Open url.png See Service Manager REST API

Connection

A connection establishes access to a given service once you have entered the required credentials for accessing the REST API, e.g. login and password, access token, app ID and client secret, etc.
 

Resource

A resource identifies an object in a given service which can be manipulated via the REST API.

  • Each service may propose several resources, each accessible via a URI.
  • You can perform different operations on the resource using REST methods, e.g. GET (read data), POST (write data), PUT / PATCH (update data) and DELETE (delete data).
  • Data read in the resource is sent to Service Manager in JSON format, a structured text data format. A Selector tool enables you to extract only the data you want.
  • Data is dynamic. It is automatically refreshed each time the data source is updated.

Examples

  • Create an Employee form in Service Manager ==> Call the Favicon EasyVista - 16.png EasyVista service to use the Service Manager REST API:
    • Service URL: https://{hostname}/api/v1/{account}/
    • Create a connection to specify the variables in the settings: {hostname} and {account}
    • Resource URI: employees
    • Method: POST

{
  "employees": [
      {
        "last_name": "{lastName_value}",
        "phone_number": "{telephone_value}"
      }
   ]
}
  • Create a card (task to do) in Trello ==> Call the Icon - Trello.pngTrello service to use the Trello REST API:
    • Service URL: https://api.trello.com/1/&key={application_id}&token={auth_token}
    • Create a connection to specify the variables in the settings: {application_id} and {auth_token}
    • Resource URI: cards
    • Method: POST

{
  "idList": "{idlist}",
  "name": "{name}"
}

Authentication methods supported by Service Manager

Authentication method Characteristics
None
  • Open or public REST API.
  • Access to public data.
  • No credentials are required for accessing the service.
Basic
  • Access to private data.
  • A user login and password are required for accessing the service.
  • Credentials are specified during login.
AWS (Amazon Web Service)
  • Access to private data.
  • An API ID and secret key are required for accessing the service.
  • Credentials are specified when accessing the service.
Bearer Token
  • Access to private data.
  • Depending on the method used to retrieve the token, an API ID and secret key or a user login and password may be required during login.
  • Authentication is performed using the token to access private data.
  • Credentials are specified when accessing the service.
OAuth2 (custom)
  • Access to private data.
  • Authentication specific to the data owner is performed using the service. Authentication is based on the authorization delegation protocol.
  • For manual authentication, a login and secret key are required for accessing the login page.
Self Help
  • Access to a Self Help domain.
  • A Self Help API key is required.
ServiceNav
  • Access to private data.
  • Depending on the method used to retrieve the token, an API ID and secret key or a user login and password may be required during login.
  • Authentication is performed using the token to access private data.
  • Credentials are specified when accessing the service.

Notes

  • Services:
    • The authentication method depends on the API set up by each third-party product and is described in the documentation of the API.
    • A list of services is provided by EasyVista with the Service Manager setup.
      • They cannot be modified.
      • You can add other services manually.
    • The service URI can contain:
      • Parameters: These must be found at the end of the URL and each one must be prefixed by &.
      • Variables or variable parameters: These must be surrounded by curly brackets { }. The values must be specified in the corresponding connection.

        example

        • XWiki service URIIcon - XWiki.png: https://{subdomain}/xwiki/rest
        • Trello service URIIcon - Trello.png: https://api.trello.com/1/&key={application_id}&token={auth_token}
  • Connections:
    • A list of authentication methods is provided by EasyVista with the Service Manager setup. You cannot add new ones.
  • Resources:
    • A list of resources for each service is provided by EasyVista.
      • They cannot be modified.
      • You can add other resources manually by defining a URI.Open url.png See the REST API documentation of the resource.
    • To find out more about the JSON table structure, please consult http://www.json.org.

Caution

  • Bearer authentication method for the Service Manager REST API
    • You must create an access token using the Access Tokens menu.
    • You must specify None for the authentication method and enter the value of the access token.
  • AWS (Amazon Web Service) authentication method
    • Check that your PHP configuration uses the CACert certificate of your system in line with your organization's policy.
    • You must specify the location of the certificate to ensure that PHP flows will be correctly initiated in HTTPS.
    • AWS resources are system resources identified by their label. You must not modify this label.

Best Practice

  • Delete the services that you are not using among those provided by EasyVista. This ensures that the palette of action types in the process graphic editor will only display those that you are using.

Screens description

Services

          REST - Service.png

Menu access: Administration > REST > Services
 

Name: Name identifying the third-party product.

Authentication Method: Authentication method used for accessing the REST API of the service.

  • The method depends on each REST API.
  • Depending on the authentication method, the information to be specified will vary.

Caution: Select the None authentication method to use the Service Manager REST API with Bearer authentication.

Service URL: Link for accessing the service.

  • 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: Image associated with the service so that users can identify it quickly among the workflow steps. 

  • Click Change to select the file you want.
  • The supported file formats are jpg, png and gif.
     

Additional information for the AWS (Amazon Web Service) authentication method

API ID: Login.

Secret Key: Secret key.

Region: AWS region.

Additional information for the Bearer Token authentication method

Access Token Endpoint: URL of the token to be retrieved.

Bearer token property name: Name of the property.

API ID Property Name: Name of the property.

API ID: Login.

Secret Key Property Name: Name of the property.

Secret Key: Secret key.

Token Method: Default, Basic or URI.

Body Param Type: Default, form-data or form-urlencoded.

Grant Type: Default or Client_ credentials.

Private Key: Private key that was downloaded.

Additional information for the OAuth2 (custom) authentication method

Authorization Endpoint: URL called by Service Manager that will return a login page for manual authentication.

  • Note: Mandatory if the third-party service has implemented this functionality.

Access Token Endpoint: URL of the token to be retrieved.

Scopes: This is generally a table that stores different authorization levels.

API ID: Login.

Secret Key: Secret key.

Callback URL: Server used for redirecting to the Service Manager Web line that will perform the REST call using OAuth authentication.

Token Method: Default, Basic or URI.

Body Param Type: Default or form-data.

Grant Type: Default or Client_ credentials.

Additional information for the Self Help authentication method

API ID: ID of the Self Help API key.

Secret Key: Secret of the API key.

Private Key: Private key downloaded from Self Help.

Service URL: https://{hostname}/selfhelp/api.

Additional information for the ServiceNav authentication method

Access Token Endpoint: URL of the token to be retrieved.

API ID Property Name: Name of the property.

API ID: Login.

Secret Key Property Name: Name of the property.

Secret Key: Secret key.

Token Method: Default, Basic or URI.

Body Param Type: Default, form-data or form-urlencoded.

Grant Type: Client_credentials.

Private Key: Private key that was downloaded.

Service URL: https://{hostname}/servicenav/{languages}.

Connections

          REST - Connection.png

Menu access: Administration > REST > Connections
 

Connection Name: Name identifying the connection.

Authentication Method: Authentication method used for accessing the REST API of the service.

Caution: Select the None authentication method to use the Service Manager REST API with Bearer authentication.

Name: Name of the service for the connection.

  • Only services corresponding to the selected authentication method will be available.

Service URL: Link for accessing the service.

  • The URL is automatically defined when the service is selected.
  • If URL contains variables, the fields related to these variables will appear and will be mandatory.

    example

    • Information required for accessing the EasyVista service
               REST - Example URL Connection with variables - EasyVista service.png  
    • Information required for accessing the AgileCRM service
               REST - Example URL Connection with variables - AgileCRM service.png  
     

Additional information required based on the authentication method and service

Username / User password: Login and password required for accessing the service called by the connection.

ACCOUNT / subdomain: Account and domain name provided by the service.

Key / Value: Used to customize the HTTP header of requests run by a third-party REST API, by passing a password, token or static API key, etc.

example  Key = Authorization; Value = {Your Authorization Token}

Caution: To call the Service Manager REST API using Bearer authentication, specify the following:

  • Key = Authorization
  • Value = Bearer + the value of the access token previously created in the Access Tokens menu.

          Connection for Service Manager bearer authentication.png

Authentication parameters (Note: Only for OAuth2 (custom) authentication)

Caution: You must click Edit icon.png and save the connection.

Resources

          REST - Resource.png

Menu access: Administration > REST > Resources

Note: Depending on the selected REST method, the information to be specified will vary.

Label: Name identifying the resource.

Caution: AWS (Amazon Web Service) resources are system resources identified by their label. You must not modify this label.

          REST - AWS resources.png

Name: Name of the service for the resource.

Connection Name: List of connections available for the service.

Resource URI: Unique ID of the resource. The URI is automatically added to the service URL.

Method: Different operations that can be performed on the object using REST methods, e.g. GET (read data), POST (write data), PUT / PATCH (update data) and DELETE (delete data).

  • If the resource authorizes users to select data, the Selector field will automatically appear. Click Apps - Edit icon.png to access the tool.
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

Contents: Body of the request containing the data to be updated.

  • You should specify the settings in curly brackets { } when creating the corresponding REST step in the workflow.

Note:  You can force a numerical value from Service Manager Autumn 2020 - Build 2020.2.125.3 onwards.

  • By default, the value of the field is sent to the REST API in text format. To force a numerical value, you must define the data type in the field as Double, Float, Int or Numeric.

Caution: The thousands separator will depend on the configuration settings of the platform used by the logged-in user. In Windows, this is specified in the Control Panel > Regional and Language Options. 

Instruction Value returned Example

Note: Default option

{"Price": "{Price}"}
  • The value is processed as an alphanumeric value.
  • It takes into consideration the regional and language options defined.
 Returns 1 500.34 in French or 1,500.34 in English.
{"Price": "{Price:double}"}
{"Price": "{Price:float}"}
{"Price": "{Price:numeric}"}
  • The value is processed as a numerical value with decimals.
  • It will not take into consideration the regional and language options defined.
 Returns 1500.34 irrespective of the language.
{"Price": "{Price:int}"}
  • The value is processed as a numerical integer.
  • It will not take into consideration the regional and language options defined.
 Returns 1500 irrespective of the language.

Description: Description of the operation performed on the resource.

Procedures and Wizards

How to associate a new resource with a REST action type

Step 1: Create a service that is not provided by EasyVista

Note: Only if there is no existing service (third-party product). 

1. Select Administration > REST > Services in the menu.

2. Click Add icon.png.

3. Complete the information required.

  • In the service URL, enter the variable names surrounded by curly brackets { }.
  • If you want to associate an icon with the service, click Change.

4. Click Save.

Step 2: Create a new connection for the service

Note: Only if there is no existing connection associated with the service.

1. Select Administration > REST > Connections in the menu.

2. Click Add icon.png.

3. Select the service.

Best Practice icon.png  Filter the list based on the authentication method.

4. Specify the additional information required.

5. Click Save.

Step 3: Create the resource associated with the connection

1. Select Administration > REST > Resources in the menu.

2. Click Add icon.png.

3. Select the service followed by the connection.

4. Enter the additional information for the resource.

The resource URI will automatically be added to the service URL.

  • Resource using the GET method: You can narrow down the data using the Selector tool.
    • Click Apps - Edit icon.png next to the Selector field.
    • You can select the tag you want in the JSON table.
      It will appear in yellow.
      or
      You can also enter an expression in the search field and click Filter.
    • Click Save.
  • For the other methods: Specify the body of the request in the Content field. Open url.png See the examples

5. Click Save.
The new resource will appear in the list of action types in the process graphic editor.

Step 4: Add the new resource to a process step using a REST action type

1. Open the workflow or the business rule-related process you want.

  • Workflow: References > Other References > Workflows (Operation/Transition)
  • Business rule: Administration > Business Rules > Related Processes

2. Click V next to the REST Actions category.

          Graphical process editor - Action types bar.png

3. Click and drag the new resource to the process graphic editor.

          Graphical process editor - Action types bar - Drag and drop.png

4. Double-click the outline of the step to specify its properties.

5. Click Confirm changes.

How to manage the result of a Service Manager REST action within a process

Workflows and business rule-related processes can contain REST actions.

  • All Service Manager REST API methods can be called.
  • You can manage the result of the REST action, i.e. Success or Error, using internal update steps.
     

example  Manage the results when calling the Create an employee method 

Service Manager REST API action type - Workflow.png

Step 1: Select the process

1. Open the process where you want to add the action.

  • Workflow: References > Other References > Workflows (Operation/Transition)
  • Business rule: Administration > Business Rules > Related Processes
     

Step 2: Create the step used to call a Service Manager REST API resource

1. Click and drag the Favicon EasyVista - 16.png EasyVista action type from the palette of action types (REST Actions category) to the graphic editor.

2. Double-click the outline of the step to specify its properties.

  • Select the resource used to identify the Service Manager REST API method. Open url.png See the list of methods
  • Specify the parameters used by the method. Note: The parameters are defined in the method.
             Service Manager REST API action type - Create employee step detail.png
     

Step 3: Create the step for the exit value, Success

1. Click and drag the Internal Update Step action type from the palette of action types (Automatic Actions category) to the graphic editor.

2. Double-click the outline of the step to specify its properties. Open url.png See Graphic editor > Description of a step.

  • Enter the SQL script used to update the Service Manager database.

    example  Update the Description field using the result returned by the REST call

    Note: You can use another field to store the result.

  • Define the entry condition.
    • Select the step linked to the Service Manager REST action you created earlier.
    • Select the exit value, True, to indicate that the update is successful.

          Service Manager REST API action type - Success step detail.png
 

Step 4: Create the step for the exit value, Error

1. Click and drag the Internal Update Step action type from the palette of action types (Automatic Actions category) to the graphic editor.

2. Double-click the outline of the step to specify its properties.

  • Enter the SQL script used to update the Service Manager database.
  • Define the entry condition.
    • Select the step linked to the Service Manager REST action you created earlier.
    • Select the exit value, False, to indicate that the update failed.

          Service Manager REST API action type - Error step detail.png

Step 5: Test the process

ManageServiceManagerRESTAPIInProcess_Result

example  Create an employee

Result returned if the update is successful

{"HREF":"https://{your_server}/api/v1/{your_account}/employees/18445"}

Result returned if the update failed

REST step workflow failed, HTTP error code returned by the service [HTTPCODE:401] (2114) "Error http4xx"x"

EndManageServiceManagerRESTAPIInProcess_Result

How to define access authorization to the Service Manager REST API

  • Via a Basic authentication with entry of a login / password. Open url.png See the procedure.
  • Via a Bearer authentication (None authentication method) with entry of an access token. Open url.png See the procedure.

Wizards

Service

Delete

Login

Delete

Resource

Duplicate
Delete

Tags:
Powered by XWiki © EasyVista 2022