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