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

This operation has the following 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.

Table 1. Start FCP Storage Discovery: 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) 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

Table 2. Start FCP Storage Discovery: 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

Figure 1. Start FCP Storage Discovery: Request
POST /api/storage-groups/2217a632-56bb-11e9-a434-fa163effe469/operations/
   start-fcp-storage-discovery HTTP/1.1
x-api-session: 36lkftjan75oyr72g1bz9bic4r68qk2dtsm0svw2ei9tpa2az4
Figure 2. Start FCP Storage Discovery: Response
202 Accepted
server: Hardware management console API web server / 2.0
location:/api/jobs/31500aa4-56bb-11e9-ac0a-fa163efc2ef4
cache-control : no-cache
date: Thu, 04 Apr 2019 09:22:38 GMT
content-type:application/json;charset=UTF-8
content-length:60
{
   "job-uri":"/api/jobs/31500aa4-56bb-11e9-ac0a-fa163efc2ef4"
}

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".