GT 3.9.5 Component Guide to Public Interfaces: WS MDS Trigger

Semantics and syntax of APIs

Programming Model Overview

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 "client" interface to the Trigger Service -- "clients" will typically interact with the Trigger Service indirectly, using some mechanism specific to the triggered executable program (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).

Semantics and syntax of the WSDL

The trigger service inherits its WSDL interface from the aggregator framework module:

Protocol overview

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:

  1. The appropriate aggregation source and sinks will be informed,
  2. the aggregator source will begin collecting data and inserting it into the corresponding service group entry,
  3. 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.)

Operations

AggregatorServiceGroup

  • 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 elsewhere).
    If you are implementing the trigger service, 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 Trigger Service Admin Guide.

AggregatorServiceGroupEntry

  • setTerminationTime: This operation can be used to set the termination time of the registration, as detailed in WS-ResourceLifetime.

Resource properties

AggregatorServiceGroup

  • 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)

In addition to the above resource properties, the trigger service exposes the following:

  • ActionsFiredCount: This resource property counts the total number and average rate of rule firings.

Faults

[list and briefly describe each fault]

WSDL and Schema Definition

Other relevant source files are the:

Note: If you are implementing the trigger service:

  • The TriggerRuleType is defined in trigger-types.xsd in trigger/source
  • The ActionsFiredCount resource property is an accumulator resource property, which is defined in the usefulrp/schema module.

Command-line tools

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 command is used to configure the Trigger Service to collect information from various sources; see the Aggregator Framework documentation for more information.

Overview of Graphical User Interface

There is no GUI specifically for the Trigger Service. The release contains a tech preview of WebMDS which can be used to display the status of resources registered to a Trigger Service in a normal web browser.

Semantics and syntax of domain-specific interface

Interface introduction

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.

Syntax of the interface

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.

Format of action script stdin

An XML document of the following format will be piped to the stdin of the action script: 

  <fire>
    <message>
 The message which caused the rule to file.
    </message>

    <MemberEPR>
 The EPR of the service registered for the firing rule.
    </MemberEPR>

    <AggregatorConfig>
 The aggregator configuration element for this rule.
    </AggregatorConfig>
  </fire>

The presence of the aggregator framework configuration element allows for additional parameters to be passed to the action script in registrations.

Format of action script stdout

The action script should output an XML document to stdout. The xml document does not need to match any particular schema. This output will be included in the ServiceGroupEntry for the rule.

Configuration interface

The trigger service is an MDS aggregator service, and so inherits much of its configuration system from the aggregator framework module. The configuration instructions for the aggregator framework should be read before this section.

  • TriggerRuleType: In addition to the source parameters specified in the aggregator framework configuration guide, this trigger-specific configuration element must be added to all registrations made to the trigger service. This registration paramete 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.
    • actionScript: the name of a script in $GLOBUS_LOCATION/libexec/trigger/ that will be executed when the matchingRule matches (except as rate limited by the following parameters).
    • 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 fire immediately the matchingRule becomes true.
    • outputXSL: (UNIMPLEMENTED in GT 3.9.3). The delivered message will be transformed by the specified XSLT stylesheet and fed into the stdin of the action script. It is intended that this will be implemented in a subsequent release of the GT3.9.x series.

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.

Environment variable interface

There are no Trigger Service specific environment variables.