Get the contents of a software services instance

You can use this operation to retrieve the contents of a software services instance.

HTTP method and URI path

GET /zosmf/provisioning/rest/<version>/scr/<object-id>

In this request, the URI path variables are described, as follows:

<version> identifies the version of the provisioning service. The following value is valid: 1.0.
<object-id> identifies the software services instance to be retrieved.

Query parameters

None.

Description

This operation retrieves the properties of a software services instance.

On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 2.

Authorization requirements

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.

For catalog registry type objects, the user issuing the request must be at least one of the following:

The owner of the software services instance
A member of the tenant of the software services instance
A member of a tenant that was given access to the software services instance
A domain administrator of the software services instance.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned and the response body is provided, as described in Table 2.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body that provides the reason code that is indicated and associated error message.

Table 1. HTTP error response codes for a get software services instance contents request
HTTP error status code	Description
`HTTP 401 Unauthorized`	The requester user ID is not authorized for this request.
`HTTP 404 Not found`	The specified software services instance was not found; the software services instance does not exist.

Response content

On successful completion, the response body is a JSON object that contains the retrieved data. Table 2 lists the fields in the JSON object.

Table 2. JSON object that is returned for a get software services instance property request
Field	Type	Description
object-id	String	The object-id for the software services instance
object-name	String	The object-name for the software services instance
type	String	Type of the software
registry-type	String	Type of registry object: catalog or general
external-name	String	External name of the software services instance
system-nickname	String	The name of the system entry in the system entry table of the software.
system	String	System on which the software is provisioned
sysplex	String	Sysplex on which the software is provisioned
vendor	String	Vendor of the software
version	String	Version of the software
description	String	Description for the software
owner	String	The user ID that identifies the owner of the software
provider	String	The user ID that identifies the provider of the software
catalog-object-id	String	The identifier of the template that is used when partitioning the software represented by this instance. Only valid when registry-type is catalog.
catalog-object-name	String	The name of the template that was used when partitioning the software represented by this instance.
workflow-key	String	The workflow key that is associated with provisioning the software.
workflow-clean-after-provisioned	String	The Indication of whether the workflow instance used to provision this instance will be removed after the workflow is completed. Must be true or false.
state	String	The current state of the software: being-initialized being-provisioned provisioned being-deprovisioned deprovisioned provisioning-failed deprovisioning-failed
quality-attributes	String	The quality attributes of the software
actions	Action[]	The actions for the software. Table 3
variables	Variable[]	The variables for the software. See Table 4.
created-time	String	The time the object was created. The time is in the ISO8601 format.
last-modified-time	String	The time the object was updated. The time is in the ISO8601 format.
created-by-user	String	The user ID that created the object
last-modified-by-user	String	The user ID that last updated the object
last-action-name	String	The name of the last action that was performed.
last-action-object-id	String	The action ID of the last action that was performed.
last-action-state	String	The state of the last action that was performed.
user-data-id	String	The user data ID.
user-data	String	The user data.
domain-id	String	The domain ID.
tenant-id	String	The tenant ID.
domain-name	String	The name of the domain.
tenant-name	String	The name of the tenant.
ssin	String	Software service instance name, used in generating names for software services instances.

Table 3. Action structure
Field	Type	Description
name	String	The name of the action. If the name of the action is deprovision, the action is for deprovisioning the software. You can indicate that the action is for deprovisioning either by setting the is-deprovision field to `true` or by naming the action `deprovision`.
type	String	The type of the action. The value must be one of the following: command workflow instructions
is-deprovision	String	Indicates if the action deprovisions the software, as follows: If true, the action deprovisions the software. If false or not set, the action does not deprovision the software. This is overriden if the value of the name field is deprovision.
command	String	For command type actions, the command.
command-run-as-user	String	For command type actions, if provided, the user ID to be used when the command is run. This is not valid when the registry-type is general.
command-sol-key	String	For command type actions, if provided, the key to search for in the solicited messages command response.
command-unsol-key	String	For command type actions, if provided, the key to search for in the unsolicited messages.
command-detect-time	String	For command type actions, if provided, the time in seconds to detect for the command-unsol-key in the unsolicited messages. Also, the minimum time before a command response is checked for after the command is submitted for execution. If not provided, the default command-detect-time is 15 seconds when the command-unsol-key is specified or 10 seconds when the command-unsol-key is not specified.
workflow-definition-file	String	For workflow type actions, the workflow definition file.
workflow-variable-input-file	String	For workflow type actions, if provided, the workflow variable input file.
workflow-variables	Variable[]	For workflow type actions, if provided, the workflow variables.
instructions	String	For instruction type actions, the instructions.
prompt-variables	PromptVariable[]	For workflow type actions, if provided, the prompt variables, which are the variables that are expected to be prompted for in preparation for running the software services template. See Table 5.
at-create-variables	String[]	For workflow type actions, if provided, these are the names of 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. These are the only variables allowed on input-variables for the do action operation.

Table 4. Variable structure
Field	Type
name	String
value	String
visibility	String. The value must be public or private.

Table 5. Prompt variable structure
Field	Type
name	String
value	String
abstract	String
description	String
error-message	String
label	String
max	String
min	String
milti-line	Boolean
must-be-choice	Boolean
choices	String List
places	String
regex	String
required	Boolean
type	String

If a failure occurs, the response body contains a JSON object with a description of the error.

Table 6. Response from a request failure
Field	Type	Description
httpStatus	Integer	HTTP status code.
requestMethod	String	HTTP request method.
requestUri	String	HTTP request URI.
messageID	String	Message identifier for the error.
messageText	String	Message text describing the error.
additionalInfo	String	Additional information describing the error.
debug	String	Debug information about for the error.

Example HTTP interaction

In the following example, the GET method is used to retrieve information about a software services instance. The software services instance is uniquely identified by the software services instance key, which is represented by the following string value: 76963ea5-81a4-42d6-99d6-f3e19747cf61.

Figure 1. Sample request to get software services instance properties

GET /zosmf/provisioning/rest/ 1.0/scr/76963ea5-81a4-42d6-99d6-f3e19747cf61

The following is an example of the response.

Figure 2. Sample response from a get request (part 1 of 2)

{
  "type":"DB2",
  "system-nickname":"SYSTEM1",
  "system":"SY1",
  "sysplex":"PLEX1",  
  "vendor":"IBM",
  "version":"V5R10",
  "description":"DB2 for test1",
  "owner":"ZOSMFAD",  
  "provider":"ZOSMFAD",
  "state":"provisioned",
  "object-id":"c7156cbf-e1ce-4f05-b7c7-96d73dfb94f9",
  "object-name":"DB2_1",
  "object-uri":"/zosmf/provisioning/rest/1.0/scr/c7156cbf-e1ce-4f05-b7c7-96d73dfb94f9",
  "registry-type":"catalog",
  "external-name":"DB2B",
  "catalog-object-id":"9f7c659e-38f5-4585-b9f9-9cd448bf9cc3",
  "catalog-object-name":"DB2template1",
  "quality-attributes":"123456789ABCDEF0",  
  "user-data":"my data",
  "user-data-id":"udid1",
  "domain-id":"izu$0",
  "tenant-id":"izu$002",
  "domain-name":"default",
  "tenant-name":"default",
  "ssin":"SSIN1",
  "workflow-key":"02e1ec78-e0db-482b-8013-3d435b52e2e3",
  "workflow-clean-after-provision":"true",
  "variables":
  [
  {
    "name":"IACTION_NAME",
    "value":"Instructions1",
    "visibility":"public"
  },
  {
    "name":"COMMAND1",
    "value":"d a,l",
    "visibility":"public"
  },
  {
    "name":"C_DETECT_TIME",
    "value":"25",
    "visibility":"public"
  },
  {
    "name":"C_SOL_K",
    "value":"VLF",
    "visibility":"public"
  },
  {
    "name":"C_UNSOL_K",
    "value":"CSV",
    "visibility":"public"
  }
 ],
  "actions":
  [
  {
    "name":"Instructions1",
    "type":"instructions",
    "is-deprovision":"false",
    "command":null,
    "instructions":"These are the instructions for the ${IACTION_NAME} action.",
    "command-run-as-user":null,
    "command-sol-key":null,
    "command-unsol-key":null,
    "command-detect-time":null,
    "workflow-definition-file":null,
    "workflow-variable-input-file":null,
    "workflow-clean-after-complete":"null",
    "variables":null,
    "at-create-variables":null,
    "prompt-variables":null 
  },

Figure 3. Sample response from a get request (part 2 of 2)

{
    "name":"command1",
    "type":"command",
    "is-deprovision":"false",
    "command":"${COMMAND1}",
    "instructions":null,
    "command-run-as-user":"IBMUSER",
    "command-sol-key":"${C_SOL_K}",
    "command-unsol-key":"${C_UNSOL_K}",
    "command-detect-time":"${C_DETECT_TIME}",
    "workflow-definition-file":null,
    "workflow-variable-input-file":null,
    "workflow-clean-after-complete":"null",
    "variables":null,
    "at-create-variables":null,
    "prompt-variables":null
  },
  {
    "name":"deprovision",
    "type":"instructions",
    "is-deprovision":"true",
    "command":null,
    "instructions":"Do the deprovision manually.",
    "command-run-as-user":null,
    "command-sol-key":null,
    "command-unsol-key":null,
    "command-detect-time":null,
    "workflow-definition-file":null,
    "workflow-variable-input-file":null,
    "workflow-clean-after-complete":"null",
    "variables":null,
    "at-create-variables":null,
    "prompt-variables":null
  }
  ],
  "created-time":"2015-12-24T15:18:51.903Z",
  "last-modified-time":"2015-12-24T15:23:43.071Z",
  "created-by-user":"ZOSMFAD",
  "last-modified-by-user":"ZOSMFAD",
  "last-action-name": "Instructions1",
  "last-action-object-id": "672c54bd-6c2b-49fd-ad3b-2ec027f54089",
  "last-action-state": "complete"
}