Plug-in Documentation

zOS Management Facility

Overview

The z/OS Management Facility (zOSMF) plug-in provides functions to discover software instances provisioned byz/OSMFCloud Provisioningorz/OS Provisioning Toolkit. A collection of resources are created inthe resource tree torepresent thesoftware instances such as CICS regions, WebSphere Liberty profile, MQ queues, and DB2 databases.

Discovering resources takes less time than manually creating resources to match the sub systems. For additional information about discovering resources, see the following topics:

This plug-in includes the following steps:

The following roles are added by this plug-in.

Step palette

To access this plug-in in the palette, click Utilities > zOS Utility > zOSMF.

Compatibility

The steps in this plug-in run on the following platforms.

  • This plug-in is supported to run on z/OS 2.2 or later.
  • This plug-in requires UrbanCode Deploy 6.2.0 or later. Specific resource icons for z/OS software instances are used in UrbanCode Deploy 6.2.6 and later

Prerequisites

  • Only software instances provisioned using z/OSMF Cloud Provisioning orz/OS Provisioning Toolkit can be discovered.
  • z/OSMF must be started and permission must be setup to allow access to the REST API
  • The user ID used to run discovery must have proper permission to access the software instance.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode products.

History

Version 6.934842includes the following updates:

  • Added zOSMF discovery feature. The plug-in is now able to discover software instances provisioned by zOSMF Cloud Provisioning or zOS Provisioning Toolkit. A set of resources representing the software instances are automatically created as the result of the discovery.
  • Added a new step to Run Published Software Service Template.

Version 5.868918includes the following updates:

  • Enhanced Start Workflow step to store job logs to output properties.

Version 4.839888includes the following updates:

  • Fixed a problem in Start Workflow step that Perform Subsequent parameter does not work.
  • Fixed a problem in Start Workflow step that partially completed workflow gives a step failure.
  • Enhanced Start Workflow step to display job logs.

Usage

Discovering Mainframe Software Services Instances

Before you begin

  • Install the current version of the z/OS Management Facility plug-in.
  • Install an UrbanCode Deploy agent on theLPAR where z/OSMF is running.
  • Verify that the Cloud Provisioning function in z/OSMF is installed and software services instances have already been provisioned.

Discovering Software Services Instances

On theIBM UrbanCode Deployserver user interface, clickResources > Agents. Open the z/OS agent to be used to run discovery. Add an agent property named zosmf.url and set the value to the URL of z/OSMF. For example: https://localhost/zosmf .

Create a top-level resource group and add the agent as an agent resource under the top-level resource group. Wait for a few seconds and refresh the Resource Tree.Eventually, another resource is displayed under the agent resource. This resource is named zOSMFService.

Open zOSMFService resource and click Configuration>Basic Settings. The resource has the zOSMFServicerole, which includes several properties that are related to z/OSMF. In theRole Propertiestable, specify the user ID and password to be used to run discovery and click Save.

Note: The ID is an MVS user ID with proper permissions setup. To ensure the user ID is working properly, use it to log into the z/OSMF web interface and list the software services instances.

Go back to the Resource Tree view, click theActionsbutton that is associated with the zOSMFServiceresource, and then clickConfigure using Software Services Instance Discovery. The discovery step runs. A log displays to show progress.When the discovery process completes, close the log window, and refresh the resource tree.Resources that represent the software services instancesare displayed in the resource tree. Thenew resources are organized in structure plex\system\software type\instance name.

Software Services Instances Resources

You may add components to the resources and add these resources to an environment to start application deployment. The resource properties contain information of the instance which can be used in a deploy process. The properties are retrieved from the z/OSMF software services instance variables.

Tips: Sometimes the name of the property is not what is expected by the deploy process. You can define the expected property name in the top-level folder and have it reference the value of an instanceproperty. See following graphic for an example.

Provisioning and Discovering Mainframe Software Services Instances

Software services instances discovery can be run manually from the resource tree and automatically in an UrbanCode Deployprocess. This document describes a use case where a software instance is provisioned and discovered in a singleautomated UrbanCode Deploy process.

Before you begin

  • Install the current z/OS Management Facility plug-in.
  • Install an UrbanCode Deploy agent on theLPAR where z/OSMF is running.
  • Verify that the Cloud Provisioning function in z/OSMF is installed anda Published Software Service template is ready to run

Create a generic process

Create a generic process using two steps.

The first step is a Run Published Software Service Template step. The following example runs the CICS53 template to provision a new CICS region. The template is available from z/OS Provisioning Toolkit

The second step is aSoftware Services Instance Discovery step. The Query Parameters fieldis set to object-name = ${p:provision/zosmf.instanceName} so that it will only discover the instance provisioned by the previous step. ${p:provision/zosmf.instanceName} is a reference to the provisioned instance name from the previous step.

Run the process

Create a top-level resource group. Add following properties to the group and set the appropriate values for connecting to z/OSMF.

  • zosmf.password
  • zosmf.url
  • zosmf.user

Add the z/OS agent tobe used to the group and run the process on the agent resource.

After the process completes, refresh the resource tree.Resources that represent the provisioned CICS region are displayed in the resource tree.

Next step

You can now provision a software services instanceand have the resources automatically created in UrbanCode Deploy to represent the subsystem. You can use the resource or you can further enhance theautomation. For example you can map a component to the resource, createenvironment and start initial deployments.

Note:If you prefer to usez/OSPTto provision software, you can replace the Run Published Software Service Template step with a Shell step and input the corresponding z/OSPT commands. You will need to parse the z/OSPT output to find the name of the instance.

Steps

Process steps in the zOSMF plug-in

Create Workflow

Use this step to create a workflow.

Input properties for the Create Workflow step
Name Type Description Required
Assign To Owner Boolean Indicates whether the workflow steps are assigned to the workflow owner when the workflow
is created. If this property is set to true steps are assigned to the user ID that
is specified on the property owner. If this property is set to false, the workflow
steps are left unassigned when the workflow is created. The default is true.
No
Comments String Specifies any information that you want to associate with the creation of this workflow.
The comment can contain up to 500 characters. This information is recorded in the
workflow history.
No
Generate Unique Name Boolean Indicates whether to append a timestamp to the workflow name. Adding a timestamp ensures
the workflow name is unique name. The default is true.
No
Owner String The user ID of the workflow owner. This user can perform the workflow steps or delegate
the steps to other users. Specify a valid user ID that is defined to your z/OS security
management product installation, such as RACF. A valid user ID consists of one to
eight alphanumeric characters (A-Z, a-z, 0-9, #, $, and @).
Yes
Print REST call in log Boolean Indicates if REST call requests and responses are written to the log file. The default
is not to write REST calls into the log file.
No
Resolve Global Conflict By Using String On creation of the workflow, z/OSMF determines whether any of the variables that are
supplied in this request (through the variable input file or variables array) would
conflict with existing global variables in the Workflows task. In such cases, this
property specifies which version of the variable is used, as follows: When set to
input, the global variable conflicts are overridden by the variables in specified
input file. The global variable value is updated with the input variable value. Use
caution with this setting; your selection will affect any other workflows that refer
to the same global variable. When set to global, or omitted, the variable value supplied
with the request (through the variable input file or variables array) is ignored and
the current global value is used. The default is global.
No
System String The nickname of the system on which the workflow is to be performed. The nickname
is a unique name for the system to differentiate it from existing systems that have
the same system and sysplex name. The nickname is 1-40 characters long. Valid characters
are alphanumeric characters (A-Z, a-z, and 0-9), hyphens (-), and special characters
($ _ # @). Nicknames are case sensitive, for example SYSTEM1 and System1 are unique
values.
Yes
Variable Input File String The name of an optional properties file that contains values for one or more of the
variables that are defined in the workflow definition file. If the workflow variable
input file resides in a data set member, specify the fully qualified data set name
including the member name. Ensure that the specified data set is cataloged. If the
workflow variable input file resides in a z/OS UNIX file, specify the fully qualified
path name of the file beginning with the forward slash (/) and including the file
name. See the zOSMF documetation, for the format of the variable input file.
No
Variables String A list of one or more variables for this workflow. The variables specified on this
property has precedence over the variables that are specified in the workflow variable
input file. Specify this property as an array of name-value objects.
No
Workflow Definition File String Location of the workflow definition file, which is the primary XML file for the workflow
definition. If the workflow definition file resides in a data set member, specify
the fully qualified data set name including the member name. Ensure that the data
set is cataloged. If the workflow definition file resides in a z/OS UNIX file, specify
the fully qualified path name of the file beginning with the forward slash (/) and
including the file name. For example: /usr/lpp/zosmf/V2R1/samples/workflow_sample_automation.xml.
Yes
Workflow Name String A unique name for the workflow up to 100 characters. The name cannot contain the following
symbols: less-than (<), greater-than (>), or ampersand (&). Each workflow name must
be unique.
Yes

Run Published Software Service Template

Use this step to define the input properties for the Run Published Software Service
template.

Input properties for the Run Published Software Service Template step
Name Type Description Required
Account Info String The account information to use in the JCL JOB statement. The default is the account
information that is associated with the resource pool for the tenant.
No
Domain Name String The domain name for the specified template. This property is required if the user
has consumer authorization to more than one domain with the template name.
No
Input Variables String A list of variable each separated by a new line. Specify each variable in the following
format: name=value.
No
Job Owner String The job owner user ID whose jobs are being queried; the default is the z/OS user ID.
The value is folded to uppercase. The value cannot exceed eight characters.
No
Job Prefix String The prefix to add to the job name prefix. The default value is an asterick(*). The
value is folded to uppercase. The value cannot exceed eight characters.
No
Max Lines String The maximum number of records to display for each output data set. Specify 0 to display
the full content. The default value is 1000.
No
Output DDName Filter String A list of one or more output ddname filters. Separate multiple filters with new lines.
The asterick (*) and question mark (?) wildcards are supported.
No
Print Job Log Boolean Indicates if information is written to the job log file. All jobs submitted during
the workflow execution time are fetched including jobs which are not submitted by
the workflow. To avoid showing jobs not submitted by the workflow, you may configure
z/OSMF workflow to use a unique job name and then use the Job Filter to exclude other
jobs.
No
Print REST log Boolean Indicates if REST call requests and responses are written to the log file. The default
is no.
No
Systems Nicknames String Each string is the nickname of the system upon which to provision the software service
defined by the template. The field is required if the resource pool associated with
the tenant used for this operation is not set up to automatically select a system.
Only one nickname is allowed. If the field is provided it is validated.
No
Template Name String The name of the software services template to run. Yes
Tenant Name String The name of the tenant for the specified template. This property is required if the
user has consumer authorization to more than one tenant in the same domain that contains
the template name.
No
Timeout String The number of seconds to wait. The default value is 120. No
User Data String User data that is passed into the software services registry. Can be specified only
if user-data-id is provided.
No
User Data ID String The ID for the user data specified with user-data. Passed into the software services
registry.
No
Wait For Provision Boolean Indicates to wait for the provision to complete. The default is to wait for the provision
to complete. If this property is not enabled, the value on the Timeout property is
ignored.
No
Write Job Log to Output Boolean If checked, the job log is stored to step output property. The Resource Role property
name is zosmf.workflowJoblog.
No

Software Services Instance Discovery

Use this step to discover all the software instances. Also use to create resources
for each software instance under a root resource, apply the correct role, and set
the properties.

Input properties for the Software Services Instance Discovery step
Name Type Description Required
Query Parameters String A list of one or more query variables. Check the z/OSMF List the software services
instances REST API for a list of valid query parameters
No
Resource String The Resource to configure. No
zOSMF URL String The URL to access the zOSMF REST API. No
zOSMF User String The zOSMF user to use. No
zOSMF User String The zOSMF password to use. No

Start Workflow

Use this step to start a workflow.

Input properties for the Start Workflow step
Name Type Description Required
Job Owner String The user ID of the job owner whose jobs are being queried. The default is the z/OS
user ID. The value is folded to uppercase. The value cannot exceed eight characters.
No
Job Prefix String The value to add as a prefix to the job name. The defaults is and askrick(*). The
value is folded to uppercase. The value cannot exceed eight characters.
No
Max Lines String The maximum number of records to be displayed for each output data set. Specify 0
to display the full content. The default is 1000.
No
Notification URL String A notification URL containing up to 2000 characters. Depending on the requirements
of your application, you might want to receive a notification when the automated step
or steps reach an end state, such as completion or failure. For example, if the application
includes a servlet that is to be given control on completion of the automated steps,
you can optionally specify a notification URL to be posted when automation ends. See
the zOSMF online document for more details.
No
Output DDName Filter String One or more output ddname filters. Separate multiple filters with new lines. Wildcard
* and ? are supported.
No
Perform Subsequent Boolean If the workflow contains any subsequent automated steps, this property indicates whether
z/OSMF is to perform the steps. If you set this property to true z/OSMF attempts to
perform the automated steps. If you set this property to false, z/OSMF attempts to
perform the specified step only. The default is true.
No
Print Job Log Boolean Indicates to print the Job log file. All jobs submitted during the workflow execution
time are fetched including jobs which are not submitted by the workflow. To avoid
showing jobs not submitted by the workflow, you may configure z/OSMF workflow to use
a unique job name and then use the Job Filter to exclude other jobs.
No
Print REST log Boolean Indicates to write REST call requests and responses to the log. The default is no. No
Resolve Conflict By Using String Indicates how variable conflicts are to be handled when the Workflows task reads in
the output file from a step that runs a REXX exec or UNIX shell script. The following
values are valid for this parameter: outputFileValue, existingValue, and leaveConflict.
Specify the outputFileValue value to allow the output file values to override the
existing values. This setting applies to instance variables only. Global variables
are not overridden by variables in the output file. The existingValue value indicate
that existing variables values instead of the output file values. The leaveConflict
value indicates that the automation is stopped and the user must resolve the conflict
manually. The default value is outputFileValue.
No
Step Name String The name of the step at which automation is to begin. If this property is omitted,
automation processing begins with the first step in the workflow.
No
Timeout String The timeout value in seconds for a wait. The default is 120 seconds.. No
Wait For Workflow Boolean Indicates whether to wait for the workflow to complete. The amount of time to wait
is specifiedin the Timeout property. If not on, the value on the Timeout property
is ignored.
No
Workflow Key String The workflow key of the workflow to be started. Yes
Write Job Log to Output Boolean Indicates if the job log file is stored based on the zosmf.workflowJoblog step output
property. The default is no.
No

zOSMF Cloud Provisioning Discovery

Use this step to discover if the zOSMF service is available by checking the URL specified
in zosmf.url agent property. If it is available, the zOSMFService role is assigned
to the resource and the properties are set.

Input properties for the zOSMF Cloud Provisioning Discovery step
Name Type Description Required
zOSMFURL String The URL to access the zOSMF REST API. No
sysUser String The user to use. No
Resource String The resource to configure. No

Roles in the zOSMF plug-in

The plug-in adds these roles automatically to resources. You cannot add these roles
manually.

zOSMFService

Role for resources that represent zOSMF Service.

Properties for the zOSMFService role
Name Type Description
zOS Version String The z/OS operating system level. The Resource Role property name is zosmf.zos_version.
zOSMF API Version String The version of the z/OSMF information retrieval service and the JSON object structure
used for this request. The version sequence starts at 1, and is incremented if the
service or the JSON structure changes. The Resource Role property name is zosmf.api_version.
zOSMF Full Version String The z/OSMF version qualified by a service level. The Resource Role property name is
zosmf.zosmf_full_version.
zOSMF Hostname String The hostname or the IP address of the z/OS system on which z/OSMF is installed. The
Resource Role property name is zosmf.zosmf_hostname.
zOSMF Password Password The zOSMF password associate with the specified user.
zOSMF Port String The port number for SSL encrypted traffic for the active instance of z/OSMF on the
z/OS system. The Resource Role property name is zosmf.zosmf_port.
zOSMF Query String A list of one or more query variables. Check the z/OSMF List the software services
instances REST API for a list of valid query parameters. The Resource Role property
name is zosmf.query.
zOSMF SAF Realm String The realm associated with the system on which z/OSMF is installed. Usually, this is
the sysplex name. The Resource Role property name is zosmf.zosmf_saf_realm.
zOSMF URL String The URL to access the zOSMF REST API. The Resource Role property name is zosmf.url.
zOSMF User String The zOSMF user to use. The Resource Role property name is zosmf.user.
zOSMF Version String The z/OSMF level. The Resource Role property name is zosmf.zosmf_version.

zOSMFSoftwareInstance

Role for resources that represent a software instance.

Properties for the zOSMFSoftwareInstance role
Name Type Description
Created By String The user ID that created the object.
Created On String The time the object was created. The time is in the ISO8601 format. The Resource Role
property name is instance.created-time.
Domain Name String The name of the domain. The Resource Role property name is instance.domain-name.
External Name String The external name of the software services instance. The Resource Role property name
is instance.external-name.
Last Action Name String The name of the last action that was performed. The Resource Role property name is
instance.last-action-name.
Last Action State String The state of the last action that was performed. The Resource Role property name is
instance.last-action-state.
Object ID String The object ID for the software services instance. The Resource Role property name
is instance.object-id.
Object Name String The object name for the software services instance. The Resource Role property name
is instance.object-name.
State String The current state of the software. The Resource Role property name is instance.state.
Tenant Name String The name of the tenant. The Resource Role property name is instance.tenant-name.
Type String The type of software instance.