RESTful API Groovy scripts

Requirements to launch a Groovy script in Entuity

Authentication

How do I run a Groovy script from the Entuity server?

How do I run a Groovy script from another machine?

Groovy script arguments

Example Groovy scripts

To add trusted certificates

In Entuity, Groovy scripts use the Entuity RESTful API to perform certain administrative actions.

Requirements to launch a Groovy script in Entuity:

If you are running the script on a different, non-Entuity system, you must have the following installed:

• Java (at least Java 8 version).
• Groovy (at least Groovy 2.4 version).

These requirements are already met if the Groovy script is executed on an Entuity server.

Authentication

Groovy scripts in Entuity can be authenticated using an API access key (e.g. if SAMLv2 authentication is enabled) or by username/password.

How do I run a Groovy script from the Entuity server?

1. Navigate to the directory that contains the Groovy scripts. Groovy scripts are located in <ENTUITY_HOME>/lib/tools/restAPI, and all have .groovy extension.
2. The next step depends on whether you are running Windows or Linux:
   • if you are running Windows:
     1. execute <ENTUITY_HOME>\bin\egroovy.bat <script>.groovy <args>
   • if you are running Linux:
     
     1. set ENTUITY_HOME environment variable, e.g. export ENTUITY_HOME=<path>
     2. execute <ENTUITY_HOME>/bin/egroovy <script>.groovy <args>

How do I run a Groovy script from another machine?

1. Ensure you have the above requirements (at least Java 8 version and Groovy 2.4 version) installed, and ensure that the groovy executable is in your PATH environment variable.
2. Copy the Groovy scripts that you will be running, plus the Tools.groovy script containing common utilities, from the Entuity installation to your machine.
3. Navigate to the directory to which you have copied the Groovy scripts to.
4. The next step depends on whether you are running Windows or Linux:
   • if you are running Windows:
     1. execute groovy.bat <script>.groovy <args>
   • if you are running Linux:
     1. execute <script>/groovy <args>

Default Groovy script arguments:

This table of Groovy script arguments represent a default set. Each script can have extra arguments beyond what is included here.

Example Groovy scripts:

• List users from the Entuity server configured with HTTPS running on myEntuityServer host:
  

  groovy listUsers.groovy -E myEntuityServer -S

• List users from the myPollingEntuityServer which is configured as the remote server to the myCentralEntuityServer:
  

  groovy listUsers.groovy -E myCentralEntuityServer -S -s myPollingEntuityServer

• List Views for the user identified by support/mysecret credentials:
  

  groovy listViews.groovy -U support -P mysecret

• Add 3 devices to a View named "My Office":
  

  groovy viewAddDevice.groovy -v "My Office" -d device1 -d dev2 -d anotherDevice

To add trusted certificates:

If the Entuity server is configured for HTTPS, then the issuing certificate authority must be trusted. Most well-known authorities are already trusted, but if you get errors related to certificate authority verification then you must add trust for the certificate authority. Self-signed certificates are inherently not trusted and so you will need to import them into the keystore.

To add a certificate to the list of trusted certificate authorities, enter the following command (Note, this command is on a single line. There are no line breaks within this command):

c:\Entuity\install\JRE\bin\keytool -importcert -keystore c:\Entuity\install\JRE\lib\security\cacerts -storepass changeit -alias <ALIAS> -file c:\certs\MyCA.cer

Note, the above command assumes that the Java Runtime Environment is isntalled at c:\Entuity\install\JRE and the CA certificate is stored as c:\certs\MyCA.cer. If this is not the case, please adjust the paths in the above command as appropriate to reflect your particular case.