Executing a command as a TWS event rule action

by Pete Meechan

TWS event action

When a TWS event rule has been satisfied, the TWS event processor will take the action described by the event rule action definition. This could be simply sending an e-mail, submitting a job stream or executing a command. Whilst most of the TWS event actions are pretty straight forward to use, the action to execute a command can raise quite a few problems when implemented. Fortunately, most of the issues surrounding the execution of a command as a TWS action are relatively simple to resolve once an understanding of the environment under which the command is being executed is obtained.

Where the event rule command executes

The first thing to understand is that the specified command will execute locally on the event server – by default this is the TWS Master Domain Manager (MDM). Keep in mind that the event server could be executing on the backup MDM if it has been switched using the conman switcheventprocessor command and therefore the command should also be available to that server.

Also, the command to be executed must be compatible with the TWS event server platform – if the MDM (or BMDM) is executing on the Windows platform, the command specified must be compatible with the Windows platform as well – irrespective of whether the TWS event being actioned originated on a UNIX or Linux platform.

TWS event rule command execution environment

The majority of the issues that I have looked at with implementation of the TWS event rule commmand action has been tracked down to the execution environment under which the command is executing. The command execution environment does not execute under the familiar interactive profile based logon environment that most commands do. Instead it is launched as a process under the TWS event server and consequenttly does not have the “usual” environment variables set that one would expect. This is true when the TWS event server is hosted on the Windows and Linux platform (and I suspect is also true for UNIX platforms).

In order to avoid the frustration of receiving lots of strange return codes from the TWS event rule execute command action, it is better to determine what is and is not availble to the command being executed. How to achieve this depends upon the OS platform hosting the TWS event server.

TWS event server on Windows platform

If the TWS event server is executing on the Windows platform, create a simple batch command script to provide details of what is available within the command execution environment. The simple batch command script (orb_event_rule_env.cmd) shown below can be used as an example for this.

orb_event_rule_env.cmd

@echo off 
@rem 
@rem Use the command below to activate the ORB_COMMAND event rule 
@rem 
@rem sendevent Event1 GenericEventPlugIn Param1="<parm>" Workstation="<MDM>" 
@rem 
@rem Change the path to an existing directory below 
@rem 
set LogFile="C:Temp__TWS_env.log" 
echo ++++++++++++++++++++++++++++++ Parameter(s) passed... > %LogFile% 
echo %* >> %LogFile% 
echo ++++++++++++++++++++++++++++++ Environment variables... >> %LogFile% 
set >> %LogFile% 
echo ++++++++++++++++++++++++++++++ Script... >> %LogFile% 
echo %0 
echo ++++++++++++++++++++++++++++++ Current Directory... >> %LogFile% 
echo %~f0 
echo %CD% 
echo ++++++++++++++++++++++++++++++ whoami... >> %LogFile% 
C:Windowssystem32whoami.exe >> %LogFile%

  

TWS event server on UNIX/Linux platform

If the TWS event server is executing on the UNIX/Linux platform, create a simple shell script to provide details of what is available within the command execution environment. The simple shell script (orb_event_rule_env.sh) shown below can be used as an example for this.

orb_event_rule_env.sh

#!/bin/bash
# Display environment contents for TWS event rule action command 
#
# Use the command below to trigger the event
#
# sendevent Event1 GenericEventPlugIn Param1="<parm>" Workstation="<MDM>"
LogFile=/tmp/__TWS_env.log
echo "++++++++++++++++++++++++++++++ Parameter(s) passed..." > $LogFile
echo $* >> $LogFile
echo "++++++++++++++++++++++++++++++ Environment variables..." >> $LogFile
env >> $LogFile
echo "++++++++++++++++++++++++++++++ Script..." >> $LogFile
echo $0 >> $LogFile
echo "++++++++++++++++++++++++++++++ Current Directory..." >> $LogFile
pwd >> $LogFile
echo "++++++++++++++++++++++++++++++ whoami..." >> $LogFile
id -un >> $LogFile

TWS event rule to execute a command

Having created a script to be executed as the command action, create a TWS event rule similar to the one shown below – change the path to the script and the workstation name (highlighted in red) accordingly.

orb_event_rule_env.xml

<?xml version="1.0"?>
<eventRuleSet  http://www.w3.org/2001/XMLSchema-instance">  http://www.w3.org/2001/XMLSchema-instance"
  http://www.ibm.com/>    <description>Execute command upon receipt of event</description>
  <eventCondition name="ORB_Generic_Command_Event" eventProvider="GenericEventPlugIn" 
eventType="Event1">
   <scope>
    * ON ARDBEG
   </scope>
   <filteringPredicate>
    <attributeFilter name="Param1" operator="eq">
     <value>*</value>
    </attributeFilter>
    <attributeFilter name="Workstation" operator="eq">
     <value>ardbeg</value>
    </attributeFilter>   </filteringPredicate>
  </eventCondition>
  <action actionProvider="GenericActionPlugin" actionType="RunCommand"
responseType="onDetection">
   <description>Orb_Generic_Command</description>
   <scope>
    /images/TWS/scripts/TWS-Testing/orb_event_rule_env.sh &
quot;%{ORB_GENERIC_COMMAND_EVENT.PARAM1}&quot;
   </scope>
   <parameter name="Command">
    <value>/images/TWS/scripts/TWS-Testing/orb_event_rule_env.sh</value>
   </parameter>
   <parameter name="WorkingDir">
    <value>/images/TWS/scripts/TWS-Testing</value>
   </parameter>
   <parameter name="Param01">
    <value>&quot;%{ORB_Generic_Command_Event.Param1}&quot;</value>
   </parameter>
   <parameter name="Env01">
    <value>ENV_VAR1=xxxxxx</value>
   </parameter>
  </action>
 </eventRule>
</eventRuleSet>

Load the rule into TWS using the composer add orb_event_rule_env.xml command.

Triggering the TWS event rule to execute a command

Trigger the TWS event rule to execute the orb_event_rule_env.cmd/.sh script using the command shown below – execute this from a TWS command/shell prompt.

sendevent

sendevent Event1 GenericEventPlugIn Param1="<parm>" Workstation="<MDM>"

The sendevent command shown above will trigger the orb_command event rule, executing the associated script and write the details to the temporary file.

Verifying the event rule command results

After the orb_event_rule_env.cmd/sh has executed, the contents of the temporary log file for Windows and Linux are shown below.

Windows temporary log file

++++++++++++++++++++++++++++++Parameter(s) passed...
 "this is my parameter" 
 ++++++++++++++++++++++++++++++ Environment variables... 
COMSPEC=C:WINDOWSsystem32cmd.exe 
 ENV_VAR1=xxxxxx 
LogFile="C:Temp__TWS_env.log" 
 PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS PROMPT=$P$G 
 ++++++++++++++++++++++++++++++ Script... 
 ++++++++++++++++++++++++++++++ Current Directory... 
 ++++++++++++++++++++++++++++++ whoami... 
 talisker/twsuser

As can be seen from the above log file output, there are very few of the “normal” Windows environmental variables set when the orb_event_rule_env.cmd script was executed. The most obvious one being that there is no %PATH% environment set, so this will need to be specified for most commands to execute correctly.

Linux temporary log file

++++++++++++++++++++++++++++++Parameter(s) passed... 
 this is my parameter 
 ++++++++++++++++++++++++++++++ Environment variables... 
 SHELL=/bin/bash 
 ENV_VAR1=xxxxxx 
 USER=twsuser 
 PWD=/images/TWS/scripts/TWS-Testing 
 SHLVL=3 
 HOME=/home/twsuser 
 LOGNAME=twsuser 
 _=/bin/env 
 ++++++++++++++++++++++++++++++ Script... 
 /images/TWS/scripts/TWS-Testing/orb_event_rule_env.sh 
 ++++++++++++++++++++++++++++++ Current Directory... 
 /images/TWS/scripts/TWS-Testing 
 ++++++++++++++++++++++++++++++ whoami... 
 twsuser

As can be seen from the above log file output, there are a few environmental variables set when the orb_event_rule_env.sh script was executed. One of the most obvious settings missing is the $PATH environment variable, so this will need to be specified for most commands to execute correctly.

Resolving the event rule execute command issues

The simplest way to resolve the issues raised by the lack of environment variables being set  when the event rule execute command action is executed, is to include and required settings within the script being executed. This would almost certainly require the setting of the %PATH% (Windows) or $PATH (UNIX/Linux) variable. It may also require additional environment variables to be set to include library files etc.

The TWS event rule action to execute a command allows the event rule developer to set environment variables for the command to be executed. If you refer to the orb_event_rule_env.xml definition above, there is a setting named Env01 that is specified as “ENV_VAR1=xxxxxx“, which tells the event processor to set the environment variable named ENV_VAR1 to the value xxxxxx prior to executing the specified command. This can be verified by reviewing the temporary log file contents, where the variable is listed as being set within the environment. TWS supports up to 15 environment variable settings within the event rule named Env01 through Env15. Likewise, up to 15 parameters can be specified using the parameter named Param01 through Param15.

Whilst this functionality is useful to set a few environment variables, in my experience it is much simpler to maintain the required environment variables within a wrapper script rather than coding them into the TWS event rule definition.

Update

As was pointed out to me following the posting of this tip, one use for using the environment variable setting directly in the rule rather than in a wrapper script, is to supply the value of the environment variable dynamically. For example, if the event being triggered contains a filename value (e.g. a file create event), the name of the created file could be passed directly to the command/script being executed by specifying for example “FILENAME=%{fileCrtEvt1.FileName}” as the value for Env01. The command/script being executed could then reference the environment variable %FILENAME% (Windows) or $FILENAME (UNIX/Linux) to get the name of the file.

Visits: 1277