Basically, the scanning workflow in SafeQ is a tool for describing process of handling scans created by MFP and uploaded to SafeQ. That means it does not describe the way the scans are uploaded to SafeQ rather than way they are processed and delivered to the end user.

The scanning workflows are defined in XML. The XML definition is called a scanning template. This template describes a scanning workflow and can be changed by the SafeQ administrator by opening it in a text editor, modifying the XML structure as described hereafter, and importing to SafeQ. A very basic knowledge of XML is therefore needed.

Structure of the scanning template

Each XML template has to start with a tag <scan> and end with the tag </scan>. Inside these tags are defined descriptive data of the workflow which can be logically divided into three sections:

• Basic workflow settings

• Workflow parameters

• Output file settings

Validation

Before the scanning workflow is uploaded to the SafeQ and activated in, an XML validation is executed to prevent occurrence of any malicious content in the provided workflow. The scanning workflow is validated against the XML schema.

The XML schema file name is a configurable parameter in the System Settings configuration. The name of this parameter is scanTemplateSchema.

The value of this parameter contains the path of the XML schema file. If this parameter is empty or even omitted, then XML validation would not be performed. Following table summarizes default contents of the scanTemplateSchema parameter in the CML configuration file.

Basic workflow settings section is usually entered on the beginning of the workflow after the <scan> tag. All these definitions are mandatory.

Workflow Name

The name of the workflow is visible on SafeQ web interface and in case of scanning with embedded terminal also on a panel of MFP where user selects from available workflows.

Name of the workflow is enclosed in tags name.

Example of name of scanning to email workflow:

Scan destination

The destination of scanned documents defines where the scanned document shall be stored. There are three possible values:

• email – SafeQ sends documents as an e-mail attachment via e-mail.

• home – SafeQ stores documents to a directory in a local or a remote file system. Typically home folder of a user is used.

• script – SafeQ stores documents to a directory in a local or a remote file system and for each of the documents it runs a defined script.

Scan destination is enclosed in tags destination.

Example of destination of scanning to home folder workflow:

Workflow description

The description can be an arbitrary string which describes the scanning workflow in a natural language. It is shown for example in the embedded terminal application when user selects a workflow. It may contain a message for a user to enter parameter values (see section about workflow parameters). The description string may be shown wrapped according to display proportions.

The workflow description is enclosed in tags description.

Example of description of scanning to email workflow:

Please do not use any special characters, including diacritics and apostrophes.

Keep Metadata

Scanned metadata will not be deleted from delivery.

Default Value: false

Workflow parameters may be used to customize a standard behaviour of a scanning workflow which is defined by the destination element. A parameter is declared as follows:

Values of parameters are taken from element default and in case of scanning with embedded terminals they can be provided by a logged user via Parameters menu in the terminal applications. For this purpose, parameters are placed in parameter spaces (see next section for information on parameter spaces).

There is a list of predefined parameters for each supported scan destination with a special purpose which may be included in the scanning template.

Moreover, a variable with the same name as parameter can be used in parameter values. This variable is then replaced by the real value (entered by user on the terminal) of the parameter. This enables the administrator to include other than a predefined parameter.

Each parameter starts with a tag <parameter> and ends with </parameter>.

Spaces

In the XML scanning template, a parameter must be placed into either parameter space. The presence of a parameter in a parameter space determines who can assign a value to the parameter. There are two parameter spaces:

• admin – only the administrator can assign a value to the parameter. This can be done using element default.

• user – user (with access rights to the scanning workflow) can assign a value to the parameter. This can be done via terminal panel interface – currently only embedded terminals allow users to enter parameter values.

To put it simply, users cannot assign a value to a parameter inside the admin parameter space. The administrator has to define such parameter with a default value using variables if necessary. Parameters in user parameter space can also have a default value but this can be changed from the panel interface.

Currently, only embedded terminals allow user to enter parameter values. Therefore, a template for scanning with hardware terminals must have all parameters in the admin parameter space (those in the user parameter space are ignored).

A parameter can be put into a parameter space by enclosing it in tags <user> and </user>, or <admin> and </admin>. Example of one parameter in user space and one parameter in admin space:

Parameter name

The parameter name is an alphanumeric identifier of the parameter. There is a set of special parameters for each scanning workflow whose names are reserved.

A value of the parameter name must be enclosed in tags pname.

Example of definition of a parameter name:

Parameter Data type

The parameter data type is used as a constraint for values of the parameter. For example, the embedded terminal application uses the data type to display a specific input component or check values entered by the user.

Data types are:

• string – any text

• numeric – any real number

• boolean – values true/false

• date – date without time

• email – string field with auto-completing of e-mails

A value of the data type must be enclosed in tags type. Dynamic "email" type is currently available only on Konica Minolta Terminal Embedded with the native user interface.

Example of definition of a parameter data type:

Parameter description label

The parameter description label is an alphanumeric description of the parameter. It should contain a short description of the parameter in a natural language. For example, the embedded terminal application shows the label next to the input field of the parameter.

A value of the description label must be enclosed in tags label.

Example of definition of a parameter label:

Mandatory parameter flag

A parameter may be defined as mandatory and a user has to enter a value for it. This flag can only be used if the parameter is defined in the user parameter space.

A value of the flag must be enclosed in tags required. Use values true or false, and if tag is omitted, the default value is false.

Example of definition of a mandatory parameter (user has to enter e-mail of the recipient prior scanning):

Default value

A parameter may have a default value which must respect data type. This value is used unless changed either way, typically from the embedded terminal application. As for the scanning with hardware terminal, the default value field is the only way to provide a value for the parameter.

The default value may contain variables.

The default value of the parameter must be enclosed in tags default.

Example of definition of a default value with a variable:

Variables

Variables provide a mechanism to resolve a parameter value according to a context of a scan job. The variables can be used in default field of the parameter or when entering parameter value from the scanning application of an embedded terminal. Basically, there are two types of variables:

• Predefined variables – statically defined variables with a special meaning.

• Template variables – dynamic variables defined in the XML scanning template.

Predefined variables

The predefined variables have reserved name and a special meaning. According to the subsystem where the variable is replaced by a real value, there are two sets of predefined variables:

• Scan server variables

• Terminal Server variables

A Scan server predefined variable is specified as text starting and ending with character "%". Such variable is substituted with a real value in time the SafeQ server starts processing of scans uploaded by the MFP. Therefore they may be used on the embedded terminal by a user providing a value for the parameter. The SafeQ server recognizes the following variables in scanning templates:

• %login% - username of a user who created a scan

• %name% - name of a user who created a scan

• %surname% - surname of a user who created a scan

• %email% - e-mail of a user who created a scan

• %userhome% - whole path to home folder of a user who created a scan

• %devicename% - name of the device where the scan has been made.

• %file% - original name of the file from the MFP (in case of filename parameter) or full path to the processed file (in case of script parameter)

• %filename% - Name of the scanned file defined in scan workflow (under this name the scanned file is delivered).

• %job_id% - job ID of the scan job (this variable is available only when createScanJobWithWorkflow = enable)

• %safeqhome% - the full path to where SafeQ is installed on this server (typically C:\SafeQ5)

• %devicesGroupId% - ID of a group the device where scan has been made belongs to

• %devicesGroupName% - name of a group the device where scan has been made belongs to

• %devicesGroupIP% - IP address of a group the device where scan has been made belongs to

• %deviceId% - ID of the device where scan has been made

• %deviceDescription% - description of the device where scan has been

• %deviceLocation% - location of the device where scan has been made

• %deviceIP% - IP address of the device where scan has been made

• %deviceActivationDate% - activation date of the device where scan has been made

• %deviceEquipmentID% - equipment ID of the device where scan has been made

• %deviceServiceAgreementID% - device service agreement ID

• %deviceContactPerson% - contact person for the device where scan has been made

• %devicePrinterType% - type of the device where scan has been made

• %deviceCostCenter% - cost center ID of the device where scan has been made

• %deviceCostCenterName% - cost center name of the device where scan has been made

• %userCostCenter% - cost center ID of the user who has made scan

• %userCostCenterName% - cost center name of the user who has made scan

• %billingCode% - billing code number used for this scan job

Example: Parameter targetDir is a special parameter which defines directory in a file system, where the scans are stored. Suppose each user in SafeQ has a home directory on the company server galileo whose name is the same as the username of the user. Then the targetDir parameter may be defined as follows:

A Terminal Server predefined variable is specified as text starting and ending with character "%" and can be used only when scanning with an embedded terminal. Such variable is substituted with a real value in time the user opens the scanning application in the embedded terminal and is shown as default values in input fields of parameter values. The following variables are recognized:

•  (date) - current date in format set by SafeQ property scanDateFormat in expert options, for example use  yyyy-MM-dd  in order to get `2012-12-21` for 21st December 2012.

•  (time) - current time in format  set by SafeQ property scanTimeFormat, for example use  HH-mm-ss-fff  in order to get `12-15-00-000` for quarter past twelve .

•  (username) - username of a currently logged user

• The Terminal Server predefined variables are currently not supported by Ricoh ESA Terminal Embedded.

• The Terminal Server predefined variables are not resolved when scanning with Terminal Professional or Terminal Ultralight.

• The Terminal Server predefined variables can also be specified with character "@", but this possibility is deprecated and is kept only for backward compatibility.

Example: Parameter filename is a special parameter which defines name of the output file. To include the current time, date and username of the user in the name of the file, the parameter may be defined as follows:

 (date)-(time)-(username) in the default value generates 20091224-120101001-demo for the user with a username "demo" and time 2009-12-24 12:01:01.000 on the panel.

Template variables

Template variables don't generally have any special meaning. They are defined in the scanning template by a parameter definition and are then used typically in default values of other parameters. They only have meaning when scanning with an embedded terminal, since they're used to carry values provided by user. Such variable has the same naming convention as a scan server predefined variable, i.e. it is in form %parameterName%, where parameterName is a name of the parameter corresponding to this variable.

Example: A typical usage of a template variable is in scanning to fax (scan to script workflow with a fax script). In default value of parameter script you can see there is variable %faxNum%. When SafeQ processes the uploaded scan it substitutes this variable with the real value of parameter faxNum entered by user on the terminal.

Scan options allows predefining settings for a resulting scan document such as resolution, file format or color. The scan options section starts with tag <options> and ends with tag </options>.

Scan options feature is available only for scanning with embedded terminal, since vendor technologies are leveraged to setup a scan job according to the settings. When a template with scan options is used for scanning with hardware terminal, the scan options are ignored.

It is possible to define that any particular scan option is locked, i.e. it can not be modified by logged user on terminal. This feature can be set by specifying an attribute locked="true" in starting tag of an option entity.

Resolution

This option specifies resolution of scanning. There are five possible values sorted from the lowest resolution to the highest resolution:

• low

• normal

• fine

• high

• super

The value of resolution option must be enclosed in tags resolution.

SafeQ can substitute file format with other similar format when the configured one can't be used because of MFD or SafeQ limitation .

Scan resolution

Example of defining the highest possible resolution:

Color

This option specifies color scheme of a scan. There are following values:

• bw – black and white

• color – full colour

• gray – greyscale

• bicolor – two colours

• monocolor – single color

• auto – color scheme is detected automatically by the scanning device

The value of color scheme option must be enclosed in tags color.

Not all technologies and MFP models support all six color schemes. If an unsupported color scheme is chosen, it is substituted with the nearest possible value.

Example of defining the automatic color scheme detection:

Output file format

This option specifies file format of the output file. There are following values:

• pdf - a standard multi-page PDF (Portable Document Format) document

• cpdf - compact PDF document with reduced size

• spdf - searchable PDF (OCR)

• jpeg - standard JPEG (Joint Photographic Experts Group standard)

• tiff - single page TIFF (Tagged Image File Format)

• mtiff - multi-page TIFF

• xps - OpenXPS document (XML Paper Specification)

The value of output file format option must be enclosed in tags fileType.

Not all technologies and MFP models support all output file formats. If an unsupported file format is chosen, it is substituted with any other similar file format.

• If unsupported format (N/A) is set in workflow, it is replaced with default MFD format.

• If format set in workflow is not supported by particular model, it is replaced with default MFD format.

Example of defining the TIFF as an output file format:

Duplex and simplex

This option specifies whether the scan shall be scanned as duplex or simplex. There are following values:

• 1 – simples

• 2 – duplex

Simplex or duplex must be enclosed in tags sides.

Some technologies and models do not support forcing duplex settings and user has to set it manually.

Example of defining duplex scanning:

Despite the scanning templates can be used for both scanning with hardware and embedded terminal, not all features declared by the template definition are supported by hardware terminals. Therefore, some features declared by template are ignored when scanning with a hardware terminal:

• User parameter space – hardware terminals does not allow user to enter values of parameters, therefore all parameters in user parameter space are ignored in such templates.

• Scan options – hardware terminal does not communicate with vendor technology, therefore scan options are ignored in such templates.

• Terminal Server predefined variables – hardware terminals does not substitute this kind of variables.

However, you can still use the same template for the both types of scanning; some parts of template are ignored when scanning with hardware terminal.

Scanning to e-mail

• Default behavior - Scanned documents are delivered to the logged user's e-mail as an attachment.

• Supported parameters:

  • from – sender of the e-mail. if the value is blank or the parameter is omitted, the sender is the logged user.

  • to – recipient of the e-mail. Parameter may be used only once. If the value is blank or the parameter is omitted, the recipient is the logged user.

  • filename – name of the files in the e-mail attachment. If the value is blank or omitted, the file produced by the MFP is not renamed. If there is more files, their names are suffixed with a value from a numeric sequence.

  • failoverDir – path to a directory in local or a remote file system, where the scan is stored if the default delivery via e-mail failed for any reason. UNC paths are allowed.

  • maxFilesPerMessage – number of scanned documents sent in one e-mail.

• Related SafeQ configuration

  • scan-job-max-size-to-mail – Maximum size of attachments. If the attachment exceeds the maximum size, the files are stored in directory specified by failoverDir.

  • scan-email-undeliverable-attempts – Number of attempts to submit the e-mail.

  • scan-email-undeliverable-timeout – Interval between two submit attempts

  • email-with-scan-subject – Subject of the e-mail with the attachment

  • email-with-scan-body – Body of the e-mail with the attachment.

  • scan-job-too-big-message – Body of the e-mail which is sent to the user who created the scan if the size of the attachment exceeded the maximum allowed size.

  • scan-job-changed-destination – Body of the e-mail which is sent when the files couldn't be sent via email neither moved to the failover directory.

  • default-scan-folder – path to a directory in local or a remote file system, where the scan is stored if it couldn't be saved to the failover directory (usually system temp).
     Note that old files are deleted from this folder based on name pattern (variables are replaced by wildcards). Therefore do not set default-scan-folder to a folder that may contain other files that shall be preserved.

  • ScanServer-maxFolderTime - A period after which scan jobs that could not be processed in the requested manner are removed from a failover folder (the failoverDir parameter of scan to email workflows or the property default-scan-folder).

Please make sure that filename parameter will not contain characters which can not be used in file, folder, or shortcut names. For example: \ / : * ? " < > |

Scanning to folder

• Default behavior – Scanned documents are moved to the logged user's home directory.

• Supported parameters

  • targetDir – a path to a directory in local or a remote file system, where the files are stored. If the value is blank or the parameter is omitted, the target directory is the logged user's home directory.

  • filename – name of the moved files. If the value is blank or omitted, the file produced by the MFP is not renamed. If a file with the same name is already present in the target directory, the file name suffixed with a value from a numeric sequence.

• Related SafeQ configuration

  • default-scan-folder - path to a directory in local or a remote file system, where the scan is stored if it couldn't be saved to the target directory (usually system temp).

  • scan-job-changed-destination – Body of the e-mail which is sent when the files couldn't be saved to the target directory.

Please make sure that filename parameter will not contain characters which can not be used in file, folder, or shortcut names. For example: \ / : * ? " < > |

Scanning to script

• Default behavior – Scanned documents are moved to the directory specified by parameter targetDir and a script call from parameter script is executed. There is one script execution per each scanned document. This behavior can be changed to process all scanned documents in single script execution by placing special parameters to script command call.

• Supported parameters

  • filename – name of the moved files. If the value is blank or omitted, the file produced by the MFP is not renamed. If a file with the same name is already present in the target directory, the file name suffixed with a value from a numeric sequence.

  • targetDir – a path to a directory in local or a remote file system, where the files are stored prior executing the script. This parameter is mandatory for this type of workflow. If the value is not specified, all files are moved to the default directory.

  • script – a script command call (includes full path to script and arguments) which is executed upon each file uploaded from the MFP. This parameter is mandatory for this type of workflow. If the value is not specified, all files are moved to the default directory.

• Related SafeQ configuration

  • default-scan-folder - path to a directory in local or a remote file system, where the scan is stored if parameters targetDir or script is undefined or the script returns a non-zero exit code.

  • scan-job-changed-destination – Body of the e-mail which is sent when the files are saved to the default directory.

• Processing all scanned documents in single script execution

  • Alternative behavior to the default, it is triggered by placing %fileList% parameter among script parameters. Filesystem paths to all scanned documents are then dumped to text file located in targetDir and %fileList% parameter in script command call gets replaced by absolute path to this text file. Replaced path to text file then effectively becomes one of the script parameters. SafeQ then invokes script only one time, it is the responsibility of the external script to resolve all scanned documents from text file and process them within single script execution.

  • Similarly to %fileList%, you can put %metadata% parameter to script parameters. SafeQ will dump all predefined scan variables into text file and replace %metadata% parameter with absolute path to this text file. External script can read all predefined scan variables from this file.

  • %metadata% parameter is not supported in default behavior.

Please make sure that filename parameter will not contain characters which can not be used in file, folder, or shortcut names. For example: \ / : * ? " < > |

Also keep in mind that in case your script is on path containing spaces, it has to be enclosed in double quotes - e.g.:

<default>"\\faxserver\spaced path\script.cmd" %faxNum% %file%</default>

Some of XML scanning parameters are not supported by all MFPs
So far the scanning template configuration on the SafeQ website allows to set up the full range of options even though that various machines may not be able to support all of them (file format, duplex, etc). On the embedded terminal user interface we try to hide these disabled options as much as the technology allows it. KM native is such an example where we cannot fully handle and hide the scan options workflow configuration so some options may have different default value than expected.