Create User Pattern

Edit online

The Create User Pattern operation creates a User Pattern object with the given properties on the console.

HTTP method and URI

POST /api/console/user-patterns

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 value to be set as the User Pattern's name property.
description String Optional The value to be set as the User Pattern's description property.
pattern String Required The value to be set as the User Pattern's pattern property.
type String Enum Required The value to be set as the User Pattern's type property.
retention-time Integer Required The value to be set as the User Pattern's retention-time property.
user-template-uri String/ URI Required The value to be set as the User Pattern's user-template-uri property.
ldap-server-definition-uri String/ URI Optional The value to be set as the User Pattern's ldap-server-definition-uri property.
template-name-override String Optional The value to be set as the User Pattern's template-name-override property.
domain-name-restrictions String Optional The value to be set as the User Pattern's domain-name-restrictions property.

Response body contents

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

Field name Type Description
element-uri String/ URI Canonical URI path of the new User Pattern object.

Description

This operation creates a new User Pattern.

On successful execution of this operation the User Pattern is created using the inputs as specified by the request body. The new User Pattern is placed at the end of the pattern search order used during logon processing. The URI of the new User Pattern is provided in the response body and in a Location response header as well.

The request body is validated against the schema described in the Request body contents. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. The request body validation will fail if it contains a property that is not valid because a prerequisite is not met (e.g., specifying template-name-override when the ldap-server-definition-uri value is null) or the specified pattern is not unique. If a URI in the request body does not designate an existing resource of the appropriate type, status code 404 (Not Found) is returned In addition, the API user must have action/task permission to the Manage User Patterns task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements

This operation has the following authorization requirement:
  • Action/task permission to the Manage User Patterns 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, and the Location response header contains the URI of the newly created object.

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 associated error message.

Table 1. Create User Pattern: 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 User Pattern with the pattern specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found 324 The ldap-server-definition-uri field in the request body does not designate an existing LDAP Server Definition object.
326 The user-template-uri field in the request body does not designate an existing template type User object.

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

Usage notes

User Patterns are searched in a defined order during logon processing. That order can be customized through the Console object's Reorder User Patterns operation.

Example HTTP interaction

Figure 1. Create User Pattern: Request
POST /api/console/user-patterns HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 260
{
   "description":"User Pattern based on company email addresses",
   "name":"Company email pattern",
   "pattern":".*@our\\.company\\.com",
   "retention-time":8,
   "type":"regular-expression",
   "user-template-uri":"/api/users/ec473e56-4a7a-11e4-91ee-1c6f65065a91"
}
Figure 2. Create User Pattern: Response
201 Created
server: zSeries management console API web server / 2.0
location: /api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 83
{
   "element-uri":"/api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91"
}