List the tenants

Use this operation to list the tenants that are defined for IBM Cloud® Provisioning and Management for z/OS®.

HTTP method and URI path

GET /zosmf/resource-mgmt/rest/<version>/tenants/

In this request:

<version>: Is the URI path variable that identifies the version of the z/OSMF resource management service. The following value is valid: 1.0.

Query parameters

None.

Description

This operation lists the tenants that are defined for IBM Cloud Provisioning and Management for z/OS.

On successful completion, HTTP status code 200 (OK) is returned, and a response body is returned. See Response content.

Request content

None.

Authorization requirements

The user must be the domain administrator, or a consumer in the tenant.

For more information, see Resource management services.

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned.

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 tenants request
HTTP error status code	Description
`HTTP 404 Not found`	The domain does not exist.
`HTTP 500 Internal server error`	The server encountered an error. See the response body for a JSON object with information about the error.

Response content

On successful completion, the service returns a response body, which contains a JSON object with details about the tenants. See Table 2.

Table 2. Response from a list tenants request
Field	Type	Description
tenant-list	Array	Information about the tenants that are defined. See Table 3.

Table 3. Tenant list
Field	Type	Description
tenant-id	String	Generated ID for the tenant.
tenant-name	String	Descriptive name for the tenant.
tenant-shared-rdp-id	String	The ID of the shared resource pool that is associated with this tenant. It is empty until a shared resource pool is created. The resource pool ID suffix ZZ is reserved for the shared resource pool of the tenant. Dedicated resource pools cannot have ZZ as an ID suffix.
tenant-domain-id	String	Generated ID for the domain to which the tenant belongs.
tenant-domain-name	String	Descriptive name of the domain to which the tenant belongs.
tenant-templates	Array of Strings	Array that describes the templates that are associated with dedicated resource pools. See Table 3. For templates that are associated with shared resource pools, see the rdp-shared-template-name-list field in a Get resource pool request.
tenant-consumer-list	Array of Strings	Consumer user IDs for the tenant.
object-uri	String	URI of the newly created object.
tenant-description	String	Description of the tenant.
tenant-metering-capping-properties	JSON Object	Properties of tenant capping: tenant-capping-enabled Indicates if capping for the tenant is enabled. Values are true or false. tenant-metering-enabled Indicates if metering for the tenant is enabled. Values are true or false. tenant-cpu-cap-type Indicates the type of capping for the tenant. Values are: lpar-share-percentage Percentage of the LPAR share in the general purpose processor pool. service-unit Unweighted CPU service units per second. cp A number of general purpose processors (CPs), including numbers with up to two decimal places. msu Millions of service units per hour. none Removes all of the capping properties. tenant-cpu-cap-limit Indicates the capacity limit for the tenant. Values vary with tenant-cpu-cap-type: lpar-share-percentage 1-100. service-unit 1-999999999. cp 0-999999. This is the number of CPs (general purpose processors) times 100. For example, 100 represents the capacity of 1 CP. msu 1-999999999. tenant-solution-id Is the tenant solution ID. It corresponds to the Container Pricing for IBM Z solution as defined in the License Management Support (LMS) web portal. This is up to 64 characters, and optional.
tenant-resource-group-name	String	Name of the tenant resource group, which can be used for processor capping or container pricing.
tenant-group-list	Array of Strings	List of groups in the tenant.
tenant-state	String	State of the tenant. security_update_failed Indicates that the security workflow that provides automatic security failed. The accompanying error message indicates the workflow name and workflow key. To understand why the security workflow failed, use the z/OSMF Workflows task to review the failed workflow step status and the workflow history. Make corrections as necessary, then use the Set Security Complete action for the domain. Pending Security Update indicates one of the following: pending_security_update indicates one of the following: Manual Security definition was selected for the domain, and security setup is required. Automatic Security workflow did not complete within 60 seconds. Use the z/OSMF Workflows task to see if the workflow for the domain completed successfully, failed, or is still running. Make corrections as necessary, then use the Set Security Complete action for the tenant. wlm-update-failed Indicates that an attempt to modify the Workload Management (WLM) service definition that is associated with the tenant failed. The attempted modification included one of these: Specifying a Solution ID, enabling metering, or enabling capping Modifying existing Workload Management resource pools. Review the accompanying error messages, make corrections as necessary and use the Set Security Complete action to try the Workload Management modification for the tenant and accompanying Workload Management resource pools again. Or, reverse the modification (for example, disable metering) and, if necessary, use the Set Security Complete action to return the state to Operational. operational Indicates that the tenant is ready for use.
create-time	String	Date and time that the tenant was created.
created-by-user	String	User who created the tenant.
last-modified-time	String	The date and time of the last modification to the tenant.
last-modified-by-user	String	User who last modified the tenant.
SAF-resources	Array of objects	Array of SAF-resource objects containing information about SAF resources used to authorize access. See Table 4.
provisioning-version	String	Identifies the provisioning version of the persistent data object for the entry.
provisioning-version-supported	boolean	Indicates if Post, Put, and Delete operations are allowed for the persistent data object for the entry: true if the operations are allowed false if the operations are not allowed.

Example HTTP interaction

In Figure 1, a request is submitted to list the tenants.

Figure 1. Sample request to list tenants


GET https://localhost:4444/zosmf/resource-mgmt/rest/1.0/tenants/

The following is the response body for the example list tenants request.


{
	"tenant-list": [{
		"tenant-id": "IYU100",
		"tenant-name": "Tenant",
		"tenant-shared-rdp-id": "IYU100ZZ",
		"tenant-domain-id": "IYU1",
		"tenant-domain-name": "Domain1",
		"tenant-state": "operational",
		"tenant-metering-capping-properties": {
			"tenant-metering-enabled": false,
			"tenant-capping-enabled": false,
			"tenant-cpu-cap-type": "",
			"tenant-cpu-cap-limit": 0.0
		},
		"tenant-templates": [{
			"template-name": "Template",
			"rdp-id": "IYU10000",
			"template-available": false
		}],
		"tenant-consumer-list": ["consumer"],
		"tenant-group-list": ["group"],
		"object-uri": "/zosmf/resource-mgmt/rest/1.0/tenants/IYU100",
		"tenant-description": "",
		"create-time": "2017-10-18T20:29:58.963Z",
		"created-by-user": "landlord",
		"last-modified-time": "2017-10-18T20:37:23.046Z",
		"last-modified-by-user": "landlord",
		"SAF-resources": [{
			"description": "Designates the user as a z/OSMF user with authorization to log in.",
			"ids": ["consumer"],
			"groups": ["group"],
			"role": "Tenant Consumer",
			"resource-class": "ZMFAPLA",
			"resource-name": "IZUDFLT.ZOSMF",
			"required-access": "SAF_READ",
			"other-required-ids": [],
			"audit-requirements": ""
		}, ...],
		"provisioning-version": "1400",
  "provisioning-version-supported": true
	}]
}