OPALE - 10.0 - Utilisation - MAPRMTPROC/en

Différence entre versions

De MappingDoc
(Page créée avec « 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. »)
 
(57 révisions intermédiaires par 3 utilisateurs non affichées)
Ligne 1 : Ligne 1 :
 +
<languages />
 
==General information==
 
==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 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.
  
We have developed an IBM i Workflow connector to allow you to benefit from the features of the Mapping Workflow, on documents supported by IBM i. This is how the connector works: we use the MapSOAPServer connected to the Workflow on the host part (UNIX or Windows) as well as command MAPRMTPROC on the client part (IBM i). Mapping thus needs to be installed on both sides.
+
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.
 
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.
Ligne 16 : Ligne 19 :
  
 
===Convert from iSeries===
 
===Convert from iSeries===
The “Convert from iSeries” command (in the Mapping group) allows you to convert any EBCDIC spooled file to Unicode.  
+
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")
 
(For more information on this, see "WorkFlow_ConvertFromISeries.pdf")
  
 
===iSeries Response===
 
===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).  
+
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.)
 +
 
 +
 
 +
<u>Response received from the command</u>
 +
 
 +
The type of response depends on the parameters set in the workflow.
 +
The response can be :
  
(For more information on this, see "WorkFlow_ISeriesResponse.pdf")
+
*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==
 
==MAPRMTPROC==
This IBM i command allows you to send a IBM i spooled file to the rule-based system (Workflow) of the M-Processing Server.
+
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===
 
===Parameters of the MAPRMTPROC command on IBM i===
Ligne 76 : Ligne 94 :
 
|-
 
|-
 
|Workflow Name
 
|Workflow Name
|Name of the workflow rule to run (leave a blank in case of workflow root)
+
|Name of the workflow rule to run (leave a blank if it is workflow root)
  
 
|Alpha
 
|Alpha
Ligne 158 : Ligne 176 :
 
• HTTP_ISERIES_DEV_FILE_LIB= device file library
 
• HTTP_ISERIES_DEV_FILE_LIB= device file library
  
• HTTP_ISERIES_TIME_FILE_OPEN= how much time it took to open the file
+
• 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_DATE_FILE_OPEN= date when the file was opened
Ligne 168 : Ligne 186 :
 
• HTTP_ISERIES_OUTPUT_BIN= output bin
 
• HTTP_ISERIES_OUTPUT_BIN= output bin
  
• HTTP_ISERIES_JOB_SYSTEM_NAME= system name of the job  
+
• HTTP_ISERIES_JOB_SYSTEM_NAME= system name of the job
 +
 
 +
• HTTP_ISERIES_USER_DFN_DATA= User defined Data attribute <b>(Since Version OPALE 10.5.1)</b>
 +
 
 +
===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 :
  
===Responses received by the MAPRMTPROC command===
+
MAPRMTPROC SPLF(&SPLF) SPLNUM(&SPLNUM) JOB(&JOB) JOBNUM(&JOBNUM) USER(&USER) LOGIN(mapadmin) PASSWD(mapadmin) SERVER('192.168.217.32')
The type of response depends on the parameters configured in the workflow. The response may be:
+
WORKFLOW(MAPRMTPROC) '''ADVANCEPAR('&key=PARAM1&value=VALUEPARAM1')'''
  
*A spooled file (*USERASCII or *AFPDS)
+
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.
*A message in the current JOBLOG (*INFO or *MESSAGE)
+
 
*Data in the MAPRMTPROC DTAARA in QTEMP
+
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==
 
==Examples==
Ligne 209 : Ligne 237 :
 
c)    Remote Server: the address of the Onyx Server
 
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, this step is not mandatory
+
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)
 
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)
Ligne 216 : Ligne 244 :
  
 
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.
 
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.
 
The retrieved variables are listed below:
 
 
*CONTENT_TYPE=text/plain
 
*CONTENT_LENGTH=16324
 
*HTTP_HOST=192.168.217.16
 
*HTTP_ACCEPT_ENCODING=gzip
 
*HTTP_ISERIES_CONTENT=spool_data
 
*HTTP_ISERIES_JOB_NAME=QPRTJOB
 
*HTTP_ISERIES_USR_NAME=QTMPLPD
 
*HTTP_ISERIES_JOB_NUMBER=109341
 
*HTTP_ISERIES_SPLF_NAME=OLP
 
*HTTP_ISERIES_FORM_TYPE=SJJI
 
*HTTP_ISERIES_USR_DATA=OWABSOC022
 
*HTTP_ISERIES_OUTQ_NAME=FMERCIER
 
*HTTP_ISERIES_OUTQ_LIB=QGPL
 
*HTTP_ISERIES_PGM_NAME=OWABSOC022
 
*HTTP_ISERIES_PGM_LIB=DIPOBJ
 
*HTTP_ISERIES_COUNT_CODE=
 
*HTTP_ISERIES_USER_TEXT=
 
*HTTP_ISERIES_PRINTER_DEVICE_TYPE=*SCS
 
*HTTP_ISERIES_SPLF_NUMBER=237
 
*HTTP_ISERIES_PAGE_LENGTH=48
 
*HTTP_ISERIES_PAGE_WIDTH=136
 
*HTTP_ISERIES_CCSID=1027
 
*HTTP_ISERIES_TOTAL_COPIES=1
 
*HTTP_ISERIES_LINES_PER_INCH=6,00
 
*HTTP_ISERIES_CHAR_PER_INCH=10,00
 
*HTTP_ISERIES_OUTPUT_PRIORITY=
 
*HTTP_ISERIES_DEV_FILE_NAME=QPRINT
 
*HTTP_ISERIES_DEV_FILE_LIB=QGPL
 
*HTTP_ISERIES_TIME_FILE_OPEN=111007
 
*HTTP_ISERIES_DATE_FILE_OPEN=1140425
 
*HTTP_ISERIES_PRINT_TEXT=
 
*HTTP_ISERIES_SOURCE_DRAWER=1
 
*HTTP_ISERIES_OUTPUT_BIN=0
 
*HTTP_ISERIES_JOB_SYSTEM_NAME=S65C7FEE 
 
 
 
Toutes ces variables peuvent être utilisées dans le workflow (pour des conditions, nommage, ou autres).
 
  
 
===Sending a file generated by the workflow back to an IBM i outq===
 
===Sending a file generated by the workflow back to an IBM i outq===
Ligne 265 : Ligne 253 :
 
[[Fichier:3A.png|centré|alt=|sans_cadre|360x360px]]
 
[[Fichier:3A.png|centré|alt=|sans_cadre|360x360px]]
  
Détail de la boite « iSeries Response » :
+
A closer look at the "iSeries Response" box:
  
 
[[Fichier:4A.png|centré|1076x1076px|alt=|sans_cadre]]
 
[[Fichier:4A.png|centré|1076x1076px|alt=|sans_cadre]]
  
Résultat sur l’iSeries (dans l’Outq FMERCIER) :
+
 
 +
Result in the IBM i (in the JDIEU_OUTQ Outq):
  
 
[[Fichier:5A.png|centré|1054x1054px|alt=|sans_cadre]]
 
[[Fichier:5A.png|centré|1054x1054px|alt=|sans_cadre]]
Ligne 275 : Ligne 264 :
  
  
Remarque :
+
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.
  
On pourrait de la même façon renvoyer un fichier XPS vers l’iSeries afin de l’imprimer à travers l’OutQ de l’AS/400 et non du spooler ONYX Server.
+
*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)
  
==En cas de problème de connexion==
+
==Connection problem==
  
En cas de problème de connexion entre OPALE et ONYX , le job MAPRMTPROC va continuer à envoyer le spool jusqu’à ce que le timeout de connexion soit atteint (si un timeout est indiqué).
+
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).
  
Si pendant ce temps plusieurs MAPRMTPROC sont réalisés, ils seront tous en "processing" sur le serveur jusqu’à ce que la connexion soit établie ou alors jusqu’à ce que le timeout soit atteint.
+
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.
 
<!-- Envoi spool AS400 // Migration AS400 Windows -->
 
<!-- Envoi spool AS400 // Migration AS400 Windows -->

Version actuelle datée du 10 janvier 2022 à 09:15

Autres langues :
English • ‎français

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.