Preparing software to exploit cloud provisioning

• 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.

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 prepares 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: text 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 uses the software services template to provision the software. This is optional.

cconsumer-documentation-type

File type of the consumer documentation file: text or pdf. This is optional, and valid only if consumer-documentation-file is specified.

• If the manifest file is a z/OS UNIX file, specify:
  • z/OS UNIX files with a full path, for example, /a/b/c/d.xml, or a relative path, for example, ../b/c/d.xml.
  • Data sets with // followed by a fully qualified name. Data sets can be either partitioned or sequential. For example, you might specify //IBMUSER.DS.PDS(XML) or //IBMUSER.DS.SEQ.
• If the manifest file is in a data set, specify:
  • z/OS UNIX files with a full path, for example, /a/b/c/d.xml.
  • Data sets with fully qualified or relative names, as follows.
    • Fully qualified names follow // and can be either partitioned or sequential. For example, you might specify //IBMUSER.DS.PDS(XML) or //IBMUSER.DS.SEQ.
    • Relative names vary with the type of the manifest file data set, as follows:
      • Partitioned: Specify just the member, which identifies a member in the manifest file data set. For example, if the manifest file is IBMUSER.DS.PDS(MF), specifying a file path of XML in the manifest file requests IBMUSER.DS.PDS(XML).
      • Sequential: Specify one or more qualifiers that are added to the manifest file data set name. For example, if the manifest file is IBMUSER.DS.SEQ, specifying a file path of XML in the manifest file requests IBMUSER.DS.SEQ.XML.

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

<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. The action definition supports the same forms as the workflow definition. For more information and examples, see Specifying approvers for a step.

<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.

<cleanAfterComplete>

Indicates whether the workflow is removed if it completes successfully. Accepts true, false, and inherit, which specifies that the value is inherited from the value of the workflow-clean-after-provisioned field for the instance. The default is inherit.

<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>

Assigns a value to a workflow instance variable defined in the action workflow. During processing of an action workflow, values for variables are obtained from the property file that is specified with element wfVarInFile. Use wfVar to assign a different value for an action workflow variable. You can:

• Specify an explicit value for the variable.
• Request that the variable value is obtained from the registry for the software services instance. Because all the variables and their values are captured in the software instance registry when the template is provisioned, using the wfVar element lets you share the selected variables between provisioning and other action workflows such as the deprovisioning action workflow.

This wfVar element is optional. Up to 1500 variables are allowed. It includes these attributes:

name

Is the name of the variable in the action workflow definition. The name must be unique.

updateRegistry

Indicates whether to update the variables in the software services instance registry from the action workflow. This is allowed only if the value for the action workflow variable is obtained from the registry. The value for updateRegistry must be true or false. The default is false. When the value is true, after the action is completed:

• If the variable already exists in the software services instance, the value for the variable is updated from the action workflow.
• If the variable does not already exist in the instance, the variable is created in the instance with the value from the workflow.

Examples: In the following example, the value for action workflow variable DFS_PORTID is obtained from the registry variable that is identified by $!{DFS_PORTID}. The registry is updated with the new value for the DFS_PORTID variable set during action processing.

<wfVar name="DFS_PORTID" updateRegistry="true">$!{DFS_PORTID}</wfVar>

In the following example, the value for action workflow variable DFS_REGION_TCPIPPORT is explicitly set to 8080. You cannot specify updateRegistry="true" when the variable value is explicitly specified.

<wfVar name="DFS_REGION_TCPIPPORT" updateRegistry="false">"8080"</wfVar>

<instructions>

Defines an instruction.

<description>

Contains a brief description of the action and the function it performs. This element is optional.

<?xml version="1.0" encoding="utf-8"?>
<actionList>
        <action name="workflow1">
              <workflow>
                   <wfDefFile>workflow1.xml</wfDefFile>
                   <wfVar name="var1" updateRegistry="false">var1val</wfVar>
                   <wfVar name="var2" updateRegistry="true">var2val</wfVar>
                   <wfVar name="var3">var3val</wfVar>
              </workflow> 
              <description>Description of Workflow 1</description>
        </action>
        <action name="workflow2">
              <workflow>
                   <wfDefFile>workflow2.xml</wfDefFile>
              </workflow>
              <description>Description of Workflow 2</description>
        </action>
        <action name="instructions1">
              <instructions>The instructions</instructions> 
              <description>For best results, read every word!</description>
        </action>
        <action name="command1">
              <command>
                   <commandValue>d iplinfo</commandValue>
              </command>
              <description>What this command does</description>
        </action>
        <action name="deprovision" deprovision="true">             
              <workflow>
                   <wfDefFile>deprovision.xml</wfDefFile>
              </workflow>
              <description>This workflow can be deprovisioned</description>
        </action>
</actionList>

<?xml version="1.0" encoding="utf-8"?>
<actionList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="./actions_v1.xsd">
    <action name="deprovision">
          <workflow>
            <wfDefFile>./deprovision.xml</wfDefFile>
            <wfVarInFile>./workflow_variables.properties</wfVarInFile>
            <wfVar name="DFS_PORTID" updateRegistry="false">$!{DFS_PORTID}</wfVar>
            <wfVar name="DFS_SSLPORTID" updateRegistry="false">$!{DFS_SSLPORTID}</wfVar>
        </workflow>
        <description>This workflow can be deprovisioned</description>
    </action>
    <action name="start">
          <workflow>
            <wfDefFile>./Start.xml</wfDefFile>
            <wfVarInFile>./workflow_variables.properties</wfVarInFile>
            <wfVar name="url" updateRegistry="true">$!{ipadd}:$!{port}</wfVar>
          </workflow>
    </action>  
    <action name="stop">
          <workflow>
            <wfDefFile>./Stop.xml</wfDefFile>
            <wfVarInFile>./workflow_variables.properties</wfVarInFile>
            <wfVar name="processID" updateRegistry="false">$!{pid}</wfVar>
          </workflow>
    </action>
</actionList>