Prepare and publish a template

This topic provides an overview of the steps for creating a standard template that can be used to provision software.

Review and modify the source files. You might need to modify the template, typically using a properties file, or the input variable file that was supplied by the software provider, to customize things like high-level qualifiers, security options, other variables, or JCL, and to add approver elements to runAsUser elements. See the information that is provided by the software provider about what you need to customize.

You might want to modify a supplied documentation file, or create a documentation file, for use by consumers or administrators.

You might also want to modify the actions definitions, typically through a properties file that was supplied by the software provider, to customize the actions for your installation, and to add approver elements to runAsUser elements. This is discussed in a later step, when you can use an actions editor that is integrated into the z/OSMF task.

1. Before making any changes, make copies of the files, so that you keep a set of files as they were originally supplied by the software vendor.
2. Review and modify the source files, typically by modifying properties files and input variables files.

Ensure that the required IDs have access to the template source files. Your user ID and the z/OSMF server user ID both require at least READ authority to the workflow definition file, the workflow variable input file, and the actions definition file.

3. To verify that the server has access to these files, contact your z/OSMF administrator. By default, the server user ID is IZUSVR, but your installation might have specified another value for this user ID during the z/OSMF configuration process.

Add a template. You add a template, specifying the files that you customized. To perform this step, you must be a domain administrator. Domain administrators are defined with the Resource Management task.

4. Expand the Cloud Provisioning category in the z/OSMF navigation area, then select Software Services.
5. Select the Templates tab.
6. In the table, click Add Template, then Standard. If Add Template is unavailable, you are not defined as a domain administrator.
7. On the Add Template page, supply the values as appropriate, including the workflow definition file and the actions definition file that are to be used in provisioning the software, and the domain. Then, click OK. For more information, see Add a template.

Review the administrator documentation file. The template may include a documentation file for administrators. Now that you have added the template, refer to that file for any considerations that might apply to the remaining steps.

8. In the templates table, click the template name to view the template properties.
9. On the View template page, find the field for the administrator documentation file. If a value is displayed there as a link, click the link to open the file.
   Review the file for anything that you need to do or consider, and respond as appropriate.

Modify the actions definition file. Now that you have added the template, you can use an editor in z/OSMF to modify the actions definition file.

10. On the templates table, select the template, click Actions, then select Modify Template.
11. On the Modify Template window, click Edit for the Actions file field.
    Use the editor to make changes. Note that there is also an Edit button for the Workflow file field.

Associate the template with a tenant. Tenants are created with the Resource Management task.

12. On the templates table, select the template, click Actions, then select Associate Tenant.
13. On the Associate Tenant window, supply values. For more information, see Associate a tenant with a template. Click OK to display the Add Template and Resource Pool window of the Resource Management task.
14. On the Add Template and Resource Pool window, supply values to describe resource pools and the selection of the target system. Then click OK.

Having used the Resource Management task to add a template to the tenant, return now to the Software task.

15. Click the Software Services tab.
16. In the templates table, select the new template.

Perform approvals as needed. If the template is in the Draft state, you can skip the steps that are related to approvals, and proceed to Test run and publish, which describes the Test Run action. Otherwise, you need to address approvals first.

17. Take the appropriate action for a template state that involves approvals.
    • A Draft state indicates that the template has no approval records that must be approved. It is ready for the next step.A Draft pending approvals state indicates that the template has approval records that must be approved. Approval records are created when a workflow or action definition file contains an element that identifies a user ID under which a workflow step or action is to be performed. Approval records can also be created for the template as a whole, or based on the domain. The middleware administrator and security administrator might be required to complete the approvals. Those users review the approvals for the workflow or action command, and make changes to runAsUser or approver elements for the installation. Domain or template approvers review the provisioning workflow and all of the actions.
      1. On the templates table, select the template, click Actions, then select Approvals.
      2. On the Approve window, review and modify the runAsUser and approval elements, and any other elements, as needed. To review a workflow step or action, click the link in the Item to Approve column to open that item in the appropriate editor.
      3. If needed, notify the approvers that they have items to approve.
      The approvers do the following:
      1. On the templates table, select the template, click Actions, then select Approvals.
      2. On the Approve window, review the items that require approval. If the item is a link, click the link to open that item in the appropriate editor.
      3. To approve an item, select the row, then click Actions, then select Approve.
      4. After returning to the templates table, if the state of the template is now Pending security update, click Refresh to see an updated state that reflects the approvals.
    • A Draft missing required approver state indicates that a runAsUser element in a definition file has no approval elements. This state, in the templates table, is a link. To identify the missing approver, click the state to view the details. When the details are displayed, click a link in the Item to Approve column to display the element in read-only mode using the Workflow Editor or actions editor, as appropriate. To resolve the missing required approver state, either:

      • Edit the definition using the appropriate editor and add an approver.
      • Add a domain approver, with the Resource Management task.
      • Add a template approver. Modify the template using the Modify action, then, on the Modify Template window, use the Template Approvers field.
      For more information, see Approvals.

Test run and publish. These steps can be completed only when the approvals have been approved. Publish makes the template available for consumers. For example, you might make a published template available as an offering in a web portal.

18. In the templates table, with the template selected, click Actions, then select Test Run. Review the information that is displayed on the Test Run window, then click Test Run.
    You test run a template to confirm that it successfully creates a software services instance, while leaving the template open for further changes.
    Test Run creates a workflow, starts the workflow, and creates a software services instance.
19. On the Instances tab, check the table for the instance that you created with Test Run.
    The name of the instance is :

    • For a standard template: software-type_prefix-for-resource-poolnumber, for example, Standard_M03.
    • For a composite template: prefix-for-resource-pool_prefix-for-resource-poolnumber, for example, C_C03. For a clustered composite, a suffix of _software-service-instance-name is added.

    In the name, prefix-for-resource-pool is the value that is specified for software service instance name prefix field on the Add Template and Resource Pool page or the Create Shared Resource Pool page, and number is assigned by z/OSMF.

    To identify the instance that you created, you might use the information in the Created On and Created By columns, in addition to the name.

    The status of the instance should be either Being-Provisioned or Provisioned. Provisioned indicates success. You might need to click Refresh to see the status change to Provisioned.

    You might want to try one or more actions against the instance to ensure that they work as expected. Click Actions, then select Perform, then select an action.

    You might also click the instance name to view the properties, then review the variables that are shown in a table. If the variables include an IP address for a server, you might test the IP address in a browser.

    • If the instance was created successfully, with a status of Provisioned, and the actions perform as expected, you are now ready to publish the template. You may want to first clean up the results of your test, that is, deprovision and remove the instance that you created with Test Run.
      1. Select the instance, then click Perform. If a deprovision action is available, select it. You cannot deprovision the child instances of a composite instance (that is, an instance created from a composite template). Instead, use the Perform deprovision action against the composite instance.
      2. Once the instance is in a Deprovisioned state, click Actions, then select Remove.
      3. Proceed to the next step to publish the template.
    • If the status is Provisioning-Failed, or the actions do not perform as expected, determine the cause of the problem, and make appropriate changes. For more information, see Fixing problems with provisioning.
20. To make the template available to consumers, select the template on the templates table, click Actions, then select Publish. On the confirmation window, select the desired options, then click OK.
    This action locks the template, allowing only limited modification, and puts it in the published state.

Run the template. You might perform this step as a further check before notifying consumers that the template is available.

21. To create an instance from the published template, click Actions, then select Run.
    Run has the same effect as Test Run: It creates a workflow, starts the workflow, and creates a software services instance. The instance is displayed on the Instances tab. When the instance is in the provisioned state, the workflow is automatically deleted.