Integration Toolkit Forward Messaging

Last updated
Save as PDF

Introduction

Forward messages (messages that are directed TO vehicles) may not be immediately transmitted across the web service to the server. At first glance, this may seem like a drawback, however we will attempt to show that it is not.

A forward message queueing mechanism has been put into place within the Services Portal Integration Toolkit. Omnitracs recommends that this mechanism be used when integrating with the Services Portal.

Overview

Quite simply, when forward messages are "sent", they are put into a temporary queue on the customer's machine. A batch process is then responsible for emptying the queue and sending the messages across the web service. The following diagram describes the basic structure:

Details

Following the red numbered circles, the logic is explained below:

(1) When wishing to send a forward text or macro message, the customer integration code will call an Integration Toolkit API named Send Text Message (Queued).

(2) The API will then format an entry and place it into a forward message queue. The API will then return control immediately to the customer integration code. At that time, the API will also return a temporary "ticket" to the integration code, a voucher ... our official name for this is Service Request Handle (SRH). The SRH says "here's your ticket; when I've sent your message, I'll let you know via the number on your ticket."

(3) An autostart batch job, always running, will continually try to empty the forward message queue. This program name is IIFWDPROC. As soon as IIFWDPROC pulls an entry off the forward message queue and processes the entry, it is removed permanently from the forward message queue.

(4) If an entry is invalid or contains any errors, it is removed from the forward message queue, written to an error file (IIFWDERRQ), and a custom callback stub is called (see (7)). The custom stub, named IIFWDCUST, will be given the SRH of the original message, and a reason code explaining why it failed. The integrator may then choose to modify IIFWDCUST to take the SRH and use it to look inside the error file for more information. It is the responsibility of the customer integrator to empty the error file.

(5) For entries that do not contain errors, the forward message process will invoke the Send Text Message (Non-Queued) web service wrapper. The wrapper then:

Formats the proper XML request
Opens the socket
Converts the macro message body to XML, if applicable
Submits the request over the internet to the Services Portal (see (6))
Receives the response from the server
Parses the XML response, and
Gives the status of the call back to the forward message process.

(7) Whether the message was successful (ie: a Global Message Handle was generated on the server), or not (ex: the server found errors in the request), the response is conveyed by calling the custom callback stub IIFWDCUST (if the stub program was created in the site library).

For successful forward messages, the call will contain the original SRH as well as the generated GMH. The custom integration code should then discard the SRH and refer to the GMH for the remainder of the lifetime of the message.

For failed forward messages, the call will contain the original SRH as well as an error code signalling what went wrong. The entry is also written to the error file. The custom integration code can then use the SRH to reference the entry in the error file, to futher handle the problem.

Using the Forward Callback Stub

The delivered stub (IIFWDCUST) is intended to be modified for integrators to suit the customer's needs of a queued forward message.
Once the manual modification(s) to the source member of IIFWDCUST is completed, the IIFWDCUST module and program must be created in the customer's site-specific library. It can then be successfully called by the Forward Message Processor.

The following is an example of the CRTPGM command needed:
CRTPGM PGM(CustomerSiteSpecificLibrary/IIFWDCUST) ACTGRP(IIACTGRP)

Advantages of the Queued Messaging Design

The forward message queueing mechanism is a better than the alternative to calling the Send Text Message web service wrapper directly from the customer's integration code for several reasons:

Callers benefit from error-handling retry logic
One hidden benefit not explained above is the retry-mechanism in place within IIFWDPROC. If there are network problems, if there are server/port/credential problems, the forward message process will alert QSYSOPR, and will then attempt to retry the same message again shortly. Problems such as these have nothing to do with the forward message content itself, and do not signify a problem with the integration code. Additionally, if one web service cannot communicate because of network issues, then none of them will be able to communicate. Therefore a retry mechanism has been developed. The alternative approach does not employ such a mechanism.

Callers are shielded from network interruptions
As mentioned above, network outages and improper network configuration need not worry the callers, because the queueing mechanism handles these conditions within.

Callers see performance optimization via supporting a non-blocking interface
Because the call does not block, does not wait for the server to reply, the caller can continue processing without having to design for a lengthy wait. Screen response time or customer application remains unaffected, minimizing resulting lags or delays experienced by the caller.

Controlling the Forward Message Process

During the installation process, a job description (in the specified site library) and an autostart job entry (for the specified subsystem) for IIFWDPROC may have optionally been created by the engineer installing the Integration Toolkit. If so, when starting the subsystem, the IIFWDPROC will be started.

If the need should arise for a manual start of the forward message process, the SBMFWDPROC command can be issued.

To end the forward message process gracefully, issue the IIENDFPROC command.

Alternative to the Queued Messaging Approach

Integrators have a choice whether the forward message is transmitted immediately across the web service. The integrator can choose to invoke the "Send Text Message" web service wrapper QTSNDMSG directly or even use it in conjunction with the queued messaging approach:

The call will block until the server replies (could be several minutes or longer!)
The caller will be told of failure conditions such as socket timeout, invalid port, etc

However:

The caller need not worry about a SRH, or how to map an SRH to a GMH
The integrator need not customize a stub program, such as IIFWDCUST