Start of change

List the software services instances

You can use this operation to list the software services instances in the software services registry.

HTTP method and URI path

GET /zosmf/provisioning/rest/<version>/scr
In this request, the URI path variable is as follows:
  • <version> identifies the version of the provisioning service. The following value is valid: 1.0.

Query parameters

You can specify the following query parameter on this request. Objects matching all query parameters are returned.
type
Optional, specifies the type of the software.
registry-type
Optional, specifies the type of the registry object: catalog or general.
object-name
Optional, regular expression, specifies the name for the software services instance.
external-name
Optional, regular expression, specifies the external name of the software.
system
Optional, specifies the system on which the software is provisioned.
sysplex
Optional, specifies the sysplex on which the software is provisioned.
vendor
Optional, specifies the vendor of the software.
owner
Optional, specifies the user ID that identifies the owner of the software.
provider
Optional, specifies the user ID that identifies the provider of the software.
state
Optional, specifies the current state of the software:
  • being-initialized
  • being-provisioned
  • provisioned
  • being-deprovisioned
  • deprovisioned
  • provisioning-failed
  • deprovisioning-failed
catalog-object-id
Optional, specifies the catalog object ID associated with the creation of this software services instance.
user-data-id
Optional, specifies the ID for the user data.
domain-id
Optional, specifies the ID of the domain.
tenant-id
Optional, specifies the ID of the tenant.
tenant-name
Optional, regular expression that specifies the name of the tenant.
domain-name
Optional, regular expression that specifies the name of the domain.
If you specify no query parameters, then all objects are returned.

Description

This operation returns the object ID and a subset of fields for software services instances.

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 that issues the request must be at least one of the following for a software services instance to be returned in the list:
  • The owner of the software services instance
  • A member of the tenant of 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 Response content.

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 list software services instances request
HTTP error status code Description
HTTP 400 Bad request The request contained incorrect parameters.
HTTP 401 Unauthorized The requester user ID is not authorized for this request.

Response content

On successful completion, the response body contains a JSON object, named scr-list, of registry objects that consist of a subset of the fields for all software services instances matching the query. Table 2 lists the fields in the JSON object.

Table 2. JSON object that is returned for a list software services instances 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 The type of the software, for example, the subsystem name, such as DB2 or MQ
registry-type String Type of registry object: catalog or general
external-name String External name of the software services instance
catalog-object-id String The identifier of the software services template used when partitioning the software represented by this software services instance. Valid only when the value for registry-type is catalog.
catalog-object-name String The name of the template that was used when partitioning the software represented by this instance.
system String Name specified for the system on the SYSNAME parameter in the IEASYSxx parmlib member.
sysplex String Name of the sysplex where the z/OS® system is a member. The name is the value specified for the SYSPLEX parameter of the cross-system coupling facility (XCF) couple data set format utility.
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
state String The current state of the software:
  • being-initialized
  • being-provisioned
  • provisioned
  • being-deprovisioned
  • deprovisioned
  • provisioning-failed
  • deprovisioning-failed
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-updated-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.
tenant-id String The tenant ID.
domain-id String The domain ID.
tenant-name String The name of the tenant.
domain-name String The name of the domain.

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

Table 3. 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 Figure 1, the GET method is used to list the software services instances.

Figure 1. Sample request to list software services instances
GET /zosmf/provisioning/rest/ 1.0/scr

Figure 2 shows the response.

Figure 2. Sample response from a list software services instances request 
{"scr-list": 
                          {   
                          "object-id":"76963ea5-81a4-42d6-99d6-f3e19747cf61",   
                          "object-name":"DB2_1",    
                          "system":"SYS1",   
                          "sysplex":"PLEX1",    
                          "type":"DB2",   
                          "vendor":"IBM",    
                          "version":"V1R0",   
                          "owner":"admin1",    
                          "provider":"provd1",   
                          "registry-type":"catalog",    
    "catalog-object-id":"9f7c659e-38f5-4585-b9f9-9cd448bf9cc3",
    "catalog-object-name":"DB2template1",
                          "state":"provisioned",   
    "user-data-id":"udid1",
                          "description":"DB2 for test1",   
                          "created-time":"2015-06-08T14:32:42.551Z",   
                          "last-modified-time":"2015-06-08T14:58:12.452Z",   
                          "created-by-user":"admin1",   
    "last-modified-by-user":"admin1",
    "last-action-name": "Instructions1",
    "last-action-object-id": "672c54bd-6c2b-49fd-ad3b-2ec027f54089",
    "last-action-state": "complete",
    "domain-id":"izu$0",
    "tenant-id":"izu$002",
    "tenant-name":"default", 
    "domain-name":"default"
                          },  
                          {   
                          "object-id":"cb98c8b1-9753-4e5f-86cb-169565b4f606",   
                          "object-name":"DB2_2",    
                          "system":"SYS1",   
                          "sysplex":"PLEX1",    
                          "type":"DB2",   
                          "vendor":"IBM",    
                          "version":"V1R0",   
                          "owner":"admin1",    
                          "provider":"provd1",   
                          "registry-type":"catalog",   
    "catalog-object-id":"9f7c659e-38f5-4585-b9f9-9cd448bf9cc3",
   "catalog-object-name":"DB2template1",
                          "state":"being-provisioned",    
    "user-data-id":"udid2",
    "description":"DB2 for test2",
                          "created-time":"2015-06-08T17:26:17.128Z",   
                          "last-modified-time":"2015-06-08T17:26:17.128Z",   
                          "created-by-user":"admin1",   
    "last-modified-by-user":"admin1",
    "last-action-name": "Instructions2",
    "last-action-object-id": "472c54bd-6c2b-49fd-ad3b-2ec027f54080",
    "last-action-state": "complete",
    "domain-id":"izu$0"
    "tenant-id":"izu$002"
    "tenant-name":"default",
    "domain-name":"default"
                          }
}

Parent topic: Software services instance services
End of change