Using REST APIs for User Management and Launchpad Administration

Attribute	Description
ok	Success flag. Possible values are `true` or `false`.
message	Error message, present if `ok` is `false`.

11.1 REST Interface for Creating and Updating Groups

The calling user must have the Access User Administration functional permission for all user administration calls.

The group object used in requests and responses has these attributes:

Attribute	Type	Description
name	String	The name of the group. Always required.
permissions	Array of strings	Functional permissions associated with group. Values are the internal identifiers representing permissions. In create or update requests, all the permissions in a category can be selected using prefix:. For example ops:* or user_admin:*.
applications	Array of strings	Applications available to the group. Values are the internal identifiers for launchpad applications.

Attribute

Type

Description

name

String

The name of the group. Always required.

permissions

Array of strings

Functional permissions associated with group. Values are the internal identifiers representing permissions.

In create or update requests, all the permissions in a category can be selected using prefix:. For example ops:* or user_admin:*.

applications

Array of strings

Applications available to the group. Values are the internal identifiers for launchpad applications.

You can perform the following tasks:

Get all groups
To return an array of group objects, use the following interface:

GET http://server:port/edq/useradmin/groups
Get named group
To get information on a single named group, use the following interface:

GET http://server:port/edq/useradmin/group/name

The result is a group object. If the group does not exist, a 404 response is returned.
Create or update single group
To create or update a single group, use the following interface:

POST http://server:port/edq/useradmin/group

The payload is a single group object. If the permissions or applications attributes are not specified, the corresponding values in the group are not changed on update. If the group does not exist, the calling user must have the Add Group permission, otherwise the user must have the Modify Group permission.
Create or update multiple groups
To create or update multiple groups, use the following interface:

POST http://server:port/edq/useradmin/groups

The payload is an array of group objects.
Delete named group
To delete a named group, use the following interface:

DELETE http://server:port/edq/useradmin/group/name

The user must have the Delete Group permission.

Update group

To update a group, use the following interface:

POST http://server:port/edq/useradmin/updategroup

This request can be used to add or remove permissions or applications from an existing group. The payload is a JSON object with these attributes:

Attribute	Description
name	The name of the group. Always required.
permissions	Permission additions and removals.
applications	Application additions and removals.

The permissions and applications attributes are object with these attributes:

Attribute	Description
add	Array of values to add to the group.
remove	Array of values to remove from the group.

Example:

{ "name": "Test Group",
  "permissions": {
    "add": [ "user_admin:*", "ops:dnviewallevents"],
    "remove": [ "server_admin:accessserveradmin"]
   },
   "applications": {
     "add": ["opsui" ]
   }
}

Get lists of supported applications and functional permissions

Use the following interface:

GET http://server:port/edq/useradmin/permissionsinfo

Group objects list applications and functional permissions using internal identifiers. The call returns lists of all supported applications and permissions including both the display strings used in the administration web UI and the associated identifiers. Permissions are grouped by the categories shown in the group administration web UI.

The result object contains these attributes:

Attribute	Description
applications	List of supported applications.
functionalpermissions	List of permission categories. Each element contains these attributes: categorylabel - Display string for the category. For example "CM.Static" or "Director". prefix - Prefix associated with the category. For example "data:" or "user_admin:". permissions - List of permissions in the category.

Individual application and permission objects contain these attributes:

Attribute	Description
label	Display string for application or permission.
identifier	Internal identifier.

Display strings are returned in the language implied by the web request.

11.2 REST Interface for External Group Mappings

Groups in external realms (LDAP etc) are mapped to EDQ internal group so that the permissions and applications available to a user can be determined on login. Calls in this category return the currently defined mappings and update mappings.

Each mapping is represented by an object with these attributes:

Attribute	Description
realm	The realm name as defined in `login.properties`. In an update call this attribute may be omitted if exactly one external realm is defined.
externalgroup	The name of group in the external realm. Always required.
internalgroups	Array of EDQ internal group names. In an update call, existing mappings are removed if this attribute is omitted or empty.

You can perform the following tasks:

Get current mappings
To retrieve information about the current external group mappings, use the following interface:

GET http://server:port/edq/useradmin/externalgroups

The result is an array of mapping objects.
Update mappings
To update information about the current external group mappings, use the following interface:

POST http://server:port/edq/useradmin/externalgroups

The payload is an array of mapping objects. The calling user must have the Modify External Group Permissions functional permission.

Example:
```
[ 
  { "realm": "EXAMPLE.COM",
    "externalgroup": "edqgroup1",
    "internalgroups": ["Data Analysts"]
  },
  { "realm": "EXAMPLE.COM",
    "externalgroup": "edqgroup2",
    "internalgroups": ["Match Reviewers", "Executives"]
  }
]
```

11.3 REST Interface for Creating and Updating Users

The user object used in requests and responses has these attributes:

Attribute	Type	Description
username	String	The name of the user. Always required.
password	String	The user password. Required when creating a new user.
blocked	Boolean	Set to `true` if the user has been blocked permanently.
fullname	String	The full name of user. Required when creating a new user.
email	String	The e-mail address of user.
organization	String	The name of the user's organization.
telephone	String	The user's telephone number.
forcepasswordchange	Boolean	If `true` forces the user to change their password on the next login.
passwordpolicy	Integer	User password expiration policy. Possible values are: 0 - Password expiry defined by system configuration 1 - Password never expires 2 - Password expires after system defined period
lockoutpolicy	Integer	User lockout policy after bad logins. Possible values are: 0 - Policy defined by system configuration 1 - No action 2 - Lockout for 2 minutes 3 - Lockout for 5 minutes 4 - Lockout for 15 minutes 5 - Lockout for 30 minutes 6 - Lockout for 1 hour 7 - Lockout for 24 hours 8 - Lockout permanently
groups	Array of strings	Groups to associate with the user.

The passwordpolicy and lockoutpolicy attributes correspond to the Password Policy and Invalid Attempts fields in the user definition web UI:

You can perform the following tasks:

Get all users
To return an array of user objects, use the following interface:

GET http://server:port/edq/useradmin/users
Get named user
To get information on a single named user, use the following interface:

GET http://server:port/edq/useradmin/username

The result is a user object. If the user does not exist a 404 response is returned.

Create or update single user

To create or update a single user, use the following interface:

POST http://server:port/edq/useradmin/group

The payload is a single user object. On update, attributes that are not included in the payload object are not modified in the target user. An attribute which is set to null in the payload is cleared in the target user object.

For example to update a user and clear the e-mail address, use this payload:

{ "username": "user23",
  "email":    null
}

To update the password for a user, but force a change on next logon, use the following:

{ "username": "user153",
  "password": "newtemppassword",
  "forcepasswordchange" : true
}

To create a new user, the caller must have the Add User permission. To modify a user, the required permissions depend on the detailed changes. The following table lists the permissions you need corresponding to the information you want to update:

Action	Required Permission
Change password	Change/Reset User Passwords
Block user permanently	Block User
Unblock user	Unblock User
Change full name, e-mail address, organization name or telephone number	Modify User Details
Change password policy, lockout policy or force change option	Modify Account Security Options
Change group membership	Modify User Group Permissions

Create or update multiple users
To create or update multiple users, use the following interface:

POST http://server:port/edq/useradmin/users

The payload is an array of user objects. To modify users, the required permissions depend on the detailed changes as listed in the table above.
Delete named user
To delete a user, the user must have the Delete User permission. Use the following interface:

DELETE http://server:port/edq/useradmin/user/username

11.4 REST Interface for Launchpad Applications

Calls in this category are used to list and update the applications that are shown on the launchpad for all users. The calling user must have the Access Server Administration and Set User Application Access permissions for both calls.

You can perform the following tasks:

Get applications

To return the current list of published applications, and a list of all applications known to the system, use the following interface:

GET http://server:port/edq/admin/web/launchpad/applications

The result object contains these attributes:

Attribute Type Description

Attribute	Type	Description
published	Array of strings	List of applications that are currently shown on the launchpad, in display order.
allapplications	Array of application objects	List of all the applications which are known to the system. Each object contains the following values: label - Display string for application identifier - Internal identifier Note that the `allapplications` list includes applications that are permission controlled by group membership (such as Case Management) and also applications that are links to simple content, such as Watchlist Screening Help.

published

Array of strings

List of applications that are currently shown on the launchpad, in display order.

allapplications

Array of application objects

List of all the applications which are known to the system. Each object contains the following values:

label - Display string for application
identifier - Internal identifier

Note that the allapplications list includes applications that are permission controlled by group membership (such as Case Management) and also applications that are links to simple content, such as Watchlist Screening Help.

Update launchpad applications
To update launchpad applications, use the following interface:

POST http://server:port/edq/admin/web/launchpad/applications

The payload is an array of strings listing the identifiers of the applications that should appear on the launchpad, in order.

For example:
```
[ "opsui", 
  "director", 
  "casemanager", 
  "casemanageradmin"
]
```