Get a software services template
Use this operation to retrieve a software services template from the catalog.
HTTP method and URI path
GET /zosmf/provisioning/rest/<version>/scc/<object-id>In this request:
- <version>
- Is the URI path variable that identifies the version of the z/OSMF software services template service. The following value is valid: 1.0.
- <object-id>
- Identifies the software services template to retrieve.
Query parameters
None.
Description
This operation retrieves a software services template from the catalog.
On successful completion, the operation returns HTTP status code 200 (OK), indicating that the request resulted in a software services template being retrieved. A response body is provided, as described in Response content
Request content
None.
Authorization requirements
The user's z/OS user ID must be defined as a landlord, domain administrator, domain approver, or template approver.
The user’s z/OS user ID must have READ access to the following resource profile in the ZMFAPLA class: <SAF-prefix>.ZOSMF.PROVISIONING.SOFTWARE_SERVICES.
HTTP status codes
On successful completion, HTTP status code 200 (OK) is returned.
Response content
On successful completion, the service returns a response body, which contains a JSON object with details about the software services template. Table 1 lists the fields in the JSON object.
| Field | Type | Description |
|---|---|---|
| base-object-id | String | The object ID that is associated with all of the versions of the software services template. |
| generated-name | String | Generated name for the software services template. |
| name | String | The name associated with the software services template. |
| version | String | Version of the software services template. |
| owner | String | User ID of the software services template owner. |
| state | String | Indicates the status of the software services template. See State values |
| description | String | Description of the software services template. |
| tenants | Array of Strings | Each string represents a tenant that the template is associated with. |
| domain-name | String | The domain the template is associated with. |
| approvals | Array of objects | Array of Approval-Object containing information about the approvals associated with this software services template. See Table 2. |
| action-definition-file | String | Location of the action definition file. |
| action-definition-file-original-source | String | Original user specified location of the action definition file |
| action-definition-file-original-timestamp | String | Last-modified time stamp for when the original action definition file source was specified, in ISO 8601 format. |
| actions | Array of objects | Array of Action-Object containing information about the actions associated with the template. See Table 3. |
| software-id | String | A short, arbitrary, value that identifies the software that is being provisioned. |
| software-name | String | Name of the software that is being provisioned. |
| software-type | String | Type of software that is being provisioned. |
| software-version | String | Version of the software that is being provisioned. |
| workflow-definition-file | String | Location of the workflow definition file, the primary XML file that defines the workflow |
| workflow-definition-file-original-source | String | Original user-specified location of the workflow definition file. |
| workflow-definition-file-original-timestamp | String | The last-modified time stamp for when the original workflow definition file source was specified, in ISO 8601 format. |
| workflow-id | String | A short, arbitrary value that identifies the workflow. |
| workflow-vendor | String | Name of the vendor that provided the workflow definition file. |
| workflow-version | String | Version of the workflow definition file. |
| workflow-variable-input-file | String | Location of the workflow variable input file, an optional properties file used to specify in advance the values for one or more of the variables that are defined in the workflow definition file. |
| workflow-variable-input-file-original-source | String | The original user-specified location of the workflow variable input file. |
| workflow-variable-input-file-original-timestamp | String | The last-modified time stamp for when the original variable input file source was specified, in ISO 8601 format. |
| workflow-clean-after-provisioned | Boolean | Indicates if a workflow that performs provisioning should be automatically deleted after it completes successfully. The value is true to delete, false to keep. The default value, if none is specified, is false, which keeps the workflow. |
| prompt-variables | Array of objects | Array of prompt variable objects containing information about the variables that are expected to be prompted for in preparation for running the software services template. See Table 5. |
| at-create-variables | Array of strings | Array of strings that name the variables that are either prompt variables (variables that are expected to be prompted for in preparation for running the software services template), or required variables (variables for which a value is required when the software services template is run), or both. |
| consumer-documentation-file | String | Location of the original file that provides information for consumers about the template. |
| consumer-documentation-type | String | Type of the consumer documentation file, either text or pdf. This is required if consumer-documentation-file is specified. |
| admin-documentation-file | String | Location of a file that provides information for administrators about the template. |
| admin-documentation-type | String | Type of the administrator documentation file, either text or pdf. This is required if admin-documentation-file is specified. |
| create-time | String | Time that this object was created, in ISO 8601 format. |
| create-by-user | String | User who created this object. |
| last-modified-time | String | The last time this object was updated, in ISO 8601 format. |
| last-modified-by-user | String | User who last updated this object. |
State values
- archived
- The entry is hidden from consumers. You can make it available again with the Publish action.
- corrupted
- The contents of the software services template are missing or incorrect. Delete the template.
- draft
- The entry is in the edit state and visible only to the owner and the administrator. No approvals are required for this template. The entry can be tested with the Test a software services template API.
- draft_approved
- The software services template is in edit state and all the approvals that are associated with the template and the respective runAs user IDs have been received. The entry can be tested with the Test a software services template API.
- draft_pending_approvals
- The software services template is in edit state and one or more associated approvals has not been approved. The entry cannot be tested (with the Test a software services template API) in this state.
- draft_missing_required_approver
- One or more of the definition files contains a runAsUser element without a corresponding approver element. Either an approver element must be added for the runAsUser element, or a domain or general approver must be added for the software services template. The entry cannot be tested (with the Test a software services template API) in this state.
- pending_security_update
- Permission to access the software services template is being processed. No API requests are allowed for the software services template until the security processing is complete.
- published
- The entry is locked and visible to consumers.
- security_update_failed
- Security access setup related to the software services template failed. Only the view and delete API requests a available.
| Field | Type | Description |
|---|---|---|
| status | String | Status of the approval for this object: pending, approved, or rejected. |
| comment | String | Comment associated with the change in status from pending to either approved or rejected. |
| description | String | Additional detail that is provided if the approval is for a workflow definition that is associated with the action definition, for example, This workflow definition is associated with the <action-name> action. |
| user-ids | Array of strings | Each string in the array is a user ID that can approve the template, workflow step, or action. Any one of the user IDs in the array can approve or reject. The last action takes precedence. |
| status-update-by | String | User ID that performed the last approve or reject action for this approval object. |
| time-of-update | String | The last time this object was updated, in ISO 8601 format. |
| run-as-user | String | The runAsUser user ID that the approval object is for. Only applicable when the type is action_definition or step_definition. |
| type | String | Type of approval object: general, domain, action_definition, or step_definition. |
| object-id | String | Unique object ID representing this approval object. |
| workflow-file | String | Workflow file definition associated with this runAsUser user ID. |
| variable-input-file | String | Variable input file associated with this runAsUser user ID. |
| step-name | String | Workflow file definition step associated with this runAsUser user ID. |
| called-by-step-name | String | Step in the parent workflow definition that called the workflow definition file that generated the approval object. Used if the definition file that generated the approval object is a callable workflow. |
| called-by-workflow-file | String | Workflow definition that called the workflow definition file that generated the approval object. Used if the definition file that generated the approval object is a callable workflow. |
| actions-file | String | Actions file definition associated with this runAsUser user ID. |
| action-name | String | Action that is defined in the actions file associated with this runAsUser user ID. |
| Field | Type |
|---|---|
| name | String |
| type | String |
| is-deprovision | String. The value must be either true or false. |
| command | String |
| command-run-as-user | String |
| command-sol-key | String |
| command-unsol-key | String |
| command-detect-time | String |
| workflow-definition-file | String |
| workflow-variable-input-file | String |
| workflow-variables | Variable[] |
| instructions | String |
| prompt-variables | The prompt variable objects that are associated with the action. |
| Field | Type |
|---|---|
| name | String |
| value | String |
| visibility: public or private | String |
| Field | Type | Description |
|---|---|---|
| name | String | Name of the property. |
| value | String | Current value for the property. |
| required | boolean | Indicates whether the variable value is required during the workflow create process. |
| label | String | Short label for the UI widget. |
| description | String | Explanation of what the variable is used for and perhaps what the syntactic requirements are. |
| abstract | String | Brief description of the variable for the UI widget. |
| type | String | Type of the variable element: boolean, string, integer, decimal, time, date. |
| must-be-choice | boolean | Indicates whether the value must come from the provided choices. |
| choices | Array of Strings | Contains allowable choices for the value of the variable. |
| regex | String | Standard regular expression that constrains the variable value. |
| multi-line | boolean | Indicates whether the value requires a multi-line text box. |
| min | String | For a string type, indicates the minimum string length of the value. For all other types, indicates the minimum value required. |
| max | String | For a string type, indicates the maximum string length of the value. For all other types, indicates the maximum value required. |
| places | String | Maximum number of decimal places that can be specified for a variable of type decimal. |
| error-message | String | Default error message associated with an incorrect value. |
Fields of type String default to null.
Example HTTP interaction
In Figure 1, a request is
submitted to retrieve a software services template.
Figure 1. Sample request to retrieve a software services template
GET https://localhost:4444/zosmf/provisioning/rest/1.0/scc/5ccbad22-94fd-4b31-bb2b-95aa8602cc48The following is the response body for the example GET request.
{
"name": "mqCBA",
"version": "1",
"owner": "domadmin",
"state": "published",
"description": "This workflow provisions an MQ for z/OS Queue Manager",
"tenants": [...],
"actions": [...],
"approvals": [],
"tested": false,
"generated-name": "mqCBA.1.default",
"domain-name": "default",
"action-definition-file": "definition/qmgrActions.xml",
"action-definition-file-original-source": "/users/gg/mqCBA/definition/qmgrActions.xml",
"action-definition-file-original-timestamp": "2016-11-18T20:00:42Z",
"software-id": "5655-W97",
"software-name": "IBM MQ for z/OS",
"software-type": "QMgr",
"software-version": "V8.0.0",
"workflow-definition-file": "definition/provision.xml",
"workflow-definition-file-original-source": "/users/gg/mqCBA/definition/provision.xml",
"workflow-definition-file-original-timestamp": "2016-11-18T20:03:47Z",
"workflow-id": "ProvisionQueueManager",
"workflow-vendor": "IBM",
"workflow-version": "1.0.1",
"workflow-variable-input-file": "definition/workflow_variables.properties",
"workflow-variable-input-file-original-source": "/users/gg/mqCBA/definition/workflow_variables.properties",
"workflow-variable-input-file-original-timestamp": "2016-11-18T20:00:42Z",
"prompt-variables": [],
"at-create-variables": [],
"workflow-clean-after-provisioned": true,
"security-wf-info": null,
"create-time": "2016-11-18T20:00:43.504Z",
"created-by-user": "domadmin",
"last-modified-by-user": "domadmin",
"last-modified-time": "2016-11-18T20:04:50.913Z",
"admin-documentation-file-original-source": "/users/gg/mqCBA/documentation/admin-mqaas_readme.pdf",
"admin-documentation":
"/zosmf/provisioning/rest/1.0/scc/5b0c3367-b856-4727-99ac-f9a79c9abf28/documentation/admin",
"admin-documentation-type": "pdf",
"consumer-documentation-file-original-source":
"/users/gg/mqCBA/documentation/consumer-workflow_variables.properties",
"consumer-documentation":
"/zosmf/provisioning/rest/1.0/scc/5b0c3367-b856-4727-99ac-f9a79c9abf28/documentation/consumer",
"consumer-documentation-type": "text",
"base-object-id": "c0e4d08f-f046-4a79-8a15-6981743d07ed",
"admin-documentation-mime-type": "application/pdf",
"consumer-documentation-mime-type": "text/plain"
}