Automation

Triggers in DATPROF Runtime

Users can Automate tasks based on the triggering of events in Runtime.

For example; when a module enters the error state, a command or shell script will execute.

Triggers are bound to an environment. 

A trigger consists of condition and an action. Triggering occurs only if certain events happen in the system. The condition determines from the event if a trigger action should be executed.  

When you create a trigger, you can test the action as if the event just happened.

By default a trigger is created enabled, you can disable it if you temporarily don’t want the actions to be executed without having to delete the automation.


Create a Trigger

You can add and edit a Trigger by accessing an environment and select the Triggers entry in the menu under Automation.

Existing entries are shown.

You can add, edit, delete these entries.

Trigger Actions

Two trigger actions are supported. One is to execute a script, the other is to send an e-mail.

Information about what event triggered this action is available in variables and is dependent on the kind of trigger condition that is used. See the different trigger conditions for the available variables.

All parameters from the environment are also available as variables in the scripts or mail actions.

Execute script

The `Execute script` action has only one property; script. This action will execute the content of the script on the machine where Runtime is installed. When Runtime is installed on a Windows machine, the script will be executed as the Windows Command Prompt (cmd). When Runtime is installed on Linux, the script will be executed as a Bash shell script.

DATPROF Runtime provides "run-status variables" and "module-status-variables". For triggers they are set as environment variables.

The use of environment variables is different for Windows (cmd) and Linux (bash).

Windows:

  • For Windows scripts the variables must be enclosed with a percentage like this: %environment%

Linux

  • for Linux scripts environment variables must be used with a dollar like this:  $environment.

A script can be tested by using the Test button. The script will then be executed with dummy values for the variables and the result will be shown in the log panel.

Send e-mail

Before using the e-mail trigger action, the mail must be configured. This must be done by an administrator by editing the configuration "mail.properties" in the <RuntimeData>/conf folder . In this folder a configuration file mail.properties.example with basic examples can be found.  Rename this to mail.properties and enter the correct settings for you mail configuration.

DATPROF Runtime uses the Open Source  JavaMail Api for sending mails. A list of all the available configuration properties can be found here: JavaMail API

 

The `Send e-mail` action has three properties;

  • a list of recipients, 
  • the e-mail subject 
  • the e-mail body.

The list of recipients is a space, comma or semicolon separated list of e-mail addresses.

Both the subject and the body are Velocity templates. The "run-status variables" and "module-status-variables" are available as velolity parameters to the template using the "dpf." prefix, for example the environment name is available as ${dpf.environment_name} in the template.  (See for information about velocity: http://velocity.apache.org/ )

When using the Test button, dummy variables are used and the e-mail will be send to all the recipients. 

Trigger Conditions

Trigger on module-status

This condition has one property, the trigger status.

When an event is raised that signals that a module changed into the selected status during a run the condition will trigger the selected action.

The event is triggered one time for every action that reaches the selected status.

StatusDescription
ERRORThis status is triggered when a module is in error.
WARNINGThis status is triggered when a module has a warning.

Trigger on module-status Variables

The following variables are available when a module-status event is triggered.

Variable nameAs Windows
Script Variable
As Linux
Script Variable

As Email Velocity

Variable

Description
event_type%event_type%$event_type${dpf.event_type}

The type of event that triggered the action (for this condition 'module-status').

environment_id%environment_id%$environment_id${dpf.environment_id}The id of the environment.
environment_name%environment_name%$environment_name${dpf.environment_name}The environment name.
module_name%module_name%$module_name${dpf.module_name}The name of the module.
status%status%$status${dpf.status}The trigger on-module status.
run_id%run_id%$run_id${dpf.run_id}The run id.
cycle%cycle%$cycle${dpf.cycle}The cycle of the module.
try_count%try_count%$try_count${dpf.try_count}The try count of the module.


Trigger on run-status

This condition is triggered when a run reaches a certain status.

StatusDescription
DONEThis status is triggered when a run finishes succesfully. Will only occur once per run.
ABORTEDThis status is triggered when a run has been aborted by a user. Will only occur once per run.
PAUSEDThis status is triggered when a run is paused. Can be triggered multiple times during a run.
ERROR

This status is triggered when a run has encountered an error. The condition wil only be triggered upon encountering the first error, Any subsequent errors will be ignored.


RUNNINGThis status is triggered when a run is running again after the run has been idle, agent crashed or the run was resumed.
CRASHEDThis status is triggered when the Runtime agent has encountered.

Trigger on Run-status Variables

The following variables are available when a run-status event is triggered.

VariableAs Windows
Script Variable
As Linux
Script Variable

As Email Velocity

Variable

Description
event_type%event_type%$event_type${dpf.event_type}The type of the event (for this condition 'run-status').
environment_id%environment_id%$environment_id${dpf.environment_id}The id of the environment.
environment_name%environment_name%$environment_name${dpf.environment_name}The name of the environment.
status%status%$status${dpf.status}The trigger on-run status
run_id%run_id%$run_id${dpf.run_id}The run id.


Trigger Example

Create Application event in eventlog on Windows

(info)
The following trigger assumes the permissions to write to the Windows Event viewer, otherwise the trigger does not work.

eventcreate /t error /id 100 /so "DATPROF Runtime" /l application /d "Runtime encountered an error while running and has stopped working in environment: %environment_name%"