Working Unit File¶

A working unit file defines one or more working units. It is an XML file named wu-*.xml.

Digital Process Factory reads working unit 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 working unit manager services read the files when they start. Each service reads only the working units of its own TYPE. After changing a working unit file, restart the service that manages the working unit, refer to Administrate the DPF Services.

Hint - node working units

Digital Process Factory does not read node working units of type WUNodeCall from these directories. It loads their definitions from their npm packages.

Hint - DPF 3.x

DPF 4.x does not evaluate all attributes that DPF 3.x evaluates. Refer to Attributes Without Effect on DPF 4.x.

DPF 4.x ignores DEFAULTS and MAPPING directly below config/workingunits as values for all working units, and a MAPPING element in a working unit. When you migrate a working unit file from DPF 3.x, move these values to the DEFAULTS of the working unit or to the DEFAULTS or MAPPING of the workflow positions.

Structure¶

A working unit file has the following structure:

The root element is DPF, followed by config and workingunits.
Each child element of workingunits defines one working unit. The element name is the name of the working unit. A workflow calls the working unit by this name, in the NAME attribute of a working unit module.
The attributes of this element specify the properties of the working unit.
The child elements DEFAULTS, INPUT, OUTPUT, and ENVIRONMENTS are optional.

The shipped working unit files contain one working unit each.

Caution - encoding

Save working unit 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 working unit file

<?xml version="1.0" encoding="UTF-8"?>
<DPF>
  <config>
    <workingunits>
      <custom.stamppdf
        CODEPAGE="UTF8"
        COMMAND="%DPFSRV%/scripts/custom/stamppdf.pl -parfile %PARFILENAME%"
        NAME="Stamp PDF files"
        PROJECT="custom"
        THREADS="2"
        TYPE="WUSystemCall"
        >
        <DEFAULTS
          STAMP_TEXT="Released"
          WU_ENABLE_DEBUG_LOOP="N"
          />
      </custom.stamppdf>
    </workingunits>
  </config>
</DPF>

Caution - same name

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

Attributes¶

Digital Process Factory evaluates the following attributes of a working unit.

CLASSNAME¶

CLASSNAME specifies the Java class that the working unit calls. Only for the WUJavaCall type.

Available values: String

CODEPAGE¶

CODEPAGE specifies the encoding of the parameter file that the working unit writes for the external script.

Available values: Enumeration

ISO-8859-1

The parameter file is encoded as Latin-1.
UTF8 or UTF-8

The parameter file is encoded as UTF-8.

Default: ISO-8859-1. Digital Process Factory also uses ISO-8859-1 for any other value.

COMMAND¶

COMMAND specifies the external script that the working unit calls, including its command line options. Only for the WUSystemCall type.

Available values: String

Digital Process Factory replaces variables in %...% by the values of job parameters. If no job parameter with this name exists, it uses the environment variable of the service with this name. Digital Process Factory starts scripts with the .pl extension with perl.

Example

COMMAND="%DPFSRV%/scripts/custom/stamppdf.pl -parfile %PARFILENAME%"

Digital Process Factory does not search scripts in %SEAL_CUSTOMDIR%. COMMAND always specifies the script path.

JSMODULE¶

JSMODULE specifies the JavaScript module that the working unit loads. Only for the WUWait type.

Available values: String

If JSMODULE is missing, the seal-dpf-wuwait service logs No JSMODULE found for working unit, does not work in DPF version 4 and ignores the working unit.

PROJECT¶

For the WUJavaCall type, PROJECT specifies the project of the Java class in CLASSNAME.

For all other types, PROJECT has no effect on DPF 4.x. DPF Director used it to group the working units.

Available values: String

THREADS¶

THREADS specifies the maximum number of jobs that the working unit processes at the same time. Only for the WUSystemCall and WUNodeCall types.

Available values: Integer

Default: 1

The service key MAX_INSTANCES limits the number of jobs that a service processes at the same time for all its working units. If THREADS reaches or exceeds this limit, the service logs a warning.

Use THREADS for the following purposes:

Keep license limits. For example, if only three licenses are available for a conversion program, set THREADS="3" for the working unit that calls it. Further jobs wait in the queue until a thread is free.
Remove a bottleneck. If jobs wait for a working unit and enough resources are available, increase THREADS so that the working unit processes several jobs at the same time.

TYPE¶

TYPE specifies the type of the working unit and by that the service that manages its calls.

Available values: Enumeration

WUJavaCall

The working unit calls a Java class. Managed by the seal-dpf-wujavacall4 service.
WUNodeCall

The working unit is a node working unit. Managed by the seal-dpf-wustandard service.
WURestCall

The working unit is processed by an external client via the REST API. Managed by the seal-dpf-wu-manager-rest service.
WUSendFile

The working unit sends files back to DPF Batch Client. Managed by the seal-dpf-wusendback service.
WUSystemCall

The working unit calls an external script, specified in COMMAND. Managed by the seal-dpf-wusystemcall service.
WUWait

The working unit waits for the response of another system without blocking other jobs. Managed by the seal-dpf-wuwait service.

Caution - WUInteractive

DPF 3.x supports the WUInteractive type. On DPF 4.x, no service manages this type. A job that reaches such a working unit stays in the QUEUED status without an error.

Child Elements¶

DEFAULTS¶

DEFAULTS specifies default values for job parameters, one attribute per parameter. A default applies only if the parameter has no value yet when the job reaches the working unit. For the order in which parameter values apply, refer to Set Parameter Values.

For working units of type WUNodeCall, DPF does not evaluate DEFAULTS. Specify default values in the DEFAULTS of the WU position in the workflow.

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.

Example

<DEFAULTS
  STAMP_TEXT="Released"
  WU_ENABLE_DEBUG_LOOP="N"
  />

INPUT¶

INPUT describes the input parameters of the working unit, for example their type, range of values, and description. DPF 4.x does not evaluate INPUT. A DEFAULT attribute in INPUT does not set a default value. Specify default values in DEFAULTS.

DPF 3.x uses the DEFAULT attributes in INPUT as default values. When you migrate a working unit file, copy these values to DEFAULTS.

OUTPUT¶

OUTPUT describes the output parameters of the working unit. DPF 4.x does not evaluate OUTPUT.

ENVIRONMENTS¶

ENVIRONMENTS specifies environment variables for the external script, one attribute per variable.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x. On DPF 4.x, the script inherits the environment variables of the service.

Attributes Without Effect on DPF 4.x¶

The following attributes occur in working unit files, but DPF 4.x does not evaluate them. You can keep them in existing files.

DPFINT-*¶

Attributes starting with DPFINT-, for example DPFINT-Icon, were used by DPF Director only.

IGNOREEXITCODE¶

IGNOREEXITCODE specifies whether DPF 3.x ignores a return code other than 0 of the external script.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x. On DPF 4.x, a return code other than 0 always ends the job with the error ERR_EXTERN_PROG_CALL, even if the workflow continues in an error branch. The ExitCode parameter is set in any case.

LICENSE¶

LICENSE specifies the license that the working unit requires.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x.

LOGLEVEL¶

LOGLEVEL specifies the log level of the working unit.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x. The job parameter LogLevel is not affected.

LOGNAME¶

LOGNAME specifies the base name of a separate log file of the working unit.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x.

LOGSTDOUT¶

LOGSTDOUT specifies whether the console output of the external script is written to the job log.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x. On DPF 4.x, the seal-dpf-wusystemcall service writes the console output to the job log only if the script fails.

NAME¶

NAME specifies a short description of the working unit. It is not the name of the working unit, refer to Structure.

NODENAMES¶

NODENAMES specifies the servers on which a remote working unit runs.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x.

TIMEOUT¶

TIMEOUT specifies the number of seconds after which the processing in the working unit is canceled.

Evaluated by DPF 3.x only. Has no effect on DPF 4.x.

VERSION¶

VERSION specifies the version of the working unit file.