Modify Storage Group Properties

The Modify Storage Group Properties operation updates one or more of the writable properties of a storage group.

HTTP method and URI

POST /api/storage-groups/{storage-group-id}/operations/modify

In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object.

Request body contents

Fields for properties whose values are not to be changed by this operation can and should be omitted from the request body.

Field name Type Rqd/Opt Description
name String (1-64) Optional The value to be set as the storage group's name property.
description String (0-200) Optional The value to be set as the storage group's description property.
shared Boolean Optional The value to be set as the storage group's shared property.
connectivity Integer Optional The value to be set as the storage group's connectivity property.

If the current value of the storage group's type property is "fcp", modifying the connectivity property requires fulfillment action from the storage administrator. The storage group’s fulfillment-state property will change to "pending". If the email-to-list is also present in the request body, an email will be sent containing the new connectivity value.

max-partitions Integer Optional

The value to be set as the storage group’s max-partitions property.

The max-partitions field is not allowed in the request body unless the current value of the storage group’s type property is "fcp".

Modifying the max-partitions property requires fulfillment action from the storage administrator. The storage group's fulfillment-state property will change to "pending". If the email-to-list is also present in the request body, an email will be sent containing the new max-partitions value.

direct-connection-count Integer (0-1000) Optional

The value to be set as the storage group's direct-connection-count property.

The direct-connection-count field is not allowed in the request body unless the current value of the storage group's type property is "fcp".

The direct-connection-count field value cannot be greater than 0 for shared storage groups.

storage-volumes Array of storage-volume-request-info nested objects Optional An array of storage-volume-request-info nested objects, where each element defines the existing storage volumes that are to be deleted or the new property values of a storage volume that is to be created or modified. The storage-volume-request-info nested object is defined in the tables that follow.

If not specified, the storage group's volumes remain unchanged.

email-to-addresses Array of String Optional

A set of zero or more email addresses for the people that are to be notified through email of the modified storage group resources that require fulfillment. These email addresses will appear in the "to:" address list in the email that is sent.

The email-to-addresses field is not allowed in the request if the type property in the target storage group has a value of "nvme".

Default value: null. No email will be sent.

email-cc-addresses Array of String Optional

A set of zero or more email addresses for the people that are to be copied on the email notification of the modified storage group resources that require fulfillment. These email addresses will appear in the "cc:" address list in the email that is sent.

The email-cc-addresses field must be null when the email-to-addresses field is null.

The email-cc-addresses field is not allowed in the request if the type property in the target storage group has a value of "nvme".

Default value: null. No one will be copied on the email.

email-insert String Optional

Text that is to be inserted in the email notification of the modified storage group resources that require fulfillment. The text can include HTML formatting tags.

The email-insert field must be null when the email-cc-users field is null.

The email-insert field is not allowed in the request if the type property in the target storage group has a value of "nvme".

Default value: null. An email without a special text insert will be sent.

Each nested storage-volume-request-info object contains the following fields:

Table 1. storage-volume-request-info nested object for "create" operations on "fc" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the property values for a new storage volume that is to be created.

Value: "create"

name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
size Float (0.88- 212489.20) Optional The value to be set as the storage volume's size property.

If the model is "EAV", the size or cylinders fields (but not both) must be specified.

If the model is not "EAV", the size field may not be present in the request body.

usage String Enum Optional The value to be set as the storage volume's usage property.
model String Enum Required The value to be set as the storage volume's model property.
cylinders Integer (1113- 268434453) Optional The value to be set as the storage volume's cylinders property.

If the model is "EAV", the size or cylinders fields (but not both) must be specified.

If the model is not "EAV", the cylinders field may not be present in the request body.

device-number String (4) Optional The value to be set as the storage volume's device-number property.
Table 2. storage-volume-request-info nested object for "create" operations on "fcp" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the property values for a new storage volume that is to be created.

Value: "create"

name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
size Float (1.00- 1048576.00) Required The value to be set as the storage volume's size property.
usage String Enum Optional The value to be set as the storage volume's usage property.
Table 3. storage-volume-request-info nested object for "create" operations on "nvme" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the property values for a new storage volume that is to be created.

Value: "create"

name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
usage String Enum Optional The value to be set as the storage volume's usage property.
device-number String (4) Optional The value to be set as the storage volume's device-number property.
adapter-uri String/URI Required The canonical URI path of the NVMe Adapter object that backs this storage volume.
Table 4. storage-volume-request-info nested object for "modify" operations on "fc" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the new property values for an existing storage volume that is to be modified.

Value: "modify"

element-uri String/ URI Required The canonical URI path for the storage volume element object that is being updated.
name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
size Float (0.88- 212489.20) Optional The value to be set as the storage volume's size property.

The size field is optional but may not be present in the request body if the cylinders field is present in the request body or if the model value is not "EAV".

Modifying the size property requires fulfillment action from the storage administrator. The volume and parent storage group’s fulfillment-state properties will change to "pending". If the email-to-addresses is also present in the request body, an email will be sent containing the new size value.

usage String Enum Optional The value to be set as the storage volume's usage property.
model String Enum Optional The value to be set as the storage volume's model property.

Modifying the model property requires fulfillment action from the storage administrator. The volume and parent storage group’s fulfillment-state properties will change to "pending". If the email-to-addresses is also present in the request body, an email will be sent containing the new model value.

cylinders Integer (1113 -268434453) Optional The value to be set as the storage volume's cylinders property.

The cylinders field is optional but may not be preset in the request body if the size field is present in the request body or if the model value is not "EAV".

Modifying the cylinders property requires fulfillment action from the storage administrator. The volume and parent storage group’s fulfillment-state properties will change to "pending". If the email-to-addresses is also present in the request body, an email will be sent containing the new cylinders value.

device-number String (4) Optional The value to be set as the storage volume's device-number property.
Table 5. storage-volume-request-info nested object for "modify" operations on "fcp" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the new property values for an existing storage volume that is to be modified.

Value: "modify"

element-uri String/ URI Required The canonical URI path for the storage volume element object that is being updated.
name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
size Float (1.00- 1048576.00) Optional The value to be set as the storage volume's size property.

Modifying the size property requires fulfillment action from the storage administrator. The volume and parent storage group’s fulfillment-state properties will change to "pending". If the email-to-addresses is also present in the request body, an email will be sent containing the new size value.

usage String Enum Optional The value to be set as the storage volume's usage property.
Table 6. storage-volume-request-info nested object for "modify" operations on "nvme" storage volumes
Field name Type Rqd/Opt Description
operation String Enum Required This nested object contains the new property values for an existing storage volume that is to be modified.

Value: "modify"

element-uri String/ URI Required The canonical URI path for the storage volume element object that is being updated.
name String (1-64) Optional The value to be set as the storage volume's name property.
description String (0-100) Optional The value to be set as the storage volume's description property.
usage String Enum Optional The value to be set as the storage volume's usage property.
device-number String (4) Optional The value to be set as the storage volume's device-number property.
Table 7. storage-volume-request-info nested object for "delete" operations on storage volumes of all types
Field name Type Rqd/Opt Description
operation String Enum Required This nested object identifies an existing storage volume that is to be deleted.

Value: "delete"

element-uri String/ URI Required The canonical URI path for the storage volume element object that is being deleted.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description
element-uris Array of String/ URI A list of the URIs for the storage volume elements that are created. The order of the URIs in this list will match the order in which the new volumes were specified in the storage-volumes field in the request body. If the storage-volumes field did not contain any entries with operation equal to "create", the element-uris field will be an empty list.

Description

This operation updates a storage group's properties with the values specified and then returns the element-uris of each storage volume that was created in the response body.

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 object to which the API user has object-access permission.

If the group’s fulfillment-state property value is "checking-migration", or if the CPC on which this storage group resource exists is not active, or if the change would put the storage group into a state where its shared and max-partitions property values or shared and direct-connection-count property values conflict, or if the shared property is false for a storage group that is attached to more than one partition, or if the a storage volume modification would put the volume into a state where its model, size and cylinders property values conflict, or the model, size or cylinders properties are being reduced, a 409 (Conflict) status code is returned. A 409 (Conflict) status code is also returned if a storage volume that is assigned as a partition's boot volume is deleted, or its usage property is changed.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because the document defines a field that is not supported for the given storage group type, or because the parent CPC is already associated with a storage group with the specified name, or because the operation would put the storage group into a state where two or more of its storage volumes would have the same name, or because both of, or neither of, the size and cylinders fields of a FICON® storage volume are defined, or because the email-insert or email-cc-addresses fields are present in the request body without the email-to-addresses field, or because any address in the email-to-addresses or email-cc-addresses fields is not a valid email address.

If the request body contents are valid, the storage group's properties are updated to their corresponding request body content's field's values. Optional fields may be excluded from the request body; if a field is not found in the request body, its property's value will not be modified. The element URIs of each new and deleted storage volume will be added to, or removed from, the storage group's storage-volume-uris list property. If at least one property being modified has a corresponding active property, the update requires action by the SAN administrator and the fulfillment-state property of the storage group is set to "pending". All active property values remain unchanged.

If the update changes the value of any property for which property-change notifications are due, those notifications are emitted asynchronously to this operation. This includes a Property Change notification for the storage-volume-uris property if the operation creates or deletes storage volumes.

If the modified storage group’s fulfillment-state is "pending" and the email-to-addresses field is present and not null in the request body, an email containing information about the modified storage group and volume resources that require fulfillment is sent to the email addresses specified in the email-to-addresses and email-cc-addresses fields in the request body. If the email-insert field is present and not null, its contents will be inserted into the email body. If an error occurs when sending the email, a 409 (Conflict) status code is returned. This could be because the HMC is not configured to support emails. A failure to send the email does not rollback the modification of the storage group. An API client should assume that the storage group was modified even though the request failed with a 409 (Conflict) status code and 491 reason code. Note that a successful completion does not imply that the emails were delivered. Errors could be encountered at an email server after the request completes, for example due to an unknown email address. If a send failure occurs, emails can be resent using the Request Storage Group Fulfillment request.

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

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.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and associated error message.

Table 8. Modify Storage Group Properties: 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.
8 A storage group with the name specified in the request body is already associated with the CPC identified by the group's cpc-uri property.
15 The storage group’s type property value is "fc" and an element of the storage-volumes field contains both the size and cylinders fields, or an operation value of "create" and neither the size nor cylinders fields.
18 A supplied property is not valid for a storage group’s type.
450 The storage group’s type property value is "fc" and an element of the storage-volumes field has an operation value of "delete" and an element-uri value that references a storage volume with an eckd-type property value of "alias".
451 The email-cc-addresses or email-insert field is present in the request body without the email-to-addresses field.
452 The value supplied in the device-number field of at least one of the entries in storage-volumes conflicts with an existing device number for another device attached to the partition associated with this storage group.
453

The operation would put the storage group into a state where the name property for at least two of its storage volumes would be the same.

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.
5 An element of the storage-volumes field has an element-uri value that is not a member of the storage group’s storage-volume-uris array property value.
409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions").
2 The storage group object with the object-id {storage-group-id} was busy and the request timed out.
8 The operation would result in conflicting values for the max-partitions and shared property values.
446 The NVMe storage adapter referenced by the adapter-uri field in any storage-volumes element is already associated with another NVMe storage volume.
471 The value of the fulfillment-state property for the storage group with the object-id {storage-group-id} is "checking-migration".
475 The max-partitions field value is less than the number of partitions to which this storage group is currently attached, or the shared property is false when the number of partitions to which the partition is attached is more than one.
490 The storage group’s type property value is "fc" and an element of the storage-volumes field would put the storage volume into a state where its model, size and cylinders property values conflict.
491 An error occurred when sending the email. This failure applies only to the sending of the email. If this reason code is returned, the storage group will have been modified.
493

The email-to-addresses field is present in the request body, but the targeted console is not configured to support the sending of emails.

494 The size or cylinders field value is less than the storage volume's current size or cylinders, or the model field value represents a size that is smaller than that of the current model.
495 The operation would result in conflicting values for the direct-connection-count and shared property values.
499 A storage volume that is assigned as a partition's boot volume is being deleted, or its usage or device-number properties are being changed.
500 The NVMe storage adapter referenced by the adapter-uri field in any storage-volumes element does not have an SSD installed.
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. Modify Storage Group Properties: Request
POST /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/operations/modify HTTP/1.1
x-api-session: 55q0cufbqgz03k1s2bmz98nxnx2ozf4e4sqzygw7q50st3zfqe
content-type: application/json
content-length: 352
{
   "description":"A sample FICON storage group",
   "storage-volumes":[
      {
         "description":"A Model 3 FICON data volume",
         "model":"3",
         "operation":"create"
      },
      {
         "description":"A Model 1 FICON boot volume",
         "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
           storage-volumes/ec738d80-9689-11e8-aa30-fa163e27d492",
         "operation":"modify"
      }
   ]
}
Figure 2. Modify Storage Group Properties: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Aug 2018 19:27:45 GMT
content-type: application/json;charset=UTF-8
content-length: 130
{
   "element-uris":[
      "/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
        22de1d40-968a-11e8-a0a5-fa163e27d492"
   ]
}