List Permitted Logical Partitions

The List Permitted Logical Partitions operation lists logical partitions to which the API user has object-access permission. This operation is supported using the BCPii interface.

HTTP method and URI

GET /api/console/operations/list-permitted-logical-partitions

Query parameters:

Name Type Rqd/Opt Description
name String Optional Filter pattern (regular expression) to limit returned objects to those that have a matching name property.
activation-mode String Enum Optional Filter string to limit returned objects to those that have a matching activation-mode property. Value must be a valid logical partition activation-mode property value.
status String Enum Optional Filter string to limit returned objects to those that have a matching status property. Value must be a valid logical partition status property value.
has-unacceptable-status Boolean Optional Filter string to limit returned objects to those that have a matching has-unacceptable-status property. Valid values are true and false.
cpc-name String Optional Filter pattern (regular expression) to limit returned objects to those whose parent CPC has a matching name property.
additional-properties List of String Enum Optional A list of properties to be included in the response in addition to the default properties included in each logical-partition-info. This is a list of comma-separated strings where each string is a property name defined in the Logical Partition’s data model.

[Added by feature secure-boot-with-certificates]

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description
logical-partitions Array of logical-partition-info objects Array of nested logical-partition-info objects as described in the next table.

Each nested logical-partition-info object contains the following fields:

Field name Type Description
name String The name property of the Logical Partition object.
object-uri String/ URI The object-uri property of the Logical Partition object.
activation-mode String Enum The activation-mode property of the Logical Partition object.
status String Enum The status property of the Logical Partition object.
has-unacceptable-status Boolean The has-unacceptable-status property of the Logical Partition object.
cpc-name String The name property of the Logical Partition's parent CPC object.
cpc-object-uri String/ URI The object-uri property of the Logical Partition's parent CPC object.
se-version String The se-version property of the Logical Partition's parent CPC object.
request-origin Boolean If true, the Logical Partition object is the same as the origin of the request. If false, the Logical Partition object is not the same as the origin of the request.
Note: This property is only returned when the BCPii interface was used for the request.
target-name String (1-17) The value that must be used on the X-API-Target-Name request header when performing an operation on this object.
Note: This property is only returned when the BCPii interface was used for the request.

Description

For the web services interface this operation lists the Logical Partition objects to which the API user has object-access permission. For the BCPii interface this operation lists the Logical Partition objects to which the source partition has receive BCPii security controls permissions. Some basic properties are provided for each logical partition that is included in the response.

If the name query parameter is specified, the returned list is limited to those logical partitions that have a name property matching the specified filter pattern. If the name parameter is omitted, no such filtering is performed.

If the activation-mode query parameter is specified, the parameter is validated to ensure it is a valid logical partition activation-mode property value. If the value is not valid, HTTP status code 400 (Bad Request) is returned. If the value is valid, the returned list is limited to those logical partitions that have an activation-mode property matching the specified value. If the activation-mode parameter is omitted, no such filtering is performed.

If the status query parameter is specified, the parameter is validated to ensure it is a valid logical partition status property value. If the value is not valid, HTTP status code 400 (Bad Request) is returned. If the value is valid, the returned list is limited to those logical partitions that have a status property matching the specified value. If the status parameter is omitted, no such filtering is performed.

If the has-unacceptable-status query parameter is specified, the returned list is limited to those logical partitions that have a has-unacceptable-status property matching the specified value. If the has-unacceptable-status parameter is omitted, no such filtering is performed.

If the cpc-name query parameter is specified, the returned list is limited to those logical partitions whose parent CPC's name property matches the specified filter pattern. If the cpc-name parameter is omitted, no such filtering is performed.

For the web services interface a logical partition is included in the list only if the API user has object-access permission to that object. For the BCPii interface a logical partition is included in the list only if the source partition has receive BCPii security controls permissions. If there is a logical partition to which the API user does not have permission, that object is omitted from the list, but no error status code results.

If there are no logical partitions known or if no logical partitions are to be included in the response due to filtering or access permissions, an empty list is provided and the operation completes successfully.

If the additional-properties parameter is specified, additional properties are included in the returned list. The properties to be included is a list of comma-separated strings where each string is a property name defined in the Logical Partition's Data model. If the additional-properties parameter is omitted, no such properties will be included. [Added by feature secure-boot-with-certificates]

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface, object-access permission to the Logical Partition objects included in the response body.
  • For the BCPii interface the source partition must have receive BCPii security controls permissions for any Logical Partition object to be included in the result.

HTTP status and reason codes

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

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

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. List Permitted Logical Partitions: Request
GET /api/console/operations/list-permitted-logical-partitions HTTP/1.1
x-api-session: 3y0qwkkon9m03c5o81oo2fz7ozezkinczcdwwr4gauzgogb5xq
Figure 2. List Permitted Logical Partitions: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 28 Aug 2017 18:07:25 GMT
content-type: application/json;charset=UTF-8
content-length: 860
{
   "logical-partitions":[
      {
         "activation-mode":"general",
         "cpc-name":"M87",
         "cpc-object-uri":"/api/cpcs/f2eb7e56-0c87-3646-887e-ec735b3844cd",
         "has-unacceptable-status":false,
         "name":"S50",
         "object-uri":"/api/logical-partitions/d39347d9-855a-3199-9ef6-a1701b7b17b4",
         "se-version":"2.14.0",
         "status":"operating"
      },
      {
         "activation-mode":"esa390",
         "cpc-name":"S15",
         "cpc-object-uri":"/api/cpcs/f6f629ca-f2c5-3f71-a80f-d9b91a492549",
         "has-unacceptable-status":false,
         "name":"APIVM2",
         "object-uri":"/api/logical-partitions/c53c7aa7-444b-3f05-87b4-fb94802240b8",
         "se-version":"2.13.1",
         "status":"operating"
      },
      {
         "activation-mode":"not-set",
         "cpc-name":"S15",
         "cpc-object-uri":"/api/cpcs/f6f629ca-f2c5-3f71-a80f-d9b91a492549",
         "has-unacceptable-status":true,
         "name":"ZOS",
         "object-uri":"/api/logical-partitions/17c4bc30-96b5-327e-8b7d-59e1b4b7261e",
         "se-version":"2.13.1",
         "status":"not-activated"
      }
   ]
}

Usage note

The response body of this operation is similar to that of the Get Inventory operation, but it returns only a subset of logical partition properties. The response also includes some properties of the parent CPC, regardless of whether the API user has object-access permission to that CPC.