ONYX:9.0:Utilisation:Workflows-Guide avancé/en

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.

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:

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.

Environment Settings

Fields of type Parameter 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 ( MAP_USER ), file name ( MAP_FILE), ..

- parameters linked to the current processing: processing input connector ( MAP_PRINTER , MAP_SOAP , SCANFOLDER_NAME...), date of submission ( MAP_DATE), ...

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

- system environment variables: temporary directory ( TEMP), system name ( COMPUTERNAME),

- session variables:

• current box input/output files: MAP_FILE_IN / MAP_FILE_OUT
• ID of the last spool inserted for the current session (execution): LAST_SPOOL_ID
• 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): MAP_CURRENT_DATE / MAP_CURRENT_TIME / MAP_CURRENT_TIMESTAMP

“DIRECT” value

Value type fields statically take the value entered in the field:

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

[% PARAMETER %]. They are widely used for constructing full paths or file names where several parameters can be used at once:

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: [[ CRITERIA ]]. So for example, from a single XPS document, to create a PDF per output client, in the To PDF Command box, we will use:

RuleFile

Fields of type Rulefile take the value of information read from a file (example: the input file MAP_FILE_IN 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:

- 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.

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

- 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:

Reading is done in XML mode and the value retrieved from the source file is identified by the XPath 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:

- 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 Rulefile_multiple allow several parameters to be defined at once, valued by information read at different locations in the same file (for example, the input file MAP_FILE_INor 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.

- (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:

- Param : Parameter name

- XPath : XPath request to read information in the source XML file

- Default : 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 ... )

Spooler command group

Hold a Queue

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

Release a Queue

• 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.

• 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.

• 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.

• 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

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

Print

Action: send a job to an ONYX Server Spooler queue

Standard Parameters:

- 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

Pages Settings:

- Start page (1 by default)

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

- Number of copies (1 by default)

Security Settings:

- Destination job owner (MAP_USER 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)

Userdata Settings: ability to add up to 10 additional custom attributes

Advanced settings:

- 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 LAST_SPOOL_ID

Send to queue and return

• 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

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

Standard Parameters:

- Unique ONYX Server identifier of the job

- ONYX Server queue name

- Attribute name

- Value given to the attribute

• Return: none.

File command group

Rename a file

• Action: rename a file

Standard Settings: - Full name of the original file

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

Advanced Settings:

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

• Return: none.

Copy/move a file

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

Standard Settings:

- Full name of the original path

- Full name of the destination file

Advanced Settings:

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

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

• Return: none.

Copy to folder

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

Standard Settings:

- Full name of the original path

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

Advanced Settings:

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

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

• Return: none.

Secure copy

Action: Copy a file to an SFTP server.

Standard Settings:

- 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)

Advanced Settings:

- 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

Action: Add text to a file.

Standard Settings:

- Name of the input file.

- Code page of the output file.

- File contents.

Delete a file

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

Replace a string in a file

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.

Standard Settings:

- 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

Example 2: Replacement of a HEXA string (to add a page break before a keyword for example)

Clean a folder

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

Standard parameter: Name of the directory to clean

Advanced Settings:

- 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.

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

String command group

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

Action: extract part of a character string

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

Standard Settings:

- 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)

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

Return: alphanumeric character string.

Cut by separator

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

Standard Settings:

- 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

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

Standard Settings:

- 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

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

DIRNAME

• 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

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

Standard Settings:

- Original character string

- Substring to replace (alphanumeric value)

- Replacement substring (alphanumeric value)

Return: alphanumeric character string.

Remove significant spaces

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

Standard Settings:

- Original character string

- Remove leading spaces: Yes (default) / No

- Remove trailing spaces: Yes (default) / No

Return: alphanumeric character string.

Capitalize

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

Set to lower case

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

Capitalize

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

Standard Settings:

- Original character string.

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

Return: alphanumeric character string.

Reverse case

• 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

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).

Standard Settings:

- 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)

Advanced Settings:

- 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.

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.

Standard Settings:

- Name of the source file (to convert)

- Destination file name (converted)

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

Advanced Settings:

- 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

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

Standard Settings:

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

- Output file name

Advanced Settings:

- 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)

Custom Parameters: 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

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

Standard Settings:

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

- Output file name

- XML ​​schema to use to produce the output

Advanced Settings:

- 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.

M-CONNECT version, XLSX output

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

Standard Settings:

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

- Output file name

Advanced Settings:

- 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.