Get a published software service template
Use this operation to retrieve a published software service template from the catalog.
HTTP method and URI path
GET /zosmf/provisioning/rest/<version>/psc/<existing-entry-name>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.
- <existing-entry-name>
- Identifies the software services template to be retrieved.
Query parameters
You can specify the following query parameter on this request. Objects matching all query
parameters are returned.
- domain-name
- Optional, string, specifies the domain name.
Description
This operation retrieves a published software service template from the catalog.
On successful completion, HTTP status code 200 (OK) is returned, 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 ID must be in a tenant that the template is associated with, or be an approver.
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. See Table 2, Table 3, Table 4, and Table 5.
| 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. It is always published. The entry is locked and visible to consumers. |
| 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 3. |
| 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 4. |
| 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 2. |
| 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. |
| 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.
| 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 provided if the approval is for a workflow definition that's 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. Any one of the user IDs in the array can approve or reject the item. The action of the last ID takes precedence. |
| status-update-by | String | The 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. This applies only when the type is action_definition or step_definition. |
| type | String | Type of approval: general (for the template), domain, action_definition, step_definition |
| object-id | String | Unique object id representing this approval object. |
| workflow-file | String | Workflow file definition associated with this runAsUser user ID. Null if the user ID is not associated with a workflow definition step or is a general approval. |
| variable-input-file | String | Variable input file associated with this runAsUser user ID. Null if the user ID is not associated with a workflow definition step or is a general approval. |
| step-name | String | Workflow file definition step associated with this runAsUser user ID. Null if the user ID is not associated with a workflow definition step or is a general approval. |
| 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. Null if the user ID is not associated with an action or is a general approval. |
| action-name | String | Action defined in the actions file associated with this runAsUser user ID. Null if the user ID is not associated with an action or is a general approval. |
| Field | Type |
|---|---|
| name | String |
| type | String |
| command | 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 |
Example HTTP interaction
In Figure 1, a request is
submitted to retrieve a software services template.
Figure 1. Sample request to get a software services template
GET https://localhost:4444/zosmf/provisioning/rest/1.0/psc/bringUpDB2{
"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"
}