Replacing QIE Web Service¶

QIE Web Service (Deprecated) is a legacy protocol for sending messages from one QIE to another over SOAP. It will be removed in a future release of QIE. Its replacement is a REST Web Service (Encoded Content) connection on the sending side and an HTTP Listener source on the receiving side.

At startup, QIE checks every zone for QIE Web Service connections and for channels whose source is the QIE Web Service receiver. When it finds any, it raises an administrator alert that lists them by zone and name, and it emails that alert to administrators. The alert clears at the next restart once none remain.

What Each Part Becomes¶

QIE Web Service	Replacement
A QIE Web Service (Deprecated) web service connection	A REST Web Service (Encoded Content) web service connection whose endpoint is the receiving channel's HTTP Listener
A Web Service destination that uses that connection	The same destination, switched to the REST connection, sending the message as its content
A Web Service mapping function that uses that connection	The same mapping function, switched to the REST connection
A script that calls `qie.callWebService()`	A call to `qie.callRESTWebService()`
A channel whose source is Web Service (the QIE Web Service receiver)	The same channel with an HTTP Listener source
Named parameters sent with each message	HTTP headers named `http.header.<name>`, read on the receiving side at `/Request/Headers/<name>`

Replace the receiving channel first. The sending side needs the receiver's new endpoint.

Replacing the Receiving Channel¶

Open the channel and change its source to HTTP Listener (see HTTP Listener for every setting).

Set the Port to a port that is open on the QIE server. The Endpoint field then shows the URL that senders call. Write it down for the sending side.

Keep the same Response option the old source used. The HTTP Listener offers the same three choices: No Response or Acknowledgement, From Acknowledgement Script and From Mapping or Destination node. The Response Script, Timeout and Timeout Script settings work the same way. A preprocessing script moves across unchanged under Preprocess Received Bytes.

Decide how the channel reads the request:

The sender sends no parameters: select Extract Content As Message. The message is the request body, exactly as the old source delivered it, so existing mappings keep working.
The sender sends parameters: leave Extract Content As Message unchecked. The message is then the request wrapped in a /Request envelope. The body is at /Request/Part/Content and each parameter is a header at /Request/Headers/<name>. See Message Content for the full envelope.

The old source copied parameters into the message cache of the Response Script and the Timeout Script only, so mappings and destinations never saw them. With the HTTP Listener, any script or node path reads a parameter from its header:

var facility = source.getNode('/Request/Headers/facility');

Update a Response Script or Timeout Script that read messageCache.getValue('facility') to read the header instead.

The HTTP Listener can also set the HTTP status code and response headers, which the old source could not. See Response Body Format.

Note

A channel whose source is Web Service only starts when the hidden qie.enableQIEWs Java option is set. Once every such channel uses an HTTP Listener, remove the option.

Replacing the Sending Side¶

Connection¶

Create a web service connection with the type REST Web Service (Encoded Content). Select Manually set the endpoint URL and enter the HTTP Listener endpoint from the receiving channel. Configure SSL and authentication if the HTTP Listener requires them, which the QIE Web Service type never supported (see SSL and Authentication Protocol).

Keep the old connection until every destination, mapping function and script has moved to the new one. Then delete it.

Destination¶

Open each Web Service destination that used the old connection and select the new connection. Set the Method to POST and the Content Type to the type of message the channel sends (e.g. text/plain for HL7).

The old destination sent the current message. Enter {m:/} in the Text, XML or JSON field to send the same thing (see Root Node Path).

Move each parameter the old destination sent to a row in the HTTP Headers dialog. Prefix the name with http.header. and keep the same Source and Value (see HTTP Headers button). For example, a parameter named facility read from the message cache becomes:

Name	Source	Value
`http.header.facility`	Message Cache	`facility`

A REST call with content sends only headers that use the http.header. prefix. Any other parameter name is dropped without an error.

Mapping Function¶

Open each Web Service mapping function that used the old connection and select the new connection. Send the message as the content and move each parameter to an http.header. entry, as for the destination.

Scripts¶

Replace each qie.callWebService() call with qie.callRESTWebService(). Pass the message as the content and put each parameter in the map with the http.header. prefix:

// before
var params = qie.newParameterMap();
params.put('facility', 'MAIN');
var response = qie.callWebService('Orders to Lab', 'Submit Message', params);

// after
var headers = qie.newParameterMap();
headers.put('http.header.facility', 'MAIN');
var response = qie.callRESTWebService('Orders to Lab REST', null, 'POST', message.getNode('/'), 'text/plain', headers, 60000);

See qie.callRESTWebService for every argument.

Checking the Result¶

Send a test message through each sending channel and confirm the receiving channel processes it. If the receiver posts a response, confirm the sender receives the same response it did before.

Restart QIE once the old connections and channels are gone. The administrator alert no longer appears.