Workflow File¶

A workflow file defines one or more workflows. A workflow specifies the order in which Digital Process Factory calls working units for a job. It is an XML file named wf-*.xml.

Digital Process Factory reads workflow files from the following locations:

the templates directory below %DPFSRV%, including all subdirectories
%SEAL_CUSTOMDIR%, including all subdirectories

For the rules on customer-specific files, refer to Customer-Specific Files on Windows or Linux.

The seal-dpf-process-manager service reads the files when it starts. After changing a workflow file, restart the service, refer to Administrate the DPF Services.

Hint - SaaS

In a SaaS installation, Digital Process Factory reads the workflows from MongoDB, refer to Administrate the DPF SaaS Configuration.

Structure¶

A workflow file has the following structure:

The root element is DPF, followed by config and workflows.
Each child element of workflows defines one workflow. The element name is the name of the workflow. A job specifies the workflow by this name. Digital Process Factory ignores upper and lower case, spaces, and underscores when it searches a workflow by name. For workflows with subprocesses, use the exact name, refer to Job Fails after a Subprocess.
Each child element of the workflow element defines one position in the workflow, except DEFAULTS. The element name is the name of the position. The TYPE attribute specifies the module type of the position.
The MAIN position specifies where the workflow starts, refer to MAIN.
The position name END ends the workflow. You do not need to define it.

Caution - encoding

Save workflow files as UTF-8. DPF 4.x ignores the encoding declaration in the XML header, so umlauts in other encodings are corrupted.

Example of a workflow file

The workflow custom.stamp calls the custom.stamppdf working unit if the STAMP parameter is a true value. Otherwise, it ends.

<?xml version="1.0" encoding="UTF-8"?>
<DPF>
  <config>
    <workflows>
      <custom.stamp
        NAME="Stamp PDF files if requested"
        PROJECT="custom"
        >
        <DEFAULTS
          STAMP="N"
          />
        <MAIN
          BEGIN="check_stamp"
          />
        <check_stamp
          TYPE="IF-THEN-ELSE"
          PROPERTY="STAMP"
          OPERATOR="is true"
          THEN="stamp_pdf"
          ELSE="END"
          />
        <stamp_pdf
          TYPE="WU"
          NAME="custom.stamppdf"
          NEXT="END"
          ERROR="END"
          >
          <DEFAULTS>
            <STAMP_TEXT
              val="Released"
              />
          </DEFAULTS>
          <MAPPING/>
        </stamp_pdf>
      </custom.stamp>
    </workflows>
  </config>
</DPF>

Caution - same name

Each workflow name must be unique within the templates directory and within %SEAL_CUSTOMDIR%. If two files in the same directory tree define a workflow with the same name, the service logs Workflow already exists in same directory tree. and stops loading the workflows. A workflow in %SEAL_CUSTOMDIR% overrides a workflow with the same name in the templates directory.

Attributes of a Workflow¶

Digital Process Factory evaluates only the VERSION attribute of a workflow element. When the workflow starts, Digital Process Factory writes the file name and the version number to the job log. It takes both from a string such as $Id: wf-stamp.xml,v 1.2 ...$ in VERSION. If VERSION is missing or has another format, the job log shows unknown instead.

Example of a job log without VERSION

Starting workflow test.copyfilesfilter at MAIN unknown (unknown)
MAIN element in process: test.copyfilesfilter -> MAIN
Starting MAIN function of workflow unknown version unknown

The shipped workflow files contain further attributes, for example NAME, PROJECT, COMMENT, LICENSE, and attributes starting with DPFINT-. These attributes have no effect on DPF 4.x.

DEFAULTS of a Workflow¶

The DEFAULTS child element of a workflow specifies default values for parameters, one attribute per parameter. Digital Process Factory uses these defaults when it expands variables in the module attributes of the workflow, for example in PROPERTY, VALUE, USE, or in a MODIFY module. A default applies only if the parameter has no value yet.

Digital Process Factory does not pass these defaults to the working units. To set a default for a working unit call, use the DEFAULTS of the WU position.

Hint - notation

Parameter names are case-insensitive. DPF also ignores underscores in parameter names. For example, CurrFileName is identical to CURRFILENAME, and WuName is identical to WU_NAME.

Caution - DPF 3.x

DPF 3.x passes the workflow DEFAULTS to the working units as well. It also evaluates a MAPPING element of the workflow. DPF 4.x ignores a workflow-level MAPPING. When you migrate a workflow, move these values to the DEFAULTS or MAPPING of the WU positions.

Module Types¶

The TYPE attribute of a position specifies the module type. If TYPE is missing, Digital Process Factory derives the module type from the attributes:

USE: SWF
SET: MODIFY
BEGIN: MAIN
none of these: WU

Any other value of TYPE stops the job with an error.

Several attributes specify the next position, for example NEXT, THEN, or ELSE. If such an attribute is missing, the workflow continues at END, unless the attribute is marked as mandatory below. A next position can also be an earlier position. This way, a workflow can run through positions several times, for example once per distribution channel.

DPF 4.x ignores the attributes COMMENT, POSX, and POSY and the child element CONNECTIONS. They were used by DPF Director to display the workflow.

MAIN¶

The MAIN position specifies where the workflow starts. Each workflow contains exactly one MAIN position.

Attributes:

BEGIN: name of the first position. Mandatory.
ERROR: name of the position at which the workflow continues if a working unit fails and its position has no ERROR attribute. Optional.

Example

<MAIN
  BEGIN="check_stamp"
  ERROR="send_error_mail"
  />

WU¶

A WU position calls a working unit.

Attributes:

NAME: name of the working unit, that means the element name in the working unit file.
NEXT: name of the next position if the working unit succeeds.
ERROR: name of the next position if the working unit fails. If ERROR is missing, the workflow continues at the ERROR position of MAIN. If that is missing as well, the workflow continues at END.

Child elements:

DEFAULTS: default values for parameters of this working unit call. Each parameter is a child element with a val attribute. A default applies only if the parameter has no value yet. DPF 4.x ignores parameters written as attributes of DEFAULTS.
MAPPING: explicit values for parameters of this working unit call, one attribute per parameter. These values always apply, independent of existing values.

For the order in which parameter values apply, refer to Set Parameter Values.

DPF 3.x reads the DEFAULTS of a WU position only as attributes, for example <DEFAULTS STAMP_TEXT="Released"/>. When you migrate a workflow, convert these attributes to child elements.

Example

<stamp_pdf
  TYPE="WU"
  NAME="custom.stamppdf"
  NEXT="END"
  ERROR="send_error_mail"
  >
  <DEFAULTS>
    <STAMP_TEXT
      val="Released"
      />
  </DEFAULTS>
  <MAPPING
    STAMP_POSITION="top-right"
    />
</stamp_pdf>

Caution - error status

If a working unit fails, the job keeps the error status, even if the workflow continues in an error branch. A job that contains a failed working unit always ends with an error.

MODIFY¶

A MODIFY position sets or deletes job parameters.

Attributes:

NEXT: name of the next position. Mandatory.

Child elements:

SET: parameters to set, one attribute per parameter. Digital Process Factory expands variables in the values, refer to Expansions and Operators.
DELETE: parameters to delete, one attribute per parameter. The value of the attribute has no effect.

The parameter values are valid until the job is finished unless they are changed again.

Example

<set_target
  TYPE="MODIFY"
  NEXT="stamp_pdf"
  >
  <SET
    TargetDir="%JobDir%/stamped"
    />
  <DELETE
    TempFile=""
    />
</set_target>

IF-THEN-ELSE¶

An IF-THEN-ELSE position branches depending on a condition.

Attributes:

PROPERTY: name of the parameter to check. The % characters around the name are optional.
OPERATOR: comparison operator, refer to Operators.
VALUE: value to compare with. Digital Process Factory expands variables in the value.
THEN: name of the next position if the condition is true.
ELSE: name of the next position if the condition is false.

Example

<check_stamp
  TYPE="IF-THEN-ELSE"
  PROPERTY="STAMP"
  OPERATOR="is true"
  THEN="stamp_pdf"
  ELSE="END"
  />

SWITCH¶

A SWITCH position branches depending on the value of a parameter.

Attributes:

PROPERTY: name of the parameter to check. The % characters around the name are optional.
CASE:<value>: name of the next position if the parameter has the value <value>. One attribute per value.
DEFAULT: name of the next position if no CASE attribute matches. Mandatory.

Digital Process Factory compares the values case-insensitively.

Example

<check_printmode
  TYPE="SWITCH"
  PROPERTY="PRINTMODE"
  CASE:D="printmode_duplex"
  CASE:S="printmode_simplex"
  DEFAULT="printmode_simplex"
  />

Instead of CASE:<value> attributes, a cases child element can contain one attribute per value.

Example with cases

<check_printmode
  TYPE="SWITCH"
  PROPERTY="PRINTMODE"
  DEFAULT="printmode_simplex"
  >
  <cases
    D="printmode_duplex"
    S="printmode_simplex"
    />
</check_printmode>

SWF¶

A SWF position calls another workflow as subprocess. When the subprocess ends, the calling workflow continues.

Attributes:

USE: name of the subprocess. Digital Process Factory expands variables in the name.
NEXT: name of the next position after the subprocess.
ERROR: name of the next position if a working unit in the subprocess failed. If ERROR is missing, the workflow continues at the ERROR position of MAIN. If that is missing as well, the workflow continues at END.

If the subprocess does not exist, the job ends with the error ERR_FIND_WF.

Example

<stamp_all
  TYPE="SWF"
  USE="custom.stamp"
  NEXT="END"
  ERROR="send_error_mail"
  />

USER_EXIT¶

A USER_EXIT position calls a subprocess only if it exists. With a user exit, you add customer-specific steps to a standard workflow without changing it.

Attributes:

USE: name of the subprocess, usually from a parameter, for example %UserExitAfterStamp%. Digital Process Factory expands variables in the name.
NEXT: name of the next position.
ERROR: name of the next position if a working unit in the subprocess failed. Same fallback as for SWF.

If the subprocess exists, Digital Process Factory calls it and then continues at NEXT. If it does not exist, Digital Process Factory continues at NEXT directly.

Example

<user_exit_after_stamp
  TYPE="USER_EXIT"
  USE="%UserExitAfterStamp%"
  NEXT="END"
  />

STOP¶

A STOP position ends the workflow. It has no further attributes. A next position named END has the same effect.