Defining entities for a workflow

You can use the document type definition (DTD) of XML to define entities in the workflow definition file. Entities are variables that can be referenced within the file. The XML processor replaces the references with the values specified in the DTD. You might use an entity to define a value that is subject to change as you develop the workflow, and thus can be changed in one place to affect all references.

You can define entities either inline, in one of the workflow XML files, or as system entities, in which case the XML processor obtains the replacement text from an external file.

Observe the following coding considerations:

An inline entity can be used like a macro instruction. That is, you can define text in one place that is frequently referenced throughout the workflow definition file.
A system entity is useful if you want to split the workflow definition file into smaller chunks for manageability, or reuse portions across multiple workflow definition files. For example, for a set of steps that is shared across different workflows. A system entity file can reside in the UNIX file system or in a z/OS data set, and the path name format is as described in References to external files.

Note, however, that the path name must be expressed as relative (not absolute). A further restriction for DTD entities is that the referenced entity must reside in the same "container" as the main workflow XML file.

For a UNIX file, the referenced entity must reside in the same directory or a subdirectory of the primary XML file
For a PDS, the referenced entity must reside in the same PDS. Here, a relative path name is simply the name of the member within the PDS.

Do not use a sequential data set to store an entity file. Also, be aware that a workflow definition that is contained in a sequential data set cannot refer to external entity files.

An entity file in a PDS member must start with the XML processing instruction, as described in Creating the workflow definition file, with IBM-1047 specified as the encoding format. In fact, any entity file using IBM-1047, whether it comes from a data set or a UNIX file, must start with this processing instruction. For UTF-8 files, the instruction is optional.

The following example shows how entities can be defined in the DTD.

<!DOCTYPE workflow [<!ENTITY copyright "Copyright IBM Corp., 2013">
                    <!ENTITY step1 SYSTEM "step1.xml" >
                    <!ENTITY step2 SYSTEM "step2.xml" >
                    <!ENTITY step3 SYSTEM "step3.xml" >
	            			 ]>

An entity can be referred to in the document using the following notation:

&copyright;

For another example, see the sample file workflow_sample_include_external.xml, which is supplied with z/OSMF in the /samples subdirectory of the product file system.