Create Storage Template

The Create Storage Template operation creates a new Storage Template object.

HTTP method and URI

POST /api/storage-templates

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
cpc-uri String/ URI Required The value to be set as the storage template's cpc-uri property.
name String (1-64) Required The value to be set as the storage template's name property.
description String (0-200) Optional The value to be set as the storage template's description property.
type String Enum Required The value to be set as the storage template's type property.
shared Boolean Optional The value to be set as the storage template's shared property.
connectivity Integer Optional The value to be set as the storage template's connectivity property.
max-partitions Integer Optional The value to be set as the storage template's max-partitions property.

The max-partitions field is not allowed in the request body unless the type field value has a value of "fcp".

direct-connection-count Integer (0-1000) Optional The value to be set as the storage template's direct-connection-count property.

The direct-connection-count field is not allowed in the request body unless the type field value has a value of "fcp".

storage-template-volumes Array of storage-template-volume-request-info nested objects Optional

The set of properties for each of the storage template volumes in the template.

An array of one or more storage-template-volume-request-info nested objects, where each element defines the new property values of a storage template volume that is to be created. The operation field of each nested object element must be set to "create". For storage templates of type "fc", the storage-template-volume-request-info nested object is defined in Table 1. For storage templates of type "fcp", the storage-template-volume-request-info nested object is defined in Table 2.

Response body contents

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

Field name Type Description
object-uri String/ URI The object-uri property of the newly created Storage Template object.
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-template-volumes field in the request body. If no volumes were specified when creating the storage template, the element-uris field will be an empty list.

Description

This operation creates a storage template with the values specified and then returns its object-uri and the element-uris of each storage volume that was created in the response body. The response also includes a Location header that provides the new storage template's URI. Inventory Change notifications for the new storage template and for each new storage template volume identified in the storage-template-volumes field are emitted asynchronously to this operation.

If the API user does not have action/task permission to the Configure Storage – System Programmer task, a 403 (Forbidden) status code is returned. If the object ID cpc-uri field does not identify a CPC object to which the API user has object-access permission, or if the CPC identified by the cpc-uri field does not support this operation, a 404 (Not Found) status code is returned. If the CPC identified by the cpc-uri field is already associated with a storage template with the specified name, or if two or more of the new storage template volumes have the same name, a 400 (Bad Request) status code is returned. If the CPC identified by the cpc-uri field is not enabled for DPM, or if restrictions on the values of the shared and max-partitions property values, or the shared and direct-connection-count property values are violated, a 409 (Conflict) status code is returned.

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 template type. If the request body contents are valid, the storage template and each of the storage template volumes defined in the storage-template-volumes field are created and their properties are set to their corresponding request body content's field's values. If a field is not found in the request body, its property's value will be defaulted.

Authorization requirements

This operation has the following authorization requirement:
  • Object-access permission to the CPC whose object-uri is cpc-uri.
  • Action/task permission to the Configure Storage – System Programmer task.

HTTP status and reason codes

On success, HTTP status code 201 (Created) 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. Create Storage Template: 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 template with the name specified in the request body is already associated with the CPC identified by the cpc-uri field.
15 The type field value is "fc" and an element of the storage-template-volumes field contains both the size and cylinders fields, or neither the size nor cylinders fields.
18 A supplied property is not valid for a storage template's type.
453 The name field for at least two of the nested entries in the storage-template-volumes field are the same.
403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage – System Programmer task.
404 (Not Found) 2

The CPC identified by the cpc-uri field does not exist on the HMC or the API user does not have object-access permission for it.

4 The CPC identified by the cpc-uri field does not support this operation.
409 (Conflict) 5 The CPC identified by the cpc-uri field is not enabled for DPM.
8 The max-partitions field value conflicts with the shared field value.
329 The operation cannot be performed because the CPC designated by the cpc-uri is an unmanaged CPC, which is not supported by this operation.
495 The direct-connection-count field value conflicts with the shared field value.
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. Create Storage Template: Request
POST /api/storage-templates HTTP/1.1
x-api-session: 4572v9cswxkse3fgdfxclgakl6c9m67h46jrv06bkgoe42dzdv
content-type: application/json
content-length: 206
{
   "connectivity":4,
   "cpc-uri":"/api/cpcs/129da68a-05ed-3ae2-b393-3b1442c6c302",
   "name":"FICON Template",
   "storage-template-volumes":[
      {
         "model":"1",
         "operation":"create",
         "usage":"boot"
      }
   ],
   "type":"fc"
}
Figure 2. Create Storage Template: Response
201 Created
server: Hardware management console API web server / 2.0
location: /api/storage-templates/9cae8872-e210-11e8-82d0-fa163e9c462b
cache-control: no-cache
date: Tue, 06 Nov 2018 22:09:21 GMT
content-type: application/json;charset=UTF-8
content-length: 217
{
   "element-uris":[
      "/api/storage-templates/9cae8872-e210-11e8-82d0-fa163e9c462b/storage-template-volumes/
         9cc736a6-e210-11e8-82d0-fa163e9c462b"
   ],
   "object-uri":"/api/storage-templates/9cae8872-e210-11e8-82d0-fa163e9c462b"
}