Get Connection Report
The Get Connection Report operation retrieves the most recent connection report for a storage group. The connection report for a storage group of type "fc" is first generated when at least one of the volumes is mapped and the storage group is attached to at least one partition. The connection report for a storage group of type "fcp" is first generated when a storage discovery operation completes successfully for the first time. For a storage group of type "fcp", the worldwide port names referenced in the connection report are the initiator worldwide port names assigned to the virtual storage resources of the storage group.
HTTP method and URI
GET /api/storage-groups/{storage-group-id}/operations/get-connection-report
In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object.
Response body contents
On successful completion, the response body contains a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
last-scan-time | Timestamp | The time the last discovery operation for a storage group completed
successfully. This field is only present when the storage group's type property value is "fcp". |
storage-group-uri | String/ URI | The canonical URI path of the storage group with which the connection report is associated. |
fcp-fabrics | Array of fcp-fabric-info objects | The list of information about the distinct storage fabrics that the storage
adapters in the system are connected. Each element in the array is an instance of an
fcp-fabric-info object, defined in Table 1. This field is only present when the storage group's type property is "fcp". |
fcp-storage-subsystems | Array of fcp-storage-subsystem-info objects | The list of information about the distinct storage subsystems, where the FCP
volumes for this storage group are defined. Each element in the array is an instance of
fcp-storage-subsystem-info object, defined in Table 4. This field is only present when the storage group's type property is "fcp". |
ficon-storage-subsystems | Array of ficon-storage-subsystem-info objects | The list of information about the distinct storage subsystems, where the FICON® volumes for this storage group are defined. Each element in the array is an instance of a ficon-storage-subsystem-info object, defined in Table 6. This field is only present when the storage group's type property is "fc". |
An fcp-fabric-info object contains information about a single fabric configured in the storage area network switches. Each fabric-info object contains the following fields:
Name | Type | Description |
---|---|---|
fabric-id | String (16) | The World Wide Name (WWN) of the uplink Fibre Channel Switch. |
expected-adapter-count | Integer | The number of adapters expected to be zoned for the worldwide port names (WWPNs) of the storage group in this fabric. |
accessible-subsystem-ids | Array of String | The list of worldwide node names (WWNNs) of the storage subsystems that are accessible for
the adapters in this fabric. Each WWNN is a 16-character lowercase hexadecimal string representing the node name defined in the storage subsystem. |
world-wide-port-names | Array of world-wide-port-name-zone-info objects | The list of information about the worldwide port names (WWPNs) that have been allocated to support this FCP storage group. Each element in the array is an instance of world-wide-port-name-zone-info object, defined in Table 2. |
unzoned-adapters | Array of adapter-info objects | The list of information about storage adapters in the system that are connected to this fabric but does not contain a zoning configuration or any of the WWPNs in this storage group. Each element in the array is an instance of adapter-info object, defined in Table 3. |
A world-wide-port-name-zone-info object contains information about the World Wide Port Names (WWPNs) of the storage group and the set of adapters that are zoned for it in the fabric which can be used to connect to the storage network. Each world-wide-port-name-zone-info object contains the following fields:
Name | Type | Description |
---|---|---|
world-wide-port-name | String (16) | A 16-character lowercase hexadecimal string that contains the world wide port name used to access the FCP storage volumes defined for the storage group. |
zoned-adapters | Array of adapter-info objects | The list of information about storage adapters that are configured in one of the active zones
of the storage fabric. Each element in the array is an instance of the adapter-info object, defined
in Table 3. The world wide port name can be assigned to the virtual storage resource created on the adapter to access the FCP storage volumes defined for the storage group. The sum of the number of distinct adapters zoned for this world wide port name across various fabrics should be greater than or equal to the value of the connectivity field of the storage group. |
An adapter-info object contains information about an adapter. Each adapter-info object contains the following fields:
Name | Type | Description |
---|---|---|
adapter-name | String (1-64) | The display name specified for this adapter |
adapter-status | String Enum | The status of the adapter. The adapter can be used to check the connections only when the status is "active". |
adapter-uri | String/ URI | The canonical URI path of the Adapter object. |
An fcp-storage-subsystem-info object contains information about a storage subsystem that the FCP volumes of the storage group are defined in. Each fcp-storage-subsystem-info object contains the following fields:
Name | Type | Description |
---|---|---|
world-wide-node-names | Array of string | The list of worldwide node names (WWNNs) defined for the storage subsystem. Each WWNN is a 16-character lowercase hexadecimal string representing the node name defined in the storage subsystem. |
world-wide-port-names-count | Integer | The number of worldwide port names (WWPNs) that are zoned and masked correctly in the storage switch and storage subsystem, to access the expected number of FCP volumes for the storage group. |
expected-volumes-count | Integer | The number of FCP volumes expected to be discovered in this storage subsystem. |
storage-configurations | Array of storage-configuration-info objects | The list of information about subsystem configurations for each worldwide port name of the storage group. Each element in the array is an instance of storage-configuration-info object, defined in Table 5. |
A storage-configuration-info object contains information about the subsystem configuration for each WWPN of the storage group. Each storage-configuration-info object contains the following fields:
Name | Type | Description |
---|---|---|
world-wide-port-name | String (16) | A 16-character lowercase hexadecimal string that contains the worldwide port name used to access the FCP storage volumes defined for the storage group. |
discovered-volumes-count | Integer | The number of volumes the WWPN is configured to access in the storage subsystem. |
volumes-configuration-status | String Enum | The configuration status of the WWPN across the subsystems. Indicates if the WWPN is able to
access the expected number of volumes in the storage subsystem. Possible values:
|
A ficon-storage-subsystem-info object contains information about a storage subsystem to which the FICON volumes of the storage group are mapped. Each ficon-storage-subsystem-info object contains the following fields:
Name | Type | Description |
---|---|---|
mapped-subsystem-uri | String/ URI | The canonical URI path of the Storage Subsystem object that contains control units mapped to the volumes of the storage group. |
mapped-control-unit-uris | Array of String/ URI | The list of storage control units within the storage subsystem that are mapped to the volumes in the storage group. Each element in this array is the canonical URI path of a Storage Control Unit object. |
Description
This operation retrieves the most recent connection report of the specified storage group. The API user must have action/task permission to the Configure Storage – System Programmer task or the Configure Storage – Storage Administrator task; otherwise, status code 403 (Forbidden) is returned.
A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a Storage Group object to which the API user has object-access permission.
A 409 (Conflict) status code is returned if a connection report has not been generated for the storage group and the user can request one using the Start FCP Storage Discovery operation for a storage group of type "fcp".
Authorization requirements
- Object-access permission to the storage group whose object-id is {storage-group-id}.
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, and the response body is a standard error response body providing the reason code indicated and the 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. |
403 (Forbidden) | 1 | The API user does not have action/task permission to the Configure Storage – System Programmer or Configure Storage - Storage Administrator tasks. |
404 (Not Found) | 1 | A storage group with the object-id {storage-group-id} does not exist on the HMC or the API user does not have object-access permission for it. |
4 | The storage group with object ID {storage-group-id} gas a type value other than "fcp". | |
409 (Conflict) | 250 | A connection report has not been generated. |
503 (Service Unavailable) | 1 | The request could not be processed because the HMC is not currently communicating with the SE needed to perform the requested operation. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Example HTTP interaction
Usage notes
- If a connection report has not been generated for a storage group of type "fcp", use the Start FCP Storage Discovery operation to initiate the creation of the connection report.
- If a connection report has not been generated for a storage of type "fc", use the Fulfill Storage Volume operation to map the ECKD storage resources to the volumes that are part of the storage group and the Attach Storage Group to Partition operation to attach the storage group to a partition.
- For a storage group of type
"fcp", the following conditions should be satisfied for a valid connection to the storage
resources:
- The number of common adapter objects in the zoned-adapters field for all world-wide-port-names in each of the fabrics defined in the fcp-fabric-info object should be greater than or equal to the expected-adapter-count value in the fcp-fabric-info field .
- For a given world-wide-port-name, the sum of the discovered-volumes-count value across the storage-configuration-objects should be greater than or equal to the number of volumes that are part of the storage request.
- The volumes-configuration-state in each storage-configuration-info object indicates the status of configuration for a worldwide port name across subsystems. For an ideal connection the volumes-configuration-state should either be "correct-volumes" or "too-many-volumes" for all the worldwide port names.