Add Candidate Adapter Ports to an FCP Storage Group
The Add Candidate Adapter Ports to an FCP Storage Group operation adds a list of storage adapter ports to a storage group's candidate adapter ports list.
HTTP method and URI
POST /api/storage-groups/{storage-group-id}/operations/add-candidate-adapter-ports
In this request, the URI variable {storage-group-id} is the object ID of the storage group to which the candidate adapter ports are to be added.
Request body contents
The request body is expected to contain a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
adapter-port-uris | Array of String/ URI | Required | A list of the adapter ports that are to be added to the storage group's candidate adapter ports list. Each element in this array is an instance of the canonical URI path of a storage adapter port. |
Description
This operation adds a list of storage adapter ports to a storage group’s candidate adapter ports list. These adapter ports become candidates for use as backing adapters when creating virtual storage resources when the group is attached to a partition. The adapter ports should have connectivity to the Storage Area Network (SAN). This operation only applies to storage groups of type "fcp". Change notification for the storage group’s candidate-adapter-port-uris property is emitted asynchronously to this operation.
Candidate adapter port may only be added before the CPC discovers a working communications path, indicated by a "validated" status on at least one of the parent storage group’s WWPNs. After that point all adapter ports in the group are automatically detected and manually adding them is no longer possible.
If the API user does not have action/task permission to the Configure Storage – System Programmer task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a storage group to which the API user has object-access permission, or if an element of the adapter-port-uris array does not identify a storage adapter 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".
If any adapter port in the adapter-port-uris list is currently a member of the storage group’s candidate adapter ports list, or if at least one WWPN in the group has been discovered, or if any adapter port in the adapter-port-uris list references a storage adapter port that does not reside in the target storage group's CPC, a 409 (Conflict) status code is returned.
If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because an adapter referenced in the adapter-port-uris array is not a FICON® adapter.
If the request body contents are valid, the adapter port URIs in the adapter-port-uris list are added to the storage group's candidate adapter ports list.
Authorization requirements
- Object-access permission to the storage group whose object-id is {storage-group-id}.
- Object-access permission to each adapter containing the ports identified in the adapter-port-uris array.
- Action/task permission to the Configure Storage – System Programmer task.
HTTP status and reason codes
On success, HTTP status code 204 (No Content) is returned and no response body is provided.
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. |
8 | An adapter referenced in the adapter-port-uris list has an adapter-family property value other than "ficon". | |
403 (Forbidden) | 1 | The API user does not have action/task permission to the Configure Storage – System Programmer task. |
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. |
2 | An adapter containing a port referenced by a URI in the adapter-port-uris field does not exist on the HMC or the API user does not have object-access permission for it. | |
4 | The storage group object with the object-id {storage-group-id} has a type value other than "fcp". | |
409 (Conflict) | 2 | The storage group object with the object-id {storage-group-id} was busy and the request timed out. |
441 | A storage adapter port in the adapter-port-uris list resides in a different CPC than the targeted storage group. | |
471 | The status property of at least one WWPN listed in the world-wide-port-names property of the storage group identified by {storage-group-id} has a value of "validated". | |
478 | A storage adapter port in the adapter-port-uris list is already a current member of the candidate-adapter-port-uris list of the storage group object with the object-id {storage-group-id}. | |
483 | The adapter that contains the port referenced by an element in the adapter-port-uris field has a type value other than "fcp". | |
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.