Preparing software for cloud provisioning

This topic describes how to prepare files that are required to make software available to exploit IBM Cloud Provisioning and Management for z/OS.

IBM Cloud Provisioning and Management for z/OS allows software consumers, from a selection of software services, to quickly provision and deprovision software as needed. For more information, see Cloud provisioning services and the online help for the Cloud Provisioning tasks in z/OSMF.

Software is provisioned from a software services template. A software services template requires the following files.

Workflow definition file

A workflow definition file is the primary XML file that defines the workflow that performs the provisioning. The workflow definition file includes information about the workflow, such as name and version, as well as step and variable definitions. For information about workflow definition files, see Creating workflow definitions for z/OS.

Variable input file

A workflow variable input file is a properties file that is used to specify values for one or more of the input variables that are defined in the workflow definition. For information, see Creating workflow definitions for z/OS.

Action definition file

An action definition file describes the actions that can be performed against the provisioned software, which is known as a software services instance. For more information, see Actions definition file.

Documentation files

A documentation file is an optional text or PDF file that provides information that is important to provisioning the software. For example, it might describe the workflow and other files, and describe requirements for using them to provision software. There can be one documentation file for administrators, who create the software services template and prepare the software for provisioning, and one for consumers, who use the published software services template to provision the software. The document for administrators might indicate, for example, whether a network resource pool or WLM resource pool is required.

Manifest, or template source file

A manifest file is optional. It provides a shortcut when a user creates the software services template using the z/OSMF Software Services task. Rather than specifying each of the files (workflow definition, input variable file, action, and documentation) individually, the user can specify just the manifest file, then click Load to supply values for the other files.

The file must be in Java™ property file format:

Each entry is a single line, in property=value or property:value format.
The \ character is a continuation character, so that a value can span lines.
For newline, carriage return, and tab, use \n, \r, and \t.
Comment characters are ! and #. Lines that start with those characters are ignored.

The fields in the manifest file are:

workflow-definition-file: Name of the workflow definition file
workflow-variable-input-file: Name of the workflow variable input file
action-definition-file: Name of the action definition file
description: Brief description of the workflow. This is optional.
admin-documentation-file: Name of the file that describes the workflow and other files. This file is intended for an administrator who will prepare a software services template that consumers can use to provision the software. This is optional.
admin-documentation-type: File type of the administrator documentation file: txt or pdf. This is optional, and valid only if admin-documentation-file is specified.
cconsumer-documentation-file: Name of the file that describes the workflow and other files, intended for a consumer who will use the software services template to provision the software. This is optional.
cconsumer-documentation-type: File type of the consumer documentation file: txt or pdf. This is optional, and valid only if consumer-documentation-file is specified.

The following is an example of a manifest file.

# provision.mf
#
# Manifest file to be used when adding a template for provisioning an MQ for z/OS Queue Manager.
#
#  <copyright
#      notice="lm-source"
#      pids="@PID###@"
#      years="2015,2016"
#      crc="3073404564">
#      Licensed Materials - Property of IBM
#
#      @PID###@
#
#      (C) Copyright IBM Corp. 2015, 2016 All Rights Reserved.
#  </copyright>
#
# Provision Queue Manager workflow file (steps to provision a Queue Manager)
workflow-definition-file:provision.xml
# Provision Queue Manager workflow variables properties file (properties to be used when provisioning a Queue Manager) 
workflow-variable-input-file:workflow_variables.properties
# Queue Manager actions file (defines the actions that can be performed against a Queue Manager)
action-definition-file:qmgrActions.xml
# Provision Queue Manager workflow description 
description:This workflow provisions an MQ for z/OS Queue Manager
# Provision Queue Manager readme file
admin-documentation-file:mqaas_readme.pdf
# Provision Queue Manager readme file type
admin-documentation-type:pdf

Actions definition file

An actions definition file has XML syntax and conforms to the rules of the actions schema. The schema defines the required and optional properties (XML elements and attributes). It imposes constraints on the order in which the elements are specified, and on the values that can be specified for each element and attribute.

The schema file is UTF-8 encoded.

If you are developing an actions definition file, you require access to the schema, and therefore access to the z/OS system on which z/OSMF is installed.

The primary XML file must start with a processing instruction (in column 1 of line 1) for the XML processor. This instruction defines the version of XML used and the encoding of the file. For example:

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

The remaining elements are as follows.

<actionList>

Is the root element. It contains the actions definitions.

<action>

Contains an action definition. There must be 1 - 50 actions in an actions definition file. The action contains either a command, workflow, or instruction element. The attributes are:

name, which specifies the name of the action
deprovision, which accepts true or false, to indicate whether the action is for deprovisioning. There must be at least one deprovision action.

<command>

Contains a command definition. It contains the following elements.

<commandValue>: Command to be issued. This is required.
<runAsUser>: User ID under which the action is to be performed. This is optional. The attribute is substitution, which accepts true or false.
<approver>: A user ID, or a list of user IDs separated by blanks. At least one user ID must approve the action before it is performed on behalf of the user ID that is specified with the runAsUser element. To specify multiple required approvers, use multiple approver elements (up to 12). The approver element is optional. If it is specified, then the runAsUser element is required.
<unsolkey>: Key to search for in the unsolicited messages, for a command-type action.
<solkey>: Key to search for in the solicited messages command response, for a command-type action.
<detectTime>: Time in seconds to search for the unsolkey in the unsolicited messages. Also, the minimum time before a command response is checked for after the command is submitted for execution.

<workflow>

Contains a workflow definition, consisting of the elements that follow.

<wfDefFile>: Workflow definition file path. This element is required. The maximum length of the file path is 1024 characters.
<wfVarInFile>: Workflow variable input file path. This element is optional. The maximum length of the file path is 1024 characters.
<wfVar>: Value of a workflow variable. This element is optional. Up to 1500 variables are allowed. It includes a name attribute, which defines the name of the variable. The name must be unique.

<instruction>

Defines an instruction.

Example

The following example shows an action definition.

<?xml version="1.0" encoding="utf-8"?>
<actionList>
        <action name="workflow1">
                <workflow>
                       <wfDefFile>workflow1.xml</wfDefFile>
                </workflow>
        </action>
        <action name="workflow2">
                <workflow>
                       <wfDefFile>workflow2.xml</wfDefFile>
                </workflow>
        </action>
        <action name="instructions1">
                <instructions>The instructions</instructions>
        </action>
        <action name="command1">
                <command>
                   <commandValue>d iplinfo</commandValue>
                </command>
        </action>
        <action name="deprovision" deprovision="true">
                <workflow>
                       <wfDefFile>deprovision.xml</wfDefFile>
                </workflow>
        </action>
</actionList>