24. 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:

Default context variables

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 modules described in the following sections by default.

Configuration for Actions

This section lists configuration parameters for AMPS actions.

On Element: When an Action Runs

This section describes the options for configuring when AMPS runs a given action.

Running an Action on a Schedule

AMPS provides the amps-action-on-schedule module for running actions on a specified schedule.

The options provided to the module define the schedule on which AMPS will run the actions in the Do element.

Parameters for Scheduling Actions

Parameter	Description
Every	Specifies a recurring action that runs whenever the time matches the provided specification. Specifications can take three forms: 1. Timer action - a specification that is simply a duration, such as 4h or 1d, creates a timer action. AMPS starts the timer when the instance starts. When the timer expires, AMPS runs the action and resets the timer. 2. Daily action - a specification that is a time of day, such as 00:32 or 17:47, creates a daily action. AMPS runs the action every day at the specified time. AMPS uses a 24 hour notation for daily actions. 3. Weekly action - a specification that includes a day of the week and a time, such as Saturday at 11:00 or Wednesday at 03:32, creates a weekly action. AMPS runs the action each week on the day specified, at the time specified. AMPS uses a 24 hour notation for weekly actions. AMPS accepts both local time and UTC for time specifications. To use UTC, append a Z to the time specifier. For example, the time specification 11:32 is 11:32 AM local time. The time specification 11:32Z is 11:32 AM UTC.
Name	The name of the schedule. This name appears in log messages related to this schedule. Default: unknown

This module does not add any variables to the AMPS context.

Running an Action in Response to a Signal

AMPS provides the amps-action-on-signal module for running actions when AMPS receives a specified signal.

The module requires the Signal parameter:

Parameters for Responding to Signals

Parameter

Description

Signal

Specifies the signal to respond to. This module supports the standard Linux signals. Configuring an action uses the standard name of the signal. For example, to configure an action to SIGUSR1, the value for the Signal element is SIGUSR1. To configure an action for SIGHUP, the value for the Signal element is SIGHUP and so on. AMPS reserves SIGQUIT for producing minidumps and does not allow this module to override SIGQUIT. AMPS registers actions for several signals by default. See Default Signal Actions for details.

This module does not add any variables to the AMPS context.

Caution

Actions can be used to override the default signal behavior for AMPS.

Default Signal Actions

By default, AMPS registers the following actions for signals:

Default signal handling actions

On Event	Action
SIGUSR1	amps-action-do-disable-authentication
SIGUSR1	amps-action-do-disable-entitlement
SIGUSR2	amps-action-do-enable-authentication
SIGUSR2	amps-action-do-enable-entitlement
SIGINT	amps-action-do-shutdown
SIGTERM	amps-action-do-shutdown
SIGHUP	amps-action-do-shutdown

The actions in the table above can be overridden by creating an explicit action in the configuration file.

AMPS reserves the SIGQUIT signal and does not allow the configuration file to override the action taken in response to SIGQUIT.

Reserved signal

On Event	Action
SIGQUIT	amps-action-do-minidump

Running an Action in Response to an HTTP Request

AMPS includes a module that allows you to configure an action to run when a specified resource underneath the /amps/administrator/actions path in the admin interface is requested. The amps-action-on-admin module allows you to add a custom action to the admin interface and provides the ability to pass parameters into the Do step of those actions using query parameters in the HTTP request.

The module requires the Path parameter, which specifies the path under /amps/administrator/actions where this action should appear:

Required parameters for ``amps-action-on-admin``

Parameter

Description

Path

Specifies the path under /amps/administrator/actions where this action should appear. The action will run when a request for the specified path is received by the AMPS admin interface. For entitlement purposes, the AMPS admin interface treats actions configured using this module identically to resources provided by AMPS. That is, the user requesting that the action run must have access to the appropriate admin resource for the action to run. For example, to add an action that runs journal maintenance at the path /amps/administrator/actions/journal_cleanup, you would use the following Path element: <Path>journal_cleanup</Path> The Path element should contain only a resource name. No / character should appear in the Path element.

Any query parameters provided as part of the request are added to the context before the Do steps for the action are run. This module adds the names and values of the query parameters without adjusting the case of the items.

For some actions, it’s important that a specific context value is present before the action runs. You can configure the module to require that the request provide one or more query parameters using the RequiredParameter option to the module. When one or more RequiredParameter is specified, the admin console will refuse any request for the resource that does not include all of the required parameters.

The action also provides support for a Name element and a Description element, which can be used to help tools that monitor or manage AMPS (such as the Galvanometer monitoring tool included with AMPS) provide information on the action.

Optional parameters for ``amps-action-on-admin``

Optional Element	Description
RequiredParameter	Specifies that a request to run this action must include the specified query parameter. If the request does not include this item as part of the query parameters, the request will return an error rather than executing the action.
Name	Specifies the name to use for display purposes for this resource.
Description	Specifies a description to use for display purposes for this resource.

For an example of configuring an action using this module, see Archive Transaction Log Journal Files Older Than A Specified Age In Response to Admin Request.

Tip

The amps-action-on-admin module should be used for ad hoc maintenance (such as responding to an unexpected increase in traffic by archiving journals ahead of schedule) or tasks that are triggered unpredictably by an external system. For tasks that need to run on a regular basis or frequently (for example, every few seconds), amps-action-on-schedule is more efficient.

Running an Action on Startup or Shutdown

AMPS includes modules to run actions when AMPS starts up or shuts down.

The amps-action-on-startup module runs actions as the last step in the startup sequence. The amps-action-on-shutdown module runs actions as the first step in the AMPS shutdown sequence.

In both cases, actions run in the order that the actions appear in the configuration file.

These modules do not require any parameters.

These modules do not add any variables to the AMPS context.

Running an Action on Client Logon

AMPS provides the amps-action-on-logon-client module for running actions when a user logs into an AMPS client.

This module does not require any parameters.

This module adds the following variables to the AMPS context:

Context Variables for On Client Logon

Variable	Description
AMPS_CLIENT_NAME	The name of the AMPS client.
AMPS_CONNECTION_NAME	The name of the AMPS connection.
AMPS_AUTHENTICATION_ID	The authentication ID of the AMPS connection.

Running an Action on Client Connection

AMPS provides modules for running actions on the connection or disconnection of an AMPS client.

The amps-action-on-disconnect-client runs actions once an AMPS client instance disconnects. The amps-action-on-connect-client runs actions once an instance of an AMPS client successfully connects.

These modules require no parameters.

These modules add the following variables to the AMPS context:

Context Variables for On Connect and Disconnect Client

Variable	Description
AMPS_CLIENT_NAME	The name of the AMPS client. (For the amps-action-on-connect-client action, this will be the connection name since this event happens before the client has provided a client name in the logon command.)
AMPS_CONNECTION_NAME	The name of the AMPS connection.
AMPS_AUTHENTICATION_ID	The authentication ID of the AMPS connection (for amps-action-on-disconnect-client action only).

Running an Action in Response to Outgoing Replication Connections

AMPS includes a set of modules that allow you to configure an action to run based on events for outgoing replication connections.

The amps-action-on-connect-replication module runs when an outgoing Destination is connected. The amps-action-on-disconnect-replication module runs when an outgoing Destination is disconnected.

The amps-action-on-replication-resync-complete module runs when a Destination has been brought up to date with the transaction log of the local instance.

The amps-action-on-upgrade-replication module runs when an outgoing replication connection that has been previously downgraded to acknowledge messages async is being upgraded to acknowledge messages sync.

The amps-action-on-downgrade-replication module runs when an outgoing replication connection that is configured to acknowledge messages sync is being downgraded to acknowledge messages async.

These modules require no parameters.

These modules add the following variables to the AMPS context:

Context Variables for Outgoing Replication Connect and Disconnect

Variable	Description
AMPS_REPLICATION_PEER_NAME	The instance name of the AMPS instance on the opposite end of the connection, if available.
AMPS_REPLICATION_CLIENT_NAME	The name of the AMPS client used for this connection.
AMPS_REPLICATION_REMOTE_ADDRESS	The remote address of the opposite end of the connection.
AMPS_REPLICATION_GROUP_NAME	The group name of the AMPS instance on the opposite end of the connection, if available.
AMPS_REPLICATION_TRANSPORT_NAME	The name of the transport making the outgoing connection.

Running an Action in Response to Incoming Replication Connections

AMPS includes a set of modules that allow you to configure an action to run based on events for incoming replication connections.

The amps-action-on-connect-incoming-replication module runs when an incoming replication connection is accepted. The amps-action-on-disconnect-incoming-replication module runs when an incoming replication connection is disconnected.

These modules require no parameters.

These modules add the following variables to the AMPS context:

Context Variables for Incoming replication Connect and Disconnect

Variable	Description
AMPS_REPLICATION_PEER_NAME	The instance name of the AMPS instance on the opposite end of the connection, if available.
AMPS_REPLICATION_CLIENT_NAME	The name of the AMPS client used for this connection.
AMPS_REPLICATION_REMOTE_ADDRESS	The remote address of the opposite end of the connection.
AMPS_REPLICATION_GROUP_NAME	The group name of the AMPS instance on the opposite end of the connection, if available.

Running an Action on Subscribe or Unsubscribe

AMPS provides modules for running actions when a client subscribes or unsubscribes.

The amps-action-on-subscribe runs actions when an AMPS client enters a subscription command. The amps-action-on-unsubscribe runs actions when an AMPS client unsubscribes (either by sending an explicit unsubscribe command or by disconnecting).

These modules require the following parameters:

Parameters for On Connect and Disconnect Client

Parameter	Description
Topic	Specifies the topic or topic regular expression pattern to monitor for subscribe commands.
MessageType	The message type of the topic to monitor for subscribe or unsubscribe. There is no default for this parameter.

These modules add the following variables to the AMPS context:

Context Variables for On Subscribe and On Unsubscribe

Variable	Description
AMPS_TOPIC	The name of the topic specified by the subscribe or unsubscribe command.
AMPS_CLIENT_NAME	The name of the client submitting the command.
AMPS_OPTIONS	The options on the subscription.
AMPS_FILTER	The filter for the subscription.

Running an Action on Message Delivery

AMPS provides modules to run actions when AMPS delivers a message to subscribers. The basic flow of AMPS messaging is to first receive a published message, find the subscriber(s) to which this message will be sent, then deliver the message to the subscriber(s).

The amps-action-on-deliver-message runs actions when AMPS delivers a publish message to subscribers.

This module requires the Topic and the MessageType of the message that has been delivered.

Parameters for On Deliver Message

Parameter	Description
Topic	The name of the topic to monitor for message delivery. This parameter supports regular expressions. There is no default for this parameter.
MessageType	The message type of the topic to monitor for message delivery. There is no default for this parameter.

This module adds the following variables to the AMPS context:

Context Variables for On Deliver Message

Variable	Description
AMPS_TOPIC	The topic of the message.
AMPS_DATA	The data the message contains.
AMPS_DATA_LENGTH	The length of the data the message contains.
AMPS_BOOKMARK	The bookmark associated with this message. This is an empty string if the message does not have a bookmark.
AMPS_CLIENT_NAME	The name of the client to which this message was delivered.
AMPS_CORRELATION_ID	The correlation ID set on the publish command, if one was set.

Running an Action on Message Publish

AMPS provides modules to run actions when a message is published to AMPS. The basic flow of AMPS messaging is to first receive a published message, find the subscriber(s) to which this message will be sent, then deliver that message to the subscriber(s).

The amps-action-on-publish-message runs actions as soon as a message is published to AMPS.

Warning

This action is treated by the AMPS engine as a subscription from an internal AMPS client.

When working with queues, use this action with the underlying topic of the queue rather than the queue topic itself. Because this action creates a subscription, using this action with the queue topic will cause the action to lease messages from the queue even though the action does not acknowledge messages. This means that, when used with the queue topic itself, the action will interfere with other subscribers and depending on the queue configuration, may only receive one message during the lifetime of the instance.

This module requires the Topic and the MessageType of the message that was published. In addition to that, this module also accepts the optional parameters listed below:

Parameters for On Publish Message

Parameter	Description
Topic	The name of the topic to monitor for publishes. This parameter supports regular expressions. There is no default for this parameter.
MessageType	The message type of the topic to monitor for publishes. There is no default for this parameter.
MessageSource	The source to monitor for publishes. The source of the message defaults to all, which monitors both publishes directly to this AMPS instance and messages received via replication. This parameter also accepts local for when the message source is published directly to this AMPS instance and replicated for messages received via replication.
Filter	Sets the filter to apply. Only messages that match this filter will cause the action to run.
Options	Sets the options to apply when listening for messages. This action supports any option that would be supported by the subscribe command when not using a bookmark.

This module adds the following variables to the AMPS context:

Context Variables for On Publish Message

Variable	Description
AMPS_TOPIC	The topic of the message.
AMPS_DATA	The data the message contains.
AMPS_DATA_LENGTH	The length of the data that the message contains.
AMPS_BOOKMARK	The bookmark associated with this message.
AMPS_TIMESTAMP	The time at which the message was processed by AMPS.
AMPS_CLIENT_NAME	The name of the client from which the message was published.

Running an Action on OOF Message

When a record that previously matched a subscription has been updated so that the record no longer matches its subscription, AMPS sends an out-of-focus (OOF) message to let subscribers know that their record no longer matches the subscription. With amps-action-on-oof-message, you can enter a subscription within AMPS and run actions when an OOF message for that subscription is produced.

Warning

This action is treated by the AMPS engine as a subscription from an internal AMPS client.

Do not use this action with queue topics. Because this action creates a subscription, using this action with the queue topic will cause the action to lease messages from the queue even though the action does not acknowledge messages. This means that, when used with the queue topic itself, the action will interfere with other subscribers and, depending on the queue configuration, may only receive one message during the lifetime of the instance.

Furthermore, because each publish to a queue topic is treated as a distinct message, a subscription to a queue topic will never produce oof messages.

This module requires the Topic and the MessageType of the OOF message. In addition to that, this module also accepts the optional parameters listed below:

Parameters for On OOF Message

Parameter	Description
Topic	The topic to monitor for OOF messages. The topic specified must be a SOW topic, view or conflated topic. This parameter supports regular expressions. There is no default for this parameter. This module should not be used with queue topics.
MessageType	The message type of the topic to monitor for OOF messages. This parameter supports regular expressions. There is no default for this parameter.
Filter	Set the filter to apply. This filter forms the internal subscription for which OOF messages will be generated.
Type	The type of OOF message to take action on. match - take action on OOF messages generated because message no longer matches filter. delete - take action on OOF messages generated because message has been removed from the SOW. expire - take action on OOF messages generated because the message expired from the SOW. all - take action on all of the above types. Defaults to all.

This module adds the following variables to the AMPS context:

Context Variables for On OOF Message

Variable	Description
AMPS_TOPIC	The topic of the OOF message.
AMPS_DATA	The data of the OOF message.
AMPS_DATA_LENGTH	The length of the data of the OOF message.
AMPS_PREVIOUS_DATA	The data previously contained from the updated record.
AMPS_PREVIOUS_DATA_LENGTH	The length of the data previously contained from the updated record.

Running an Action on Affinity Assignment

AMPS includes a module to help with building a message affinitization strategy.

With message affinitization, each record in a SOW Topic can be assigned to a single affinitized client. The amps-action-on-message-affinity module handles monitoring the SOW topic and running an action when a key is affinitized or de-affinitized.

A client connection indicates that it wants to participate in affinitization by subscribing to a topic to be used for the assignment metadata, referred to as the “control topic”.

Notice that although this action runs when message affinitization is updated, the On step does not, by itself, specify what happens when affinitization is updated. It is up to the Action configuration to take appropriate steps when affinitization is updated.

Tip

This module keeps track of affinitizing messages to processors and runs an action when affinity is assigned or changed. However, it is up to the configuration of the action to manage alerting processors, and it is up to the processors themselves to respond to the alert and adjust their subscriptions accordingly.

This action requires the following parameters. In addition to that, this module also accepts an optional parameter listed below:

Parameter	Description
MessageType	The message type of the monitored topic and the control topic.
ControlTopic	The name of the control topic. This topic is monitored for subscriptions. Any client that subscribes to the ControlTopic is considered to be eligible to have messages affinitized to that client.
DataTopic	The name of the topic that contains the messages to be affinitized. Each distinct record in the topic (that is, each distinct SOW Key) will be affinitized. By default, all data within the topic will be affinitized. Optionally, you can restrict affinitization to only certain records (for example, orders in a certain state) by setting the DataFilter option.
DataFilter	When present, restricts affinitization to only those messages in the DataTopic that also match the DataFilter.

Parameters for On Message Affinity

This module adds the following variables to the AMPS context:

Variable	Description
AMPS_DATA	The data of the message being affinitized.
AMPS_CLIENT_NAME	The name of the client the message is being affinitized to or removed from.
AMPS_AFFINITY_ACTION	The type of event. If the message is being affinitized to this client, the type will be assign. If the message is being de-affinitized, the type will be unassign.
AMPS_AFFINITY_REASON	The reason for the event. For example, if the message no longer matches the DataFilter or has been deleted, the reason would be oof. If the update is happening because the client that was assigned to the message is no longer active, the reason would be unsubscribe.

Context Variables for On Message Affinity

Considerations and Limitations

The amps-action-on-message-affinity module has the following considerations for use:

• Affinitization is tracked independently on each instance of AMPS. In a replicated mesh of AMPS instances, each instance independently monitors the DataTopic and ControlTopic. AMPS does not make any effort to coordinate affinitization across replicated instances.
• The affinitization module relies on the SOW key (or grouping, for affinitization over views) to determine message identity. Therefore, affinitization can only be used for a Topic, RegexTopic, View, or ConflatedTopic. Since each message in a Queue, LocalQueue, or GroupLocalQueue is considered to be a distinct message, monitoring one of these topic types for affinitization would not produce useful results (however, if the underlying topic of a queue is maintained as a Topic in the SOW, using that Topic for affinitization could be useful).

Affinitization Configuration Example

The following example shows one way to use the amps-action-on-message-affinity module to assign specific symbols to a processor. In this example, a processor would subscribe to the symbol_processor_assignments topic to receive the symbols that have been affinitized to that processor. It would then maintain a subscription to the orders topic with a filter that limits the subscription to just the symbols that have been provided to the subscriber from the symbol_processor_assignments topic.

When a processor receives an event with a symbol and the event "assign", the processor adds the symbol in that event to the list of symbols in the filter for the subscription to the orders topic (typically, using the replace option to adjust the existing subscription in place). When a processor receives an event with a symbol and the event "unassign", the processor removes that symbol from the filter for the subscription to the orders topic.

<Action>
   <On>
     <Module>amps-action-on-message-affinity</Module>
     <Options>
       <MessageType>json</MessageType>
       <DataTopic>symbols</DataTopic>
       <ControlTopic>symbol_processor_assignments</ControlTopic>
     </Options>
   </On>
   <Do>
       <Module>amps-action-do-extract-values</Module>
       <Options>
         <Data>{{AMPS_DATA}}</Data>
        <MessageType>json</MessageType>
         <Value>SYMBOL=/symbol</Value>
       </Options>
   </Do>
   <Do>
     <Module>amps-action-do-publish-message</Module>
     <Options>
       <MessageType>json</MessageType>
       <Topic>symbol_processor_assignments</Topic>
       <Data>{"client_name":"{{AMPS_CLIENT_NAME}}",
              "symbol":"{{SYMBOL}}",
              "event":"{{AMPS_AFFINITY_ACTION}}",
              "reason":"{{AMPS_AFFINITY_REASON}}"}</Data>
     </Options>
   </Do>
   <If>
     <Module>amps-action-if-condition</Module>
     <Options>
        <Condition>"{{AMPS_AFFINITY_ACTION}}" == "unassign"</Condition>
     </Options>
   </If>
   <Do>
     <Module>amps-action-do-delete-sow</Module>
     <Options>
        <Topic>symbol_processor_assignments</Topic>
        <MessageType>json</MessageType>
        <Filter>/symbol = "{{SYMBOL}}"</Filter>
     </Options>
   </Do>
 </Action>

The underlying topics can be defined as needed. For example, the following configuration automatically tracks the set of symbols in an orders topic to be affinitized using the action above:

<SOW>
  <Topic>
     <Name>orders</Name>
     <MessageType>json</MessageType>
     <Key>/id</Key>
     <FileName>${AMPS_DATA}/sow/%n.sow</FileName>
  </Topic>
  <View>
     <Name>symbols</Name>
     <MessageType>json</MessageType>
     <UnderlyingTopic>orders</UnderlyingTopic>
     <Projection><Field>/symbol</Field></Projection>
     <Grouping><Field>/symbol</Field></Grouping>
   </View>
   <Topic>
      <Name>symbol_processor_assignments</Name>
      <MessageType>json</MessageType>
      <Key>/symbol</Key>
      <Durability>transient</Durability>
  </Topic>
</SOW>

This action attempts to affinitize new messages so as to keep the overall number of messages roughly balanced across the current processors. If a processor unsubscribes from the ControlTopic, messages currently affinitized to that processor will be distributed to other processors. However, messages are not rebalanced among running processors. Once a given SOW Key is affinitized to a processor, it remains affinitized to that processor until the processor unsubscribes, or the record is deleted from the topic.

Running an Action on Minidump

AMPS provides the amps-action-on-minidump module for running actions when AMPS generates a minidump.

This module does not require parameters.

This module adds the following variable to the AMPS context:

Context Variable for On Minidump

Variable	Description
AMPS_MINIDUMP_PATH	The path to where the minidump is created.

Running an Action on Offline Start or Stop

AMPS provides modules to run actions when an AMPS client is marked as a slow client and also for when the AMPS client catches up to no longer be subject to slow client offlining.

Slow client offlining is a feature in AMPS that reduces the memory resources consumed by slow clients. More on this feature can be found in Slow Client Management and Capacity Limits.

The amps-action-on-offline-start module runs actions as the first step when AMPS’s result set reaches its disk limit and has to disconnect the client. The amps-action-on-offline-stop module runs actions as AMPS is no longer subject to slow client offlining.

In both cases, actions run in the order that the actions appear in the configuration file.

Both modules do not require any parameters.

Both modules add the following variables to the AMPS context:

Context Variables for On Offline Start and Stop

Variable	Description
AMPS_CLIENT_NAME	The name of the AMPS client.
AMPS_CONNECTION_NAME	The name of the AMPS connection.

Running an Action on SOW Message Deletion

AMPS provides a module to run an action when a message is deleted from a topic in the SOW.

The amps-action-on-sow-delete-message module monitors a topic for deletions from the SOW. The action runs once for each message that is deleted in the matching topic.

This action requires the following parameters:

Parameters for On SOW Message Deletion

Parameter	Description
Topic	The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be either a SOW topic, a view, a conflated topic or a queue. There is no default for this parameter.
MessageType	The message type of the topic to monitor for messages. There is no default for this parameter.

The module adds the following variables to the AMPS context:

Context Variables for On SOW Message Delete

Variable	Description
AMPS_TOPIC	The topic of the message that was deleted.
AMPS_DATA	The current data of the message.
AMPS_DATA_LENGTH	The length of the current data of the message, in bytes.
AMPS_CORRELATION_ID	The correlation ID set on the publish command, if one was set.

Running an Action on SOW Message Expiration

AMPS provides a module to run an action when a message expires from a topic in the SOW.

The amps-action-on-sow-expire-message module monitors a topic for expirations. The action runs once for each message that expires in the matching topic. Notice, in particular, that this includes monitoring messages that expire from the queue, which are presented as SOW expirations to this module.

This action requires the following parameters. In addition to that, this module also accepts an optional parameter listed below:

Parameters for On SOW Message Expiration

Parameter	Description
Topic	The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be either a SOW topic, a view, a conflated topic or a queue. There is no default for this parameter.
MessageType	The message type of the topic to monitor for messages. There is no default for this parameter.
Reason	An optional comma-delimited string indicating the expiration reasons to monitor for. For example, setting this to time_limit,forced_expire will cause this action to be invoked only when the expiration reason includes one of time_limit or forced_expire. For more information on the allowed values and definitions, see the documentation for AMPS_REASON below.

The module adds the following variables to the AMPS context:

Context Variables for On SOW Message Expire

Variable	Description
AMPS_TOPIC	The topic of the message that expired.
AMPS_DATA	The current data of the message.
AMPS_DATA_LENGTH	The length of the current data of the message, in bytes.
AMPS_REASON	A comma-delimited string indicating one or more reason(s) the message was expired. This string contains one or more of the following values: time_limit - the expiration time for this message or topic has passed. forced_expire - this queue message was acknowledged with an expire option resulting in the message’s immediate removal. max_cancels - this queue message was acknowledged with a cancel option and the number of cancels exceeded the queue’s configured MaxCancels limit. max_deliveries - this queue message was not successfully acknowledged by a subscriber and the number of deliveries has exceeded the queue’s MaxDeliveries limit.
AMPS_CORRELATION_ID	The correlation ID set on the publish command if one was set.

Running an Action on Message State Change

AMPS provides two modules, amps-action-on-alert and amps-action-on-message-condition-timeout, to run an action when a message in a SOW topic meets a specific condition for longer than a specified period of time. These modules provide a way to track specific messages in a SOW topic and indicate whether the message has timed out (that is, been in the monitored state longer than expected) or whether the message has been processed as expected and is no longer being tracked within the specified timeout.

The amps-action-on-alert action monitors a SOW topic for messages that match a filter and triggers an action when either:

• The message has remained matched on the filter for at least the specified duration (indicating a timeout), or
• An out-of-focus message is received for the message (indicating that the message is no longer tracked)

The amps-action-on-message-condition-timeout action monitors a SOW topic for messages that match a filter and triggers an action when:

• The message has remained matched on the filter for at least the specified duration (indicating a timeout)

Use amps-action-on-message-condition-timeout if only timeouts are important, otherwise use amps-action-on-alert if both timeouts and message tracking are important.

For example, a set of actions might be configured to publish a message to an Alerts topic if an order is unprocessed for more than a specified timeout. When the order is processed, the actions might publish a message to a Statistics topic for tracking purposes. Rather than creating two independent actions, which could lead to overlap if the order is processed at the same time that the alert is being generated, use this action to guarantee that only one of the events will be generated.

The module tracks each message that matches the filter individually, and will run once for each message tracked.

This module uses the Out-of-Focus notification (OOF) mechanism. When a message matches the specified topic and filter, the module begins tracking that message. If no OOF notification is received for that message within the specified timeout, the action runs for that message and indicates that the timeout has been exceeded. If an OOF notification is received before the timeout expires, then the action runs for that message, indicating that the message is no longer tracked.

This module uses the custom event system as a way of indicating whether a given message was removed from tracking, or whether the message timed out. When configuring the action, you specify the event to raise for each of these states. This module stores the exact event raised in a context variable, which you can then use with amps-action-do-event to raise the event.

Caution

While the AMPS server is running, this action will trigger exactly once for each message after it reaches the timeout period. When AMPS restarts, if a message that had previously triggered this action still exists in the SOW topic (and still matches the filter provided, if any), the action will run for that message immediately after the module initializes on restart.

This action requires the following parameters. In addition to that, this module also accepts the optional parameters listed below:

Parameters for On Alert

Parameter	Description
Topic	The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be either a SOW topic, a view or a conflated topic. Queues are not supported. There is no default for this parameter.
MessageType	The message type of the topic to monitor for messages. There is no default for this parameter.
OOFEvent	The value to store when an out-of-focus notification is received for a tracked message. There is no default for this parameter.
TimeoutEvent	The value to store when a message is in the tracked state for longer than the timeout period. There is no default for this parameter.
EventVariable	The name of the context variable in which to store the reason that the action is running (either the string in OOFEvent or the string in TimeoutEvent). There is no default for this parameter.
Duration	The amount of time to wait for an OOF notification for the message before running the action.
Filter	Sets the filter to apply. Only messages that match this filter will be monitored by this action. If no filter is provided, every message of the specified message type in topics that match the Topic value will be monitored.

The module adds the following variables to the AMPS context:

Context Variables for On Alert

Variable	Description
AMPS_TOPIC	The topic of the message that triggered the alert.
AMPS_DATA	The current data of the message.
AMPS_DATA_LENGTH	The length of the current data of the message, in bytes.
AMPS_BOOKMARK	The bookmark of the message. Empty if there is no bookmark for the message.
AMPS_TIMESTAMP	The timestamp at which the module began tracking the message.
AMPS_CLIENT_NAME	The client name of the current value of the message.
AMPS_SOW_KEY	The current SowKey for the message.
The variable specified in EventVariable	The reason the action is running. This will be either the value of OOFEvent or the value of TimeoutEvent, depending on what caused the action to run.

Running an Action on Message Condition Timeout

AMPS provides a module to run an action when a message in a SOW topic meets a specific condition for longer than a specified period of time. For example, an action might be configured to publish a message to an Alerts topic if an order is unprocessed for more than a specified timeout.

AMPS also provides a module, amps-action-on-alert, that runs when either a message has been in a specific condition for a longer than expected period of time, or the module receives an out-of-focus notification indicating that the message no longer meets the tracking condition. Use that module if both conditions are important. Use this module if it is only important to track timeouts.

The amps-action-on-message-condition-timeout monitors a SOW topic for messages that match a filter and triggers an action for each message that remains matched on that filter for at least the specified duration.

This module uses the Out-of-Focus notification (OOF) mechanism. When a message matches the specified topic and filter, the module begins tracking that message. If no OOF notification is received for that message within the specified timeout, the action runs for that message.

The module tracks each message that matches the filter individually, and will run once for each message that exceeds the timeout.

Caution

While the AMPS server is running, this action will trigger exactly once for each message after it reaches the timeout period. When AMPS restarts, if a message that had previously triggered this action still exists in the SOW topic (and still matches the filter provided, if any), the action will run for that message immediately after the module initializes on restart.

This action requires the following parameters. In addition to that, this module also accepts the optional parameters listed below:

Parameters for On Message Condition Timeout

Parameter	Description
Topic	The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be either a SOW topic, a view or a conflated topic. Queues are not supported. There is no default for this parameter.
MessageType	The message type of the topic to monitor for messages. There is no default for this parameter.
Duration	The amount of time to wait for an OOF notification for the message before running the action.
Filter	Sets the filter to apply. Only messages that match this filter will be monitored by this action. If no filter is provided, every message of the specified message type in topics that match the Topic value will be monitored.

The module adds the following variables to the AMPS context:

Context Variables for On Message Condition Timeout

Variable	Description
AMPS_TOPIC	The topic of the message that triggered the alert.
AMPS_DATA	The current data of the message.
AMPS_DATA_LENGTH	The length of the current data of the message, in bytes.
AMPS_BOOKMARK	The bookmark of the message. Empty if there is no bookmark for the message.
AMPS_TIMESTAMP	The timestamp at which the module began tracking the message.
AMPS_CLIENT_NAME	The client name of the current value of the message.
AMPS_SOW_KEY	The current SowKey for the message.

Running an Action on a Custom Event

The AMPS action system provides a way to create custom events and run an action when the custom event is raised. The amps-action-on-execute-event action runs when a specified custom event is raised by the amps-action-do-execute-event action.

This action takes a single parameter:

Parameters for On Execute Event

Parameter	Description
Event	The value to watch for. When an event with this name is raised, the action runs. There is no default for this parameter.

This module does not add any variables to the AMPS context.

Do Element: Defining the Action to Take

This section describes the default modules for specifying what AMPS does when an action runs.

Rotate Log Files

AMPS provides the following module for rotating log files and loads this module by default:

Managing Logs

Module Name	Does
amps-action-do-rotate-logs	Rotates logs that are older than a specified age, for log types that support log rotation. Rotating a log involves closing the log and opening the next log in sequence. AMPS will use the name specifier provided in the AMPS configuration for the new log file. This may overwrite the current log file if the specifier results in the same name as the current log file.

This module does not require options.

This module does not add any variables to the AMPS context.

Manage the Statistics Database

AMPS provides the following modules for managing the statistics database. As a maintenance strategy, 60East recommends truncating statistics on a regular basis. This frees space in the database file, which will be reused as new statistics are generated. It is generally not necessary to vacuum statistics unless you have changed your retention policy so that less data is retained between truncation operations. With regular truncation, the statistics database file will usually stabilize at the correct size to hold the amount of data your application generates between truncation operations.

AMPS loads these modules by default.

Managing Statistics

Module Name	Usage
amps-action-do-truncate-statistics	Removes statistics that are older than a specified age. This frees space in the statistics file, but does not reduce the size of the file.
amps-action-do-vacuum-statistics	Deprecated This action has been deprecated in current versions of AMPS and will no longer vacuum statistics. 60East recommends offline maintenance of the statistics database instead. See the section on the AMPS Statistics Database, in the AMPS User Guide, for details on shrinking the size of a statistics database.

The amps-action-do-truncate-statistics module requires an Age parameter that specifies the age of the statistics to process.

Parameters for Managing Statistics

Parameter	Description
Age	Specifies the age of the statistics to remove. The module processes any file older than the specified Age. For example, when the Age is 5d, the module removes statistics that are older than 5 days. There is no default for this parameter.

These modules do not add any variables to the AMPS context.

Manage Journal Files

AMPS provides the following modules for managing journal files and loads these modules by default:

Managing Journals

Module Name	Does
amps-action-do-archive-journal	Archives journal files that are older than a specified age to the JournalArchiveDirectory specified for the transaction log. This action marks files to be archived and then returns.
amps-action-do-compress-journal	Compresses journal files that are older than a specified age. This action marks files to be compressed and then returns.
amps-action-do-remove-journal	Deletes journal files that are older than a specified age. This action marks files to be deleted and then returns. If a journal file is currently in use, it will be removed when it is no longer in use.

AMPS will only remove journal files that are no longer needed by the instance. AMPS ensures that all replays from a journal file are complete, all queue messages in that journal file have been delivered (and acknowledged, if required), and all messages from a journal file have been successfully replicated before removing the file.

Journal files that have been compressed or archived (or both) are still part of the transaction log. AMPS will compress and archive journal files that have undelivered queue messages, or that have not yet been fully replicated, and so on.

Each of these modules requires an Age parameter that specifies the age of the journal files to process.

Parameters for Managing Journals

Parameter

Description

Age

Specifies the age of files to process. The module processes any file older than the specified Age. For example, when the Age is 5d, only files that have not been written to for longer than 5 days will be processed by the module. AMPS does not remove the current journal file or files that are being used for replay, files that are being used for replication or files that contain unacknowledged and unexpired messages in a queue; even if the file is older than the Age parameter. AMPS does not allow gaps in the journal files, so it will only remove a given file if all previous files have been removed. AMPS can compress and archive journal files that are still in use since compressed or archived journal files are part of the transaction log and AMPS will replay messages from these files. There is no default for this parameter.

These modules do not add any variables to the AMPS context.

Compressing Files

AMPS provides the following module for compressing files. Use this action to compress error log files that are no longer needed. AMPS loads this module by default.

Caution

This action compresses files that match an arbitrary pattern. If the pattern is not specified carefully, this action can compress files that contain important data, are required for AMPS, or are required by the operating system.

Caution

This action cannot be used to safely compress journal files (also known as transaction log files). Use the actions described in Manage Journal Files for these files.

Compressing Files

Module Name

Does

amps-action-do-compress-files

Compresses files that match the specified pattern that are older than the specified age. This action accepts an arbitrary pattern, and removes files that match that pattern. While AMPS attempts to protect against deleting journal files, using a pattern that removes files that are critical for AMPS, for the application, or for the operating system may result in loss of data. The module does not recurse into directories. It skips open files. The module does not compress AMPS journals (that is, files that end with a .journal extension), and reports an error if a file with that extension matches the specified Pattern. The commands to remove files are executed with the current permissions of the AMPS process.

This module requires an Age parameter that specifies the age of the files to remove, as determined by the update to the file. This module also requires a Pattern parameter that specifies a pattern for locating files to remove.

Parameters for Compressing Files

Parameter	Description
Age	Specifies the age of files to process. The module removes any file older than the specified Age that matches the specified Pattern. For example, when the Age is 5d, only files that have not been modified within 5 days and that match the pattern will be processed by the module. There is no default for this parameter.
Pattern	Specifies the pattern for files to remove. The module removes any files that match the specified Pattern that have not been modified more recently than the specified Age. This parameter is interpreted as a Unix shell globbing pattern. It is not interpreted as a regular expression. As with other parameters that use the file system, when the pattern specified is a relative path, the parameter is interpreted relative to the current working directory of the AMPS process. When the pattern specified is an absolute path, AMPS uses the absolute path. There is no default for this parameter.
Keep	Specifies the number of files that meet the Age and Pattern criteria to leave uncompressed. When this parameter is specified, AMPS will compress files matching the criteria, starting with the oldest files, and stop when the number of remaining files is the number specified in this parameter. There is no default for this parameter. When both Keep and Count are specified, AMPS will not compress any files if the number of files meeting the criteria is less than the number specified in the Keep parameter.
Count	Specifies the maximum number of files that meet the Age and Pattern criteria to compress. AMPS will compress files matching the criteria, starting with the oldest files, and stop when the number of files specified in this parameter have been compressed. There is no default for this parameter. When both Keep and Count are specified, AMPS will not compress any files if the number of files meeting the criteria is less than the number specified in the Keep parameter.

This module does not add any variables to the AMPS context.

Removing Files

AMPS provides the following module for removing files. Use this action to remove error log files that are no longer needed. AMPS loads this module by default.

Caution

This action cannot be used to safely remove journal files (also known as transaction log fies). Use the actions described in Manage Journal Files for these files.

Removing Files

Module Name

Does

amps-action-do-remove-files

Removes files that match the specified pattern that are older than the specified age. This action accepts an arbitrary pattern, and removes files that match that pattern. While AMPS attempts to protect against deleting journal files, using a pattern that removes files that are critical for AMPS, for the application, or for the operating system may result in loss of data. The module does not recurse into directories. It skips open files. The module does not remove AMPS journals (that is, files that end with a .journal extension), and reports an error if a file with that extension matches the specified Pattern. The commands to remove files are executed with the current permissions of the AMPS process.

This module requires an Age parameter that specifies the age of the files to remove, as determined by the update to the file. This module also requires a Pattern parameter that specifies a pattern for locating files to remove.

Parameters for Removing Files

Parameter	Description
Age	Specifies the age of files to process. The module removes any file older than the specified Age that matches the specified Pattern. For example, when the Age is 5d, only files that have not been modified within 5 days and that match the pattern will be processed by the module. There is no default for this parameter.
Pattern	Specifies the pattern for files to remove. The module removes any files that match the specified Pattern that have not been modified more recently than the specified Age. This parameter is interpreted as a Unix shell globbing pattern. It is not interpreted as a regular expression. As with other parameters that use the file system, when the pattern specified is a relative path, the parameter is interpreted relative to the current working directory of the AMPS process. When the pattern specified is an absolute path, AMPS uses the absolute path. There is no default for this parameter.
Keep	Specifies the number of files that meet the Age and Pattern criteria to retain. When this parameter is specified, AMPS will remove files matching the criteria, starting with the oldest files, and stop when the number of remaining files is the number specified in this parameter. There is no default for this parameter. When both Keep and Count are specified, AMPS will not remove any files if the number of files meeting the criteria is less than the number specified in the Keep parameter.
Count	Specifies the maximum number of files that meet the Age and Pattern criteria to remove. AMPS will remove files matching the criteria, starting with the oldest files, and stop when the number of files specified in this parameter have been removed. There is no default for this parameter. When both Keep and Count are specified, AMPS will not remove any files if the number of files meeting the criteria is less than the number specified in the Keep parameter.

This module does not add any variables to the AMPS context.

Deleting Messages from SOW

AMPS also provides modules for deleting SOW contents. The amps-action-do-delete-sow module deletes messages from the specified SOW topic.

This module requires the Topic, MessageType and Filter parameters in order to delete the desired message.

Parameters for Deleting SOW Messages

Parameter	Description
Topic	The name of the SOW topic from which to delete messages. This parameter supports regular expressions. There is no default for this parameter.
MessageType	The message type of the SOW topic or topics to delete from. There is no default for this parameter.
Filter	Set the filter to apply. Only messages matching that filter will be deleted.

This module does not add any variables to the AMPS context.

Compacting a SOW File

AMPS also provides a module for reducing the unused space in a SOW file. The amps-action-do-compact-sow module rearranges the messages in the SOW into a smaller amount of space, where possible. Since AMPS uses memory-mapped files to store messages for the SOW topic, this can also potentially reduce the memory footprint of the topic.

This module can compact a specific SOW file or the SOW files for every topic in the instance.

While messages are being added or updated within a topic in the SOW, AMPS reuses free space when possible. It is not necessary to compact the SOW file during most normal operations. This action is most useful after an activity peak that leaves a large amount of unneeded space in the file, or in installations where space is at a premium. Depending on the file size, the number of topics to be compacted, and the amount of free space, the reorganization that this operation performs may require a noticeable amount of I/O bandwidth.

60East recommends that this action run during a maintenance window or in response to a critical lack of disk space. This operation will pause updates to the topic while it is being compacted, reducing overall throughput even if the compaction process runs quickly.

When a Topic and MessageType are provided, this module compacts the SOW file for that topic. Otherwise, the module compacts the file for all topics in the SOW.

Parameters for Deleting SOW Messages

Parameter	Description
Topic	The name of the SOW topic from which to compact. This option must be specified if the MessageType is provided. There is no default for this parameter.
MessageType	The message type of the SOW topic or topics to compact. This option must be specified if the Topic is provided. There is no default for this parameter.

This module does not add any variables to the AMPS context.

Querying a SOW Topic

AMPS provides a module for querying a SOW topic. The amps-action-do-query-sow queries the SOW topic, and stores the first message returned by the SOW query into a user-defined variable.

This module requires the Topic, MessageType and Filter parameters to identify the query to run. This module requires the CaptureData parameter in order to be able to store the result of the query.

Parameters for Querying SOW Messages

Parameter	Description
Topic	The name of the topic to query. This topic must be a SOW topic, a view, a queue, or a conflated topic. There is no default for this parameter. This parameter supports regular expressions.
MessageType	The message type of the topic to query. There is no default for this parameter
Filter	Set the filter to apply. If a Filter is present, only messages matching that filter will be returned by the query.
CaptureData	Sets the name of the variable within which AMPS will store the first message returned.
DefaultData	If no records are found, AMPS stores the DefaultData in the variable specified by CaptureData.
OrderBy	An OrderBy expression to use to order the results returned by the query. For example, to order in descending order of the /date field in the messages, you would provide an OrderBy option of /date DESC.
Options	The options for the query. This action accepts any valid option for a sow command except the top_n option (since this action is already limited to a top_n value of 1).

Once you query messages from the SOW topic, you can use the captured data in other actions. The example below uses amps-action-do-query-sow to query the SOW on a schedule in order to echo messages to the log for diagnostic purposes:

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-schedule</Module>
            <Options>
                <Every>Saturday at 23:59</Every>
                <Name>Diagnostic_Schedule</Name>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-query-sow</Module>
            <Options>
                <MessageType>xml</MessageType>
                <Topic>SOW_TOPIC</Topic>
                <Filter>/Trans/Order/@Oname = 'PURCHASE'</Filter>
                <CaptureData>AMPS_DATA</CaptureData>
            </Options>
        </Do>
        <Do>
            <Module>amps-action-do-extract-values</Module>
            <Options>
                <MessageType>xml</MessageType>
                <Data>{{AMPS_DATA}}</Data>
                <Value>SAVED_VARIABLE=/Value</Value>
            </Options>
        </Do>
        <Do>
            <Module>amps-action-do-echo-message</Module>
            <Options>
                <Message>{{SAVED_VARIABLE}} was in the message</Message>
            </Options>
        </Do>
    </Action>
</Actions>

Manage Security

AMPS provides modules for managing the security features of an instance.

Authentication and entitlement can be enabled or disabled, which is useful for debugging or auditing purposes. You can also reset security and authentication, which clears the AMPS internal caches and gives security and authentication modules the opportunity to reinitialize themselves, for example, by re-parsing an entitlements file.

AMPS loads the following modules by default:

Security Modules

Module Name	Does
amps-action-do-disable-authentication	Disables authentication for the instance.
amps-action-do-disable-entitlement	Disables entitlement for the instance.
amps-action-do-enable-authentication	Enables authentication for the instance.
amps-action-do-enable-entitlement	Enables entitlement for the instance.
amps-action-do-reset-authentication	Resets authentication by clearing AMPS caches and reinitializing authentication.
amps-action-do-reset-entitlement	Resets entitlement by clearing AMPS caches and reinitializing entitlement.

These modules require no parameters. The amps-action-do-reset-authentication module and the amps-action-do-reset-entitlement module accept an optional Transport parameter which specifies the transport to reset.

Parameters for Reset Authentication or Entitlement

Parameter	Description
Transport	The name of the transport for which to reset authentication or entitlements. If no name is provided, these modules affect all transports.
AuthenticationId	The authentication ID of the client for which to reset entitlements. If no ID is provided, these modules affect all clients.

These modules do not add any variables to the AMPS context.

Enable and Disable a Transport

AMPS provides modules that can enable and disable specific transports. The amps-action-do-enable-transport module enables a transport. The amps-action-do-disable-transport module disables a transport.

Transport Action Modules

Module Name	Does
amps-action-do-enable-transport	Enables a specific transport.
amps-action-do-disable-transport	Disables a specific transport.

Both modules require the name of the transport to disable or enable.

Parameters for Managing Transports

Parameter	Description
Transport	The name of the transport to enable or disable. If no name is provided, the module affects all transports.

Both modules do not add any variables to the AMPS context.

Publishing Messages

The amps-action-do-publish-message module publishes a message into a specified topic.

Publishes from this action are treated as publishes from an AMPS client inside the AMPS engine. This means that:

• There are no user credentials associated with the publish, so entitlements are not applied.
• There is no special handling for the publish. The publish is recorded in the transaction log exactly as if it arrived from outside of the instance and is processed within the instance as if the publish had arrived from an external publisher.

Warning

This action is treated by the AMPS engine as a publish from an internal AMPS client. When an amps-action-do-publish-message runs in response to the amps-action-on-publish-message event or the amps-action-on-deliver-message event, use caution, the message published from this action could cause the event to trigger again.

This warning includes cases where the action publishes to a topic directly monitored by the action and cases where the action monitors a view and publishes to an underlying topic of the view. The warning also applies to configurations in which two or more actions “cross publish” to topics that are monitored by the other action. An example of the last case is an action that monitors TopicOne and publishes to TopicTwo, while another action monitors TopicTwo and publishes to TopicOne.

The result of a configuration like the ones described above is called a publish loop. AMPS does not support unterminated publish loops or loops that produce a large number of cycles before terminating.

To publish a message, this module requires a Topic, the MessageType to publish on and also the Data that the message will contain. In addition to that, this module also accepts optional parameters listed below:

Parameters for Publishing Messages

Parameter	Description
Topic	The topic of the message being published.
MessageType	The message type for the topic. There is no default for this parameter.
Data	The data that the message will contain.
Delta	Whether to use a delta publish. When this option is present, and the value is true, the action will use a delta publish.
UpdateOnly	Specifies whether a delta publish is allowed to insert a record, or only update a record. When a delta publish is specified (that is, Delta is true ), and this option is set to true, AMPS will only accept the publish if there is a record present to be updated. When no value is specified, this option is false

This module does not add any variables to the AMPS context.

Manage Replication

AMPS provides modules for downgrading replication destinations that fall behind and upgrading them again when they catch up.

Replication Management Modules

Module Name	Does
amps-action-do-downgrade-replication	Downgrades replication connections from synchronous to asynchronous if the age of the last acknowledged message is older than a specified time period.
amps-action-do-upgrade-replication	Upgrades previously-downgraded replication connections from asynchronous to synchronous if the age of the last acknowledged message is more recent than a specified time period. This action has no effect on replication destinations that are specified as async in the configuration file.

The modules determine when to downgrade and upgrade based on the age of the oldest message that a destination has not yet acknowledged. When using these modules, it is important that the thresholds for the modules are not set too close together, otherwise; AMPS may repeatedly upgrade and downgrade the connection when the destination is consistently acknowledging messages at a rate close to the threshold values. To avoid this, 60East recommends that the Age set for the upgrade module is 1/2 of the age used for the downgrade module.

The amps-action-do-downgrade-replication module accepts the following options:

Parameters for Downgrading Replication

Parameter	Description
Age	Specifies the maximum message age at which AMPS downgrades a replication destination to async. When this action runs, AMPS downgrades any destination for which the oldest unacknowledged message is older than the specified Age. For example, when the Age is 5m, AMPS will downgrade any destination where a message older than 5 minutes has not been acknowledged. There is no default for this parameter.
GracePeriod	The approximate time to wait after start up before beginning to check whether to downgrade links. The GracePeriod allows time for other AMPS instances to start up and for connections to be established between AMPS instances.

The amps-action-do-upgrade-replication module only applies to destinations configured as sync that have been previously downgraded. The module accepts the following options:

Parameters for Upgrading Replication

Parameter	Description
Age	Specifies the maximum message age at which a previously-downgraded destination will be upgraded to sync mode. When this action runs, AMPS upgrades any destination that has been previously downgraded where the oldest unacknowledged message is more recent than the time value specified in the Age parameter. For example, if a destination has been downgraded to async mode and the Age is 2m, AMPS will upgrade the destination when the oldest unacknowledged message to that destination is less than 2 minutes old. There is no default for this parameter.
GracePeriod	The approximate time to wait after start up before beginning to check whether to upgrade links. The GracePeriod allows time for other AMPS instances to start up, and for connections to be established between AMPS instances.

These modules do not add any variables to the AMPS context.

Extract Values

The amps-action-do-extract-values module extracts message values from a message and stores the values in a variable.

To extract values from a message, this module requires the MessageType and Value parameters. In addition to that, this module also accepts an optional parameter listed below:

Parameters for Extract Values

Parameter	Description
MessageType	The message type for the message to parse. There is no default for this parameter.
Value	An assignment statement that specifies the variable to store the extracted value in and the XPath identifier for the value to extract. This action can contain any number of Value elements, each providing an assignment statement. The format of the assignment is as follows: variable=amps-expression For example, the following assignment statement stores the value of the /previousRegionCode within the message to the variable PREVIOUS_REGION. After this action runs, the content of the variable can be referenced in subsequent action steps as {{PREVIOUS_REGION}}. PREVIOUS_REGION=/previousRegionCode Likewise, the following assignment statement creates a string from the values of the /firstName and /lastName fields within the message, and stores that to the variable COMBINED_NAME. After this action runs, the content of the variable can be referenced in subsequent action steps as {{COMBINED_NAME}}. COMBINED_NAME=CONCAT(/firstName, ' ', /lastName) There is no default for this option. If no Value options are provided, AMPS does not save any values from the parsed message.
Data	Contains the data to parse. Typically it is a message received from a publish event or retrieved from a SOW query. There is no default value for this parameter. If it is omitted, AMPS will not parse data when the action is run.

The module amps-action-do-extract-values adds the variables specified by the Value options to the current context.

Translate Data

The amps-action-do-translate-data action allows you to translate the value from variables in the current context. One common use for this action is to translate a large number of status values into a smaller number of states before publishing that information in a message. For example, an order processing system may track a large number of finely-grained status codes, while the reporting view for customers may want to map those status codes to a smaller set of codes such as “pending”, “shipped” and “delivered”. This action allows you to easily translate those codes within AMPS.

When used to assemble a message, this action provides equivalent results to a set of nested conditional statements in a view projection. However, if you are using actions to parse, assemble and publish messages, this action gives you the ability to change values.

Parameters for Translate Data

Parameter	Description
Data	The data to translate. Most often, this is the value of a variable in the current context.
Value	The variable to store the translated value in.
Case	A translation statement. The translation statement takes the form of original_value=translated_value. This action allows you to provide any number of Case statements. The action matches the Data provided to the original_value in each Case statement. When it finds a matching value, the action stores the translated value in the variable identified by the Value statement. For example, the following translation statement translates a value of credit_check_in_progress to a value of pending <Case>credit_check_in_progress=pending</Case> There is no default for this option.
Default	The default translation. AMPS sets the value of the variable to the contents of this element if no Case statement matches the Data provided. This element is optional. If no Default is specified, AMPS uses the value of the original Data as the default translation.

Increment Counter

The amps-action-do-increment-counter module allows AMPS to increment a counter by a value. Counters persist across action runs, and are saved in the instance memory until the instance is restarted.

If a counter with the specified name does not currently exist in the instance when the action runs, AMPS creates the counter with a value of 0 and then immediately increments it with the specified value. If the counter is already present, AMPS will simply increment the counter.

To see an example of amps-action-do-increment-counter, refer to the Action Configuration Examples section at the end of this chapter.

This module requires a Key that tells AMPS which counter to increment and a Value that tells AMPS where to store the incremented value.

Parameter for Increment Counter

Parameter	Description
Key	The name of the counter that AMPS will increment. There is no default value for this parameter.
Value	The variable in which to store the current value of the counter.

This module adds a variable that contains the counter, as specified in the Value parameter, to the current context.

Raising a Custom Event

The AMPS action system provides a way to create custom events and run an action when the custom event is raised. A custom event is raised by the amps-action-do-execute-event action. Events are received by the amps-action-on-execute-event module.

This action requires one of the following parameters:

Parameters for Do Execute Event

Parameter	Description
Event	The name of the event to raise. There is no default value for this parameter.
EventVariable	The variable from which to retrieve the name of the event to raise. There is no default value for this parameter.

This module does not add any variables to the AMPS context.

Executing System Commands

The amps-action-do-execute-system module allows AMPS to execute system commands.

The parameter for this module is simply the command. The command executes in the current working directory of the AMPS process, with the credentials and environment of the AMPS process.

The thread used to execute the command is monitored by AMPS thread monitoring. This means that the command must complete within a short period of time (on the order of a second or two at the longest) or AMPS may consider the thread to have become deadlocked.

Parameter for Execute System

Parameter	Description
Command	The command to execute. When the action runs, this command is executed as a shell command on the system where AMPS is running.

This module does not add any variables to the AMPS context.

Caution

This module executes system commands with the credentials of the AMPS process. It is possible to damage the system, interrupt the AMPS service, or cause data loss by executing commands with this module. 60East recommends against using any data extracted from an AMPS message in the command executed.

Managing Queue Transfer Requests

AMPS provides actions to enable and disable the “proxied transfer” setting for message queues. As described in the Failover and Queue Message Ownership section of the Replicating Messages Between Instances chapter of the AMPS User Guide, this setting allows an instance to manage ownership of a queue message that is owned by an instance that is offline (or otherwise unreachable from this instance). 60East recommends that these actions only be configured in situations where the administrative interface is unavailable. Unlike most other settings for which actions are provided, the “proxied transfer” setting is intended for disaster recovery rather than normal maintenance.

The amps-action-do-enable-proxied-transfer action can be used to enable proxied transfer for a queue. The amps-action-do-disable-proxied-transfer action can be used to disable proxied transfer for a queue.

Enabling proxied transfer will allow this instance to take ownership of messages owned by an unreachable instance, allowing those messages to be delivered. However, it also introduces the risk of duplicate delivery and duplicate processing in cases where the instance that currently owns the message is still online (but the replication network connection has failed), or in cases where the instance that currently owns the message becomes available again and begins servicing requests. See the Failover and Queue Message Ownership section for more details.

Although an action is provided for flexibility, 60East does not recommend that the enable_proxied_transfer setting is enabled automatically, due to the possibility of duplicate delivery. Instead, this action should be configured to run in response to action by an administrator, after the administrator determines that one of the instances that contains the queue is, in fact, offline and that the possibility of duplicate processing is an acceptable risk.

Caution

These actions are intended to assist in maintaining message delivery from a distributed queue during an outage of one of the instances that services the queue. When this setting is enabled, the possibility of duplicate delivery exists.

These actions require the following parameters:

Parameters for Do Enable Proxied Transfer

Parameter	Description
Topic	The name of the queue topic for which to enable or disable proxied transfer. There is no default value for this parameter.
MessageType	The message type of the topic for which to enable or disable proxied transfer. There is no default value for this parameter.

This module does not add any variables to the AMPS context.

Debugging Actions

AMPS provides modules for debugging your AMPS action configuration.

Debugging Modules

Module Name	Does
amps-action-do-nothing	Takes no action. Does not modify the state of AMPS in any way. The module simply logs that it was called.
amps-action-do-echo-message	Echoes the specified message to the log. The message appears in the log as message 29-0103, at info level. The logging configuration must allow this message to be recorded for the output of this action to appear in the log.

The amps-action-do-nothing module requires no parameters.

The amps-action-do-echo-message module requires the following parameter:

Parameter for Echo Message

Parameter	Description
Message	The message to echo. The default for this parameter is simply an empty string.

These modules do not add any variables to the AMPS context.

Creating a Minidump

AMPS provides a module for creating minidumps. The amps-action-do-minidump module provides a way for developers and/or administrators to easily create minidumps for diagnostic purposes.

Running this module does not cause AMPS to exit.

Module to Create Minidump

Module Name	Does
amps-action-do-minidump	Creates a minidump.

This module does not require any parameters.

This module does not add any variables to the AMPS context.

Shut Down AMPS

The amps-action-do-shutdown module shuts down AMPS. This module is registered as the default action for several Linux signals, as described in Default Signal Actions.

Causing this module to run is the recommended way to shut down AMPS. This is most often done by sending SIGINT to the AMPS process, which is handled by amps-action-on-signal to run this module.

Shut Down Module

Module Name	Does
amps-action-do-shutdown	Shuts down AMPS.

This module does not require any parameters.

This module does not add any variables to the AMPS context.

If Element: Conditionally Stop Action Sequence

AMPS includes the ability to run actions only if certain conditions are true. For some actions (such as the replication management actions), the condition is included as a part of the action. In other cases, AMPS provides If actions.

An If action is evaluated each time the execution of an action reaches the If action. When the condition specified in an If action is true, AMPS proceeds to the next Do action. If the condition in an If action is False, AMPS does not run any further Do elements in the action.

File System Usage

AMPS provides the following If module for taking action based on the file system capacity. AMPS loads this module by default:

File System Usage

Module Name	Does
amps-action-if-file-system-usage	Checks whether the specified path on the filesystem meets the specified usage level. If so, allows execution to continue. If not, stops the action.

Parameters for Running Actions Based on File System Usage

Parameter	Description
Path	Specifies the filesystem path to monitor. The AMPS process must have sufficient permissions to check the disk usage for this path at the time the check runs. There is no default for this parameter.
GreaterThan	The threshold to check, specified as a percentage. If the provided path has more space used than specified in this parameter, subsequent Do and If blocks will run. Otherwise, the action will complete with this step.

This module does not add any variables to the AMPS context.

For example, the following action will log a message in the AMPS log every minute when the file system becomes more than 90% full, and perform a full shutdown of AMPS if the file system is more than 98% full.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-schedule</Module>
            <Options>
                <Every>1m</Every>
            </Options>
        </On>
        <If>
            <Module>amps-action-if-file-system-usage</Module>
            <Options>
                <GreaterThan>90%</GreaterThan>
                <Path>/mnt/fastdrive/amps</Path>
            </Options>
        </If>
        <Do>
            <Module>amps-action-do-echo-message</Module>
            <Options>
                <Message>ALERT: You're getting low on space!</Message>
            </Options>
        </Do>
        <If>
            <Module>amps-action-if-file-system-usage</Module>
            <Options>
                <GreaterThan>98%</GreaterThan>
                <Path>/mnt/fastdrive/amps</Path>
            </Options>
        </If>
        <Do>
            <Module>amps-action-do-echo-message</Module>
            <Options>
                <Message>CRITICAL: Shutting down AMPS</Message>
            </Options>
        </Do>
        <Do>
            <Module>amps-action-do-shutdown</Module>
        </Do>
    </Action>
</Actions>

Conditional Expression

AMPS provides the following If module for taking action based on the results of an AMPS expression:

Running an action if a condition is true

Module Name	Does
amps-action-if-condition	Evaluates the specified condition. If the condition is true, allows execution to continue. Otherwise, stops the action.

Parameters for Running Actions Based on a Conditional Expression

Parameter

Description

Condition

Specifies the condition to evaluate. Context variables are expanded before the condition is evaluated. The condition may use AMPS functions. The condition must be a valid AMPS filter when evaluated. If variable expansion produces an expression that is not a valid filter, the module logs an error and stops the action. Notice that the condition does not have direct access to an AMPS message (even if this If step is a part of an action started by a message, such as the amps-action-on-publish-message On event). When the On step for this action provides an option for conditional execution (for example, the Filter option for amps-action-on-publish-message), it is more efficient to use that Filter to only run the action if the filter matches, than to use this step to stop the action. You can use the amps-action-do-extract-values Do step to extract values into context variables, or use a filter on the On event to only run the action for messages that meet the criteria. There is no default for this parameter.

This module does not add any variables to the AMPS context.

For example, the following action will enable the transport named subscriber-transport when a client named ImportantPublisher logs on, and disable the transport named subscriber-transport when the client named ImportantPublisher disconnects. An action of this type could be used to ensure that subscribers can only connect to an instance of AMPS if the ImportantPublisher is also connected to that instance. (Not shown in this snippet is that the subscriber-transport is set to the initial state of disabled, and that there is a different transport available for ImportantPublisher to connect to.)

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-logon-client</Module>
        </On>
        <If>
            <Module>amps-action-if-condition</Module>
            <Options>
                <Condition>"{{AMPS_CLIENT_NAME}}" = "ImportantPublisher"</Condition>
            </Options>
        </If>
        <Do>
            <Module>amps-action-do-enable-transport</Module>
            <Options>
                <Transport>subscriber-transport</Transport>
            </Options>
        </Do>
      </Action>
      <Action>
        <On>
            <Module>amps-action-on-disconnect-client</Module>
        </On>
        <If>
            <Module>amps-action-if-condition</Module>
            <Options>
                <Condition>"{{AMPS_CLIENT_NAME}}" = "ImportantPublisher"</Condition>
            </Options>
        </If>
        <Do>
            <Module>amps-action-do-disable-transport</Module>
            <Options>
                <Transport>subscriber-transport</Transport>
            </Options>
        </Do>
      </Action>
 </Actions>

Action Configuration Examples

Archive Transaction Log Journal Files Older Than One Week, Every Saturday

The listing below asks AMPS to archive transaction log journal files older than 1 week, every Saturday at 12:30 AM.

This configuration moves journal files from the JournalDirectory to the JournalArchiveDirectory, while maintaining the files as an active part of the transaction log (ensuring that they are still available for bookmark replay, replication, and so on):

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-schedule</Module>
            <Options>
                <Every>Saturday at 00:30</Every>
                <Name>Saturday Night Fever</Name>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-archive-journal</Module>
            <Options>
                <Age>7d</Age>
            </Options>
        </Do>
    </Action>
</Actions>

Disable and Re-enable Security on Signal

The listing below disables authentication and entitlement when AMPS receives the USR1 signal. When AMPS receives the USR2 signal, AMPS re-enables authentication and entitlement. This configuration is, in effect, the configuration that AMPS installs by default for these signals:

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-signal</Module>
            <Options>
                <Signal>SIGUSR1</Signal>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-disable-authentication</Module>
        </Do>
        <Do>
            <Module>amps-action-do-disable-entitlement</Module>
        </Do>
    </Action>
    <Action>
        <On>
            <Module>amps-action-on-signal</Module>
            <Options>
                <Signal>SIGUSR2</Signal>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-enable-authentication</Module>
        </Do>
        <Do>
            <Module>amps-action-do-enable-entitlement</Module>
        </Do>
    </Action>
</Actions>

Reset Entitlements for a Disconnected Client

The listing below resets entitlement cache for a user when a client with that authentication ID is disconnected. This is a practical approach when an application expects that each user will have a single connection to AMPS.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-disconnect-client</Module>
        </On>
        <Do>
            <Module>amps-action-do-reset-entitlement</Module>
            <Options>
                <AuthenticationId>{{AMPS_AUTHENTICATION_ID}}</AuthenticationId>
            </Options>
        </Do>
    </Action>
</Actions>

Extract Values on Publish of a Message

The listing below extracts values from a locally published xml message and stores them into VALUE.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-publish-message</Module>
            <Options>
                <Topic>message-sow</Topic>
                <MessageType>xml</MessageType>
                <MessageSource>local</MessageSource>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-extract-values</Module>
            <Options>
                <MessageType>xml</MessageType>
                <Data>{{AMPS_DATA}}</Data>
                <Value>VALUE = /VALUE</Value>
            </Options>
        </Do>
    </Action>
</Actions>

Increment a Counter and Echo a Message on Signal

The listing below increments a counter and echoes the counter’s value when AMPS receives the USR1 signal.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-signal</Module>
            <Options>
                <Signal>SIGUSR1</Signal>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-increment-counter</Module>
            <Options>
                <Key>MY_COUNTER</Key>
                <Value>CURRENT_COUNTER_VALUE</Value>
            </Options>
        </Do>
        <Do>
            <Module>amps-action-do-echo-message</Module>
            <Options>
                <Message>AMPS has gotten {{CURRENT_COUNTER_VALUE}}
                    SIGUSR1 signals.</Message>
            </Options>
        </Do>
    </Action>
</Actions>

Recording Expired Queue Messages in a Dead Letter Topic

The listing below detects when a message expires from a queue, and publishes those messages to a dead letter topic.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-sow-expire-message</Module>
            <Options>
                <Topic>interesting-queue</Topic>
                <MessageType>json</MessageType>
            </Options>
        </On>
        <On>
            <Module>amps-action-on-sow-expire-message</Module>
            <Options>
                <Topic>another-interesting-queue</Topic>
                <MessageType>json</MessageType>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-publish-message</Module>
            <Options>
                <Topic>dead-letter</Topic>
                <MessageType>json</MessageType>
                <Data>{"topic":"{{AMPS_TOPIC}}","message":{{AMPS_DATA}} }</Data>
            </Options>
        </Do>
    </Action>
</Actions>

Copy a Message to a Different Topic When a Timeout is Exceeded

The listing below, in effect, copies messages from the Orders topic to the Orders_Stale topic when the status has been PENDING for more than 5 seconds.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-message-condition-timeout</Module>
            <Options>
                <MessageType>nvfix</MessageType>
                <Topic>Orders</Topic>
                <Filter>/status = 'PENDING'</Filter>
                <Duration>5s</Duration>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-publish-message</Module>
            <Options>
                <MessageType>nvfix</MessageType>
                <Topic>Orders_Stale</Topic>
                <Data>{{AMPS_DATA}}</Data>
            </Options>
        </Do>
    </Action>
</Actions>

Shutting Down AMPS When Filesystem Fills

The listing below directs AMPS to perform a graceful shutdown when the filesystem becomes full, with a check run every 3 seconds.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-schedule</Module>
            <Options>
                <Every>3s</Every>
            </Options>
        </On>
        <If>
         <Module>amps-action-if-file-system-usage</Module>
            <Options>
                <Path>./</Path>
                <GreaterThan>99%</GreaterThan>
            </Options>
        </If>
        <Do>
            <Module>amps-action-do-shutdown</Module>
       </Do>
    </Action>
</Actions>

Archive Transaction Log Journal Files Older Than a Specified Age in Response to Admin Request

The listing below directs AMPS to archive journals when a query is made to the /amps/administrator/actions/archive_journals resource. The request must include an AGE query parameter. When the request is submitted, AMPS will mark journals older than the specified age for archival.

<Actions>
    <Action>
        <On>
            <Module>amps-action-on-admin</Module>
            <Options>
                <Path>archive_journals</Path>
                <RequiredParameter>AGE</RequiredParameter>
                <Name>Archive Journals</Name>
            </Options>
        </On>
        <Do>
            <Module>amps-action-do-archive-journal</Module>
            <Options>
                <Age>{{AGE}}</Age>
            </Options>
        </Do>
    </Action>
</Actions>

The On configuration for this action specifies that the action will run when a request is made to the /amps/administrator/actions/archive_journals resource, and that the request must contain an AGE query parameter. When the request runs, the AGE parameter is added to the context for the action.

The Do configuration for this action runs the amps-action-do-archive-journal module, and fills in the value of the AGE parameter provided by the HTTP request.

If the AGE parameter is missing, the amps-action-on-admin module will refuse the request.

If the AGE parameter is not a valid interval (for example, if someone provided the string "LastThursday" instead of a valid AMPS interval like 48h), the amps-action-do-archive-journal module will log an error and refuse to run the request.