Creating and viewing the workflow definition file

This topic is intended to give application programmers guidance on how to create a workflow definition file.

To be considered valid, a workflow definition file must follow normal XML syntax conventions and also conform to the rules of the Workflows task schema that is supplied with z/OSMF.

Editing XML files on your workstation

It is recommended that you create and view the workflow XML files on a workstation, rather than on a z/OS system.

When working with XML files, use a text editor that includes an XML validation function. Validation is the process of comparing your XML files with the Workflows task schema. Doing so ensures that the files use only those tags that have been defined in the schema, and ensures that the files conform to the element rules specified in the schema.

To perform the XML validation, you will need to transfer the schema file to the XML editor on your workstation. The Workflows task schema resides on the z/OS system according to the z/OSMF product directory path. By default, at this location:

/usr/lpp/zosmf/V2R1/workflow/schemas/workflow_v1.xsd

For information about transport protocols, see Transferring the workstation files to z/OS.

Specifying the processing instruction in the primary XML file

As mentioned in Structure of a workflow definition file, the primary XML file must begin with a processing instruction in column 1 of line 1. This instruction indicates to the XML processor the version of XML used and the file encoding format. For example:

<?xml version="1.0" encoding="UTF-8"?>

The following encoding formats are valid:

UTF-8 (ASCII) or IBM-1047 (EBCDIC) for workflow definition files in UNIX files
IBM-1047 for workflow definition files in z/OS data sets.

You must include a processing instruction in the primary XML file, but you do not need to specify a processing instruction in any XML fragment files that you include with the primary XML file.

Some workstation XML editors might not recognize the IBM-1047 processing instruction and will therefore not display the file. Also, it is not possible to display a file in EBCDIC on your workstation. As a workaround, if you want a file to be IBM-1047, you can specify UTF-8 in the processing instruction while you are editing the file on your workstation. Then, after transferring the file to z/OS in ASCII mode, you can edit the file on z/OS to change the processing instruction to IBM-1047, which allows the Workflows task to process the file correctly.

Transferring the workstation files to z/OS

It is recommended that you use File Transfer Protocol (FTP) to transfer the XML files to a z/OS system. Doing so helps to ensure that the files are encoded properly for use on z/OS.

For XML files:

If the processing instruction (the first line in the XML file) indicates that the file uses UTF-8 encoding, transfer the file to z/OS in binary mode, to preserve the file encoding.
If the processing instruction indicates that the file used IBM-1047 encoding, transfer the file to z/OS in ASCII mode, to have the file converted to EBCDIC.

As supplied by IBM, the Workflows task schema file is encoded in UTF-8. Thus, you should specify binary mode when transferring this file to a z/OS system. After transferring the files to the z/OS system, check the file permissions of the transferred files to ensure that they can be opened by the z/OSMF Workflows task. For testing and workflow development purposes, consider setting the file permission of the transferred files to the octal value of 0777 (in "properties").