Defining the REST Agent

After installing it, the REST Agent is available in the Administration perspective under Agents in Client 0, where you can define its properties. The Agent definition consists of several pages. The Web Service page is specific to REST Agents; the rest are common to all Agents. On the Web Service page you define two key aspects of the Agent:

Whether you allow using Groovy queries and cURL commands in REST Jobs. You do this in the Settings section.
Security parameters. Once installed, the Agent must authenticate to the target RESTful service. Trusted certificates are the most secure way of proving the verified identity of the Agent.

Important!
The certificates, their passwords, keystores and so on are most probably managed by a dedicated security person or team in your organization or by the team in charge of the target REST WebService that you must connect to. You will have to request this data from them.

To Define the REST Agent

In Client 0, go to the Administration perspective > Agents & Groups > Agents list and open the REST Agent for which you want to set the parameters.
On the Agent page you can specify the following parameters:
- Attributes Section - Trusted IPs
  
  If the communication with the Agent runs with encryption, you can specify the IP addresses from which the Agent accepts non-encrypted connections. They must be separated by semicolons.
  
  Releasing individual IP addresses is only reasonable if login attempts of former Agent versions should be rejected.
- Service Manager Section
  
  These properties are necessary for the connection between the Agent and the Service Manager, an external monitoring tool that allows you to start and stop the Automation Engine and its components.
  
  The Service Manager comes with a proprietary user interface. If you want to use the AWI instead, you can do so provided you enter the necessary information.
For more information, see Agents (HOST).
On the Web Service page you can specify the following parameters:
1. In the Settings section:
  - Allow Groovy parsing of response data
    
    Allows anyone with access to edit REST Agent Jobs to select Groovy as a query type and include Groovy code as the input when defining queries. By default this option is unchecked for security purposes. Check it if you want to use Groovy query types when defining queries on the Response page for Jobs. For more information, see Defining REST Agent Jobs: Responses.
  - Allow cURL Commands
    
    Allows anyone with access to edit REST Agent Jobs to define cURL commands for their request on the Request page of the Job. For more information, see Defining REST Agent Jobs: Requests.
2. If you updated your Certification Authority (CA) password outside of the REST Agent, you need to update it in the Password field in the CA Certificates section. You must then restart the Agent.
3. In SSL Certificates you define the keystore, which holds trusted certificates for client/server authentication. In Keystore either enter the path where your company stores it or click the icon to browse to the keystore.
Save and close the Agent definition.
Stop and restart the processes for the Agent.
1. In the list of Agents, select the REST Agent that you have just defined.
2. Right-click it and select Stop.
3. Right-click it again and select Start.
Open the Agent object again and go to the Web Service page. The certificates for the keystore are now listed in the SSL Certificates table. From this table you can do the following:

Import a der certificate
1. Click Import to open the Import dialog.
2. On the Import dialog, enter a certificate file and alias in the Certificate File and Certificate Alias fields. You can use the browse icon to browse to the certificate file.
3. Click Import.
Important !
You cannot import .pem certificates. Additionally, if you have a .der certificate that was converted from a .pem format, you may not be able to browse to it.

Export a certificate
1. Select the certificate in the table and click Export. The Save file on agent file system dialog is displayed.
2. Browse to or enter the absolute file name to which you want to export the certificate.
3. Click Save to start the export.
Delete a certificate

Select the certificate and click Delete.

Defining the Agent: Common Definition Pages

Agents are Automic Automation objects. All objects have several definition pages and some of them are common to all. Optionally, you can specify additional parameters on those pages:

Defining the REST Agent

On this page you can assign the Agent a title, which is an alternative way to name it. You can also apply custom values (archive keys) that you can later use for filtering and you specify certain reporting settings.
Defining the REST Agent

The Object Authorizations page helps administrator users fine-tune the access and function rights at object level and complements the company policy defined in the Authorization system.

Important!
It is recommended to implement your user management policy at User Group level rather than at User or object level (Agents are also objects in Automic Automation). Read the User Management topics in the Automic Automation product documentation carefully before granting/removing rights at object level.
Agent (see description above)
Defining the REST Agent

On this page you enter the information you consider important to understand the configuration and behavior of the object. By default, this page allows you to enter unstructured documentation. Automic Automation system administrators can configure how many documentation pages will be displayed and whether they can contain unstructured or structured documentation.

For more information, see the Automic Automation documentation at Defining the Common Object Properties.

Next Step

Once the Agent definition is done, you must authenticate the Agent, otherwise, you will not be able to start it. For more information, see Agent Authentication in the Automic Automation documentation.

Once the Agent is authenticated, you must establish the connection to the target system. For more information, see Establishing the Connection between the REST Agent and the Target System.