ROMessage Object

The ROMessage object provides read-only access to Rhapsody messages.

Properties

Property	Description
`text`	Read property. Gets the body of the message using the default system encoding.
`body`	Read property. Gets the body of the message as a byte array.
`connectionId`	Read property. Gets the connection identifier for this message, as an integer, if it was received on a communication point that has connection tracking enabled.
`bodyEncoding`	Read property. Gets the name of the current character encoding for the body of this message. Returns null if no character encoding has been set.
`xml`	Read property. Gets the message body as an XML object, as defined by the E4X standard. This will throw an exception if the message is not XML. Refer to The Global XML Object for details on E4X's XML object. For performance reasons, the E4X XML object returned by the `xml` property is cached so that the message body does not have to be re-parsed every time it is referenced. Therefore, any changes made to the XML object are persisted between requests to the property instead of a new copy being retrieved each time. If you need to make changes to the XML object but still reference its original value, then either reference the XML property of two different message objects (for example, the input and output message separately), or alternatively copy the XML object before the changes are made, for example: var myXml = new XML(input[0].xml); The `prettyPrinting` property of the E4X XML object is enabled by default. You can disable this property, but only for all JavaScript filters in your configuration, by setting it to `false` as follows (you cannot assign it to `false` directly): var settings = XML.settings(); settings.prettyPrinting = false; XML.setSettings(settings);

Methods

The following methods are designed to fetch the original input message, even if you have modified it in the interim.

Method	Description
`getBody()`	Gets the body of the message as a byte array.
`getBodySize()`	Returns a number representing the current message body size in bytes. This is a more efficient way of retrieving the message body size than calling `input.body.length`.
`isBodyLargerThan(threshold)`	Returns true if the current message body size is larger than the provided threshold, or false otherwise. The threshold must be numeric and in bytes. This is a more efficient way of comparing the message body size against a threshold than directly retrieving the size and performing a comparison.
`getText(string encoding)`	Gets the body of the message as a string using the specified Java character encoding. Refer to Supported Encodings for a list of Java supported encoding sets.
`getField(string fieldPath)`	Extracts the field, specified by the string argument, from the message and returns it as a string. If the field is valid but does not exist, null is returned. If the field is not valid, based on the message definition, an exception is thrown. The message must be parsable using one of the message definitions associated with the route.
`getFieldAsList(string fieldPath)`	Extracts the field, specified by the string argument, from the message and returns it as an array. If the field is valid but does not exist, null is returned. If the field is not valid, based on the message definition, an exception is thrown. The message must be parsable using one of the message definitions associated with the route.
`getRepeatCount(string fieldPath)`	Returns the number of repeats if the field specified by `fieldPath` is a repeating field, or the number of elements within the field if the field is non-repeating. The message must be parsable using one of the message definitions associated with the route.
`getProperty(string propertyName)`	Returns the value of the message property as a string, or null if the property does not exist on the message.
`getPropertyAsList(string propertyName)`	Returns a list of the message property values with the given name. The list returned is an instance of `java.util.List` containing strings. If no property with the given name exists, an empty list is returned. Property lists are stored in a serialized format in Rhapsody, with special encoding, which allows them to be parsed correctly. This may change in a future release, therefore, you must NOT parse the list manually, as you may run into problems when extensions are required. You should use the `getPropertyAsList(name)` method to retrieve the list.
`getPropertyNames()`	Returns an instance of `java.util.Iterator` that iterates over all the available properties (returned as strings) in the message.
`getErrors()`	Returns the array of strings that describe the parsing errors that occurred when processing this message. Any filter that indicates errors either by calling `Message.addError()`, or by throwing an exception out of the filter, has its errors available through the `getErrors()` method available in JavaScript. These are only available when a message has come from an error output. Returns an empty array if there are no errors. If any exception is thrown out of a filter while processing a message, the exception message and the name of the filter are added as an error to the message, allowing subsequent retrieval using the `getErrors()` method. If the exception has a nested cause (that is, a nested exception), all the messages from the nested exceptions are also added as errors to the message (identified as nested exceptions). If an exception is thrown out of a filter, any other changes made to the message by the filter are discarded. If the thrown exception is a `FilterProcessingException` (or a derived class), this indicates an error with the message, so the message is sent to the error connector of the filter. If the thrown exception is any other type, the message is sent directly to the error queue (as it generally indicates an issue with the filter rather than the message). If the message is sent to the error connector, but there is nothing connected to the error connector for this filter, the message is sent to the error queue. If an exception is thrown when there were multiple input messages (that is, a collector), the exception error messages are added to all the input messages, and all the messages are sent to the error connector / Error Queue. If a filter explicitly adds errors to the message using the `addError()` method, the message is sent to the error connector once it leaves the filter. Unlike when an exception is thrown, any changes made to the message in this case are saved (as the filter did complete execution).
`getReadableEdiMessage()`	Gets access to the internal Symphonia `MessageElement` if this is an EDI message. Retrieves the root `com.orion.symphonia3.MessageElement` object representing the entire parsed message. The Symphonia API can then be used to browse the message. Refer to Parsing EDI Messages for details. Important! Do not attempt to use this method to change the message. Instead, use the `getWritableEdiMessage()` method.
`getHapiMessage(boolean isXml)`	Creates a JavaScript object of a transformable HAPI HL7 message using the HAPI HL7 structures. `isXml` indicates whether the input message is in XML format. It is optional and defaults to `false`, which indicates the input message is in pipe-delimited HL7 format. Refer to HAPIMessage Object for details.
`isInputIndexedProperty(string propertyName)`	Returns `true` if the specified property is indexed for input.
`isOutputIndexedProperty(string propertyName)`	Returns `true` if the specified property is indexed for output.
`loadMessageSnapshot()`	Loads the snapshot of the message which was saved with the Save Snapshot filter and returns it as a ROMessage object. This object contains the same message body and message properties that the message had when it was saved. An error is raised if you attempt to load a snapshot message after the component that saved it has been deleted. The snapshot message must be loaded within the same locker it was saved in. Attempting to load it in another locker will result in an error.
`loadMessageSnapshotForId(string snapshotMessageId)`	Loads the snapshot of a message with the specified message ID which was saved with the Save Snapshot filter and returns it as a ROMessage object. This object contains the same message body and message properties that the message had when it was saved. An error is raised if you attempt to load a snapshot message after the component that saved it has been deleted. The snapshot message must be loaded within the same locker it was saved in. Attempting to load it in another locker will result in an error. This method can, in fact, be used to retrieve any message using its message ID, including messages that were not saved as snapshots.

Examples

The input object that is accessible in a JavaScript filter script is an array of ROMessage objects. The following examples illustrate how to use the ROMessage properties and methods:

Store Message Body
Extract a Field from a Message
Find the Number of Repeating Elements for a Message Field
Extract a List of Values from a Message Field
Obtain Message Properties
Load a Snapshot Message
Load a Snapshot Message with Specified Message ID

Store Message Body

The following code excerpt gets each input message's body, and stores it in the local string readOnlyBody:

for (var i = 0; i < input.length; i++) {
    var readOnlyMessage = input[i];

    // Get the message body
    var readOnlyBody = readOnlyMessage.text;

    //...

}

In this example (and the code excerpts on this page), no message is inserted into the output MessageCollection. Each element in the input[] array is a read-only message, so cannot be altered in any way. Later examples show how to edit the messages and add them to the output message collection.

Extract a Field from a Message

The following code excerpt demonstrates how to extract a field from a message.

For an EDI message, the . or / symbol should be used to separate the elements leading to the field. A specific repeating element can be specified by putting the repeating element number in square brackets (as in a later example). If the field is not valid, based on the message definition, an exception will be thrown. For an XML message, the field should be addressed using XPath notation. Use / to separate elements and square brackets to specify a repeating element's index.

For an XML message, an exception will never be thrown; XML messages have no concept of an invalid field and thus will return null when the field does not exist.

For the following, we assume the route has a message definition attached to it, that defines an HL7 ADT^A01 message with an MSH segment that contains the CountryCode field.

for (var i = 0; i < input.length; i++) {
    var readOnlyMessage = input[i];

    // Get a field from the message
    var countryCode = readOnlyMessage.getField("MSH/CountryCode");

    //...
}

Find the Number of Repeating Elements for a Message Field

The following code excerpt finds the number of repeating elements for a message field, and iterates through each of them. In this example, the route requires a message defined with an NK1 repeating message segment containing a Religion field. The value of the Religion field on each repeat is concatenated into the string religions, separated by semicolons.

for (var i = 0; i < input.length; i++) {
    var readOnlyMessage = input[i];

    // Get the number of repeats for the "NK1" field
    var repeatCount = readOnlyMessage.getRepeatCount("NK1");

    // Iterate through each repeat, getting the "Religion" field of each
    var religions = "";
    for (var i = 0; i < repeatCount; i++) {
        var religion = readOnlyMessage.getField("NK1[" + i + "]/Religion");
        religions += religion + ";";
    }

    //...
}

Extract a List of Values from a Message Field

The following code excerpt demonstrates how to extract a list of values from repeating elements for a message field, and iterates through each of them. In this example, the route requires a message defined with a DG1 (Diagnosis) repeating message segment containing a DiagnosisCode/Text field.

var readOnlyMessage = input[0];
var diagnosisCodes = readOnlyMessage.getFieldAsList("DG1[*]/DiagnosisCode/Text");
var str_diagnosisCodes = "";

for (var i = 0; i < diagnosisCodes.length; i++) {
str_diagnosisCodes += diagnosisCodes[i] + ";"; 
}
log.info("List of diagnosis codes: " + str_diagnosisCodes);

Obtain Message Properties

The following two code listings show the two ways that the value of message properties can be obtained.

The first way, you can access the properties as a list. Each item in the list can be accessed by iterating through the list, as with a Java List object. We print a warning message to the log for each value property of the multi-valued property.

for (var i = 0; i < input.length; i++) {
    var readOnlyMessage = input[i];

    // Get a list of message properties
    var properties = readOnlyMessage.getPropertyAsList("PropertyList");

    // Loop through the properties, 
    var iterator = properties.iterator();
    while (iterator.hasNext()) {
        var oneProperty = iterator.next();
        log.info("One property is: " + oneProperty);
    }
}

Alternatively, you can obtain the value of a property MessageName as a string property.

for (var i = 0; i < input.length; i++) {
    var readOnlyMessage = input[i];

   // Get a single message property string
   var property = readOnlyMessage.getProperty("MessageName");

   //...
}

Load a Snapshot Message

This code excerpt shows how to load a previously saved message snapshot. This contains an example of retrieving the original message property from the snapshot message and accessing the message bodies of the current message and the snapshot message.

var inputMessage = input[0];
  
// Load the snapshot
var snapshot = inputMessage.loadMessageSnapshot();
  
// Retrieve one of the old properties
var messageName = snapshot.getProperty("MessageName");
  
//...
  
// Combine both message bodies
var combinedText = inputMessage.text + '\n' + snapshot.text;
  
var outputMessage = output.append(inputMessage);
outputMessage.text = combinedText;

Load a Snapshot Message with Specified Message ID

This code excerpt shows how to load a specified saved message snapshot using its message ID. This contains an example of retrieving the original message property from the snapshot message and accessing the message bodies of the current message and the snapshot message.

var inputMessage = input[0];
  
// Load the snapshot
var messageId = inputMessage.getProperty("rhapsody:SnapshotMessageId");
var snapshot = inputMessage.loadMessageSnapshotForId(messageId);
  
// Retrieve one of the old properties
var messageName = snapshot.getProperty("MessageName");
  
//...
  
// Combine both message bodies
var combinedText = inputMessage.text + '\n' + snapshot.text;
  
var outputMessage = output.append(inputMessage);
outputMessage.text = combinedText;