User Guide

Overview

Web Transaction Framework (webTF) is a lightweight IBM i (AS400, iSeries) component that simplifies the implementation of outbound (IBM i -> External API) integrations for companies that implement Mulesoft, Confluent, or similar integration platforms.

Sample Use Cases

Below are some examples where real time outbound API calls deliver better customer experiences or improve the process quality and operational efficiency:

Request shipping quote and delivery date from multiple third party logistics providers
Run a real time credit application check, getting back FICO score and other credit rating and decision details directly into IBM i application
Check if customer already exists in Customer Data Platform or CRM, before creating the customer in the back-end application to avoid duplicates
Call an external Tax calculation service for the orders entered directly into the back-end system

Product Features

Automatically manages low level communications with Mulesoft or similar platforms with no API or Data Queue development required
Simple extensible developer friendly framework built with native IBM i stack
Easy configuration and management of all outbound API integrations within the product UI
Transaction tracking and exception logging details can be streamed into log aggregation, alerting and monitoring platforms such as Splunk or Elastic stack
Offered as free add-on to any other Infoview product

How does it work?

All interaction with the external APIs is offloaded from IBM i to Mulesoft or similar integration platform. The product communicates with the integration platforms via pair of data queues (request and response). WebTF places a new transaction / message into request DQ then waits for the reply to response DQ with the same transaction ID. The tool has a basic timeout and retry functionality. The IBM i developer only needs to configure the integration (referred to as "Transaction Type") then call standard webTF program CRTTRN or PRCTRN to create and process (send / receive) the transaction via DQs

IBM i requirements and considerations

Minimal supported OS release level is 7.1
Even though the product is a free add-on, it does require valid license to operate. Please contact Infoview Sales team at sales@infoviewsystems.com to obtain the license key

Installation Instructions

Transfer the SAVF with the product to your IBM i
Restore the product library WTF400 into your system. Infoview Customer Success team will build a save file already packaged with the license key for your serial numbers.

Product Configuration

Set up new transaction type (outbound integration)
```
ADDLIBLE WTF400
CALL EDTTYPES
```
Use F6 to create new type, or use option 2 to edit the existing type

Transaction Type: Give it a unique name, such as TimeCharges Transaction Category: Any string, just for documentation Description: Free form field Process Program PRCTRNDQ data queue processing program Request Data Queue Specify the name of the Request Data Queue Response Data Queue Response DQ name Log Level Not used, just type in something like WARNING Sync (Y/N) Not used, set to Y Time out Number of seconds to wait till the entry is picked up by middleware No of Retries Number of retries if the client didn't pickup or there's no response Auto process on Create If the transaction data can be fit into 255 string, then no need to stage the data in the file and it should be set to Y to release the transaction right when it's created.

If the transaction data must be staged, then set this flag to N - it will just create the new transaction record but will not process it right away. The client program can then stage the transaction data in custom files, typically using the transaction ID as a key, then call another WebTF program PRCTRN to trigger the transaction processing (for example sending the DQ entry for middleware to pick up).
Next, create the pair of data queues in the application library that is already in the application library list. Generally it's not recommended to create one in WTF400 in case it must be re-installed.
```
CRTDTAQ DTAQ(<request-queue-name>) MAXLEN(255) FORCE(*YES) SEQ(*KEYED) KEYLEN(20) SIZE(*MAX2GB) TEXT('Request data queue')
```
Only change the request queue name and library, and optionally DQ text. The rest of the parameters must be specified exactly as above.

Repeat the same steps for Response DQ.
Optionally, for larger files, create staging table(s)

This step is specific to each application and the structure of the staging tables will vary. Typically the staging table would include the transaction ID as a key - this is how the Mule middleware would pull the correct data from sting table(s)

At this point, webTF integration should be ready for use in the integration programs

Using webTF in the program

Generally the Web TF supports two modes:

Simple transaction - where the message sent to Middleware can fit into 255 characters. In this case, the application program will use WebTF program CRTTRN to create and process the transaction
Transaction with data staging - the transaction process is split into the following steps:
- Call CRTTRN to create new transaction (but do not send the entry into Data Queue yet)
- Using the transaction ID generated by CRTTRN as a key, add one or more records to staging file(s) - staging files ? key only?
- Once the transaction data is in the staging files, call PRCTRN which will generate new DQ entry in the request data queue and wait for response. aany parms for either of these calls.

Detailed Processing Flow

Caller program: calls CRTTRN program to generate new transaction ID
webTF: generates new transaction ID and writes new entry into TRNHDR table
Caller program: optionally, if the transaction data must be saved into a table then retrieved by the middleware as it doesn't fit into DQ entrystages the request data into a custom table, using transaction ID as a key
Caller Program: optionally, for staged transactions, calls PRCTRN, passing the transaction ID as parm
webTF: places new entry into Request data queue, using transaction ID as DQ key and the data passed by the caller program
webTF: wait for the response DQ entry with the same key = transaction ID
Middleware: picks up the message from the queue
Middleware: processes the request - for example calls the external API, generates the Word Doc etc
Middleware: places the entry into response data queue, again using transaction ID from the request entry as a key and response data (if necessary) in the DQ body
webTF: upon receipt of the confirmation message, update transaction status in TRNHDR and return the control back to the application
- webTF supports time outs and retries - for example will retry up to 2 times with 10 sec wait time each
- if no response is received within defined time out and retry, or the entry hasn't been picked up by the middleware, webTF changes the transaction status to PRCFAILED in TRNHDR, removes the transaction from the data queue, and returns the error back to the caller

CRTTRN and PRCTRN definitions

CRTTRN call prototype:

    d crttrn          pr                  extpgm('CRTTRN')                 
    d  transType                    10    const options(*nopass)           
    d  altTrnID                     30    const options(*nopass)           
    d  reqData                     254a   const options(*nopass)           
    d  transID                      20i 0       options(*nopass)           
    d  returnCd                      3s 0       options(*nopass)           
    d  returnMsg                   254          options(*nopass)

PRCTRN call prototype:

    d prctrn          pr                  extpgm('PRCTRN')           
    d  transID                      20i 0 const options(*nopass)     
    d  transType                    10    const options(*nopass)     
    d  reqData                     254a   const options(*nopass)     
    d  returnCd                      3s 0       options(*nopass)     
    d  returnMsg                   254          options(*nopass)