Rhapsody enables you to track transient state within Rhapsody between otherwise unrelated messages in order to assist you with implementing complex workflows within Rhapsody:
Rhapsody's transient state service enables simple in-memory state to be maintained independently of the message flow within an engine. Transient state is an in-memory store of key and value pairs which can be set using JavaScript or the REST API, and then can be used via message properties on any communication point or filter using a user-specified message property for a configuration parameter. It provides an alternative to using an external database or Rhapsody message collectors for passing values between messages.
It is recommended that you clearly document any use of the transient state in either the notes in Rhapsody IDE or your own configuration documentation, as the transient state references may be completely unrelated to the visible message flow within the engine.
Configuration Options
The following configuration options are available via the rhapsody.properties file:
| Property | Type | Description | Min. | Default | Max. |
|---|---|---|---|---|---|
TransientStateService.maximumStateKeys |
Number | The maximum number of non-expired transient state keys that can be in use at a time. The oldest keys (in terms of time in use) are discarded after this limit is reached. A value of zero disables transient state functionality entirely (any attempts to set the transient state would fail). | 0 | 100 | 10000 |
TransientStateService.maximumStateValueSize |
Number | The maximum size of transient state values (in terms of number of characters) that can be stored, with errors raised if a transient value exceeds this limit. | 100 | 1000 | 10000 |
TransientStateService.allowedStateKeys |
Comma- or whitespace-separated string list | The enumerated list of transient state keys that are permitted to be used, giving an administrator the ability to restrict the use of keys. If this property is not set, then any key is permissible. If it is set, then it is deemed to be a comma- or whitespace-separated list of allowed keys, and the use of unlisted keys is rejected. |
Transient State Keys and Values
Transient state keys and values are both stored as strings, but non-string values can be stored by encoding the value in base64 or JSON format. State values can optionally be given an expiry time after which they are automatically removed. However, all Rhapsody transient states are cleared when the engine is restarted.
Transient state keys must have a unique name across the Rhapsody system.
The viewing or modification of transient state values is restricted to the locker in which they were first set. They are not accessible across lockers. If an attempt is made from one locker to retrieve or set a transient state value that belongs to another locker, an error message is displayed containing the name and identifier of the locker that owns the respective transient state key.
If the specified transient state key does not exist, has expired, or is not visible to the current configuration locker, then an empty string is returned.
Transient State Message Properties
Rhapsody transient state can be accessed using message properties that follow a special format for the property name. This functionality can be used with any communication point or filter that normally accepts a message property for the associated configuration value and allows the name of that message property to be configured. This is done transparently to the communication point or filter so can be used with custom components without any changes (provided they accept message properties).
The property name format is: @State_<key>, where <key> is the transient state key. For example, to access transient state with a key of myKey1 you would use a property name of @State_myKey1.
If a communication point or filter requires a message property name to be prepended with a dollar sign in order to distinguish it from a string literal, then this is needed in addition to this syntax (for example, $@State_myKey1).
Transient state accessed through message properties is immutable.
Viewing and Modifying Transient State
You can monitor or update the transient state using:
REST API
The REST API provides methods for you to fetch or modify the transient state. Refer to Transient State Monitoring for details on the REST API methods relating to transient state.
You require the following access rights for transient state viewing and modification:
- 'Read transient state REST API' - to call the REST API to read the transient state.
- 'Modify transient state REST API' - to call the REST API to modify the transient state.
These access rights are granted on a per locker basis, by default only to the superuser, and are only used for viewing and modifying transient state via the REST API.
JavaScript
A global object called TransientState is available in all JavaScript components that relate to message processing, including but not limited to the:
- JavaScript filter.
- JavaScript Conditional connector.
- JavaScript REST Client communication point.
- Web Service Client communication point.
The TransientState object can also be used in shared JavaScript libraries invoked from one of those components.
Refer to TransientState Object for details on the Javascript methods you can use to view or modify the transient state.
Example: Using Transient State
An upstream filter uses JavaScript to set the transient state value of the key remoteHost to localhost. If that value is empty (in other words if it is not already set), and the transient state value of the key remotePort to 15000 if that value is empty:
transientState.compareAndSetState('remoteHost', '', 'localhost');
transientState.compareAndSetState('remotePort', '', '15000');
A downstream communication point uses the transient state values relating to the keys remoteHost and remotePort to set its configuration properties Remote Host and Remote Port, respectively:
