Job Execution Strategy Groovy

XTAM Server includes a facility to run a script inside an XTAM server itself, not even on the host OS it is deployed on (although this script might trigger an OS execution).

These scripts should be developed in the scripting language called Groovy.

Groovy scripts work the same way whether XTAM is deployed on Windows or on Linux OS.

Groovy scripts could be used to implement sophisticated password reset strategies for the WEB portals using REST API, custom devices.

They can also be used to automate system processes whether periodic ones or those based on the system events such as session completion, password unlock or workflow execution for certain records or record types.

Groovy scripts are created in the Script Library as described in the following guide.

A record type or a record task list can include the Groovy script as any other script in the system. Check Task Configuration guide.

System administrators can assign any task execution policies to a Groovy script such as scheduled periodic policies (once a month, etc), event-based policies (after session, etc) or manual on-demand policies.

Check system policy guide.

Groovy script specification

Groovy class in the job execution script should implement three functions:

  1. The function isReset indicates whether the script resets password on record or it is just a script to automate something. Reset the password scripts generate a password based on the complexity formula. Reset password scripts also update records at the end of the successfully completed task execution workflow.
  2. The function execute is called to execute the script. The function receives the following parameters in the argument array.
    1. Record is the map of record attributes

    2. Shadow is the map of shadow record attributes

    3. Password is the new password to assign if applicable

    4. Parameters is the map of the parameters defined by the operator at the time of the scheduling of the task. This map also includes all record fields in using the key RECORD.FieldName as well as all fields of the shadow record using the key SHADOW.FieldName

    5. System logger for info, warn, debug and trace logs

    6. The function execute returns the value saved in the job execution details. When the function returns a value, the task is considered successful. When the function has thrown an exception, the task is considered to error.

  3. The function verify is called to verify the results of the script execution. As an example, the function might be used to check the validity of newly reset password. The function receives the following parameters in the argument array.

    1. Record is the map of record attributes

    2. Shadow is the map of shadow record attributes

    3. Password is the new password to assign if applicable

    4. System logger for info, warn, debug and trace logs

  4. The function execute returns the value saved in the job execution details. When the function returns a value, the task is considered successful. When the function thrown an exception, the task is considered to error. An example of an exception statement is given below
  5.  

    throw new Exception ("Groovy script failure");

     

    When an exception is thrown the function stops its control flow. XTAM catches the exception, saves it in job details and marks the job as Error.

XTAM job execution workflow

When job is scheduled based on policies (once a month), events (after session) or manually on-demand, XTAM goes through several steps to process this job.

  • generate – generates new password based on the record complexity formula if this is reset job.
  • reset – executes the script (calls Groovy execute)
  • verify – verifies the results of the script execution (checks the password, for example) – this part calls Groovy.verify
  • update – updates a record with the newly generated, executed and verified password
  • trigger – optionally triggers dependencies such as update related services or fallbacks
  • complete – completes the job with ether completed or error state

 

As a result, the job could be on one of the following states that are displayed on the Job History report for a record or system one.

 

  • Scheduled – the job is scheduled
  • GeneratedXTAM generates a password for the job. On-demand job when user provides a password land in this status in the job queue right away
  • Executed – script is executed
  • Verified – script is verified
  • Updated – record is updated with the new password (if this is isReset job)
  • Error – job failed
  • Completed – job completed successfully
  • Cancelled – job is cancelled in the job history report

Methods of the record and shadow record objects

Record and shadow record objects passed to execute or verify functions have the following methods that access record attributes:

 

getCert()

getCheckStatusSelf()

getCommandPassword()

getCommandUser()

getConnectionString()

getEnabledSSL()

getHost()

getHostNameDNS()

getIntPort()

getPassword()

getPasswordAttribute()

getPasswordSu()

getPort()

getPrologue()

getReconcilePassword()

getReconcilePasswordSU()

getReconcileUser()

getReconcileUserSU()

getService()

getServicePort()

getUser()

getUserSu()

Script access to record and shadow record custom field values

In addition to this, the script has access to all custom fields for a record or a shadow record through parameters argument.

In the example below we used a parameter called RECORD:Host.

In this case, the script developer can use any other out of the box or custom field instead of Host defined in a record to get its value in a script.

For shadow record the value would be SHADOW:FieldName

Copy
                def String execute(final Object... args) {
                                def record = args[0];
                                def shadow = args[1];
                                def password = args[2];
                                def params = args[3];
                                def logger = args[4];
 
                                def user = record.getUser();
                                return ("XTAM Success Execute: " + user + " field: " + params.get("RECORD:Host"));
                }