- Welcome to the EasyVista Wiki
- ev|Service Engine - Administration
- REST API - Action types settings
REST API - Action types settings
Through steps in the process or workflow (workflows or business rule related processes) defined in the graphic editor, can call the REST API of other products in order to access external data.
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.
- 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
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
1. Create a card (task to do) in Trello ==> Call the Trello service 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
Body of the request for creating a new card
{
"idList": "{idlist}",
"name": "{name}"
}
2. Modify an Employee form in ==> Call the
service 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
Body of the request for updating a form
{
"identification": "123",
"last_name": "Talma, Bart",
"phone_number": "+34902430685"
}
3. Create an Employee form in ==> Call the
service 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
Body of the request for creating a new form
{
"employees": [
{
"last_name": "{lastName_value}",
"phone_number": "{telephone_value}"
}
]
}
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
with the
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.
- XWiki service URI
: https://{subdomain}/xwiki/rest
- Trello service URI
: https://api.trello.com/1/&key={application_id}&token={auth_token}
- XWiki service URI
- Connections:
- The authentication methods available are None and Basic.
- Resources:
- For each third-party product,
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.
See the REST API documentation of the resource.
- To find out more about the JSON table structure, please consult http://www.json.org.
- For each third-party product,
- It is possible to export and import REST services and resources.
Best practice
- In the list of services provided by
, 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
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
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.
- Information required for accessing the
service
- Information required for accessing the AgileCRM service
- Information required for accessing the
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.
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
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
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: Access to the tool for extracting the data you want from the JSON table which contains all data retrieved from the resource.
- The JSON table contains a list of tags surrounding data subsets using curly brackets, { }.
- You can select the Selector tool using an expression in the search field (1) or by selecting a tag from the JSON table (2).
To find out more about:
- The JSON data structure: json.org
- The use of regular expressions in the search field (1): JSONSelect
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.
Description: Description of the operation to be performed on the resource.
Procedure and Wizards
Procedure
How to define a new resource and associate it to a REST action type
1. If the new resource concerns a third-party product service that is not provided as standard by , create this one:
- Select Administration > REST > Services in the menu.
- Click
.
- Specify the fields. Note: In the service URL, enter the variable names in between curly brackets { }.
- If you want to associate an icon with the service, click [ CHANGE ] to select it.
- Click [ SAVE ].
2. If the connection associated with the service doesn't exist, create this one:
- Select Administration > REST > Connections in the menu.
- Click
.
- Select the service you just created by selecting the relevant authentication method from the list to filter the values.
- Specify the information required, such as the login and password, and the values of the variable parameters.
- Click [ SAVE ].
3. Create the resource associated with this connection:
- Select Administration > REST > Resources in the menu.
- Click
.
- Select the service and the connection desired.
- Specify the information required.Note: The resource URI will automatically be added to the service URL.
- If the resource uses GET, you can narrow down the data you want using the Selector tool.
- Click
next to the Selector field.
- You can click the tag you want in the JSON table (Note: It will appear in yellow). You can also enter an expression in the search field and click [ FILTER ].
- Click [ SAVE ].
- Click
- For the other methods, specify the body of the request in the Content field.
See the examples.
- Click [ SAVE ]. It will now appear in the list of action types in the graphic editor of the process.
4. You can now add the new resource to a step in a process via a REST action type :
- Open the workflow or business rule related process you want.
- Workflow: Transition or Operation > References > Workflows
- Business rule: Administration > Business Rules > Related Processes
- Click V next to REST Actions.
- Click and drag the new service to the graphic editor.
- Double-click the outline of the new step and complete the properties pane.
- Click [ CONFIRM CHANGES ].
EndProcedure
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).