Workflows-Guide avancé/en

<languages/>

==Valorization of input fields==


In all types of Workflow objects, fields or input zones are used, whether to define a condition, a command or parameters. The fields can be the operands of a condition, the execution parameters of a command or the names and values assigned to a parameter.


Two families of fields can appear in Workflows: free text boxes and drop-down lists. Text fields accept free entry while drop-down lists are limited to a selection of values (yes/no, file type, etc.).

Input fields have a default type that can be changed as needed using the right mouse button (context menu). Depending on the type of field chosen, entry aids are offered to correctly structure the field value.

[[Fichier:OX S WRKFL Saisie.png|centré|sans_cadre|800x800px]]



===Functions on fields===


Functions are available on fields (text or list type) to retrieve values automatically.
Field functions allow you to define the value of the fields of a command, a condition or a parameter using variables, the content of a file or the result of commands.


Some fields are predefined with a function such as the list of users, the list of M-Designer formats, etc. while others are not.
To call a function, right-click on a field and choose the desired function from the context menu:

[[Fichier:OX S wrkfl champ.png|centré|sans_cadre|624x624px]]


Note:

To modify the value given to a field, only the first two types above (parameter and free text) can be edited directly in the input zone. For all others, you should go through the function immediately.


===Fields specific to ONYX Server===

Some fields have a particular typing and benefit from predefined input assistance. Their possible values are then limited to a list of elements defined in ONYX Server. As this typing is independent of the functions on the fields, it is therefore possible to have two possibilities for helping to fill in a field.

[[Fichier:OX S WRKFLW CHAMP.png|centré|sans_cadre|677x677px]]


===Environment Settings===


Fields of type <FONT color="blue"> Parameter </FONT> dynamically take the value of the application's environment parameters.


The parameter function allows you to use all the parameters available when executing the file:


- attributes of the file being processed: user (<FONT color="blue"> MAP_USER </FONT>), file name (<FONT color="blue"> MAP_FILE</FONT>), ..


- parameters linked to the current processing: processing input connector (<FONT color="blue"> MAP_PRINTER </FONT>, <FONT color="blue"> MAP_SOAP </FONT>, <FONT color="blue" > SCANFOLDER_NAME</FONT>...), date of submission (<FONT color="blue"> MAP_DATE</FONT>), ...

- personalized parameters: userdata, passing workflow parameters, etc.


- system environment variables: temporary directory (<FONT color="blue"> TEMP</FONT>), system name (<FONT color="blue"> COMPUTERNAME</FONT>),

- session variables:

*current box input/output files: <FONT color="blue"> MAP_FILE_IN / MAP_FILE_OUT </FONT>
*ID of the last spool inserted for the current session (execution): <FONT color="blue"> LAST_SPOOL_ID </FONT>
*date, time, current date and time, evaluated by Mapping when the variable is called (the information retrieval syntax is controlled by the corresponding Mapping environment variables): <FONT color="blue"> MAP_CURRENT_DATE / MAP_CURRENT_TIME / MAP_CURRENT_TIMESTAMP</FONT>


===“DIRECT” value===
Value type fields statically take the value entered in the field:

[[Fichier:OX S valD1.png|centré|sans_cadre|378x378px]]



But the values entered can also be dynamic using the same environment variables as previously with the particular Mapping syntax:


<FONT color="red"> [%</FONT><FONT color="blue"> PARAMETER</FONT><FONT color="red"> %]</FONT>. They are widely used for constructing full paths or file names where several parameters can be used at once:
[[Fichier:OX S ValD2.png|centré|sans_cadre|372x372px]]


For certain specific processes (sorting, splitting or merging of documents, etc.), it is finally possible to use document indexing criteria values (XPS) in a field value with the specific Mapping syntax: <FONT color="red"> [[</FONT><FONT color="blue"> CRITERIA</FONT> <FONT color="red"> ]]</FONT>. So for example, from a single XPS document, to create a PDF per output client, in the <FONT color="blue"> To PDF </FONT> Command box, we will use:

[[Fichier:OX S ValD3.png|centré|sans_cadre|628x628px|alt=]]


===RuleFile===

Fields of type <FONT color="blue"> Rulefile </FONT> take the value of information read from a file (example: the input file <FONT color="blue"> MAP_FILE_IN </FONT> or a other).
Several methods of reading the source file are proposed and detailed below.

POINT OF ATTENTION: the different methods for retrieving a value from a file are optimized by loading only a small part of the data file. This is done via the '''maxsize''' parameter. Its default value (20000) limits loading to the first 20000 bytes of the file. Thus, if the desired value is further away, it will be impossible to reach it without modifying the value of this parameter. It is indeed a number of bytes and not characters. Also, for a UCS or UTF-16 file, it will be appropriate to multiply this value by 2 in relation to the number of characters that must actually be loaded. 


====Keyword: Search by keyword====
Reading is done in text mode and the value retrieved from the source file is identified by searching for a keyword:

[[Fichier:OX S motclé.png|centré|sans_cadre|905x905px]]


- Value: Value of the keyword to search for


- Skip: Number of characters to skip after the keyword

- Len: Number of characters to return


- maxsize: Maximum buffer size for reading the source file

- charset: Code page of the source file


- trim: Deletion of any spaces at the end of the returned string (0 or 1)


- file: Source file

Noticed : 
To use the keyword search, right-click on a field and choose the '''rulefile''' function in the context menu, after clicking on the magnifying glass.



====Line: Search by position====


To search by position, simply click on the drop-down list and choose '''line'''.

[[Fichier:OX S Rulefile line.png|centré|sans_cadre|895x895px]]



Reading is done in text mode and the value retrieved from the source file is located by its position (line/column) and its length:

[[Fichier:OX S Line pos.png|centré|sans_cadre|912x912px]]




- line: Line number


- pos: Starting column number in the line

- len: Number of characters to return


- maxsize: Maximum buffer size for reading the source file

- charset: Code page of the source file

- trim: Removal of any spaces at the end of the returned string


- file: Source file



====XML: Direct reading in an XML file====
To search by position, simply click on the drop-down list and choose '''xml:'''
[[Fichier:Workflow-rulefile-xml.png|centré|vignette|300x300px]]



Reading is done in XML mode and the value retrieved from the source file is identified by the <FONT color="blue"> XPath</FONT> query provided.


- xpath: xpath query allowing you to select the desired value, with the syntax "SELECTML.... FROM ...."


- default: default value if no value is found


- maxsize: Maximum buffer size for reading the source file


- file: Source file



Examples of XML search with the following file:


[[Fichier:OX S XML.png|centré|sans_cadre|694x694px]]


- Search for the name of the page tag:
 SELECTXML @name FROM /doc/page

- Search for the value of the field named id_lang:
 SELECTXML . FROM /doc/page/field[@name=id_lang]


- Search for the value of the first SRLNBR field:
 SELECTXML . FROM /doc/page/group[@name=Items]/line[@name=item]/field[@name=SRNLBR]
 SELECTXML . FROM /doc/page/group[@name=Items]/line/field[@name=SRNLBR]
 SELECTXML . FROM /doc/page/group[@name=Items]/line/field[@title=Serial Number]


- Search for the value of the second SRLNBR field:
 SELECTXML . FROM /doc/page/group[@name=Items]/line[2]/field[@name=SRNLBR]
 SELECTXML . FROM /doc/page/group[@name=Items]/line[2]/field[@title=Serial Number]

===Command===


Command type fields take the value returned by the execution of a predefined ONYX Server command. All the predefined commands are detailed below.


Warning: not all predefined Mapping commands are likely to return a usable value in a field.



===CMD===
CMD type fields take the value returned by the execution of a user command (a script for example).



===SQL===
SQL type fields take the value returned by executing an SQL query (SELECT).



===Resolution table===
Resolve type fields take the value returned by searching in an ONYX Server Resolution table. 

Their XML files can be found in ''/rules/workflow/resolve''
===RulefileMultiple===
Fields of type <FONT color="blue"> Rulefile_multiple</FONT> allow several parameters to be defined at once, valued by information read at different locations in the same file (for example, the input file <FONT color= "blue">MAP_FILE_IN</FONT>or another). Available only in XML reading for the moment, it is an optimization of the definition of several parameters of type "rulefile", reducing to a single opening and closing of file.

[[Fichier:OX S RulefileM.png|centré|sans_cadre|644x644px]]


- (1) Selection of reading type (XML only for now)


- (2) Maximum buffer size for reading the source file


- (3) Name of the source file to read


- (4) Deleting a parameter


- (5) Added a new parameter



Then definition of n parameters, with for each:


- <FONT color="blue"> Param </FONT>: Parameter name


- <FONT color="blue"> XPath </FONT>: XPath request to read information in the source XML file


- <FONT color="blue"> Default </FONT>: Default value (optional) if the information is not found in the file



==Predefined commands==


To display the list of predefined commands, simply right-click on a field, choose "Command" from the context menu, click on the lightning bolt icon and finally choose the desired group of commands (Spooler, String, File ... )

[[Fichier:OX S Commande.png|centré|sans_cadre|931x931px]]


===Spooler command group===
[[Fichier:OX S Groupe Spooler.png|centré|sans_cadre|771x771px]]
 

====Hold a Queue====
[[Fichier:OX S suspQ.png|gauche|sans_cadre|60x60px]]


*Action: suspend a spooler queue
*Parameter: name of the M-Processing Server queue to suspend
*Return: none.


====Release a Queue====
[[Fichier:OX S librQ.png|gauche|sans_cadre]]


*Action: release a queue from the spooler
*Parameter: name of the M-Processing Server queue to release
*Return: none.



====Hold a job====
Note: action not applicable on the current job.

[[Fichier:OX S SusJob.png|gauche|sans_cadre]]

*Action: suspend a job in the ONYX Server Spooler
*Parameter: the number (ONYX Server identifier) of the job to suspend (numeric value)
*Return: none.



====Delete a job====
Note: action not applicable on the current job.
[[Fichier:OX S deleteJob.png|gauche|sans_cadre]]


*Action: delete a job in the ONYX Server Spooler
*Parameter: the number (ONYX Server identifier) of the job to delete (numeric value)
*Return: none.



====Release a job====
Note: action not applicable on the current job.
[[Fichier:OX S libJob.png |gauche|sans_cadre]]


*Action: release a job in the ONYX Server Spooler
*Parameter: the number (ONYX Server identifier) of the job to be released (numeric value)
*Return: none.



====Suspend current work====
[[Fichier:OX S susOccrtJob.png|gauche|sans_cadre]]


*Action: suspend the currently running job
*Parameter: none
*Return: none.


====Print====
[[Fichier:OX S IMPRT.png|gauche|sans_cadre|53x53px]]





Action: send a job to an ONYX Server Spooler queue


<u>Standard Parameters</u>:

- Destination queue name


- Full name of the file to send

- Title given to the job in the destination queue

- Send job in suspended state: Yes / No (default)


- Keep the job in the destination queue after processing: Yes / No (default)


- Transport attributes from the current job to the destination job: Yes (default) / No


- Add the current session parameters to the destination job: Yes (default) / No



<u>Pages Settings</u>:


- Start page (1 by default)


- End page (0 by default, meaning the end of the current job)


- Number of copies (1 by default)



<u>Security Settings</u>:


- Destination job owner (<FONT color="blue">MAP_USER</FONT> by default)


- Access rights of the destination job in the file system (777 by default, i.e. read/write for everyone)


- Accounting code (alphanumeric value)



<u>Userdata Settings</u>: ability to add up to 10 additional custom attributes


<u>Advanced settings</u>:


- Priority of output work

- Number of days of retention of output work


- Number of days before compression of output work


- Paper media type


- Loyalty


- Spool file name


Return: None. A new job is created in the destination queue and its ONYX Server ID is stored in the session variable <FONT color="blue">LAST_SPOOL_ID</FONT>



====Send to queue and return====
[[Fichier:OX S Envoyerà la file d'aatente.png|gauche|sans_cadre|alt=|73x73px]]







*Action: interrupt current processing, send the current job to another ONYX Server queue, wait for the correct one

processing the job in the destination queue and then resume current processing.


*Parameter: destination queue name
*Return: none.


====Define a job attribute====
[[Fichier:OX S Attribut Travail.png|gauche|sans_cadre]]







*Action: Set or modify the value of an attribute of a job in a spooler queue.


<U>Standard Parameters</U>:


- Unique ONYX Server identifier of the job

- ONYX Server queue name

- Attribute name


- Value given to the attribute


*Return: none.


===File command group===
[[Fichier:OX S Commande File.png|centré|sans_cadre|839x839px]]



====Rename a file====
[[Fichier:OX S renameFile.png|gauche|sans_cadre]]





*Action: rename a file


<u>Standard Settings</u>:
- Full name of the original file


- Name of the destination file (the destination directory being the current directory)

<u>Advanced Settings</u>:

- Overwrite the destination file if it already exists: Yes / No (default)

*Return: none.


====Copy/move a file====
[[Fichier:OX S deplcefile.png|gauche|sans_cadre]]





*Action: Copy a file, renaming it or not, deleting the original or not.


<u>Standard Settings</u>:


- Full name of the original path


- Full name of the destination file


<u>Advanced Settings</u>:


- Overwrite the destination file if it already exists: Yes / No (default)


- Delete the original file: Yes / No (default)

*Return: none.


====Copy to folder====

[[Fichier:OX S Copier Foldr.png|gauche|sans_cadre]]







*Action: copy a file to a destination folder, deleting the original or not.

<u>Standard Settings</u>:


- Full name of the original path


- Path of the destination folder (the file name being kept from the original)

<u>Advanced Settings</u>:


- Overwrite the destination file if it already exists: Yes / No (default)

- Delete the original file: Yes / No (default)


*Return: none.


====Secure copy====
[[Fichier:OX S SecureCopie.png|gauche|sans_cadre]]







Action: Copy a file to an SFTP server.

<u>Standard Settings</u>:


- Name of the input file.


- Server IP.

-	Port.


- Identifier.


- Password (leave empty if using a private key).


- Path on the server.


- File name on the server.


- File permissions after copying.


- Number of copy attempts before failure.


- Overwrite the destination file if it already exists: Yes / No (default)

<u>Advanced Settings</u>:


- Use a private key: Yes / No (default).


- Path to the file containing the private key.


- Private key password.


Variables: This command also stores a number of variables.

- Timestamp begin: start date of the copy.


- Timestamp end: date of end of the copy.


- Filename: name of the copied file


- File Size (local): size of the local file.


- File Size (remote): size of the file after copying.


- Return Code: return code from the SFTP server.


====Adding text to a file====

[[Fichier:OX S addtxt.png|gauche|sans_cadre]]








Action: Add text to a file.

<u>Standard Settings</u>:

- Name of the input file.

- Code page of the output file.

- File contents.


====Delete a file====
[[Fichier:OX S Deletefile.png|gauche|sans_cadre]]


*Action: delete a file
*Parameter: the full name of the file to delete
*Return: none.



====Replace a string in a file====
[[Fichier:OX S rplce.png|gauche|sans_cadre]]









Action: Replace one character string with another in a data file. The input file may or may not be Unicode. The strings to be replaced and replaced can be ASCII, hexadecimal, or a mix of both.


<u>Standard Settings</u>:


- Name of the input file.


- Output file name.


- Character string to replace.

- Replacement character string.


Return: none. A new file is created as output.


Example 1: Replacing an ASCII string
[[Fichier:OX S wrkflexepl1.png|centré|sans_cadre|580x580px]]




Example 2: Replacement of a HEXA string (to add a page break before a keyword for example)
[[Fichier:OX S wrklow expl2.png|centré|sans_cadre|580x580px]]


====Clean a folder====

[[Fichier:OX S NettoyDossier.png|gauche|sans_cadre]]








Action: Delete files from a directory, based on the filters used.

<u>Standard parameter</u>: Name of the directory to clean

<u>Advanced Settings</u>:


- Filter on the name of the files to delete (ex: *[%MAP_JOBNUM%]*)


- Filter on the extension of the files to delete (eg: *.tmp)


Return: None.


====Existence of a file====


Note: Not used in command mode alone but in a condition or to define a parameter.
[[Fichier:OX S Existencefile.png|gauche|sans_cadre]]







*Action: check the existence of a file.
*Parameter: full file name
*Return: character string “yes” or “no”.



===String command group===
<br />
[[Fichier:OX S Commande-String.png|centré|sans_cadre|763x763px]]


None of the functions in this set can be used in command-only mode. They are to be executed under conditions or to define parameters.

====Cut by position====

[[Fichier:OX S CUTPOS.png|gauche|sans_cadre]]







Action: extract part of a character string


es based on the position of the information to be extracted.


<u>Standard Settings</u>:


- Original character string (from which the information must be extracted)


- Default value to return if the information is not found


- Start position of the information to extract (numerical value)


- End position of the information to extract (numerical value)


<u>Advanced parameter</u>: number of characters to ignore from the start position (numeric value)

Return: alphanumeric character string.


====Cut by separator====
[[Fichier:OX S CUT SEP.png|gauche|sans_cadre]]








Action: extract part of a character string based on substring separators.


<u>Standard Settings</u>:


- Original character string (from which the information must be extracted)


- Default value to return if the information is not found


- Start separator of the information to extract (alphanumeric value)


- End separator of the information to extract (alphanumeric value)


Return: alphanumeric character string.


====Cut by field====

[[Fichier:OX S CUT CH.png|gauche|sans_cadre]]








Action: Extract part of a character string, based on a substring separator (CSV type strings).

<u>Standard Settings</u>:


- Original character string (from which the information must be extracted)


- Default value to return if the information is not found


- Field separator (alphanumeric value)


- Field number to return (numeric value)

Return: alphanumeric character string.


====BASENAME====
[[Fichier:OX S Basename.png|gauche|alt=|sans_cadre]]


*Action: extract the file name from a full path.
*Parameter: full path of a file
*Return: alphanumeric character string.



====DIRNAME====
[[Fichier:OX S DIRENAME.png|gauche|sans_cadre]]


*Action: extract the file path from a full path, without the name.
*Parameter: full path of a file
*Return: alphanumeric character string


====Replace one channel with another====
[[Fichier:OX S Replacechaine.png|gauche|sans_cadre]]






Action: in a character string, recursively replace one substring with another.

<u>Standard Settings</u>:


- Original character string

- Substring to replace (alphanumeric value)

- Replacement substring (alphanumeric value)


Return: alphanumeric character string.


====Remove significant spaces====
[[Fichier:OX S Delete space.png|gauche|sans_cadre]]







Action: remove spaces at the start and/or end of a character string


<u>Standard Settings</u>:


- Original character string


- Remove leading spaces: Yes (default) / No


- Remove trailing spaces: Yes (default) / No


Return: alphanumeric character string.

====Capitalize====
[[Fichier:OX S maj.png|gauche|sans_cadre]]


*Action: put a character string in uppercase.
*Parameter: original character string.
*Return: alphanumeric character string.



====Set to lower case====
[[Fichier:OX S min.png|gauche|sans_cadre]]


*Action: put a character string in lowercase.
*Parameter: original character string.
*Return: alphanumeric character string.


====Capitalize====
[[Fichier:OX S Capitaliser.png|gauche|sans_cadre]]






Action: put a capital letter at the start of a character string or at the start of each word in a character string.

<u>Standard Settings</u>:


- Original character string.


- At the beginning of each word: Yes / No (default)

Return: alphanumeric character string.


====Reverse case====
[[Fichier:OX S Inversecasse.png|gauche|sans_cadre]]


*Action: reverse the case (upper/lower case) of a character string.
*Parameter: original character string.
*Return: alphanumeric character string



===Mapping command group===


====Code page conversion====
[[Fichier:OX S CVRT CODEPAGE.png|gauche|sans_cadre]]






Action: Convert a file from one code page to another. This command is usually used to convert a file to Unicode (UTF-16, or code page 1200).

<u>Standard Settings</u>:


- Name of the source file (to convert)


- Destination file name (converted)


- Original code page (alphanumeric value to be selected using the entry help function)


- Destination code page (alphanumeric value to be selected by the entry help function, 1200 by default)

<u>Advanced Settings</u>:


- Convert numbers to Arabic numerals: Yes / No (default)


- Replace unknown characters with spaces: Yes / No (default)

Return: none. A file is created as output.



====ISERIES spool conversion====
Note: the default values reflect the attributes of the file sent by the remote iSeries.
[[Fichier:OX S CVRT ISERIES.png|gauche|sans_cadre]]








Action: Convert an EBCDIC file to ASCII Unicode. This command is usually used to convert spools produced on iSeries then processed in ONYX Server Unix or Windows version.


<u>Standard Settings</u>:


- Name of the source file (to convert)


- Destination file name (converted)


- Original code page (alphanumeric value to be selected using the entry help function)


<u>Advanced Settings</u>:


- Type of data from the iSeries (*SCS, *AFPDS, etc.)


- Number of lines per page (numeric value)


- Output width (numeric value)


- Option to retain SO/SI information for DBCS files

Return: none. A file is created as output.


====M-CONNECT execution, TXT output====

[[Fichier:OX S EXEC TXT.png|gauche|sans_cadre]]







Action: Run an M-Connect format producing text output.


<u>Standard Settings</u>:


- M-Connect format name (value to be selected using the entry help function)

- Output file name


<u>Advanced Settings</u>:

- Activation of debug mode: Yes / No (default)


- Port number if operating in persistent mode (numeric value)

- Name of the error log if operating in persistent mode (alphanumeric value)


- Type of output data (acts on the calculation of automatic page breaks)


<u>Custom Parameters</u>: input parameters for executing the M-Connect format of type DB.PARAM=value.

Return: none. A file is created as output.



====M-CONNECT execution, XML output====
[[Fichier:OX S CVRT XML.png|gauche|sans_cadre]]







Action: Run an M-Connect format producing XML output.


<u>Standard Settings</u>:

- M-Connect format name (value to be selected using the entry help function)


- Output file name


- XML schema to use to produce the output


<u>Advanced Settings</u>:


- Activation of debug mode: Yes / No (default)


- Port number if operating in persistent mode (numeric value)


- Name of the error log if operating in persistent mode (alphanumeric value)


<u>Custom Parameters</u>: input parameters for executing the M-Connect format, of type DB.PARAM=value.


Return: none. A file is created as output.



====M-CONNECT version, XLSX output====
[[Fichier:OX S CVRT XLSX.png|gauche|sans_cadre]]








Action: Run an M-Connect format producing XLSX output.


<u>Standard Settings</u>:


- M-Connect format name (value to be selected using the entry help function)

- Output file name


<u>Advanced Settings</u>:


- Activation of debug mode: Yes / No (default)


- Port number if operating in persistent mode (numeric value)


- Name of the error log if operating in persistent mode (alphanumeric value)


Custom Parameters: Input parameters for executing the M-Connect format, of type DB.PARAM=value.


Return: None. A file is created as output.