Software services template services

The software services template services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to create and manage software services templates, which can be used to provision z/OS software in support of IBM Cloud Provisioning and Management for z/OS.

For information about cloud provisioning, including a description of the roles, see Cloud provisioning services.

The basic procedure for provisioning software is:

Define domains and tenants. See Resource management services.
Create a template, specifying the workflow, action and variables files that were provided by the software vendor.
The template is added to the software services catalog.
Add the template to a tenant.
Modify the template as needed.
Approve any approval records. 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 (a runAsUser ID). They can also be defined for the template in general, and for a domain.
Test the template and ensure that it successfully creates an instance, that is, that it provisions the software and that the actions defined for the instance perform as expected. Optionally, clean up the results of your test, that is, deprovision and remove the instance that you created by testing the template.
Publish the template to make it available to consumers.
Run the template to create a software instance.

Table 1 lists the operations that the software services template services provide.

Published software service template services describes the REST APIs for working with published software services templates, for example, for running a template to create an instance.

Software services instance services describes the REST APIs for working with software services instances.

Software services template

Table 1. z/OSMF software services template services: operations summary
Operation name	HTTP method and URI path
Create a software services template	`POST /zosmf/provisioning/rest/<version>/scc`
Create a new version of a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/create_new_version`
Create a new software services template based on an existing one	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/create_based_on`
Modify a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>`
Delete a software services template	`DELETE /zosmf/provisioning/rest/<version>/scc/<object-id>`
List the software services templates	`GET /zosmf/provisioning/rest/<version>/scc`
Get a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>`
Get software services template documentation	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/documentation/admin GET /zosmf/provisioning/rest/<version>/scc/<object-id>/documentation/consumer`
Get prompt variables for a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/prompt-variables`
Get source information for a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/sources`
Publish a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/publish`
Test a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/test`
Refresh a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/refresh`
Archive a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/actions/archive`
Add an approval for a software services template	`POST /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals`
Get an approval for a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals/ <approval-object-id>`
List the approvals for a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals`
Approve an approval record for a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals/ <approval-object-id>/actions/approve`
Reject the use of your user ID with a software services template	`GET /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals/ <approval-object-id>/actions/reject`
Delete an approval for a software services template	`DELETE /zosmf/provisioning/rest/<version>/scc/<object-id>/approvals/ <approval-object-id>`

Authorization requirements

Use of the software services template services API requires the client to be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

In addition, the user’s z/OS user ID may need access to other resources, including those that define roles such as the landlord and domain administrator. The specific requirements for each software services template service are described in the topic for that service. For an overview of the security requirements for cloud provisioning roles, see Authorization requirements. For details, see IBM z/OS Management Facility Configuration Guide.

Error response content

For the 4nn HTTP error status codes, additional diagnostic information beyond the HTTP status code is provided in the response body for the request. This information is provided in the form of a JSON object containing the following fields:

Table 2. Response from a software services template request failure
Field	Type	Description
`http-status`	String	HTTP status code.
`request-method`	String	HTTP request method.
`request-uri`	String	HTTP request URI.
`reason`	String	HTTP status reason code.
`message`	String	Message describing the error.
`detailed-message`	String	Message describing the error in more detail.
`debug`	String	Debug information about for the error.

Error logging

Errors from the software services template services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM Support, if required. For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.

HTTP status codes

The following HTTP status codes are valid:

HTTP 200 OK: The request succeeded. A response body is provided, which contains the results of the request.
HTTP 201 Created: The request succeeded and resulted in the creation of an object.
HTTP 202 Accepted: The request was successfully validated and is performed asynchronously.
HTTP 204 No content: The request succeeded, but no content is available to be returned.
HTTP 400 Bad request: The request contained incorrect parameters.
HTTP 401 Unauthorized: The request cannot be processed because the client is not authorized. This status is returned if the request contained an incorrect user ID or password, or both. Or, the client did not authenticate to z/OSMF by using a valid WWW-Authenticate header.
HTTP 404 Not found: The requested resource does not exist.
HTTP 409 Request conflict: The request cannot be processed because of conflict in the request, such as an edit conflict between multiple updates.

Related information

The publish operation locks the template, preventing any further modification, and creates a public copy of it. To work with a published software services template, use the REST APIs that are described in Published software service template services.

The run operation for a published template creates a workflow, starts the workflow, and creates a corresponding software services instance in the software services registry. To work with a software services instance, use the REST APIs described in Software services instance services.