JavaScript REST Client

The JavaScript REST Client communication point enables users to make REST calls against configured REST clients by executing a user-configured script to handle the connection and response. The connection itself is established by the Rhapsody REST client framework, and the custom JavaScript code performs the HTTP calls.

Supported Operational Modes: Output, Out->In.

Configuration Properties

Output Mode

Out->In Mode

The configuration properties for the JavaScript Rest Client communication point in Out->In mode is the same as Output mode. Refer to Out->In and In->Out Properties for general details on the Out->In mode for communication points.

When in this mode, an additional output object is available for use within JavaScript. Through the output object you can set the message body and properties based on the response received.

JavaScript REST Objects

You can utilize the following REST-specific JavaScript objects in the Request JavaScript property to configure the JavaScript REST Client communication point:

The output object (used to define the message received on a route) is only available if the communication point is in Out->In mode. The standard input object is available in Output and Out->In modes. Refer to:

• the JavaScript filter for details on the use of JavaScript within Rhapsody.
• JavaScript Object Reference for details on general JavaScript objects that Rhapsody exposes.

Client Object

The client object is used from within the script to invoke the REST request using the methods GET, POST, DELETE, and PUT. These methods take the request configuration as a parameter, perform the REST request synchronously and return a response object. The configured REST client is used to perform these operations.

Configuring the Request Options

When calling the GET, POST, DELETE or PUT methods on the client object, a request configuration is passed as a parameter. This request configuration should be created in the script defined on the JavaScript REST Client communication point.

The following options can be defined in the request configuration:

var config = {
	'accept-type': 'application/xml+fhir',
	'relative-url': '/patient/1',
	'headers': [{'header':'headerA','value':'a'}, {'header':'headerB','value':'b'}],
	'parameters': [{'parameter':'a','value':'a'}],
	'content-type': 'application/xml',
    'remove-headers': ['header1', 'header2']
};
var response = client.get(config);

var config = {
	'relative-url': '/patient/2',
	'headers': [{'header':'headerA','value':'a'}, {'header':'headerB','value':'b'}],
	'parameters': [{'parameter':'a','value':'a'}],
	'content-type': 'application/xml'
};
var messageBody = input.text;
var response = client.post(config, messageBody);

Default Response Handling

The default response handling options are configured on the REST client. Using the REST client response actions, the JavaScript REST Client communication point can be configured to throw a connection or message error based on the status code response to a REST request. For example, when the selected REST client has On 4xx action configured as Treat as message error, and has a status code response of 404 is received the communication point will stop executing the configured JavaScript at the point the request was made, and move the message to the Error Queue. If instead the response action On 4xx action is configured as Treat as connection error, then a connection error is raised and the communication point attempts to reprocess the message through the configured JavaScript up to the number of allowed connection retries configured on the communication point.

The default response action handling can be disabled from the JavaScript REST Client communication point by setting the enable-response-handling request option to false.

If you configure the JavaScript on the communication point to make multiple REST requests within a single JavaScript REST client, the requests are not atomic. For example, if a connection error is raised when the second REST request is performed, the first REST request is not rolled back and will be re-invoked as the communication point re-attempts to process the message at the beginning of the configured JavaScript on the next connection attempt.

Custom Response Handling

The JavaScript REST Client provides custom response handling in the request script for sending errored messages to the Error Queue or retrying connection by treating responses as a connection error.

var config = {
    'accept-type': 'application/xml+fhir',
    'relative-url': '/patient/1',
    'headers': [{'header':'headerA','value':'a'}, {'header':'headerB','value':'b'}],
    'parameters': [{'parameter':'a','value':'a'}],
    'content-type': 'application/xml',
    'remove-headers': ['header1', 'header2'],
    'enable-response-handling' : 'false'
};
var response = client.get(config);

if (response.status == 200) {
    // When response was valid but has empty body, send message to Error Queue.
    if (response.response == "") {
        throw new SendingMessageError(response, 'Patient data returned empty');
    } 
} else if (response.status >= 400) {
    throw new ConnectionError(response);
}

The response object returned from a GET, POST, PUT or DELETE method can be inspected to check the status code returned, the body of the response, and the response headers returned.

If connection fails, for example when the hostname to connect to cannot be resolved or an incorrect port number is used, then no response object is returned. Instead, an exception is thrown and the message placed on the Error Queue.

Output Data Encoding

As of Rhapsody 6.3, the encoding of the output data for PUT and POST methods is determined as follows:

• If the output data is a byte array (or the optional type parameter is set to bytes), then no encoding is performed and the output data is sent as is.
• If the charset parameter is provided in the content-type header, then the encoding specified in the parameter charset is used to encode the output data.
  For example: Content-Type: application/json; charset=UTF-16.
• If the charset parameter is not provided in the content-type header, then the encoding of the output message is used to encode the output data.

In previous versions of Rhapsody, the encoding of the output data is set to the default encoding of the operating system the engine is running on (for example, the default Windows®  encoding).