MAPRMTPROC

General information

The Mapping Workflow is the new rule-based system available for Mapping on both Onyx Server and Mapping UNIX 7.0.36. In terms of features and performance, the Mapping Workflow is far more powerful than the IBM i Mapping Robot.

The program is Apache 2.2 compatible and Apache 2.4 compatible since Opale 10.3.0

An IBM-i workflow connector has therefore been developped in a way to take advantage of Mapping Workflows on IBM-i documents. To do so, we use the mapsoapserver connected to the Onyx Workflow in addition to the MAPRMTPROC command on the client side (IBM-i). Therefore, Mapping has to be installed on both sides.

When the IBM i spooled files are sent to the Mapping server, a Workflow rule runs a series of commands and generates the resulting output. this output can then be sent back to the IBM i with log messages if deemed necessary.

Requirements

Check that network communication between the IBM i and the remote Mapping server on which the Workflow runs, can be established using the HTTP protocole - check the IP adresses, firewall, antivirus software etc.

The MapSOAPServer has to be properly configured. You can find the detailed configuration parameters of the MapSOAPServer in the Mapping Web Services section of this wiki.

Useful Workflow commands

Convert from iSeries

The “Convert from iSeries” command (in the Mapping group) allows you to convert any EBCDIC spooled file to Unicode. This box is often used in the case we receive a spooled file from the IBM-i server to convert the EBCDIC stream to Unicode ASCII.

(For more information on this, see "WorkFlow_ConvertFromISeries.pdf")

iSeries Response

The « iSeries Response » command (in the Web Interactivity group) allows you to send a response to the iSeries command. This response can be a file (*USERASCII or *AFPDS) or a message (JOBLOG input or update of a DTAARA). A video is available for more information.

Since version ONYX 10.5.1, it is possible to set the USRDFNDTA of the spooled created in response to the iSeries Response workflow box. (Either with a fixed value or using the same value as the one from the sent spooled file using the parameter HTTP_ISERIES_USER_DFN_DATA.)

Response received from the command

The type of response depends on the parameters set in the workflow. The response can be :

• A spooled file (*USERASCII or *AFPDS)
• A message in the current JOBLOG (*INFO or *MESSAGE)
• Data in the DTAARA MAPRMTPROC in QTEMP

For more information, please refer to the training video.

MAPRMTPROC

This IBM i command allows you to send an IBM i spooled file to the rule-based system (Workflow) of the M-Processing Server.

Parameters of the MAPRMTPROC command on IBM i

Spooled File	Name of the spooled file (SPLF)	Alpha
Spooled File Number	Number of the spooled file (SPLNUM)	Alpha
Job Name	Name of the job (JOB)	Alpha
Job number	Number of the job	Num.
User	User name	Alpha
Login	Mapping Workflow user	Alpha
Password	Mapping Workflow password	Alpha
Remote Server	Mapping Workflow IP address	Alpha
Move to Queue	Destination OUTQ of the input file. Leave a blank if N/A	Alpha
Library	Library of the destination OUTQ	Alpha
Delete File	Delete input file. Y(O) or N	Alpha
Workflow Name	Name of the workflow rule to run (leave a blank if it is workflow root)	Alpha
Protocol	Type of connection protocole: http or https	Alpha
Remote Port	Connection port of the Mapping Workflow	Num.
Remote Backup Server	IP address of the back-up Mapping Workflow	Alpha
Remote Backup Port	Connection port for the back-up Mapping Workflow	Alpha
Advanced Parameter	HTTP command for a specific treatment	Alpha
Timeout	Connection timeout in seconds	Num.

Workflow input parameters

The following spooled file parameters are sent with the spooled file and are visible in the Workflow.

• HTTP_HOST= IP address of the host

• HTTP_ISERIES_CONTENT= type of data sent (spool_data)

• HTTP_ISERIES_JOB_NAME= job name

• HTTP_ISERIES_USR_NAME= user name

• HTTP_ISERIES_JOB_NUMBER= job number

• HTTP_ISERIES_SPLF_NAME= name of the spooled file

• HTTP_ISERIES_FORM_TYPE= form type

• HTTP_ISERIES_USR_DATA= user data

• HTTP_ISERIES_OUTQ_NAME= outq of the input file

• HTTP_ISERIES_OUTQ_LIB= outq library

• HTTP_ISERIES_PGM_NAME= name of the program which opened the file

• HTTP_ISERIES_PGM_LIB= program library

• HTTP_ISERIES_COUNT_CODE= count code

• HTTP_ISERIES_USER_TEXT= specific user data

• HTTP_ISERIES_PRINTER_DEVICE_TYPE= type of printer device

• HTTP_ISERIES_SPLF_NUMBER= spooled file number

• HTTP_ISERIES_PAGE_LENGTH= page length

• HTTP_ISERIES_PAGE_WIDTH= page width

• HTTP_ISERIES_CCSID= CCSID

• HTTP_ISERIES_TOTAL_COPIES= total copies number

• HTTP_ISERIES_LINES_PER_INCH= lines per inch

• HTTP_ISERIES_CHAR_PER_INCH= characters per inch

• HTTP_ISERIES_OUTPUT_PRIORITY= output priority

• HTTP_ISERIES_DEV_FILE_NAME= device file name

• HTTP_ISERIES_DEV_FILE_LIB= device file library

• HTTP_ISERIES_TIME_FILE_OPEN= how much time the file was open for

• HTTP_ISERIES_DATE_FILE_OPEN= date when the file was opened

• HTTP_ISERIES_PRINT_TEXT= Print text

• HTTP_ISERIES_SOURCE_DRAWER= source drawer

• HTTP_ISERIES_OUTPUT_BIN= output bin

• HTTP_ISERIES_JOB_SYSTEM_NAME= system name of the job

• HTTP_ISERIES_USER_DFN_DATA= User defined Data attribute (Since Version OPALE 10.5.1)

Passing some custom parameters

Beside the HTTP_XXX parameters sent, it is also possible to send some others. To do so, we will use the "custom parameter" of the MAPRMTPROC command using the following syntax : &key=MYPARAM&value=MYVALUEPARAM (Please not the key and value in lowercase)

Example

Let's take in example the need to send the PARAM1 attribute to Onyx. Here is the command to put in the MAPPING IBM-i Robot action :

MAPRMTPROC SPLF(&SPLF) SPLNUM(&SPLNUM) JOB(&JOB) JOBNUM(&JOBNUM) USER(&USER) LOGIN(mapadmin) PASSWD(mapadmin) SERVER('192.168.217.32') 
WORKFLOW(MAPRMTPROC) ADVANCEPAR('&key=PARAM1&value=VALUEPARAM1')

Onyx will receive, on the top of all the HTTP_XXXX parameters, the parameter VALUEPARAM1 with the value of the attribute VALUEPARAM1 of the sent spooled file.

Remarks : Please note that the case of &key and &value is important (must be in lowercase) and also note the &TRIM tag right triming the value of the &USRDFNDTA attribute. If this &TRIM tag is not used, the value will not be trimed, therefore the length of the value will depend on the passed value. (example : the &USRDFNDTA would be of 35 characters, and the MAPRMTPROC command would fail)

Examples

Sending a spooled file to ONYX Server

The goal is to send a spooled file which contains the following information to the MAPRMTPROC.rules.xml workflow of the ONYX Server:

Spooled file . . . . . . . . . . >          OLP

Spooled file number  . . . . . . >    237

Job Name . . . . . . . . . . . . >          QPRTJOB

Job number . . . . . . . . . . . >         109341

User . . . . . . . . . . . . . . >               QTMPLPD

What you will need to do:

1. Create a workflow on ONYX: called MAPRMTPROC here
2. Note: You do not need to create an entry point
3. Run command MAPRMTPROC on the IBM i:

a)     Specify the attributes of the spooled file to send

b)   Login and password for the webservice (Apache)

c)    Remote Server: the address of the Onyx Server

d)   Move to Queue: Use this if you would like to save the spooled file in an outqueue, if not, you can skip this step

e)    Workflow name: Name of the workflow to run on Onyx Server (if the workflow is empty then the workflow root.rules.xml will be used)

f)     Potential connection timeout

Because the transfer is done via web service, do not expect to find a spooled file in the spooler. The file simply goes in the workflow. To retrieve it, you can use a une copying box for instance. To get the retrieved variables, you can use a set which redirects to a file.

Sending a file generated by the workflow back to an IBM i outq

The goal is to send a file from the workflow back to the IBM i.

The workflow shown below, receives a spooled file from the IBM i, converts it to Unicode and sends the unicode file back to the IBM i via the "iSeries Response" box.

A closer look at the "iSeries Response" box:

Result in the IBM i (in the JDIEU_OUTQ Outq):

Note:

You could also send an XPS file back to the IBM i to print it via the IBM i Outq (rather than through the ONYX Server spooler), using the same principles.

• The USRDFNDTA is coded in two different possible ways :
  • In the case we retrieve the USRDFNDTA from the spooled file sent (HTTP_ISERIES_USER_DFN_DATA), we keep the same encoding as the original spooled file.
  • If the value is hardcoded, then we encode the USRDFNDTA in 037 (no changeable)

Connection problem

In case of connection problem between OPALE and ONYX, the MAPRMTPROC job will continue to send the spooled file until a connection timeout is reached (if a timeout is declared).

If you ran several MAPRMTPROC commands during that time, they will be declared as "processing" on the server until the connection is established, or until the timeout is reached.