- Welcome to the EasyVista Wiki
- Service Manager Documentation
- Service Manager - Administration Overview - Workflows and Business Rules
- Settings of REST Action Types
Settings of REST Action Types
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 (accessible via an authentication.
See the different authentication modes.).
- Service Manager can also be used as a service via its REST API.
- A connection establishes access to the service by specifying the authentication elements required for accessing the REST API of this service, such as login and password, access token, key and client secret.
- 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 accessible via a URI.
- You can perform different operations on the resource using REST methods (GET for reading data, POST for writing data, PUT / PATCH for modifying data, DELETE for deleting data).
- 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
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
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
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}"
}
Authentication methods supported by Service Manager
Authentication method | Characteristics | |
---|---|---|
None |
|
|
Basic |
|
|
AWS (Amazon Web Service) |
|
|
Bearer Token |
|
|
OAuth2 (custom) |
|
|
Self Help |
|
|
ServiceNav |
|
Notes
- Services:
- The mode of authentication 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
: https://{subdomain}/xwiki/rest
- Trello service URI
: https://api.trello.com/1/&key={application_id}&token={auth_token}
- XWiki service URI
- Connections:
- A list of connections is provided by EasyVista with the Service Manager setup. You cannot add a connection.
- Resources:
- For each third-party product, EasyVista provides a list of resources for each service.
- They cannot be modified.
- You can add other resources manually 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, EasyVista provides a list of resources for each service.
- It is possible to export and import REST services and resources.
Best Practice
- Delete the services you do not need in the list of services provided by EasyVista. In this way, the palette of action types in the graphic editor will only display the REST action types you require.
Caution
AWS (Amazon Web Service) authentication
- 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.
Screens description
Services
Menu access: Administration > REST > Services
Service 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.
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: Default or Client_ credentials.
Private Key: Private key that was downloaded.
Service URL: https://{hostname}/servicenav/{languages}.
Connections
Menu access: Administration > REST > Connections
Connection Name: Name identifying the connection.
Authentication Method: Mode of authentication for accessing the REST API of the service.
Service Name: Name of the third-party service for the connection.
- Only services corresponding to the selected authentication mode will be available.
Service URL: URL for accessing the service.
- The URL is automatically displayed when the service is selected.
- If the URL contains variables, the fields related to these variables will automatically appear and will be mandatory.
example
- Information required for accessing the EasyVista service
- Information required for accessing the AgileCRM service
- Information required for accessing the EasyVista service
Additional information to specify depending on the authentication mode and the service
User Name Authentication / Password Authentication: Login and password for accessing the service called by the connexion.
ACCOUNT / subdomain: Account and domain name provided by the 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 Authorization key associated with {Your Authorization Token} value
Authentication parameters (Note: Only for the Oauth2 (custom) authentication mode): Caution: You must click and save the connection.
Resources
Menu access: Administration > REST > Resources
Note: Depending on the 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.
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 a REST method (GET for reading data, POST for writing data, PUT / PATCH for modifying data, DELETE for deleting data).
- If the resource authorizes users to select data, the Selector field will automatically appear. Click
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
See How to use regular expressions: JSONSelect website
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.
- 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}"} |
|
Returns 1 500.34 in French or 1,500.34 in English. | ||
{"Price": "{Price:double}"} {"Price": "{Price:float}"} {"Price": "{Price:numeric}"} |
|
Returns 1500.34 regardless of the language. | ||
{"Price": "{Price:int}"} |
|
Returns 1500 regardless of the language. |
Description: Description of the operation to be performed on the resource.
Procedures and Wizards
How to associate a new resource 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 .
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 .
3. Select the service.
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 .
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
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.
- Click
- For the other methods: Specify the body of the request in the Content field.
See the examples.
- Click Save.
The new resource will be available in the list of action types in the graphic editor of the process.
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.
3. Click and drag the new resource to the graphic editor of the process.
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
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 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.
See the list of methods.
- Specify the parameters used by the method.Note: The parameters are defined in the method.
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. 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.
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.
Step 5: Test the process.
ManageServiceManagerRESTAPIInProcess_Result
example Create an employee
Result returned if the update is successful
Result returned if the update failed