Last updated: September 19, 2008
Installation and Configuration
EventManager Error Code Reference
Appendix A: Licenses and Acknowledgements
Note that EventManager registration information is persistent data. This means that if you register with the EventManager service, if you shutdown STAF and restart it (even if you reboot the machine), the prior registration information will still be active. When STAF starts, it reads in the previous EventManager registration information, and again registers each STAF command with the Event service.
Note: The version of the Event service must be 3.1.0 or later.
SERVICE <Name> LIBRARY JSTAF EXECUTE <EventManager Jar File Name> [OPTION <Name[=Value]>]... [PARMS "[EVENTSERVICEMACHINE <EventServiceMachine>] [EVENTSERVICENAME <EventServiceName>] [OLDVARRESOLUTION]"]
where:
Notes:
Examples:
SERVICE EventManager LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/eventmanager/STAFEventManager.jar
SERVICE EventManager LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/eventmanager/STAFEventManager.jar \
PARMS "EVENTSERVICEMACHINE machA.austin.ibm.com"
SERVICE EventManager LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/eventmanager/STAFEventManager.jar \
PARMS "EVENTSERVICEMACHINE machA.austin.ibm.com EVENTSERVICENAME Event2"
MACHINE specifies the name of the machine where the command will be executed. This option will not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the EventManager service). When the specified Event Type/Subtype is generated, the value of MACHINE will not be evaluated as a python string.
PYTHONMACHINE specifies the name of the machine where the command will be executed. This option will not resolve STAF variables. When the specified Event Type/Subtype is generated, the value of PYTHONMACHINE will be evaluated as a python string.
SERVICE specifies the name of the service to be executed. This option will not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the EventManager service). When the specified Event Type/Subtype is generated, the value of SERVICE will not be evaluated as a python string.
PYTHONSERVICE specifies the name of the service to be executed. This option will not resolve STAF variables. When the specified Event Type/Subtype is generated, the value of PYTHONSERVICE will be evaluated as a python string.
REQUEST specifies the request to be executed. This option will not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the EventManager service). When the specified Event Type/Subtype is generated, the value of REQUEST will not be evaluated as a python string. This option will handle private data.
PYTHONREQUEST specifies the request to be executed. This option will not resolve STAF variables. When the specified Event Type/Subtype is generated, the value of PYTHONREQUEST will be evaluated as a python string. This option will handle private data.
TYPE specifies the Event Type for which this command will be registered. It is not case sensitive. This option will resolve STAF variables.
SUBTYPE specifies the Event SubType for which this command will be registered. It is not case sensitive. This option will resolve STAF variables. If SUBTYPE is not specified, the request will be executed when any Event with the specified TYPE is generated.
DESCRIPTION specifies a description of the registration. It is for informational purposes only. This option will resolve STAF variables.
PREPARE specifies Python code which will be executed when the registered event is generated. This code will be executed prior to the PYTHONMACHINE, PYTHONSERVICE, and PYTHONREQUEST options being evaluated as python strings. This option will not resolve STAF variables. If the Python code sets the variable STAFEventManagerSubmit to any string other than 'true', then the request will not be submitted.
ENABLED specifies that the command will be enabled when it is registered. This means that the command will be submitted when an Event with the specified type/subtype is generated. This is the default if the ENABLED or DISABLED options are not specified.
DISABLED specifies that the command will be disabled when it is registered. This means that the command will not be submitted when an Event with the specified type/subtype is generated.
In addition, each PROPERTY option name=value pair for the generated event will be set as Python variables.
Also, a Python dictionary named "eventinfo" will contain all of the above name/value pairs.
Syntax: STAF local EVENTMANAGER REGISTER MACHINE local SERVICE PROCESS REQUEST "START COMMAND notepad" TYPE a SUBTYPE b DESCRIPTION "Start the Windows Notepad application"
Syntax:
STAF local EVENTMANAGER REGISTER MACHINE local SERVICE PROCESS PYTHONREQUEST "'START COMMAND %s' % (mycmd)" TYPE a SUBTYPE b
STAF local EVENT GENERATE TYPE a SUBTYPE b PROPERTY mycmd=notepad
STAF local EVENT GENERATE TYPE a SUBTYPE b PROPERTY mycmd=regedit
Syntax:
This example uses the PYTHONREQUEST option to specify the request using Python syntax which is needed so that it can access the Python variables named myTestMachine and myServerMachine. Because the PYTHONREQUEST value is enclosed in double quotes and single quotes, any quotes used within this value need to be escaped with a backslash. This example also uses the PREPARE option to construct the map of arguments in Python which are passed to the STAX job which helps eliminate the need to escape some quotes.
STAF local EVENTMANAGER REGISTER MACHINE server1 SERVICE STAX PYTHONREQUEST "'EXECUTE FILE /tests/TestA.xml ARGS \"%s\"' % (args)" PREPARE "args = { 'testMachine': myTestMachine, 'serverMachine': myServerMachine }" TYPE RunSTAXJob SUBTYPE TestA
STAF local EVENT GENERATE TYPE RunSTAXJob SUBTYPE TestA PROPERTY myTestMachine=client1 PROPERTY myServerMachine=server9
Actually, it's usually easier to register a more complex request like this that uses Python code via the EventManagerUI instead of the command line because then you don't have to bother so much with escaping quotes. See the Registration Example using Python and Prepare Script section for an example of how to register this STAF command via the EventManager User Interface.
ID specifies the EventManager ID which is to be unregistered.
MACHINE specifies the machine for which EventManager requests should be listed.
TYPE specifies the Type for which EventManager requests should be listed.
LONG indicates to list more detailed information about each EventManager request.
SETTINGS indicates to list the operational settings for the EventManager service. The operational settings include the name of the Event service machine and the name of the Event service that the EventManager service registers with. The Event service machine/name can be specified using the EVENTSERIVCEMACHINE and EVENTSERVICENAME parameters when registering the EventManager service.
Definition of map class STAF/Service/EventManager/Settings | |||
---|---|---|---|
Description: This map class represents the operational settings for the service. | |||
Key Name | Display Name | Type | Format / Value |
eventServiceMachine | Event Service Machine | <String> | |
eventServiceName | Event Service Name | <String> |
Definition of map class STAF/Service/EventManager/EMID | |||
---|---|---|---|
Description: This map class represents a registered EventManager request. | |||
Key Name | Display Name | Type | Format / Value |
eventManagerID | ID | <String> | |
description | Description (Desc) | <String> | <None> | |
machine | Machine | <String> | |
service | Service | <String> | |
request | Request | <String> | Private data will be masked. |
type | Event Type | <String> | |
subtype | Event Subtype | <String> | <None> |
Definition of map class STAF/Service/EventManager/EventManagerIDShort | |||
---|---|---|---|
Description: This map class represents a general registered EventManager request. | |||
Key Name | Display Name | Type | Format / Value |
eventManagerID | ID | <String> | |
description | Description (Desc) | <String> | <None> | |
machine | Machine | <String> | |
service | Service | <String> | |
request | Request | <String> | Private data will be masked. |
Definition of map class STAF/Service/EventManager/EventManagerID | |||
---|---|---|---|
Description: This map class represents a registered EventManager request with detailed information. | |||
Key Name | Display Name | Type | Format / Value |
eventManagerID | ID | <String> | |
description | Description | <String> | <None> | |
machine | Machine | <String> | |
machineType | Machine Type | <String> | 'Literal' | 'Python' |
service | Service | <String> | |
serviceType | Service Type | <String> | 'Literal' | 'Python' |
request | Request | <String> | Private data will be masked. |
requestType | Request Type | <String> | 'Literal' | 'Python' |
type | Event Type | <String> | |
subtype | Event Subtype | <String> | <None> | |
prepareScript | Prepare Script | <String> | <None> | Private data will be masked. |
enabled | Enabled | <String> | 'true' | 'false' |
Syntax: STAF local EVENTMANAGER LIST
Result: If the request is submitted from the command line, the result, in the table format, could look like:
ID Description Machine Service Request Event Type Event Subtype -- --------------- ----------- ------- -------------- ----------- ------------- 1 Start the Windo client1.aus PROCESS START COMMAND mytype <None> ws Registry Edi tin.ibm.com regedit tor 2 <None> client2 PROCESS START COMMAND myType mySubType /tests/TestA 3 Notify tester t client1.aus EMAIL SEND TO JohnDo manual-test BEGIN:default hat the manual tin.ibm.com e@us.ibm.com M test is ready t ESSAGE "Manual o be executed Test begin"
Syntax: STAF local EVENTMANAGER LIST SHORT
Result: If the request is submitted from the command line, the result, in the table format, could look like:
ID Description Machine Service Request -- ----------------- ---------------------- ------- --------------------------- 1 Start the Windows client1.austin.ibm.com PROCESS START COMMAND regedit Registry Editor 2 <None> client2 PROCESS START COMMAND /tests/TestA 3 Notify tester tha client1.austin.ibm.com EMAIL SEND TO JohnDoe@us.ibm.com t the manual test MESSAGE "Manual Test begin" is ready to be e xecuted
Syntax: STAF local EVENTMANAGER LIST MACHINE client1.austin.ibm.com TYPE manual-test LONG
Result: If the request is submitted from the command line, the result, in the verbose format, could look like:
[ { ID : 3 Description : Notify tester that the manual test is ready to be executed Machine : client1.austin.ibm.com Machine Type : Literal Service : EMAIL Service Type : Literal Request : SEND TO JohnDoe@us.ibm.com MESSAGE "Manual Test begin" Request Type : Literal Event Type : manual-test Event Subtype : BEGIN:default Prepare Script: <None> Enabled : true } ]
Syntax: STAF local EVENTMANAGER LIST SETTINGS
Result: If the request is submitted from the command line, the result could look like:
Event Service Machine: server1.austin.ibm.com Event Service Name : event
ID specifies the EventManager ID which is to be triggered.
SCRIPT defines Python code to be executed. You may specify any number of SCRIPT options. They will be executed in the order specified, and will be executed prior to the registration's PREPARE, PYTHONMACHINE, PYTHONSERVICE, AND PYTHONREQUEST values are evaluated. It is useful when you need to simulate values that would normally be available with the event information (such as Properties).
Upon successful return:
Definition of map class STAF/Service/EventManager/Trigger | |||
---|---|---|---|
Description: This map class represents information about the submitted STAF command. | |||
Key Name | Display Name | Type | Format / Value |
machine | Machine | <String> | |
requestNumber | Request Number | <String> |
Syntax: STAF local EVENTMANAGER TRIGGER ID 5
Result: If the request is submitted from the command line, the result, in the verbose format, could look like:
Machine : dave2268.austin.ibm.com Request Number: 1426
Syntax: STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME eventmanager CONTAINS "[ID=5] [dave2268.austin.ibm.com:1426]"
Result: If the request is submitted from the command line, the result, in the verbose format, could look like:
20060809-13:57:27 Info [ID=5] [dave2268.austin.ibm.com:1426] Submitted a STAF command. Event information: N/A Submitted STAF command: STAF local var RESOLVE STRING {STAF/Config/MachineNickname} 20060809-13:57:27 Info [ID=5] [dave2268.austin.ibm.com:1426] Completed a STAF command. RC=0, Result=testmachine1
Syntax:
STAF local EVENTMANAGER TRIGGER ID 12 SCRIPT "platform = 'win32'" SCRIPT "version = '3.x'"
Result: If the request is submitted from the command line, the result, in the verbose format, could look like:
Machine : client1.austin.ibm.com Request Number: 293851
ID specifies the EventManager ID which is to be enabled.
ID specifies the EventManager ID which is to be disabled.
VERSION specifies to display the version level of the EventManager service or the version level of Jython packaged with the EventManager service.
JYTHON specifies to display the version level of Jython packaged with the EventManager service.
Syntax: VERSION
Result: 3.3.3
Syntax: VERSION JYTHON
Result: 2.1-staf-v3
Syntax: HELP
Result:
EventManager Service Help REGISTER [DESCRIPTION <description>] MACHINE <machine> | PYTHONMACHINE <machine> SERVICE <service> | PYTHONSERVICE <machine> REQUEST <request> | PYTHONREQUEST <request> TYPE <eventType> [SUBTYPE <eventSubType>] [PREPARE <script>] [ENABLED | DISABLED] UNREGISTER ID <registrationID> LIST <[MACHINE <machine>] [TYPE <eventType>] [LONG | SHORT]> | SETTINGS TRIGGER ID <registrationID> [SCRIPT <Python code>]... ENABLE ID <registrationID> DISABLE ID <registrationID> VERSION [JYTHON] HELP
Note that EventManager registration information is persistent data. This means that if you register with the EventManager Service, if you shutdown STAF and restart it (even if you reboot the machine), the prior registration information will still be active. When STAF starts, it reads in the previous EventManager registration information, and will execute the registered STAF commands when the corresponding events are generated.
In EventManager V3.1.3, the format of this data was modified. Persistent registration data for versions prior to EventManager V3.1.3 will automatically be migrated to the new format. Note that the new format can not be used with versions of EventManager prior to V3.1.3.
The EventManager service maintains a machine log where it writes information about the STAF commands that it has submitted. It is important to check the log to determine the results of STAF commands submitted by the EventManager service. The EventManager service will log an entry when the following occurs:
[ID=<xx>] [<machine>, <handleName>]where <xx> is the ID that was registered, <machine> is the machine that originated the REGISTER request, and <handleName> is the name of the handle that originated the REGISTER request. The level of the log entry will be Info.
[ID=<xx>] [<machine>:<requestNumber>]where <xx> is the ID for which the STAF command was submitted, <machine> is the machine on which the STAF command was submitted, and <requestNumber> is the request number for the STAF command. The level of the log entry will be Info.
[ID=<xx>] Python errorwhere <xx> is the registration ID for which the Python interpreter encountered an error. The level of the log entry will be Error.
[ID=<xx>] Error submitting a STAF command.where <xx> is the registration ID of the STAF command that was submitted. The level of the log entry will be Error.
[ID=<xx>] ID is disabled. STAF command not submitted.where <xx> is the registration ID for which the type/subtype matched. The level of the log entry will be Info.
[ID=<xx>] [<machine>:<requestNumber>]where <xx> is the registration ID for which the STAF command was executed, <machine> is the machine on which the STAF command was executed, and <requestNumber> is the request number for the STAF command. The log entry will include the RC and Result from the STAF command. If the RC is 0, the level of the log entry will be Pass; otherwise the level of the log entry will be Fail.
[ID=<xx>] [<machine>:<requestNumber>]where <xx> is the registration ID for which the STAF command was executed, <machine> is the machine on which the STAF command was executed, and <requestNumber> is the request number for the STAF command. The log entry will include the RC and Result from the STAF process. If the RC is 0, the level of the log entry will be Pass; otherwise the level of the log entry will be Fail.
[ID=<xx>] [<machine>, <handleName>]where <xx> is the registration ID that was unregistered, <machine> is the machine that originated the UNREGISTER request, and <handleName> is the name of the handle that originated the UNREGISTER request. The level of the log entry will be Info.
[ID=<xx>] [<machine>, <handleName>]where <xx> is the registration ID that was enabled, <machine> is the machine that originated the ENABLE request, and <handleName> is the name of the handle that originated the ENABLE request. The level of the log entry will be Info.
[ID=<xx>] [<machine>, <handleName>]where <xx> is the registration ID that was disabled, <machine> is the machine that originated the DISABLE request, and <handleName> is the name of the handle that originated the DISABLE request. The level of the log entry will be Info.
The [ID=<xx>] and [ID=<xx>] [<machine>:<requestNumber>] tags in the log entries can be useful when querying the log. They can be used with the CONTAINS option of the log service's QUERY request.
The logname for the EventManager service is the name under which the service is registered.
Here is an example of what an EventManager service log on the local machine could look like shown via a request from the command line in the table format:
C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME eventmanager Response -------- Date-Time Level Message ----------------- ----- ------------------------------------------------------- 20060808-15:33:34 Info [ID=1] [local://local, STAF/Client] Registered a STAF c ommand. Register request: REGISTER DESCRIPTION :20:Get the STAF version MACHINE local SERVICE misc REQUEST ver sion TYPE q SUBTYPE p 20060808-15:33:34 Info [ID=2] [local://local, STAF/Client] Registered a STAF c ommand. Register request: REGISTER DESCRIPTION :17:Run java -version MACHINE local SERVICE process REQUEST :61 :start command java parms -version returnstdout stderrt ostdout TYPE s SUBTYPE t 20060808-15:33:34 Info [ID=3] [local://local, STAF/Client] Registered a STAF c ommand. Register request: REGISTER DESCRIPTION :20:Pyth on runtime error MACHINE local SERVICE misc REQUEST ver sion TYPE a SUBTYPE b PREPARE a=b 20060808-15:33:39 Info [ID=1] [dave2268.austin.ibm.com:2322] Submitted a STAF command. Event information: type=q subtype=p prepare= e ventservice=Event eventid=4 generatingmachine=local://l ocal generatingprocess=STAF/Client generatinghandle=94 eventtimestamp=20060808-15:33:39 properties={} Submitte d STAF command: STAF local misc version 20060808-15:33:39 Pass [ID=1] [dave2268.austin.ibm.com:2322] Completed a STAF command. RC=0, Result=3.1.4.1 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Submitted a STAF command. Event information: type=s subtype=t prepare= e ventservice=Event eventid=5 generatingmachine=local://l ocal generatingprocess=STAF/Client generatinghandle=95 eventtimestamp=20060808-15:33:42 properties={} Submitte d STAF command: STAF local process start command java p arms -version returnstdout stderrtostdout 20060808-15:33:42 Pass [ID=2] [dave2268.austin.ibm.com:2336] Completed a STAF command. RC=0, Result=96 20060808-15:33:42 Pass [ID=2] [dave2268.austin.ibm.com:2336] Process completed . Process info: {key=, handle=96, rc=0, endTimestamp=20 060808-15:33:42, fileList=[{rc=0, data=java version "1. 5.0" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64) Java HotSpot(TM) Client VM (build 1. 5.0-b64, mixed mode) }]} 20060808-15:33:45 Error [ID=3] Python error in the PREPARE value. PREPARE: a=b PyException: Traceback (innermost last): File "<st ring>", line 1, in ? NameError: b Processing registr ation: ID: 3 machine: local service: misc reque st: version prepare: a=b Event service message infor mation: eventservice: Event eventid: 6 type: a subtype: b generatingmachine: local://local generat ingprocess: STAF/Client generatinghandle: 97 eventt imestamp: 20060808-15:33:45 properties: {} 20060808-15:33:48 Info [ID=3] [local://local, STAF/Client] Unregistered a STAF command. 20060808-15:33:50 Info [ID=2] [local://local, STAF/Client] Unregistered a STAF command. 20060808-15:33:50 Info [ID=1] [local://local, STAF/Client] Unregistered a STAF command.
Here is an example of only displaying the log records for a particular registration ID:
C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME eventmanager CONTAINS [ID=2] Response -------- Date-Time Level Message ----------------- ----- ------------------------------------------------------- 20060808-15:33:34 Info [ID=2] [local://local, STAF/Client] Registered a STAF c ommand. Register request: REGISTER DESCRIPTION :17:Run java -version MACHINE local SERVICE process REQUEST :61 :start command java parms -version returnstdout stderrt ostdout TYPE s SUBTYPE t 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Submitted a STAF command. Event information: type=s subtype=t prepare= e ventservice=Event eventid=5 generatingmachine=local://l ocal generatingprocess=STAF/Client generatinghandle=95 eventtimestamp=20060808-15:33:42 properties={} Submitte d STAF command: STAF local process start command java p arms -version returnstdout stderrtostdout 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Completed a STAF command. RC=0, Result=96 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Process completed . Process info: {key=, handle=96, rc=0, endTimestamp=20 060808-15:33:42, fileList=[{rc=0, data=java version "1. 5.0" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64) Java HotSpot(TM) Client VM (build 1. 5.0-b64, mixed mode) }]} 20060808-15:33:50 Info [ID=2] [local://local, STAF/Client] Unregistered a STAF command.
Here is an example of only displaying the log records for a particular registration ID, machine, and STAF request number:
C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME eventmanager CONTAINS "[ID=2] [dave2268.austin.ibm.com:2336]" Response -------- Date-Time Level Message ----------------- ----- ------------------------------------------------------- 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Submitted a STAF command. Event information: type=s subtype=t prepare= e ventservice=Event eventid=5 generatingmachine=local://l ocal generatingprocess=STAF/Client generatinghandle=95 eventtimestamp=20060808-15:33:42 properties={} Submitte d STAF command: STAF local process start command java p arms -version returnstdout stderrtostdout 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Completed a STAF command. RC=0, Result=96 20060808-15:33:42 Info [ID=2] [dave2268.austin.ibm.com:2336] Process completed . Process info: {key=, handle=96, rc=0, endTimestamp=20 060808-15:33:42, fileList=[{rc=0, data=java version "1. 5.0" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64) Java HotSpot(TM) Client VM (build 1. 5.0-b64, mixed mode) }]}
Here is an example of only displaying the error log records, and using the -verbose option so that the error output is more readable:
C:\>STAF -verbose local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME eventmanager LEVELMASK error Response -------- [ { Date-Time: 20060808-15:33:45 Level : Error Message : [ID=3] Python error in the PREPARE value. PREPARE: a=b PyException: Traceback (innermost last): File "<string>", line 1, in ? NameError: b Processing registration: ID: 3 machine: local service: misc request: version prepare: a=b Event service message information: eventservice: Event eventid: 6 type: a subtype: b generatingmachine: local://local generatingprocess: STAF/Client generatinghandle: 97 eventtimestamp: 20060808-15:33:45 properties: {} } ]
The EventManager service provides a User Interface to simplify interaction with the EventManager service. It is especially useful when registering complex STAF commands with Python code; this can have quoting issues when registering at the command line, and the EventManager User Interface handles these issues for you. It also allows you to modify existing registrations (without having to unregister and the re-register the updated STAF command), and view the EventManager service's log.
Note that when viewing the EventManager service's log, the EventManager User Interface utilizes the STAFLogViewer class to display the logs. For more information on how to use the STAFLogViewer, refer to section "3.11 Class STAFLogViewer" of the STAF Java User's Guide ( http://staf.sourceforge.net/current/STAFJava.htm).
java -jar STAFEventManager.jar
If the STAFEventManager.jar file is not in the current directory where you are executing this command, then you will need to specify the full path (or the path relative to the current directory) to the STAFEventManager.jar file.
Note that to run this command, the STAFEventManager.jar file does not need to be included in your CLASSPATH.
java com.ibm.staf.service.eventmanager.EventManagerUI
Note that to run this command, the STAFEventManager.jar file must be included in your CLASSPATH.
A User Interface will be displayed which allows you to interact with
the EventManager service.
The main EventManagerUI window displays a table of all of the currently registered STAF commands. The screen capture above shows what the table would look like if there are no registrations. The window is comprised of the following components (from to to bottom):
The File menu bar contains the following menu items:
The View menu bar contains the following menu items:
The Selected menu bar will only be enabled if there is a row currently selected in the registration table, and contains the following menu items:
Note that all of the "Selected" menu items are also available in a pop-up menu when you right click on a row in the registration table, and they perform the exact same functions as the "Selected" menu bar items.
The Help menu bar contains the following menu items:
The "Service Machine" text field allows you to specify the hostname of the machine where the EventManager service is running. The default is "local".
The "Service Name" text field allows you to specify the service name for which the EventManager service was configured. The default is "EventManager".
After changing either of these values, you can press the "Enter" key to refresh the table, or click on "View" in the menu bar, and then select "Refresh".
The registration table displays the current registrations for the EventManager service you specified in the service configuration fields (for Service Machine and Service Name). It is refreshed every time you click on "View" in the menu bar and selecte "Refresh", as well as when you change the Service Machine or Service Name fields and press "Enter".
It is also refreshed whenever you add a new registration, unregister a registration, edit a registration, or copy an existing registration to a new registration.
The registration table has the following columns:
The status bar shows informational messages. Here are the possible messages:
To submit a new registration, click on "File" in the menu bar and then
select "New Registration...". You will see the following window:
This window allows you to specify the data for the registration:
To get help on any of these options while using EventManagerUI, mover the cursor over the text field or checkbox and a tool tip will be displayed.
Fill in the appropriate information for the STAF command you wish to have
executed. For example, to have a STAX job executed whenever an Event of
type "ProductXYZ" and subtype "acceptComplete" is generated:
Click on the "Register" button and you will see that the STAF command has
been assigned a unique registration ID, and that it is listed in the
registration table.
To register a more complex STAF command, you may find it easier to use the EventManagerUI instead of submitting a REGISTER request to the EventManager service via the command line. This is especially true for STAF commands that use Python and possibly need to access Python variables that are specified as properties when generating an event. Also, if you select to specify the request using Python and use the "Prepare Script" field, you usually don't have to escape as many quotes.
This section shows an example of registering a more complex STAF command using the EventManagerUI. It will use the same example that was discussed in the REGISTER section that registered a STAF command via the command line to execute STAX job /tests/TestA.xml via the STAX service on machine server1 whenever an event with type RunSTAXJob and subtype TestA is generated. This STAX job's main function must be passed a map of arguments with the names 'testMachine' and 'serverMachine'. This example passes the STAX job a map with these arguments and gets the values for these arguments from Python variables named myTestMachine and myServerMachine which are set using the property options when generating an Event with type "RunSTAXJob" and subtype "TestA" via the Event service's GENERATE request.
For example, the following event generation:
STAF local EVENT GENERATE TYPE RunSTAXJob SUBTYPE TestA PROPERTY myTestMachine=client1 PROPERTY myServerMachine=server9
will trigger the following STAX EXECUTE command to run:
STAF server1 STAX EXECUTE FILE "/tests/TestA.xml" ARGS "{'testMachine': 'client1', 'serverMachine': 'server9'}"
To edit a registration, double click on its row in the registration table, click on "Selected" in the menu bar and select "Edit", or right-click on its row in the registration table, and select "Edit" in the popup menu.
For example, if we wanted to change the registration ID 1 to change the
STAX job to be executed:
Click on the "Register" button to unregister the existing ID, and register
the updated registration data:
Click on yes, and you will see that the updated registration data has been saved. In this scenario, since we only had one existing registration, the ID for the updated registration is still 1. If there are already existing registration IDs, then the assigned registration id would be the next sequential ID.
To copy the information from an existing registration to a new registration, click on "Selected" in the menu bar and select "Copy to new registration", or right-click on its row in the registration table, and select "Copy to new registration" in the popup menu.
Update the information for the new registration:
Click on the "Register" button to register.
To unregister a registration, click on "Selected" in the menu bar and select
"Unregister", or right-click on
its row in the registration table, and select "Unregister" in the popup menu.
You will get a confirmation popup:
Click on "Yes" and the ID will be unregistered.
Next, let's register to have the command "java -version" executed when an
event is generated with type "myType" and subtype "mySubtype".
In the menu bar click on "File" and then "New
Registration..." and fill in the data:
Click on the "Register" button and we will see that it has been assigned
a unique registration ID:
Suppose we want to test the STAF command that we just registered, and we don't want to generate the Event. To do this, click on "Selected" in the menu bar and select "Trigger", or right-click on its row in the registration table, and select "Trigger" in the popup menu.
The STAF command will be submitted and a STAFLogViewer window will open to
display the service log entries for that STAF command:
In this case, since the process returned the version immediately, the log query shows that the process has completed, and includes the information it returned.
To view the service log's entries for a particular registration ID, click
on "View" in the menu bar and then select "Service Log for ID...". In the
popup dialog, enter ID "3" and click on OK. A STAFLogViewer window will open
with all of the log entries for ID 3:
To view the last 100 entries in the service log, click on "View" in the
menu bar and then select "Service Log last 100 records". A STAFLogViewer window
will open with the last 100 entries:
To view the log entries for a particular submitted STAF command, click on
"View" in the menu bar and then select "Service log for submitted STAF
command...". A new dialog will be displayed showing a list of all of the
submitted STAF commands:
Select the submitted STAF command, and click on "OK". A STAFLogViewer
window will open with all of the log entries for that submitted STAF command:
To view the entire service log, click on "View" in the menu bar and then
select "Entire Service Log". A STAFLogViewer window
will open with all of the log entries:
To delete the service log, click on "View" in the menu bar and then
select "Delete Service Log". You will receive a confirmation popup:
In addition to the common STAF return codes, the following EventManager
return codes are defined:
Table 1. EventManager Service Return Codes
Error Code | Meaning | Comment |
---|---|---|
4001 | Python error | A Python error during a TRIGGER command occurred while evaluating the request to be submitted. The result buffer will include details about the Python error. |
4002 | Request not submitted | The request for a TRIGGER command was not submitted because the value of STAFEventManagerSubmit was not set to true. The result buffer will include the value of STAFEventManagerSubmit. |
Jython Software License ======================= Copyright (c) 2000, Jython Developers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - Neither the name of the Jython Developers nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.