REST action types settings


Through steps in the processes (workflows or business rule related processes) defined in the graphic editor, Service Manager can call the REST API of other products in order to access external data. 

example  The Trello REST API is called to access the list of projects and tasks

This functionality is based on the concept of service, connection and resources.

  • 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 relies on the REST (Representational State Transfer) HTTP protocol.
    • The service's data may be public and accessible to everyone or restricted to certain users (Basic authentication requiring a login and password).
    • Service Manager can also be used as a service via its REST API.
  • A connection establishes access to the service once the authentication elements for accessing the REST API of this service have been specified:
    • Login and password for Basic authentication.
    • If the URL of the service contains variables, these values must be specified.
  • A resource identifies an object in a given service which can be manipulated via the REST API of the service.
    • Each service may propose several resources, each accessible via a URI.
    • You can perform different operations on the resource using methods corresponding to HTTP verbs: GET for reading data, POST for writing data, PUT and PATCH for modifying data, and DELETE for deleting data.
    • Once access is authorized, data is read and 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 updated each time the data source is modified.

Examples

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

Click to see the body of the request

{
  "employees": [
      {
        "last_name": "{lastName_value}",
        "phone_number": "{telephone_value}"
      }
   ]
}
  • Modify an Employee form in Service Manager ==> Call the Logo - EasyVista EV initials - Circle.png EasyVista service to use the Service Manager REST API:
    • URL: https://{hostname}/api/v1/{account}/
    • Create a connection that enables you to specify the variables in the settings: {hostname} and {account}
    • Resource URI: employees/{id_employee}
    • Method: PATCH

Click to see the body of the request

{
"identification": "123",
"last_name": "Talma, Bart",
"phone_number": "+34902430685"
}
  • Create a card (task to do) in Trello ==> Call the Icon - Trello.png Trello service to use the Trello REST API:
    • URL: https://api.trello.com/1/&key={application_id}&token={auth_token}
    • Create a connection that enables you to specify the variables in the settings: {application_id} and {auth_token}
    • Resource URI: cards
    • Method: POST

Click to see the body of the request

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

Notes

  • Services (third-party products):
    • The type of authentication that can be used 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 found between curly brackets { }. The values must be specified in the corresponding connection.

        example 

        • XWiki service URI Icon - XWiki.png: https://{subdomain}/xwiki/rest
        • Trello service URI Icon - Trello.png: https://api.trello.com/1/&key={application_id}&token={auth_token}
  • Connections:
    • The authentication methods available are None and Basic.
  • Resources:
    • For each third-party product, EasyVista provides a list of predefined resources to meet the most common user requirements.
      • They cannot be modified.
      • You can add other resources manually for specific requirements 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.

Best Practice

  • In the list of services provided by EasyVista, delete the services you do not need. In this way, the palette of action types in the graphic editor will only display the REST action types you require.

Screens description

Services

         REST - Service.png

Menu access: Administration > REST > Services
 

Service Name: Name identifying the third-party product.

Authentication Method: Type of authentication for accessing the REST API of the service. The method depends on each REST API.

  • None: No authentication required.
  • Basic: Users must enter their login and password when they want to access the service.

Service URL: URL for accessing the service.

  • The URL can contain the names of variables between curly brackets { } as follows: {variable_name}.
  • The URL can contain parameters found at the end of the URL, each one of which must be prefixed by &.

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. Note: The supported file formats are jpg, png and gif.

Connections

        REST - None Connection.png  REST - Basic Connection.png

Menu access: Administration > REST > Connections
 

Connection Name: Name identifying the connection.

Authentication Method: Filter used to display only the services with the selected authentication method.

  • None: No authentication required.
  • Basic: Users must enter their login and password. In this case, the User Name Authentication and Password Authentication fields will automatically appear and will be mandatory.

Service Name: Name of the third-party service for the connection.

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

Service URL: URL for accessing the service. It is automatically displayed when the service is selected.

  • If the service URL contains variables, the fields related to these variables will automatically 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  

Key / Value: Used to customize the HTTP header of the requests made to a third-party REST API.

  • In particular with a Basic authentication, any third-party REST APIs require to pass a static password token/API Key (generally created/revoked in an admin interface) in the HTTP header of all API calls.

    example   Authorization key associated with {Your Authorization Token} value

  • Note: According to the third API, you should use None or Basic authentification mode.
     

User Name Authentication and Password Authentication (Note: Only for the Basic authentication method): A login and password is required in order to access the service for which the connection is defined.

Resources

         REST - Resource.png

Menu access: Administration > REST > Resources

Note: Based on the method selected, the fields below may differ.

Label: Name identifying the resource.

Service Name: Name of the third-party 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: Operation to be performed on the object using HTTP verbs:

  • GET: Read the resource. Note: If the resource authorizes users to select data, the Selector field will automatically appear. Click Apps - Edit icon.png to access the tool.
  • POST: Add a resource.
  • PUT and PATCH: Perform a partial update of the resource without modifying the fields that are not passed as parameters.
  • DELETE: Delete the resource.
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

Content: 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: Forcing the value in numeric format is available since version Autumn 2020 - Build 2020.2.125.3 of Service Manager.
  • By default, the value of a field will be sent to the REST API in Text format. In order to force the value in numeric format, you should specify the field type with one of those parameters: Double, Float, Int, Numeric.
    Caution: The thousands separator depends on the platform configuration settings used by the logged-in user. In Windows, this is specified in: Control Panel > Regional and Language Options.
Instruction Returned value Example

Note: Default option

{"Price": "{Price}"}
  • The value will be treated as an alphanumeric value.
  • It takes into account the regional settings of the language.
Returns 1 500.34 in French or 1,500.34 in English.
{"Price": "{Price:double}"}
{"Price": "{Price:float}"}
{"Price": "{Price:numeric}"}
  • The value will be treated as an decimal numeric value.
  • It does not take into account the regional settings of the language.
Returns 1500.34 regardless of the language.
{"Price": "{Price:int}"}
  • The value will be treated as an decimal numeric value.
  • It does not take into account the regional settings of the language.
Returns 1500 regardless of the language.

Description: Description of the operation to be performed on the resource.

Procedure and Wizards

How to define a new resource and associate it to a REST action type

Step 1: Create a service not provided as standard byEasyVista.

Note: Only if the service (third-party product) doesn't exist.

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

2. Click Add icon.png.

3. Specify the information.

  • In the service URL, enter the variable names in between curly brackets { }.
  • To associate an icon with the service, click Change to select it.

4. Click Save.

Step 2: Create a new connection for the service.

Note: Only if the connection associated with the service doesn't exist.

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

2. Click Add icon.png.

3. Select the service.

Best Practice icon.png  Filter the list by selecting the relevant authentication method.

4. Specify the other information.

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 then the connection.

4. Specify the other information of the resource.

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

  • The resource uses GET: You can narrow down the data you want using the Selector tool.
    • Click Apps - Edit icon.png next to the Selector field.
    • Click the tag you want in the JSON table.
      It will appear in yellow.
      or
      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.

Step 4: Add the new resource to a step in a process via a REST action type.

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

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

2. Click V next to REST Actions.

        Graphical process editor - Action types bar.png

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

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

4. Specify the step properties by double-click its outline.

5. Click Confirm Changes.

How to manage the result of a Service Manager REST action in 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 EasyVista action Logo - EasyVista EV initials - Circle.png 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 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 just created.
    • 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 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 just created.
    • 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, the service send a bad http code [HTTPCODE:401] (2114) "Error http4xx"
EndManageServiceManagerRESTAPIInProcess_Result

Wizards

Service

Delete: Used to delete the service. Caution: No check will be performed on services used in a workflow step.

Connection

Delete: Used to delete the connection. Caution: No check will be performed on connections used by services or in a workflow step.

Resource

Duplicate: Used to create a new resource using a template. The new resource will automatically be associated with the same service and with the same connection as the template.

Delete: Used to delete the resource. Caution: No check will be performed on resources used by services or in a workflow step.

Tags:
Last modified by Christine Daussac on 2021/05/10 10:12
Created by Administrator XWiki on 2017/03/17 13:08

Shortcuts

Powered by XWiki ©, EasyVista 2021