List User Patterns

The List User Patterns operation lists User Patterns defined to the console.

HTTP method and URI

GET /api/console/user-patterns

Query Parameters

Name Type Rqd/Opt Description
name String Optional Filter pattern (regular expression) to limit returned objects to those that have a matching name property.
type String Enum Optional Filter string to limit returned objects to those that have a matching type property. Value must be a valid type property value.

Response body contents

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

Field name Type Description
user-patterns Array of objects Array of nested user-pattern-info objects as described in the next table.

Each nested user-pattern-info object contains the following fields:

Field name Type Description
element-uri String/ URI The element-uri property of the User Pattern object.
name String The name property of the User Pattern object.
type String Enum The type property of the User Pattern object.

Description

This operation lists User Patterns defined to the console. Some basic properties are provided for each User Pattern.

A User Pattern is included in the list only if the API user has user-related-access permission to that object or action/task permission to the Manage User Patterns task. If there is a User Pattern to which the API user does not have permission, that object is omitted from the list, but no error status code results.

If there are no User Patterns defined to the console or if no User Patterns are to be included in the results due to filtering or access permissions, an empty list is provided and the operation completes successfully.

Authorization requirements

This operation has the following authorization requirement:
  • User-related-access permission to the User Pattern objects included in the response body or action/task permission to the Manage User Patterns 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.

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.

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.

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 operation Reorder User Patterns. The List User Patterns operation does not specify the order in which the User Pattern URIs appear in the response body, and there is no guarantee that the order in the response will not change in subsequent invocations. Use the search-order-index property to determine a pattern's position in the search order.

Example HTTP interaction

Figure 1. List User Patterns: Request
GET /api/console/user-patterns?type=regular-expression HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
Figure 2. List User Patterns: Response
200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 314
{
   "user-patterns":[
      {
         "element-uri":"/api/console/user-patterns/497bf4ec-1dbf-11e4-8ceb-1c6f65065a91",
         "name":"IBM Intranet User Pattern",
         "type":"regular-expression"
      },
      {
         "element-uri":"/api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91",
         "name":"Company email pattern",
         "type":"regular-expression"
      }
   ]
}