Create Custom Group

Use the Create Custom Group operation to create a custom group. This operation is supported using the BCPii interface.

HTTP method and URI

POST /api/groups

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 Required The name for the new custom Group object
description String Optional The description for the new custom Group object
match-info match-info object Optional A nested object describing the pattern match. If not provided, this is not a pattern-match custom group. Refer to Class specific additional properties for details.

Response body contents

Field name Type Description
object-uri String The object URI of the new custom group.

Description

Group objects are programmatically identified by object-id and not by name. To avoid the confusion which might result from allowing redundant names, the name property is required for this operation, and the (case-sensitive) value supplied for the name property must be distinct from that of all currently-existing Group objects. In keeping with restrictions imposed by the Hardware Management Console's Graphical User Interface (GUI), the following set of names is also not allowed:

  • the current name of the Console
  • the GUI View names {Groups, Exceptions, Active Tasks, Console Actions, Task List, Books, Help, Ensemble}

On success, a custom group managed object is created reflecting the Request Body contents and HTTP status code 201 (Created) is returned.

Authorization requirements

This operation has the following authorization requirement:
  • For the web services interface action/task permission to the Grouping task.
  • For the BCPii interface the source partition must have receive BCPii security controls permissions for the CPC object.

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. In addition, the Location response header contains the URI of the newly created object.

On error, appropriate 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 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.
261 One of the following errors was detected:
  • The pattern string specified in match-info is not valid. This must be a non-empty string which is a valid regular expression.
  • One or more of the types specified in match-info is invalid. At least one type must be specified, and all must be values as documented for the match-info types property.
290 The requested name is either reserved or already in use.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the required authority to perform this operation.
500 (Server Error) 273 An unexpected error occurred during the operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Create Custom Group: Request
POST /api/groups HTTP/1.1
x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp
content-type: application/json
content-length: 74
{
   "description": "Spacely Sprockets Web Servers", 
   "name": "SS-Web-Servers"
}
Figure 2. Create Custom Group: Response
201 Created
server: zSeries management console API web server / 1.0
location: /api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341
cache-control: no-cache
date: Fri, 25 Nov 2011 16:45:44 GMT
content-type: application/json;charset=UTF-8
content-length: 65
{
   "object-uri": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
}