Software Links
Getting Started
- Doc Structure
- A Globus Primer
- Quickstart
- Installing GT
- Platform Notes
- Migrating from GT2
- Migrating from GT3
Reference
- PDF version
- Best Practices
- Coding Guidelines
- API docs
- Public Interfaces
- Resource Properties
- Samples
- Glossary
- Index
- Performance Studies
Common Runtime
Security
Data Mgt
Information Svcs
Execution Mgt
Table of Contents
There are two programmatic interfaces to the Trigger Service: information is collected using an Aggregator Source and acted upon by an executable program.
There is no specialized client interface to the Trigger Service -- "clients" will typically interact with the Trigger Service indirectly by creating triggers using mds-servicegroup-add. The trigger parameters are contained within the TriggerRuleType XML type which is specified as one or more elements in the AggregatorConfig section of the registration message.
Information about how to configure existing aggregator sources (such as the aggregator sources distributed with the Globus Toolkit, which include one that polls for resource property information, one that collects resource property information through subscription/notification, and one that collects information by executing an executable program) is found in Aggregator Sources Reference; information about how to create new aggregator sources can be found in Aggregator Developer's Guide.
The administrator of a Globus installation configures the set of available executable programs that are available to be used as action scripts (for example, an executable program may send mail to an end-user or write a structured log file that will later be read by some other program).
The trigger service inherits its WSDL interface from the Aggregator Framework module, included below:
The Aggregator Framework builds on the WS-ServiceGroup and WS-ResourceLifetime specifications. Those specifications should be consulted for details on the syntax of each operation.
Each Aggregator Framework is represented as a WS-ServiceGroup (specifically, an AggregatorServiceGroup).
Resources may be registered to an AggregatorServiceGroup using
the AggregatorServiceGroup Add operation. Each registration will be
represented as a ServiceGroupEntry resource. Resources may be
registered to an AggregatorServiceGroup using the service
group add operation, which will cause an entry to be
added to the service group.
The entry will include configuration parameters for the aggregator source; when the registration is made, the following will happen:
- The appropriate aggregation source and sinks will be informed,
- the aggregator source will begin collecting data and inserting it into the corresponding service group entry,
- and the aggregator sink will begin processing the information in the service group entries.
The method of collection by source and processing by the sink is dependent on the particular instantiation of the aggregator framework (see per-source documentation for source information and per-service documentation for sink information - for example the Index Service and the Trigger Service.)
add:This operation is used to register a specified resource with the Aggregator Framework. In addition to the requirements made by the WS-ServiceGroup specification, the Content element of each registration must be an AggregatorContent type, with the AggregatorConfig element containing configuration information specific to each source and sink (documented in the Aggregator System Administrator's Guide).
Entry:This resource property publishes details of each registered resource, including both an EPR to the resource, the Aggregator Framework configuration information, and data from the sink.RegistrationCount:This resource property publishes registration load information (the total number of registrations since service startup and decaying averages)
The Aggregator Framework throws standard WS-ServiceGroup, WS-ResourceLifetime, and WS-ResourceProperties faults and does not define any new faults of its own.
Other relevant source files are the:
- WSRF service group schema
- WSRF resource lifetime schema
- MDS Usefulrp schema.
The AggregatorConfig element must contain an element of xsi:type
TriggerRuleType, defining the conditions upon which this
trigger registration will fire. This element is documented further
in the "Additional configuration for the Trigger Service" section under Configuring the Trigger Service.
In addition to the resource properties for the Aggregator Framework, the Trigger Service exposes the following:
ActionsFiredCount:This resource property counts the total number and average rate of rule firings. This is an accumulator resource property, which is defined in the usefulrp/schema module.
The Trigger Service itself does not have any command-line clients for end users; instead, the trigger service is configured to run an executable program to take some action (for example, send mail to a set of users, or write a log entry to a file).
The mds-servicegroup-add(1) command in the Aggregator Framework is used to configure the Trigger Service to collect information from various sources.
There is no GUI specifically for the Trigger Service. The release contains WebMDS which can be used to display the status of resources registered to a Trigger Service in a normal web browser.
The trigger service provides an API to action scripts, which are executed when trigger rules fire. These take the form of fork-exec executables (written in any language) which are supplied with rule information on stdin and must output status information on stdout.
Trigger action scripts take the form of native OS executables, and so can be written in any language that can generate such (for example, bash, PERL, C).
Information on the match that caused an action to fire is fed
into the action script through stdin. Status information
from the action script should be sent to stdout, and
will reported in the content of the ServiceGroupEntry for the rule.
An XML document of the following format will be piped to the stdin of the action script:
<actionInput>
<inputMessage>
The message which caused the rule to fire.
</inputMessage>
<xpathResult>
The result produced by the evaluation of the XPath matching rule.
</xpathResult>
<MemberEPR>
The EPR of the service registered for the firing rule.
</MemberEPR>
<AggregatorConfig>
The aggregator configuration element for this rule.
</AggregatorConfig>
</actionInput>
The inputMessage element may or may not be present in the action script input, based on how the boolean variable disableUnmodifiedActionScriptInput is set in TriggerRuleType. Defaults to false.
The xpathResult element may or may not be presentin the action script input, based on how the boolean variable enableFilteredActionScriptInput is set in TriggerRuleType. Defaults to false.
The presence of the Aggregator Framework AggregatorConfig configuration element allows for additional parameters to be passed to the action script in registrations.
Please see Deploying the Trigger Service for the method of registering the sample trigger scenario with your globus deployment.
The trigger service is an MDS aggregator service, and so inherits much of its configuration system from the Aggregator Framework module.
The Aggregator Framework does not have its own service side configuration, although services which are based on the framework have their own service side configuration options (such as MDS Index and MDS Trigger") which are documented in the per-service documentation.
Registrations to a working Aggregator Framework are configured for the mds-servicegroup-add(1) tool. This tool takes an XML configuration file listing registrations, and causes those registrations to be made.
In general, configuration of aggregator services involves configuring the service to get information from one or more sources in a Grid. The mechanism for doing this is defined by (inherited from) the Aggregator Framework and described in this section.
Configuring an Aggregating Service Group to perform a data aggregation is performed by specifying an AggregatorContent object as the content parameter of a ServiceGroup add method invocation. An AggregatorContent object is composed of two xsd:any arrays: AggregatorConfig and AggregatorData:
- The AggregatorConfig xsd:any array is used to specify parameters that are to be passed to the underlying AggregatorSource when the ServiceGroup add method is invoked. These parameters are generally type-specific to the implementation of the AggregatorSource and/or AggregatorSink being used.
- The AggregatorData xsd:any array is used as the storage location for aggregated data that is the result of message deliveries to the AggregatorSink. Generally, the AggregatorData parameter of the AggregatorContent is not populated when the ServiceGroup add method is invoked, but rather is populated by message delivery from the AggregatorSource.
The following links provide information for configuring the three types of aggregator sources provided by the Globus Toolkit:
An aggregator sink may require sink-specific configuration (the MDS Trigger Service requires sink-specific configuration; the MDS Index Service does not). See the documentation for the specific aggregator service being used for details on sink-specific documentation.
In addition to the source parameters specified
above, the TriggerRuleType element must be added to all registrations
made to the trigger service.
The TriggerRuleType is defined in
trigger-types.xsd in trigger/source.
This registration parameter contains the following options:
matchingRule: XPath rule to be applied against incoming data. The XPath expression will be evaluated against aggregated data, and will be regarded as matching the incoming data if it matches one or more nodes in that data.namespaceMappings: An array of string namespace mappings in the form xmlns:foo=http://foo.bar. This array of namespace mappings will be used to resolve namespace prefixes used in the XPath matchingRule statement.actionScript: the logical name of a script that will be executed when the matchingRule matches (except as rate limited). This logical name must be mapped to a physical file name located in the$GLOBUS_LOCATION/libexec/trigger/directory. The logical-to-physical filename mapping is specified in theexecutableMappingsparameter of thetriggerConfigurationblock of the file$GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/jndi-config.xml.minimumFiringInterval: the action script will not be executed more than once in this number of seconds. If unspecified, there will be no minimum interval.minimumMatchTime: the matchingRule must be true for this number of seconds before the actionScript will be executed. If unspecified, there is no minimum time period that the rule must match and the rule will be eligible to fire immediately after the matchingRule becomes true.invalidityTime: An array of TriggerInvalidityTime time ranges during which the trigger will not fire under any condition. If the current trigger fire time falls within any of the time ranges present in this variable, the trigger will not fire.enableFilteredActionScriptInput: If this value is present and set to true, the service will pass the filtered output result of the XPath matchingRule as additional input to the stdin of the action script, in addition to the original input to which the matching rule was applied. The default behavior if unspecified is false, meaning the Xpath query result will not be passed as input to the action script.disableUnmodifiedActionScriptInput: If this value is present and set to true the service will not pass the original trigger message input (to which the matching rule was applied) to the action script. The default behavior is to always pass the entire input message to the action scripts. For action scripts which do not need to consume the unmodified input, this variable may be set to true in order to increase performance.outputXSL: (CURRENTLY UNIMPLEMENTED) The delivered message will be transformed by the specified XSLT stylesheet and fed into the stdin of the action script.
The rate limiting parameters behave in such a way that the rate of action
script executions can be decreased by increasing the minimumFiringInterval and/or by increasing the minimumMatchTime.