Snapshot Filters

The Snapshot Save and Snapshot Load filters enable users to save and restore messages bodies at specific states. The filters are designed to work together.

The Snapshot Save filter takes a 'snapshot' of a message by recording its message body and encoding as it passes through the filter. The message ID and encoding of the snapshot message is appended to the message as set of standard message properties. When the message arrives at the Snapshot Load filter, the filter uses the snapshot message stored in its message properties to replace its message body and respective encoding.

Running Error Queue defragmentation can cause any affected saved snapshot messages in the Error Queue to become irretrievable. Refer to Error Queue Defragmentation for details.

Standard Properties

The filters make use of the following standard message properties:

Property	Description
`rhapsody:SnapshotMessageId`	The message identifier representing the message body at the time the snapshot is taken.
`rhapsody:SnapshotBodyEncoding`	The message encoding of message body at the time the snapshot is taken.

Snapshot Save Filter

The Snapshot Save filter copies a reference to the current message body to the property rhapsody:SnapshotMessageId. It also copies the value in the encoding type property (rhapsody:BodyEncoding) of a message to the property rhapsody:SnapshotBodyEncoding.

The snapshot message property values can be used by a downstream Snapshot Load filter to restore the message body to the state it was in when it entered the Snapshot Save filter. A snapshot message is available in Rhapsody until the message it is associated with is removed by Archive Cleanup.

The Snapshot Save filter has no configuration properties.

Snapshot Load Filter

The Snapshot Load filter replaces the message body of an input message with the message body of the snapshot message specified in the rhapsody:SnapshotMessageId property. You can configure the filter to allow an input message to pass through unmodified or direct it to the Error Queue when rhapsody:SnapshotMessageId is missing. The filter also replaces the message encoding of the input message with the message encoding specified in the rhapsody:SnapshotBodyEncoding property. The rhapsody:SnapshotBodyEncoding is not a required property: if it is missing or otherwise unusable, the body encoding is set to undefined, erasing any previous encoding setting.

The filter only modifies the message body of the input message (and the message encoding if available); the input message retains all of its existing message properties. The Snapshot Load filter is suitable for cases where a message is required to retain its current meta-state (such as message properties), as well as its original message body, for example when handling an acknowledgment of a message sent to an external system.

It is possible for other filters to change the values of rhapsody:SnapshotMessageId and rhapsody:SnapshotBodyEncoding. The Snapshot Load filter will attempt to use these properties as appropriate. If multiple filters change the values of these properties, the Snapshot Load filter restores the body text to the most recent values only. It will set the message encoding as defined, so users must ensure these properties are set correctly. However, it is recommended that the Snapshot Load filter is used in conjunction with the Snapshot Save filter whenever possible.

Messages can only be loaded using the Snapshot Load filter if the target message state was set within the same locker. Any attempt to load a message state from outside the existing locker will result in an error.

Configuration Properties

Property Description

Property	Description
`Fail on processing error`	Specifies whether the filter should abort the operation if any errors occur while replacing the message body: `True` (default) - the message is sent to the Error Queue if any errors occur replacing the message bodies. `False` - the filter ignores any errors and allows the message to pass through unchanged. This property should only be set to false in scenarios where a failure to replace the message body should not stop normal processing on the route.
`Fail on missing snapshot properties`	Specifies whether the filter should abort the operation if the required snapshot message ID is missing: `True` (default) - the message is sent to the Error Queue if any required properties are missing. `False` - the filter ignores any errors and allows the message to pass through unchanged. This property should only be set to false in scenarios where not all of the messages reaching the filter have a saved snapshot, but need to continue processing on the route.

Fail on processing error

Specifies whether the filter should abort the operation if any errors occur while replacing the message body:

True (default) - the message is sent to the Error Queue if any errors occur replacing the message bodies.
False - the filter ignores any errors and allows the message to pass through unchanged. This property should only be set to false in scenarios where a failure to replace the message body should not stop normal processing on the route.

Fail on missing snapshot properties

Specifies whether the filter should abort the operation if the required snapshot message ID is missing:

True (default) - the message is sent to the Error Queue if any required properties are missing.
False - the filter ignores any errors and allows the message to pass through unchanged. This property should only be set to false in scenarios where not all of the messages reaching the filter have a saved snapshot, but need to continue processing on the route.

Javascript Objects

Filters that use JavaScript can load snapshot messages using the following JavaScript object methods:

loadMessageSnapshot() - loads a ROMessage object from the rhapsody:SnapshotMessageId property.
loadMessageSnapshotForId(string snapshotMessageId) - loads a ROMessage object from the specified message ID.

Unlike the Load Snapshot filter, the load snapshot JavaScript methods retrieve the snapshot message exactly as it was saved by the Snapshot Save filter. They do not alter the loaded message in any way – the message body, encodings, and all message properties are unchanged. To modify any attribute of a loaded snapshot message, you must use the appropriate JavaScript methods to do so.

These JavaScript methods are suitable for scenarios where an amalgam of the original message and its later modified version is required, for example when performing complex mappings. Note, however, If you replace the message body with the one from the snapshot message, then ensure you preserve the encodings by either using the setText(string body, string encoding) method or setting the text and bodyEncoding properties synchronously.

Refer to ROMessage Object for details and examples on these methods.

Multiple Snapshots

Only one snapshot message ID can be stored at a time in the rhapsody:SnapshotMessageId property. However, you can capture additional snapshot messages during the lifetime of the message.

For example, to replace a snapshot message with another:

Use the Snapshot Save filter to populate the value stored in the rhapsody:SnapshotMessageId property with the message ID of the first snapshot message.
Create a new property, say StoreSnapshotMsg1 and set it to the value stored in the rhapsody:SnapshotMessageId property (the message ID of the first snapshot message) using a JavaScript filter, for example:
```
 next.setProperty("StoreSnapshotMsg1", next.getProperty("rhapsody:SnapshotMessageId"));
```
Use the Snapshot Save filter to replace the value stored in the rhapsody:SnapshotMessageId property with the message ID of the second snapshot message.

To restore the first snapshot message:

Set the rhapsody:SnapshotMessageId property to the value from the property StoreSnapshotMsg1.
Use Snapshot Load filter to load the first snapshot message.

Alternatively, to restore the first snapshot message, use a JavaScript filter and the loadMessageSnapshotForId method, for example:

loadMessageSnapshotForId(next.getProperty("StoreSnapshotMsg1"));