The following global functions are available for components that use JavaScript:

It is not possible to set properties on the prototypes of standard JavaScript objects. For example, String.prototype.myCustomFunction = function() {return 0;} results in an error.

General Functions

Function

Description
generateUuid()

Used to generate a type4 UUID:

var uuid = generateUuid();
dateChangeFormat(string dateTimeString,
string oldFormat, string newFormat)

Transforms date-time formats. It takes three parameters:

  • dateTimeString - the original date-time string whose format you want to change.
  • oldFormat - the date-time format of the original string. This can be set to a built-in format, HL7 (yyyy[MM[dd[HH[mm[ss[.s[s[s[s]]]]]]]]][+/-ZZZZ]) or ISO (ISO8601 format), or a custom format.
  • newFormat - the desired date-time format. This can be set to a built-in format, HL7 or ISO, or a custom format.

The following code excerpt illustrates the conversion of 2012/01/02 using a custom format to 02/01/2012:

return (dateChangeFormat('2012/01/02', 'YYYY/MM/dd', 'dd/MM/YYYY'));

Invalid formats display errors in the stack trace:

  • Current format is invalid: {0} - the old format is invalid or null.
  • Old date format does not match input string - the original date-time string does not match the old format.
  • New date format is invalid: {0} - the new format is not valid or null.
  • Date text is invalid: {0} - the original date-time string is null.

When invoked on the engine, the DateChangeFormat function converts date-time values with a time zone offset to the local engine time. The function does not print the time zone after converting it to local time when using the HL7 and ISO formats, whereas it does print the time zone when using a custom format.

JavaScript Counters

The following functions provide the ability to manage general-purpose JavaScript counters:

Function

Description

getCounter(counterName)

Retrieves the current value of the global counter with the specified name. The value is always returned as an integer, and the counter is created with an initial value of zero if it does not currently exist.

setCounter(counterName, int)

Sets the global counter with the specified name to have the value provided. If no counter with the given name exists, one will be created.

incCounter(counterName[, increment])

Increments the global counter with the specified name by the value provided and then returns the new value. This is the safest way to use counters as it will atomically retrieve the current value, increment it, set the new value, and return it. If the increment parameter is not provided then it defaults to 1.

The following example illustrates how the incCounter() method can be used to generate new globally unique IDs. The first time this script is executed, if the MyUID counter does not exist, it will be created with value 0. As this is then incremented by 1, as specified in the second argument, the counter's initial value is 1. The ID is then set as a property on the message.

Incrementing Counter 
for (var i = 0; i < input.length; i++) {
    var next = output.append(input[i]);

    // Increment global counter to get new unique ID
    var myUniqueID = incCounter("MyUID", 1);

    // Set the new ID as a property on the message
    next.setProperty("UniqueID", myUniqueID);
}

Rhapsody Variables

The following functions provide the ability to manage Rhapsody variables:

Function

Description

getVariable(variableName[, decryptVariable])

Returns the value of the Rhapsody variable with the given name. For example, getVariable("MyVar"). The optional decryptVariable parameter defaults to true, and determines if encrypted Rhapsody variables are decrypted prior to being returned. If it is set to false, then the encrypted variables are instead returned in an obfuscated form that can be used directly by a number of components. Refer to Encrypted Rhapsody Variables for details.

substituteVariables(string[, decryptVariables])

Takes a string which may include coded references to Rhapsody variables and returns a string in which the coded variable references have been substituted with the value of the referenced variables.

If the variable has not been defined then this function will remove the coded variables reference from the string.

To reference Rhapsody variables, use the following syntax: $(MyVar), where MyVar is the variable name. For example, an encoded string such as My variable value is $(MyVar) returns My variable value is 75, if the value of MyVar is 75.

The optional decryptVariables parameter defaults to true, and determines whether encrypted Rhapsody variables are decrypted prior to being returned. If it is set to false, then the encrypted variables are instead returned in an obfuscated form that can be used directly by a number of components. Refer to Encrypted Rhapsody Variables for details.

substituteExistingVariables(string[, decryptVariables])

Takes a string which may include coded references to Rhapsody variables and returns a string in which the coded variable references have been substituted with the value of the referenced variables.

If the variable has not been defined then this function will throw an exception.

To reference Rhapsody variables, use the following syntax: $(MyVar), where MyVar is the variable name. For example, an encoded string such as My variable value is $(MyVar) returns My variable value is 75, if the value of MyVar is 75.

The optional decryptVariables parameter defaults to true, and determines if encrypted Rhapsody variables are decrypted prior to being returned. If it is set to false, then the encrypted variables are instead returned in an obfuscated form that can be used directly by a number of components. Refer to Encrypted Rhapsody Variables for details.

Encrypted Rhapsody Variables

Encrypted Rhapsody variables are frequently used to store passwords for external systems. In some cases these passwords can be provided dynamically using Rhapsody message properties, thus allowing a single instance of the relevant communication point type to communicate with numerous external systems that use different credentials. However, retrieving the passwords and storing them in a message property means that they are subsequently visible in the Management Console to a user with permissions to view message properties.

In order to limit the need for storing passwords in message properties, the following Rhapsody communication points can use the password directly in its obfuscated form:

The obfuscated password form can be used by setting the decryptVariable parameter to false when retrieving the password using one of the JavaScript variable functions: getVariable, substituteVariables(), and substituteExistingVariables(). Alternatively, the Encrypt Password function in Rhapsody IDE can be used if the password is being set directly as a message property, without using a Rhapsody variable.

Base64

Function

Description

decodeBase64(base64encodedString)

decodeBase64(value[, encoding])

Decodes a Base64 value to a string:

  • value - must either be a byte array or a string. If value is not a valid base64 value, a ScriptException is raised.
  • encoding (optional) - used to perform the final byte array-to-string conversion after the base64 decoding has completed. It defaults to the default system encoding if not provided.
decodeBase64ToByteArray(value)

Decodes a Base64 value to a byte array:

  • value - must either be a byte array or a string. If value is not a valid Base64 value, a ScriptException is raised. It does not perform character encoding translations.

encodeBase64(value[, chunked[, encoding]])

Encodes a value to Base64 value:

  • value - must either be a byte array (for example, next.body) or a string.
  • chunked (optional) - determines whether the encoded Base64 value is split over multiple lines or not. If chunked is not provided or set to true or 1, the encoded string is formatted as 76 characters per line with crlf at the end of each line; if chunked is set to false or 0, the encoded string is formatted as a single line.
  • encoding (optional) - used to convert the value from a string to a byte array prior to the Base64 encode operation. The encoding is ignored if the value is a byte array already as it is not required in that case. It defaults to the default system encoding if not provided.

dataMap

dataMap functions translate a string or field using a translation table. Refer to dataMap Functions for details.

Lookup Tables

The Global Lookup functions perform lookups on specified lookup tables. Refer to Lookup Global Functions for details.