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:

Table 1. fcp-fabric-info nested object
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:

Table 2. world-wide-port-name-zone-info nested object
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:

Table 3. adapter-info nested object
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:

Table 4. fcp-storage-subsystem-info nested object
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:

Table 5. storage-configuration-info nested object
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:
  • "no-volumes" - The WWPN cannot access any volume across the subsystems.
  • "too-many-volumes" - The WWPN can access more volumes than what was expected for the storage group.
  • "too-few-volumes" - The WWPN can access fewer volumes than what was expected for the storage group.
  • "different-volumes" - The WWPN can access one or more volumes not defined to the storage group, or it cannot access one or more of the volumes that are defined to the storage group, but not all.
  • "correct-volumes" - The WWPN can access all of the defined volumes of the storage group and no other volumes.

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:

Table 6. ficon-storage-subsystem-info nested object
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

This operation has the following authorization requirement:
  • 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.

Table 7. Get Connection Report: HTTP status and reason codes
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

Figure 1. Get Connection Report: Request
GET /api/storage-groups/249cbe64-56bc-11e9-bcc3-fa163effe469/operations/
  get-connection-report HTTP/1.1
x-api-session: 1wianh609dwilk4lfgyriv8ywx4o2okf4dl9kn3jln1p9d1msw
Figure 2. Get Connection Report: Response (Part 1)
200 OK
server: Hardware management console API web server/2.0
cache-control: no-cache
date: Thu ,04 Apr 2019 19:36:08 GMT
content-type:application/json;charset=UTF-8
content-length:3623
{
 "fcp-fabrics":[
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
   "expected-adapter-count":1,
   "fabric-id":"100099906",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0131 Z01B-17",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/4b3c435a-448d-11e9-9536-fa163effe469"
      }
     ]
    }
   ]
  },
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
Figure 3. Get Connection Report: Response (Part 2)

   "expected-adapter-count":0,
   "fabric-id":"100099901",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0101 Z01B-02",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/45b2e5a6-448d-11e9-9536-fa163effe469"
      }
     ]
    }
   ]
  },
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
   "expected-adapter-count":0,
   "fabric-id":"100099905",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0130 Z01B-17",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/4aaaf260-448d-11e9-9536-fa163effe469"
      }
     ]
    }
   ]
  },
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
Figure 4. Get Connection Report: Response (Part 3)

   "expected-adapter-count":0,
   "fabric-id":"100099904",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0105 Z01B-03",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/a5a6bb22-448d-11e9-ad2d-fa163effe469"
      }
     ]
    }
   ]
  },
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
   "expected-adapter-count":0,
   "fabric-id":"100099903",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0100 Z01B-02",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/3ee50ee8-448d-11e9-9536-fa163effe469"
      }
     ]
    }
   ]
  },
  {
   "accessible-subsystem-ids":[
    [
     "5005076400c00003",
     "5005076400c00002",
     "5005076400c00004",
     "5005076400c00001",
     "5005076400c00000"
    ]
   ],
Figure 5. Get Connection Report: Response (Part 4)

   "expected-adapter-count":0,
   "fabric-id":"100099902",
   "unzoned-adapters":[],
   "world-wide-port-names":[
    {
     "world-wide-port-name":"a1b2c3d4e5f60045",
     "zoned-adapters":[
      {
       "adapter-name":"FCP 0104 Z01B-03",
       "adapter-status":"active",
       "adapter-uri":"/api/adapters/a317e23c-448d-11e9-ad2d-fa163effe469"
      }
     ]
    }
   ]
  }
 ],
 "fcp-storage-subsystems":[
  {
   "expected-volumes-count":1,
   "storage-configurations":[
    {
     "discovered-volumes-count":5,
     "volumes-configuration-status":"too-many-volumes",
     "world-wide-port-name":"a1b2c3d4e5f60045"
    }
   ],
   "world-wide-node-names":[
    "5005076400c00003",
    "5005076400c00002",
    "5005076400c00004",
    "5005076400c00001",
    "5005076400c00000"
   ],
   "world-wide-port-names-count":1
  }
 ],
 "last-scan-time":1554370171000,
 "storage-group-uri":"/api/storage-groups/249cbe64-56bc-11e9-bcc3-fa163effe469"
}

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.