Create Capacity Group

The Create Capacity Group operation creates a capacity group for the specified CPC.

HTTP method and URI

POST /api/cpcs/{cpc-id}/capacity-groups

In this request, the URI variable {cpc-id} is the object ID of the CPC.

Request body contents

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

Field name	Type	Rqd/Opt	Description
`name`	String (1-64)	Required	The value to be set as the Capacity Group's name property.
`short-name`	String (1-8)	Optional	The value to be set as the Capacity Group's short-name property. If a short-name is not specified, it will be auto-generated and assigned to this capacity group. The name, if specified, must be unique within the CPC.
`description`	String (0-1024)	Optional	The value to be set as the Capacity Group's description property.
`capping-enabled`	Boolean	Optional	The value to be set as the capacity group's capping-enabled property.
`absolute-general-purpose-proc-cap`	Float	Optional	The value to be set as the Capacity Group's absolute-general-purpose-proc-cap property.
`absolute-ifl-proc-cap`	Float	Optional	The value to be set as the Capacity Group's absolute-ifl-proc-cap property.

Response body contents

On successful completion, HTTP status code 201 (Created) is returned and a JSON object with the following field is also provided. The element-uri of the capacity group created is also available in the Location header of the response.

Field name	Type	Description
`element-uri`	String/ URI	The element-uri property of the created capacity group.

Description

This operation creates a capacity group with the specified attributes. It is required that the CPC designated by {cpc-id} is in DPM mode. On successful execution, the element-uri of the created capacity group is returned in the response body and in the Location response header. An Inventory Change notification is emitted asynchronously to this operation.

Exactly one processor type must have an absolute processor cap other than 0.0 and within the valid range of 0.01 and 255.0. Otherwise, a 400 (Bad Request) status code is returned.

If the {cpc-id} does not designate a CPC that is in DPM mode, an HTTP status code 409 (Conflict) is returned.

The URI path must designate an existing CPC, and the API user must have object-access permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code 404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage Processor Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

If the request body contents fail to validate, a 400 (Bad Request) status code is returned.

Authorization requirements

This operation has the following authorization requirements:

Object-access permission to the specified CPC.
Action/task permission to the Manage Processor Sharing 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 Capacity Group: 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 the required action/task permission to the Manage Processor Sharing task.
404 (Not Found)	1	The CPC identified by `{cpc-id}` does not exist or the user does not have object-access permission to the CPC.
409 (Conflict)	5	The CPC is not in DPM mode.
409 (Conflict)	329	The operation cannot be performed because the CPC designated by the request URI is an unmanaged CPC, which is not supported by this operation.
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 Capacity Group: Request

POST /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups HTTP/1.1
x-api-session: jht693kvysnx78mws1i0sacatmvougd2y11jz0e0jmgy3fv94
content-type: application/json
content-length: 160
{
   "absolute-general-purpose-proc-cap":5.0,
   "capping-enabled":true,
   "description":"Test Group for CP Procs",
   "name":"Cap group 123",
   "short-name":"CPGRP111"
}

Figure 2. Create Capacity Group: Response

201 Created
server: zSeries management console API web server / 2.0
location: /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/a4d8826c-
   d9fa-11e5-8b15-42f2e9ef1641
cache-control: no-cache
date: Tue, 23 Feb 2016 07:00:57 GMT
content-type: application/json;charset=UTF-8
content-length: 117
{
   "element-uri":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-
      d9fb-11e5-8b3e-42f2e9ef1641"
}