Start FCP Storage Discovery
The Start FCP Storage Discovery operation triggers asynchronous storage discovery for an FCP storage group. The system will check the connections for the storage group and create a connection report indicating the status of those connections. Because the system periodically performs storage discovery for FCP storage groups and creates a connection report for those storage groups, it is not necessary to use this operation; however, issuing this operation may cause the discovery to be performed sooner than it would have otherwise.
HTTP method and URI
POST /api/storage-groups/{storage-group-id}/operations/start-fcp-storage-discovery
In this request, the URI variable {storage-group-id} is the object ID of the target storage group.
Request body contents
An optional request body can be specified as a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
force-restart | Boolean | Optional | Indicates if there is an in-progress discovery operation for the specified
storage group, it should be terminated and started again. If false or there is no
in-progress discovery operation for the specified storage group, a new one is started. Default: false |
Response body contents
Once the start request is accepted, the response body contains a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
job-uri | String/ URI | URI that may be queried to retrieve status updates. |
Asynchronous result description
Once the operation has completed, a job-completion notification is sent, and results are available for the asynchronous portion of this operation. These results are retrieved using the Query Job Status operation directed at the job URI provided in the response body.
The result document returned by the Query Job Status operation is specified in the description for the Query Job Status operation. When the status of the job is "complete", the results include a job completion status code and reason code (fields job-status-code and job-reason-code) which are set as indicated in Job status and reason codes. The job-results field is null when this operation is successful. When it is not successful, the job-results field contains an object with the following field:
Field name | Type | Description |
---|---|---|
message | String | The message text describing the detailed error that occurred when the operation was not successful. |
Description
The operation triggers Logical Unit Number (LUN) discovery for the target storage group. Once the LUN discovery operation is completed a connection report is generated for the storage group, indicating the status of the connections. Once the connection report is created, the Get Connection Report operation can be used to retrieve it. This operation is only valid for the storage groups of type "fcp". 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 or if the storage group identified by the object ID {storage-group-id} is not of type "fcp".
Authorization requirements
- Object-access permission to the storage group whose object-id is {storage-group-id}.
- Action/task permission to the Configure Storage – System Programmer or the Configure Storage - Storage Administrator task.
HTTP status and reason codes
On success, HTTP status code 202 (Accepted) 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) | 1 | The state of the CPC to which the storage group is associated is not valid to perform the operations. It must be one of the following states: "active", "service-required", "degraded", or "exceptions". |
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.
Job status and reason codes
HTTP error status code | Reason code | Description |
---|---|---|
200 (OK) | N/A | The operation completed successfully |
404 (Not Found) | 1 | The storage group with object-id {storage-group-id} does not exist on the HMC or the API user does not have object-access permission for it. |
500 (Server Error) | 263 | The storage discovery operation failed and there will be no automatic retry. |
Example HTTP interaction
Usage notes
- At any point in time, there will be at most one in-progress discovery operation checking connections for a given storage group. While a discovery operation is in progress, any new request for the same storage group from the APIs or the Graphical User Interface will be linked to that in-progress discovery operation. An in-progress discovery operation can be interrupted for various reasons, such as starting a partition to which this storage group is attached, reassigning adapters of the virtual resources of the storage group, or invoking the Start FCP Storage Discovery operation with a force-restart flag set to true. If an in-progress discovery operation is interrupted for any reason, the operation will be automatically retried and the previous requests associated with that in-progress discovery operation will be linked to the new operation.
- If the request fails for any reason, all requests associated with that in-progress request will fail and an error code will be returned in the asynchronous result.
- If the HMC stops communicating with the Support Element or if the CPC enters into an invalid state, when the discovery operation for a storage group is in progress, the operation will be retried when the HMC starts communicating with the SE again or if the CPC enters a valid state, respectively. The valid CPC states for the discovery operation are "active", "service-required", "degraded", and "exceptions".