1 Overview
2 Permissions
3 Create a User
4 Create, Modify, and Read a User: XML and JSON Examples
5 Delete a User
- 5.1 Delete a User: URI Parameters
6 List Users
- 6.1 List Users: URI Parameters
- 6.2 List Users: XML and JSON Examples
7 Modify a User
8 Read a User
- 8.1 Read a User: URI Parameters
9 List User Preferences
- 9.1 List User Preferences: URI Parameters
- 9.2 List User Preferences: XML and JSON Examples
10 Read a User Preference
- 10.1 Read a User Preference: URI Parameters
- 10.2 Read a User Preference: XML and JSON Examples
11 Update a User Preference
- 11.1 Update a User Preference: URI Parameters
12 Properties
- 12.1 User Properties
- 12.2 User Permission Properties
  - 12.2.1 Command Permissions
- 12.3 User Preference Properties
- 12.4 User Role Properties
13 Create Personal Access Token
- 13.1 Create Personal Access Token: Payload Properties (XML, JSON)
- 13.2 Create Personal Access Token: XML and JSON Examples
14 List Personal Access Tokens
- 14.1 List Personal Access Tokens: Query Parameters
- 14.2 List Personal Access Tokens: XML and JSON Examples
15 Revoke Personal Access Token
- 15.1 Revoke Personal Access Token: Query Parameters

Overview

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

Create a User
Delete a User
List Users
Modify a User
Read a User
List User Preferences
Read a User Preference
Update a User Preference
Create Personal Access Token
List Personal Access Tokens
Revoke Personal Access Token

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

Note
If you want to change only the User's password, rather than modifying the whole User record, you can use the Password API.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user retainSysIds="true">
    <active>true</active>
    <browserAccess>-- System Default --</browserAccess>
    <businessPhone />
    <commandLineAccess>-- System Default --</commandLineAccess>
    <department />
    <email />
    <firstName>stone b</firstName>
    <impersonate/>
    <lastName>branch</lastName>
    <lockedOut>false</lockedOut>
    <loginMethod>Standard</loginMethod>
    <manager />
    <middleName />
    <mobilePhone />
    <passwordNeedsReset>false</passwordNeedsReset>
    <permissions>
        <permission>
            <allGroups>true</allGroups>
            <commands />
            <defaultGroup>true</defaultGroup>
            <nameWildcard>*</nameWildcard>
            <notGroups>false</notGroups>
            <opCreate>false</opCreate>
            <opDelete>true</opDelete>
            <opExecute>true</opExecute>
            <opRead>true</opRead>
            <opUpdate>true</opUpdate>
            <opswiseGroups/>
            <permissionType>Agent</permissionType>
            <sysId>83c2d3b15d0c417f8a8890be17f1f4cd</sysId>
        </permission>
    </permissions>
    <sysId>4e820e27b548497bb8005bb884f2816a</sysId>
    <timeZone>System</timeZone>
    <title>IT Technician</title>
    <tokens/>
    <userName>stonebranch-user-02</userName>
    <userRoles>
        <userRole>
            <role description="Can create reports that belong to a group to which I am a member.">ops_report_group</role>
            <sysId>018b60fc6bb54ca68571f789e5ee1ad5</sysId>
        </userRole>
        <userRole>
            <role description="Can create global reports.">ops_report_global</role>
            <sysId>b21ecafbcd3f4424bfeca3d9846f2c34</sysId>
        </userRole>
        <userRole>
            <role description="The report publishing role.">ops_report_publish</role>
            <sysId>cb84572b5bf44ddfb1e9e0e9b9d1b65a</sysId>
        </userRole>
    </userRoles>
    <webServiceAccess>-- System Default --</webServiceAccess>
</user>

{
    "active": true,
    "browserAccess": "-- System Default --",
    "businessPhone": null,
    "commandLineAccess": "-- System Default --",
    "department": null,
    "email": null,
    "firstName": "stone b",
    "impersonate": [],
    "lastName": "branch",
    "lockedOut": false,
    "loginMethod": "Standard",
    "manager": null,
    "middleName": null,
    "mobilePhone": null,
    "passwordNeedsReset": false,
    "permissions": [
        {
            "allGroups": true,
            "commands": null,
            "defaultGroup": true,
            "nameWildcard": "*",
            "notGroups": false,
            "opCreate": false,
            "opDelete": true,
            "opExecute": true,
            "opRead": true,
            "opUpdate": true,
            "opswiseGroups": [],
            "permissionType": "Agent",
            "sysId": "83c2d3b15d0c417f8a8890be17f1f4cd"
        }
    ],
    "retainSysIds": true,
    "sysId": "4e820e27b548497bb8005bb884f2816a",
    "timeZone": "System",
    "title": "IT Technician",
    "tokens": [],
    "userName": "stonebranch-user-02",
    "userRoles": [
        {
            "role": {
                "description": "Can create reports that belong to a group to which I am a member.",
                "value": "ops_report_group"
            },
            "sysId": "018b60fc6bb54ca68571f789e5ee1ad5"
        },
        {
            "role": {
                "description": "Can create global reports.",
                "value": "ops_report_global"
            },
            "sysId": "b21ecafbcd3f4424bfeca3d9846f2c34"
        },
        {
            "role": {
                "description": "The report publishing role.",
                "value": "ops_report_publish"
            },
            "sysId": "cb84572b5bf44ddfb1e9e0e9b9d1b65a"
        }
    ],
    "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	http://localhost:8080/uc/resources/user?username=Test_User_Name http://localhost:9080/uc/resources/user?userid=18fcf558002743e38edc49114734b6d9
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 />
        <firstName>stone b</firstName>
        <impersonate/>
        <lastName>branch</lastName>
        <lockedOut>false</lockedOut>
        <loginMethod>Standard</loginMethod>
        <manager />
        <middleName />
        <mobilePhone />
        <passwordNeedsReset>false</passwordNeedsReset>
        <permissions/>
        <sysId>4e820e27b548497bb8005bb884f2816a</sysId>
        <timeZone>System</timeZone>
        <title>IT Technician</title>
        <tokens/>
        <userName>stonebranch-user-02</userName>
        <userRoles>
            <userRole>
                <role description="Can create reports that belong to a group to which I am a member.">ops_report_group</role>
                <sysId>018b60fc6bb54ca68571f789e5ee1ad5</sysId>
            </userRole>
            <userRole>
                <role description="Can create global reports.">ops_report_global</role>
                <sysId>b21ecafbcd3f4424bfeca3d9846f2c34</sysId>
            </userRole>
            <userRole>
                <role description="The report publishing role.">ops_report_publish</role>
                <sysId>cb84572b5bf44ddfb1e9e0e9b9d1b65a</sysId>
            </userRole>
        </userRoles>
        <webServiceAccess>-- System Default --</webServiceAccess>
    </user>
    <user>
        <active>true</active>
        <browserAccess>-- System Default --</browserAccess>
        <businessPhone />
        <commandLineAccess>-- System Default --</commandLineAccess>
        <department />
        <email />
        <firstName>stone c</firstName>
        <impersonate/>
        <lastName>branch</lastName>
        <lockedOut>false</lockedOut>
        <loginMethod>Standard</loginMethod>
        <manager />
        <middleName />
        <mobilePhone />
        <passwordNeedsReset>false</passwordNeedsReset>
        <permissions/>
        <sysId>c212afe3dd6b4cb98cc3cb432cf7be46</sysId>
        <timeZone>System</timeZone>
        <title>IT Technician</title>
        <tokens/>
        <userName>stonebranch-user-03</userName>
        <userRoles/>
        <webServiceAccess>-- System Default --</webServiceAccess>
    </user>
</users>

[
    {
        "active": true,
        "browserAccess": "-- System Default --",
        "businessPhone": null,
        "commandLineAccess": "-- System Default --",
        "department": null,
        "email": null,
        "firstName": "stone b",
        "impersonate": [],
        "lastName": "branch",
        "lockedOut": false,
        "loginMethod": "Standard",
        "manager": null,
        "middleName": null,
        "mobilePhone": null,
        "passwordNeedsReset": false,
        "permissions": [],
        "sysId": "4e820e27b548497bb8005bb884f2816a",
        "timeZone": "System",
        "title": "IT Technician",
        "tokens": [],
        "userName": "stonebranch-user-02",
        "userRoles": [
            {
                "role": {
                    "description": "Can create reports that belong to a group to which I am a member.",
                    "value": "ops_report_group"
                },
                "sysId": "018b60fc6bb54ca68571f789e5ee1ad5"
            },
            {
                "role": {
                    "description": "Can create global reports.",
                    "value": "ops_report_global"
                },
                "sysId": "b21ecafbcd3f4424bfeca3d9846f2c34"
            },
            {
                "role": {
                    "description": "The report publishing role.",
                    "value": "ops_report_publish"
                },
                "sysId": "cb84572b5bf44ddfb1e9e0e9b9d1b65a"
            }
        ],
        "webServiceAccess": "-- System Default --"
    },
    {
        "active": true,
        "browserAccess": "-- System Default --",
        "businessPhone": null,
        "commandLineAccess": "-- System Default --",
        "department": null,
        "email": null,
        "firstName": "stone c",
        "impersonate": [],
        "lastName": "branch",
        "lockedOut": false,
        "loginMethod": "Standard",
        "manager": null,
        "middleName": null,
        "mobilePhone": null,
        "passwordNeedsReset": false,
        "permissions": [],
        "sysId": "c212afe3dd6b4cb98cc3cb432cf7be46",
        "timeZone": "System",
        "title": "IT Technician",
        "tokens": [],
        "userName": "stonebranch-user-03",
        "userRoles": [],
        "webServiceAccess": "-- System Default --"
    },
  
]

Modify a User

	Description

	Description
URI	http://host_name/uc/resources/user
HTTP Method	PUT
Description	Modifies the User specified by the sysId in the request. To modify User properties without modifying related records, see the excludeRelated property.
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.
User Properties	See User Properties.
User Permission Properties	See User Permission Properties.
User Role Properties	See User Role Properties.
Example Response	Status 200 /OK Successfully updated the user with sysId <sysId>.

Read a User

	Description

	Description
URI	http://host_name/uc/resources/user
HTTP Method	GET
Description	Retrieves information on a specific User.
URI Parameters	See Read a User: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/user?username=test.user http://localhost:8080/uc/resources/user?userid=c489750500d444eca9325559d0ef9673 http://localhost:9090/uc/resources/user?username=test&showTokens=true
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
User Properties	See User Properties.
User Permission Properties	See User Permission Properties.
User Role Properties	See User Role Properties.
Example Response	Status 200 /OK (See Create, Modify, and Read a User: XML and JSON Examples.) Status 404 /Not Found A user with id "f87848b00a0001037f43e7c81c8ec969" does not exist.

Read a User: URI Parameters

Name	Description	Specifications	Required	Mutually Exclusive With

Name

Description

Specifications

Required

Mutually Exclusive With

userid

Unique ID for this User.

Y
(unless username
is specified)

username

Name used within the Controller to identify this User.

Maximum 40 alphanumerics.

Y
(unless userid
is specified)