Automating AMPS with Actions

AMPS provides the ability to run scheduled tasks or respond to events, such as Linux signals, using the Actions interface.

To create an action, you add an Actions section to the AMPS configuration file. Each Action contains one (or more) On statement which specifies when the action occurs, and one (or more) Do statement which specifies what the AMPS server does for the action. Within an action, AMPS performs each Do statement in the order in which they appear in the file.

AMPS actions may require the use of parameters. AMPS allows you to use variables in the parameters of an action. You can access these variables using the following syntax:

{{VARIABLE_NAME}}

AMPS defines a set of default variables when running an action. The event, or a previous action, can add variables in the context of the action. Those variables can be expanded in subsequent parameters. If a variable is used that isn't defined at the point where it is used, AMPS will expand that variable to an empty string literal. The context can also be updated as the module is running, so any variables that are available at any given point in the file depend on what action was previously executed.

By default, AMPS loads the following variables when it initializes an AMPS action:

Variable	Description
AMPS_INSTANCE_NAME	The name of the AMPS instance.
AMPS_BYTE_XX	Insert byte XX, where XX is a 2-digit uppercase hex number (00-FF). AMPS expands this variable to the corresponding byte value. These variables are useful for creating field separators or producing characters that are not permitted within XML.
AMPS_DATETIME	The current date and time in ISO-8601 format.
AMPS_UNIX_TIMESTAMP	The current date and time as a UNIX timestamp.

An example to echo a message when AMPS starts up is shown below. Note the AMPS_INSTANCE_NAME is one of the variables that AMPS pushes to the context when an action is loaded.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-startup</Module>
        </On>
        <Do>
            <Module>amps-action-do-echo-message</Module>
            <Options>
                <Message>instance={{AMPS_INSTANCE_NAME}}</Message>
            </Options>
        </Do>
    </Action>
</Actions>

AMPS actions are implemented as AMPS modules. To run each statement, AMPS simply calls the module that implements that Do statement. The module is free to take any necessary actions. If a Do statement returns a failure, AMPS does not run subsequent Do statements in that action. This is intended to help make maintenance processes reliable. For example, if a Do statement that is intended to copy a log file to a storage directory fails because the device that holds the storage directory is not mounted, further steps in the action -- which might do things like remove the log file from the original directory -- should not be run. Likewise, if AMPS exits unexpectedly during a given Do statement, subsequent statements will not be run.

AMPS provides the following modules by default:

On: Choosing When an Action Runs

The following table lists the On actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Condition	Modules
On a Schedule	amps-action-on-schedule
On AMPS Startup or Shutdown	amps-action-on-startup amps-action-on-shutdown
On a Linux Signal	amps-action-on-signal
On a REST Request	amps-action-on-admin
On Minidump Creation	amps-action-on-minidump
On Client Connect or Disconnect	amps-action-on-connect-client amps-action-on-disconnect-client
On Client Logon	amps-action-on-logon-client
On Client Offline Message Buffering	amps-action-on-offline-start amps-action-on-offline-stop
On Subscribe or Unsubscribe	amps-action-on-subscribe amps-action-on-unsubscribe
On Incoming Replication Connections	amps-action-on-connect-incoming-replication amps-action-on-disconnect-incoming-replication
On Outgoing Replication Connections	amps-action-on-connect-replication amps-action-on-disconnect-replication amps-action-on-replication-resync-complete amps-action-on-upgrade-replication amps-action-on-downgrade-replication
On Message Published to AMPS	amps-action-on-publish-message
On Message Delivered to Subscriber	amps-action-on-deliver-message
On Message Affinity	amps-action-on-message-affinity
On SOW Message Expiration	amps-action-on-sow-expire-message
On SOW Message Delete	amps-action-on-sow-delete-message
On Out-of-Focus Message	amps-action-on-oof-message
On Message Condition Timeout	amps-action-on-message-condition-timeout
On Message State Change	amps-action-on-alert
On Custom Event	amps-action-on-execute-event

Do: Choosing What an Action Does

The following table lists the Do actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Action	Module
Rotate Error/Event Log	amps-action-do-rotate-logs
Compress Files	amps-action-do-compress-files
Truncate Statistics	amps-action-do-truncate-statistics
Manage Transaction Log Journal Files	amps-action-do-archive-journal amps-action-do-compress-journal amps-action-do-remove-journal
Remove Error/Event Log Files	amps-action-do-remove-files
Delete SOW Messages	amps-action-do-delete-sow
Compact SOW Topics	amps-action-do-compact-sow
Query a SOW Topic	amps-action-do-query-sow
Manage Security	amps-action-do-disable-authentication amps-action-do-enable-authentication amps-action-do-reset-authentication amps-action-do-reset-entitlement amps-action-do-disable-entitlement amps-action-do-enable-entitlement
Enable or Disable Transports	amps-action-do-enable-transport amps-action-do-disable-transport
Publish Message	amps-action-do-publish-message
Manage Replication Acknowledgement	amps-action-do-downgrade-replication amps-action-do-upgrade-replication
Extract Values from a Message	amps-action-do-extract-values
Translate Data Within an Action	amps-action-do-translate-data
Increment Counter	amps-action-do-increment-counter
Raise a Custom Event	amps-action-do-execute-event
Execute System Command	amps-action-do-execute-system
Manage Queue Transfers	amps-action-do-enable-proxied-transfer amps-action-do-disable-proxied-transfer
Create a Minidump	amps-action-do-minidump
Shutdown AMPS	amps-action-do-shutdown
Debug Action Configurations	amps-action-do-nothing amps-action-do-echo-message

Conditionally Stop an Action

The following table lists the If actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Condition	Module
Stop Based on File System Capacity	amps-action-if-file-system-usage
Stop Based on Evaluating an Expression	amps-action-if-condition

Examples

See the configuration section of the AMPS documentation for examples of action configuration.