/
User Web Services

User Web Services

Jul 31, 2023

Overview

Universal Controller supports the following RESTful-based web services for User operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.

Permissions

The following table identifies the web service operations that a user can perform

Operation

User without any role

User with ops_service_role

User with ops_user_admin or ops_admin role

Operation

User without any role

User with ops_service_role

User with ops_user_admin or ops_admin role

Read

Read its own record (details).

Read its own Role, Permissions, and Member of Groups (group membership),
but cannot read any Group record.

Read any user record.

Create/update/read/delete any fields or any related data.

Update

Update a subset of fields of its own record.

Cannot update any related data.

Update a subset of fields of its own record.

Cannot update any related data.

Create

No permission to create a user.

No permission to create a user.

Delete

No permission to delete a user.

No permission to delete a user.



Create a User



Description



Description

URI

http://host_name/uc/resources/user

HTTP Method



Description

Creates a new User.

Example URI

http://localhost:8080/uc/resources/user

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example

See Create, Modify, and Read a User: XML and JSON Examples: XML and JSON Examples, below.

User Properties

See User Properties, below.

User Permission Properties

See User Permission Properties, below.

User Role Properties

See User Role Properties, below.

Example Response

  • Status 200 /OK
    Successfully created the user with sysId {sysId}.

Create, Modify, and Read a User: XML and JSON Examples

The excludeRelated and retainSysIds properties are specified as attributes in the <user> element of XML web services.
 

XML

JSON

XML

JSON

<user retainSysIds="true"> <active>true</active> <browserAccess>-- System Default --</browserAccess> <businessPhone /> <commandLineAccess>-- System Default --</commandLineAccess> <department /> <email>test@test.com</email> <firstName>Joe</firstName>
<impersonate/> <lastName>Doe</lastName> <lockedOut>false</lockedOut> <loginMethod>Standard, Single Sign-On</loginMethod> <manager>Administrator</manager> <middleName>M</middleName> <mobilePhone /> <passwordNeedsReset>false</passwordNeedsReset> <permissions> <permission> <allGroups>false</allGroups> <commands>ALL</commands> <defaultGroup>true</defaultGroup> <nameWildcard>*</nameWildcard> <opCreate>false</opCreate> <opDelete>true</opDelete> <opExecute>true</opExecute> <opRead>true</opRead> <opUpdate>true</opUpdate> <opswiseGroups /> <permissionType>Agent</permissionType> <sysId>c489750500d444eca9325559d0ef9673</sysId> </permission> </permissions> <sysId>3de4c72e27c94d4aa840bffcbd7509ca</sysId> <timeZone /> <title>Vice President</title> <userName>test.user</userName> <userPassword>abc123</userPassword> <userRoles> <userRole> <role description="The universal template admin role.">ops_universal_template_admin</role> <sysId>187ecb3a27544b7fb702caee6dc8d5e3</sysId> </userRole> <userRole> <role description="The report publishing role.">ops_report_publish</role> <sysId>2e1dc86f47c6431884373f0e06b841da</sysId> </userRole> </userRoles> <webServiceAccess>-- System Default --</webServiceAccess> </user>

{ "active": true, "browserAccess": "-- System Default --", "businessPhone": null, "commandLineAccess": "-- System Default --", "department": null, "email": "test@test.com", "firstName": "Joe",
"impersonate":[], "lastName": "Doe", "lockedOut": false, "loginMethod": Standard, Single Sign-On", "manager": "Administrator", "middleName": "M", "mobilePhone": null, "passwordNeedsReset": false, "permissions": [ { "allGroups": false, "commands": "ALL", "defaultGroup": true, "nameWildcard": "*", "opCreate": false, "opDelete": false, "opExecute": true, "opRead": true, "opUpdate": true, "opswiseGroups": [], "permissionType": "Agent", "sysId": "c489750500d444eca9325559d0ef9673" } ], "retainSysIds": true, "sysId": "3de4c72e27c94d4aa840bffcbd7509ca", "timeZone": null, "title": "Vice President", "userName": "test.user", "userPassword": "abc123", "userRoles": [ { "role": { "description": "The universal template admin role.", "value": "ops_universal_template_admin" }, "sysId": "b8c25922d370438aada276cff669136d" }, { "role": { "description": "The report publishing role.", "value": "ops_report_publish" }, "sysId": "fda36f00cc4544bc8f7fbd203290539a" } ], "webServiceAccess": "-- System Default --" }


Delete a User



Description



Description

URI

http://host_name/uc/resources/user

HTTP Method

DELETE

Description

Deletes a User.

URI Parameters

See Delete a User URI Parameters, below.

Example URI

Example Response

  • Status 200 /OK
    User {username} deleted successfully.

  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify userid and username at the same time.

  • Status 404 /Not Found
    User with {username/userid} does not exist.

Delete a User: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

Parameter

Description

Specifications

Required

Mutually Exclusive With

userid

ID used within the Controller to identify this user.

String; URI parameter.

Y (unless userename is specified)

username

username

Name used within the Controller to identify this user.

String; URI parameter.

Y (unless userid is specified)

userid


List Users



Description



Description

URI

http://host_name/uc/resources/user/list

HTTP Method

GET

Description

Retrieves information on all Users.

Example URI

http://localhost:8080/uc/resources/user/list

http://localhost:9090/uc/resources/user/list?showTokens=true

Authentication

HTTP Basic

Produces Content-Type

application/xml, application/json

Example

See List Users: XML and JSON Examples.

User Properties

See User Properties.

User Permission Properties

See User Permission Properties.

User Role Properties

See User Role Properties.

List Users: URI Parameters 

Name

Description

Specifications

Required

Name

Description

Specifications

Required

showTokens

Show personal access tokens.

Boolean

  • True - Includes the Token details

  • False (Default) - Empty Token List

N

List Users: XML and JSON Examples

XML

JSON

XML

JSON

<users>
<user> <active>true</active> <browserAccess>-- System Default --</browserAccess> <businessPhone /> <commandLineAccess>-- System Default --</commandLineAccess> <department /> <email>test@test.com</email> <firstName>Joe</firstName>
<impersonate/> <lastName>Doe</lastName> <lockedOut>false</lockedOut> <loginMethod>Standard, Single Sign-On</loginMethod> <manager>Administrator</manager> <middleName>M</middleName> <mobilePhone /> <passwordNeedsReset>false</passwordNeedsReset> <permissions /> <sysId>3de4c72e27c94d4aa840bffcbd7509ca</sysId> <timeZone /> <title>Vice President</title> <userName>test.user</userName> <userPassword>abc123</userPassword> <userRoles /> <webServiceAccess>-- System Default --</webServiceAccess> </user>
<user>
<active>true</active>
<browserAccess>-- System Default --</browserAccess>
<businessPhone />
<commandLineAccess>-- System Default --</commandLineAccess>
<department />
<email>test@test.com</email>
<firstName>Joe</firstName>
<lastName>Doe</lastName>
<impersonate/>
<lockedOut>false</lockedOut>
<loginMethod>Standard, Single Sign-On</loginMethod>
<manager>Administrator</manager>
<middleName>M</middleName>
<mobilePhone />
<passwordNeedsReset>false</passwordNeedsReset>
<permissions>
<permission>
<allGroups>false</allGroups>
<commands>ALL</commands>
<defaultGroup>true</defaultGroup>
<nameWildcard>*</nameWildcard>
<opCreate>false</opCreate>
<opDelete>true</opDelete>
<opExecute>true</opExecute>
<opRead>true</opRead>
<opUpdate>true</opUpdate>
<opswiseGroups />
<permissionType>Agent</permissionType>
<sysId>c489750500d444eca9325559d0ef9673</sysId>
</permission> <permissions> <sysId>3de4c72e27c94d4aa840bffcbd7509ca</sysId> <timeZone /> <title>Vice President</title> <userName>test.user</userName> <userPassword>abc123</userPassword> <userRoles /> <webServiceAccess>-- System Default --</webServiceAccess> </user></users>