Get the variables for a software services instance

HTTP method and URI path

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

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

You can specify the following query parameter on this request:

name: Use this optional parameter to specify variable names. You can use regular expressions.
visibility: Use this optional parameter to specify the visibility of the variables.

Description

This operation retrieves the variables for a software services instance.

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

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 that the software services instance is associated with, , if the option has been set in the resource pool, through the Resource Management task of z/OSMF, to allow members of the tenant to access and run actions for software instances
A domain administrator of the software services instance.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 200 (Normal) is returned and the response body is provided, as described in Response content.

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

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

Response content

On successful completion, the response body contains a JSON object consisting of an array of the variable names and values for the software services instance, described in the tables that follow.

Table 2. Get variables request: Format of the variables object
Field name	Type	Description
`variables`	Array of variables	Variables for the software services instance. Refer to Table 3

Table 3. Variable structure
Field	Type	Description
name	String	Name of the variable.
description	String	Description of the variable.
value	String	Value of the variable.
visibility	String. The value must be public or private.	Visibility of the variable.
update-registry	String. The value must be true or false. The default is false.	Indicates whether to update the variables in the instance from the workflow.

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

Table 4. 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 variables for a software object. 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 variables

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

An example of the response is shown in the figures that follow.

Figure 2. Sample response from a get software services instance variables request


{
  "variables": [
    {
      "name": "INS",
      "description": "This is some text that describes the variable."
      "value": "Instructions",
      "visibility": "public",
      "update-registry": "false"
    }
  ]
}