Integration Toolkit Configuration

Macros

The customer's macro definitions are kept on the Services Portal (SP), and modified via the Services Portal website. If the customer intends to send forward macros from the integration machine, copies of these macro template definitions will need to be retrieved from the Services Portal onto the customer's iSeries and then kept synchronized with any future macro template changes that might be made via the Services Portal web UI. A new callable Macro Template Refresh API (IIMACRFSH) may be used after PIT v2.2 installation or upgrade, and anytime thereafter to synchronize the macro definitions. The new version of the PIT (>= v2.2) also supports automatic synchronization which the customer may enable by subscribing to the T.2.09.0 ESS Macro Template Change Notification transaction type and then calling the IIMACRFSH API as previously described. Customers with PIT v2.2 or higher no longer need assistance from an Omnitracs engineer who utilizes the #Customer Data Export Utilityto retrieve macro definitions as described in a later section. However, customers who haven't upgraded to PIT v2.2 or higher will be required to use the export utility and Omnitracs engineer assistance to synchronize their macro definitions.

ESS Transaction Format Data

In order for the customer to use the Portal Event Subscription Service, a local copy of several Services Portal-resident ESS data files must be made on the customer's machine. This allows the Portal Integration Toolkit's ESS return transaction parser to properly convert the received XML-formatted transactions into their fixed-format equivalents. An Omnitracs engineer will be responsible for doing this. The engineer will either upgrade the customer to the latest version of the PIT or use the #Customer Data Export Utility, which is described in a later section.

A copy of these files was delivered when the Toolkit was installed. Those files represent the defined ESS transaction formats at the time the toolkit distribution was created.

NOTE: New copies of these files will need to be copied from the Services Portal to the customer's machine by an Omnitracs engineer, when changes to ESS transaction types are made that are of interest to the customer and their integration requirements. New copies are NOT necessarily required when the ESS transaction type changes are NOT relevant or of interest to the customer's integration requirements. In this case the customer may continue to use older copies of the ESS data files without any problems, other than an inability to access the latest transaction type fields or newly added transaction types.

Customer Data Export Utility

This utility handles the export of both ESS and Macro datafiles from the Portal for customer who haven't installed or upgrade to PIT v2.2 or higher. These files occasionally need to be transferred to the customer's AS/400. An Omnitracs engineer will conduct the export.

The Omnitracs engineer will follow these steps:

Sign onto the SP's iSeries machine in San Diego
Invoke program IICPYCOMAC, passing the Customer ID and target OS level as input parameters
- Target OS level added as of November 2011 SP release
IICPYCOMAC will copy the necessary ESS and macro data into a save file QTEMP/IIINTDATA
Transfer the save file to the customer's machine (via FTP or other means)
Restore components from the save file to the customer's machine.
THIS PAGE has complete, detailed information.

SSL Configuration

The Portal uses a digital certificate which helps guarantee secure connections between the Services Portal and integrators. This certificate needs to be imported into your iSeries and made available to the components of the Toolkit. An Omnitracs engineer will be responsible for doing this.

Initial Setup

Ensure a *SYSTEM store has already been created.
Using IBM Digital Certificate Manager, create a DCM Application which has access to the certificate store. Save the name of the DCM Application, it will be necessary later.
Grant iSeries users read-authority to the iSeries certificate store.

Webservice Debugging Using the Integrated File System (IFS)

The Toolkit's webservice wrappers can be configured to emit both the webservice request and response XML to files on the IFS. These files can be useful to help understand how webservices work, and to help debug them if necessary. This configuration is not required, and can be skipped if desired.

Create a path on the IFS to receive the optional log output file generated by each web service wrapper.
Grant write-authority to all necessary users (ex: QPGMR) to this path.
Store the pathname in the Toolkit configuration file (see next section).

Everyday Default Configuration Settings

The Toolkit's everyday configuration settings are kept in a data file called IICONFIGP which was delivered with the Toolkit. Minor modifications to this file are necessary. These will typically be made by an Omnitracs engineer. The fields of the IICONFIGP file are listed below.

Field Name	Data Type	Description
DFKEY	Decimal	Do not modify.
DFHOST	Character	Do not modify. Should contain "https://services.omnitracs.com"
DFPORT	Character	Do not modify. Should be left blank.
DFHTTPAPP	Character	The name of the DCM Application you chose (see "SSL Configuration" above).
DFUSER DFCOMPANY DFPWD	Character	Proxy User ID, Proxy Company ID, Proxy User Password
DFIFSPATH	Character	Webservice Debugging IFS Path (see section above). Can be left blank.
DFMTDLY	Character	The number of seconds to wait (after being told by ESS that the transaction queue is empty) before attempting another Dequeue.
DFFAILDLY	Decimal	The number of seconds to wait after a web service request failure (for an operator to correct a configuration issue) before attempting to transmit a forward message again.
DFFREQ	Decimal	Minimum number of minutes between error alert notifications. Notifications will not be sent twice within this number of minutes, even though the error condition may persist.
DFALRTUSR	Character	iSeries user identifier to notify on error. Errors will be sent via QSNDMSG.
DFTIMEOUT	Decimal	The number of seconds to wait before declaring a "timeout" condition waiting for a web service response from the server. In the case of forward messages, timeouts always result in a repeat attempt to send the message. For all other web services, timeout conditions return to the caller.
DFSUBID	Decimal	Default ESS Subscriber ID ("Reference ID") to use to Dequeue ESS transactions.
DFHIGHTXID	Decimal	Do not modify. The last ESS transaction that was acknowledged by the dequeue process.