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
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
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

<?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>

JSON

{
    "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
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/resourcess/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
`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
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

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

<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>

JSON

[
    {
        "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
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
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

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)

userid

showTokens

Show personal access tokens.

Boolean

True - Includes the Token details
False (Default) - Empty Token List

N

List User Preferences


URI	http://host_name:port/uc/resources/user/preference/list
HTTP Method	GET
Description	Retrieves information on all user preferences for a particular user.
Example URI	http://localhost:8080/uc/resources/user/preference/list?username=ops.admin
Authentication	HTTP Basic
Produces Content-Type	Application/XML, Application/JSON
Consumes Content-Type	N/A
Example Responses	Status 200 (See List User Preferences: XML and JSON Examples) Status 403 Operation prohibited due to security constraints. Status 500 Unexpected request failure. See log(s) for more details.

List User Preferences: URI Parameters

Property	Description	Required	Mutual Exclusive With
`userid`	Unique ID for this User.	N	`username`
`username`	Name used within the Controller to identify this User.	N	`userid`

List User Preferences: XML and JSON Examples

XML

JSON

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<preferences>
    <preference>
        <name label="Activity Monitor Automatically">uc.activity.monitor_automatically</name>
        <value>No</value>
    </preference>
    <preference>
        <name label="Activity Refresh Rate">uc.activity.refresh_rate</name>
        <value>10 seconds</value>
    </preference>
    <preference>
        <name label="Activity Results Per Page">uc.activity.results_per_page</name>
        <value>25 per page</value>
    </preference>
    <preference>
        <name label="Activity Time Constraint">uc.activity.time_window</name>
        <value>Last week</value>
    </preference>
    <preference>
        <name label="Agent Task Instances Tab Time Constraint">uc.agent.task_instances.tab.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Audit Time Constraint">uc.audit.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Boolean Column Display Format">uc.grid.column.boolean.format</name>
        <value>Yes/No</value>
    </preference>
    <preference>
        <name label="Console Error Fade Out Delay">uc.console.error.fadeout_delay</name>
        <value>10</value>
    </preference>
    <preference>
        <name label="Console Info Fade Out Delay">uc.console.info.fadeout_delay</name>
        <value></value>
    </preference>
    <preference>
        <name label="Console Location">uc.console.location</name>
        <value>Bottom</value>
    </preference>
    <preference>
        <name label="Console Open For Info">uc.console.info.open</name>
        <value>Yes</value>
    </preference>
    <preference>
        <name label="Dashboard Force Refresh On Focus">uc.dashboard.refresh_on_focus</name>
        <value>Yes</value>
    </preference>
    <preference>
        <name label="Dashboard Force Refresh On Focus Threshold">uc.dashboard.refresh_on_focus.threshold</name>
        <value>25 seconds</value>
    </preference>
    <preference>
        <name label="Expand Lists Automatically">uc.lists.expand_automatically</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Go To Operator">uc.grid.go_to.operator</name>
        <value>contains</value>
    </preference>
    <preference>
        <name label="History Time Constraint">uc.history.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Navigation Auto Collapse">uc.navigation.auto_collapse</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Node Time Display">uc.node_time.display</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Node Time Display Background Color">uc.node_time.display.background_color</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Node Time Display Color">uc.node_time.display.color</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Node Time Display Time Zone">uc.node_time.display.tz</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Pin Tabs Automatically">uc.tabs.pin_automatically</name>
        <value>No</value>
    </preference>
    <preference>
        <name label="Record New In Tab">uc.record.new_in_tab</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Record Open In Tab">uc.record.open_in_tab</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Reference New In Tab">uc.reference.new_in_tab</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Reference Open In Tab">uc.reference.open_in_tab</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Reference Picker Display Columns">uc.reference.picker.display_columns</name>
        <value>2</value>
    </preference>
    <preference>
        <name label="Services Recently Visited Limit">uc.services.recently_visited.limit</name>
        <value>10</value>
    </preference>
    <preference>
        <name label="Services Show Animations">uc.services.show_animations</name>
        <value>Yes</value>
    </preference>
    <preference>
        <name label="Show Metadata">uc.form.show_metadata</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Show Variables Fetch Global Automatically">uc.show_variables.fetch_global</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Target Task Instances Tab Time Constraint">uc.target_task_instances.tab.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Task Instances Tab Time Constraint">uc.task_instances.tab.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Task Instances Time Constraint">uc.task_instances.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Trigger Task Instances Tab Time Constraint">uc.trigger_task_instances.tab.time_window</name>
        <value>Last 48 hours</value>
    </preference>
    <preference>
        <name label="Use Dashboard Visibility Icons">uc.dashboard.use_visibility_icons</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="Use Default Dashboard For Home">uc.home.use_default_dashboard</name>
        <value>No</value>
    </preference>
    <preference>
        <name label="User Interface Density">uc.user_interface.density</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="User Interface Theme">uc.user_interface.theme</name>
        <value>-- System Default --</value>
    </preference>
    <preference>
        <name label="View/Edit JCL Credentials">uc.task.zos.view_edit_jcl.credentials</name>
        <value></value>
    </preference>
</preferences>

JSON

[
    {
        "name": {
            "label": "Activity Monitor Automatically",
            "value": "uc.activity.monitor_automatically"
        },
        "value": "No"
    },
    {
        "name": {
            "label": "Activity Refresh Rate",
            "value": "uc.activity.refresh_rate"
        },
        "value": "10 seconds"
    },
    {
        "name": {
            "label": "Activity Results Per Page",
            "value": "uc.activity.results_per_page"
        },
        "value": "25 per page"
    },
    {
        "name": {
            "label": "Activity Time Constraint",
            "value": "uc.activity.time_window"
        },
        "value": "Last week"
    },
    {
        "name": {
            "label": "Agent Task Instances Tab Time Constraint",
            "value": "uc.agent.task_instances.tab.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Audit Time Constraint",
            "value": "uc.audit.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Boolean Column Display Format",
            "value": "uc.grid.column.boolean.format"
        },
        "value": "Yes/No"
    },
    {
        "name": {
            "label": "Console Error Fade Out Delay",
            "value": "uc.console.error.fadeout_delay"
        },
        "value": "10"
    },
    {
        "name": {
            "label": "Console Info Fade Out Delay",
            "value": "uc.console.info.fadeout_delay"
        },
        "value": ""
    },
    {
        "name": {
            "label": "Console Location",
            "value": "uc.console.location"
        },
        "value": "Bottom"
    },
    {
        "name": {
            "label": "Console Open For Info",
            "value": "uc.console.info.open"
        },
        "value": "Yes"
    },
    {
        "name": {
            "label": "Dashboard Force Refresh On Focus",
            "value": "uc.dashboard.refresh_on_focus"
        },
        "value": "Yes"
    },
    {
        "name": {
            "label": "Dashboard Force Refresh On Focus Threshold",
            "value": "uc.dashboard.refresh_on_focus.threshold"
        },
        "value": "25 seconds"
    },
    {
        "name": {
            "label": "Expand Lists Automatically",
            "value": "uc.lists.expand_automatically"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Go To Operator",
            "value": "uc.grid.go_to.operator"
        },
        "value": "contains"
    },
    {
        "name": {
            "label": "History Time Constraint",
            "value": "uc.history.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Navigation Auto Collapse",
            "value": "uc.navigation.auto_collapse"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Node Time Display",
            "value": "uc.node_time.display"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Node Time Display Background Color",
            "value": "uc.node_time.display.background_color"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Node Time Display Color",
            "value": "uc.node_time.display.color"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Node Time Display Time Zone",
            "value": "uc.node_time.display.tz"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Pin Tabs Automatically",
            "value": "uc.tabs.pin_automatically"
        },
        "value": "No"
    },
    {
        "name": {
            "label": "Record New In Tab",
            "value": "uc.record.new_in_tab"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Record Open In Tab",
            "value": "uc.record.open_in_tab"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Reference New In Tab",
            "value": "uc.reference.new_in_tab"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Reference Open In Tab",
            "value": "uc.reference.open_in_tab"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Reference Picker Display Columns",
            "value": "uc.reference.picker.display_columns"
        },
        "value": "2"
    },
    {
        "name": {
            "label": "Services Recently Visited Limit",
            "value": "uc.services.recently_visited.limit"
        },
        "value": "10"
    },
    {
        "name": {
            "label": "Services Show Animations",
            "value": "uc.services.show_animations"
        },
        "value": "Yes"
    },
    {
        "name": {
            "label": "Show Metadata",
            "value": "uc.form.show_metadata"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Show Variables Fetch Global Automatically",
            "value": "uc.show_variables.fetch_global"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Target Task Instances Tab Time Constraint",
            "value": "uc.target_task_instances.tab.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Task Instances Tab Time Constraint",
            "value": "uc.task_instances.tab.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Task Instances Time Constraint",
            "value": "uc.task_instances.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Trigger Task Instances Tab Time Constraint",
            "value": "uc.trigger_task_instances.tab.time_window"
        },
        "value": "Last 48 hours"
    },
    {
        "name": {
            "label": "Use Dashboard Visibility Icons",
            "value": "uc.dashboard.use_visibility_icons"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "Use Default Dashboard For Home",
            "value": "uc.home.use_default_dashboard"
        },
        "value": "No"
    },
    {
        "name": {
            "label": "User Interface Density",
            "value": "uc.user_interface.density"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "User Interface Theme",
            "value": "uc.user_interface.theme"
        },
        "value": "-- System Default --"
    },
    {
        "name": {
            "label": "View/Edit JCL Credentials",
            "value": "uc.task.zos.view_edit_jcl.credentials"
        },
        "value": ""
    }
]

Read a User Preference


URI	http://host_name:port/uc/resources/user/preference
HTTP Method	GET
Description	Retrieves information on a specific user preference for a particular user.
Example URI	http://localhost:8080/uc/resources/user/preference?preferencename=uc.activity.monitor_automatically&username=ops.admin
Authentication	HTTP Basic
Produces Content-Type	Application/XML, Application/JSON
Consumes Content-Type	N/A
Example Responses	Status 200 (See Read a User Preference: XML and JSON Examples) Status 403 Operation prohibited due to security constraints. Status 404 A user preference with name "{preferencename}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

Read a User Preference: URI Parameters

Property

Description

Specifications

Required

Mutual Exclusive With

preferencename

User preference name.

See User Preference Properties.

Y

userid

Unique ID for this User.

N

username

Name used within the Controller to identify this User.

N

userid

Read a User Preference: XML and JSON Examples

XML

JSON

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<preference>
    <name label="Activity Monitor Automatically">uc.activity.monitor_automatically</name>
    <value>No</value>
</preference>

JSON

{
    "name": {
        "label": "Activity Monitor Automatically",
        "value": "uc.activity.monitor_automatically"
    },
    "value": "No"
}

Update a User Preference


URI	http://host_name:port/uc/resources/user/preference
HTTP Method	PUT
Description	Modify a user preference for a particular user.
Example URI	http://localhost:8080/uc/resources/user/preference?preferencename=uc.activity.monitor_automatically&value=No&username=ops.admin
Authentication	HTTP Basic
Example Responses	Status 200 User Preference updated successfully. Status 400 Error message. Status 403 Operation prohibited due to security constraints. Status 404 A user preference with name "{preferencename}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

Update a User Preference: URI Parameters

Property	Description	Specifications	Required	Mutual Exclusive With
`preferencename`	User preference name.	See User Preference Properties.	Y
`value`	User preference value.	See User Preference Properties.	Y
`userid`	Unique ID for this User.		N	`username`
`username`	Name used within the Controller to identify this User.		N	`userid`

Properties

User Properties

Property	UI Field Name	Description	Specifications	Required
`active`	Active	Specification for whether or not the user is active. An active user can log in to the Controller. An inactive user cannot log in to the Controller, and the user will not appear in user lists.	Boolean. Valid Values: true/false. Default is false.	N
`browserAccess`	Web Browser Access	Specification for whether or not the user can log in to the user interface.	Valid Values: As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2 Default is – System Default – (0).	N
`businessPhone`	Business Phone	Business phone number of this user.		N
`commandLineAccess`	Command Line Access	Specification for whether or not the user can log in to the Universal Controller Command Line Interface (CLI).	Valid values: As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2 Default is – System Default – (0).	N
`department`	Department	Business department of this user.		N
`email`	Email	Email address of this user.		N
`excludeRelated`	n/a	For the Modify User web service; specification for whether or not to exclude related records (User Permissions, User Roles) from the update, even if they are provided in the request. Note In XML, `excludeRelated` is specified as an attribute in the <user> element.	Valid values: true/false (default is false).	N
`firstName`	First Name	First Name of this user.		N
`impersonate`	Allowed Impersonation Users	Specifies the users that can be impersonated by this user using the X-Impersonate-User HTTP header on Web Service requests. User impersonation requires the ops_user_impersonate role. Users with the ops_admin role can impersonate any user and do not need to specify Allowed Impersonation Users. Format: XML <impersonate> <allowed>jane.doe</allowed> <allowed>john.doe</allowed> </impersonate> JSON "impersonate": [ "jane.doe", "john.doe" ]		N
`lastName`	Last Name	Last Name of this user.		N
`lockedOut`	Locked out	Specification for whether or not the user is locked out of the Controller.	Boolean. Valid Values: true/false. Default is false.	N
`loginMethod`	Login Methods	Login method(s) that the user can authenticate with.	Valid Values: Standard Single Sign-On Standard, Single Sign-On Standard / Authenticator App (TOTP) Standard / Authenticator App (TOTP), Single Sign-On	N
`manager`	Manager	Business manager of this user.	Manager user ID	N
`middleName`	Middle Name	Middle Name of this user.		N
`mobilePhone`	Mobile Phone	Mobile phone number of this user.		N
`passwordNeedsReset`	Password Requires Reset	Specification for whether or not the user will be prompted to reset the password at next login.	Boolean. Valid Values: true/false. Default is false.	N
`retainSysIds`	n/a	Specification for whether or not the Create a User web service will persist the sysId property. If retainSysIds="true" and `sysId` is included in the request/response, `sysId` will be persisted to the database. If retainSysIds="false" and `sysId` is included in the request/response, `sysId`will be ignored; it will be autogenerated by the Controller. Note In XML, `retainSysIds` is specified as an attribute in the <user> element.	Valid values: true/false (default is true).	N
`sysId`	n/a	System ID field in the database for this record.	Persisted only if retainSysIds is set to true.	N
`timeZone`	Time Zone	Time zone of this user.	When this user logs in, all scheduling times will be shown in the user's time zone, unless the trigger specifies a different time zone.	N
`title`	Title	Business title of this user.		N
`tokens`	Personal Access Tokens	List of personal access tokens. If `showTokens` = true, these tokens will be displayed in the response. Format: XML <tokens> <token> <createTime>2022-10-26 16:14:54 -0400</createTime> <expiration>20221230</expiration> <lastUsed>20221026</lastUsed> <name>test1</name> <userName>ops.admin</userName> </token> </tokens> JSON "tokens": [ { "createTime": "2022-10-26 16:14:54 -0400", "expiration": "20221230", "lastUsed": "20221026", "name": "test1", "userName": "ops.admin" }, { "createTime": "2022-10-26 16:29:22 -0400", "expiration": "Never", "lastUsed": "Never", "name": "test2", "userName": "ops.admin" } ],		N
`showTokens`	n/a	Specifies whether the tokens will be displayed in the response.	Boolean. Valid Values: true/false. Default is false.	N
`userName`	User ID	Log in ID for this user.		Y
`userPassword`	Password	Password of this user. If `userPassword` is included in the request, `userPassword` will be updated. Alternatively, the User's password can be changed with the Password API.	Used only by the Create a User and Modify a User web services.	Y (for Create a User)
`webServiceAccess`	Web Service Access	Specification for whether or not the user can log in to the Universal Controller RESTful Web Services API.	Valid values: As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2 Default is – System Default – (0).	N

User Permission Properties

Property	UI Field Name	Description	Specifications	Required
`allGroups`	Member of Any Business Service or Unassigned Business Service Criteria Member of Any Business Service or Unassigned	Specification for whether or not this permission applies both to records that belong to any Business Service and to records that do not belong to any Business Service. If `allGroups` is specified as true, `defaultGroup` is set to true, `notGroups` is set to false, and `opswiseGroups` is cleared, regardless of what you specify in the payload.	Boolean. Valid Values: true/false. Default is false.	N
`commands`	Commands	Commands that are associated with each permission.	Valid values: see Command Permissions, below.	N
`defaultGroup`	Unassigned to Business Service Business Service Criteria Member of Specific Business Services or Unassigned Unassigned Not Member of Specific Business Services or Unassigned	Specification for whether or not this permission applies to records that do not belong to any Business Service.	Boolean. Valid Values: true/false. Default is false.	N
`nameWildcard`	Name	Specification to apply this permission to records whose name matches the string specified here.	Wildcards (*'s) can be used.	Y
`notGroups`	Not Member of Business Services Business Service Criteria Not Member of Specific Business Services or Unassigned Not Member of Specific Business Services	Specification for whether or not this permission applies to records that are a member of `opswiseGroups` or not a member of `opswiseGroups`.	Boolean. Valid Values: true/false. Default is false.	N
`opCreate`	Create	Allows the user to create records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. Cannot be set to true if `permissionType` is Agent.	N
`opDelete`	Delete	Allows the user to delete records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false.	N
`opExecute`	Execute	Allows the user to execute records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. If the Strict Connection Execute Constraints Universal Controller system property is false: `opExecute` can be set to true only if `permissionType` is Agent, Credential, Script, or Virtual Resource. If the Strict Connection Execute Constraints Universal Controller system property is true: `opExecute` can be set to true only if `permissionType` is Agent, Credential, Database Connection, Email Connection, SAP Connection, Script, SNMP Manager, or Virtual Resource.	N
`opRead`	Read	Allows the user to read records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. If the Strict Business Service Membership Read Constraints Universal Controller system property is false: `opRead` must be set to true if `permissionType` is Agent, Agent Cluster, Calendar, Credential, Database Connection, Email Connection, SAP Connection, Email Template, SNMP Manager, or Virtual Resource.	N
`opUpdate`	Update	Allows the user to update records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. Must be set to true if `opCreate` is set to true.	N
`opswiseGroups`	Member of Business Services	Applies this permission to records that are members of the selected Business Service(s). XML JSON		N
`permissionType`	Type	Type of permission for this user.	Valid values: As String = Agent, As Value = 1 As String = Calendar, As Value = 2 As String = Credential, As Value = 3 As String = Task, As Value = 4 As String = Task Instance, As Value = 5 As String = Trigger, As Value = 6 As String = Application, As Value = 7 As String = Script, As Value = 8 As String = Variable, As Value = 9 As String = Virtual Resource, As Value = 10 As String = Agent Cluster, As Value = 11 As String = Email Template, As Value = 12 As String = Email Connection, As Value = 13 As String = Database Connection, As Value = 14 As String = SAP Connection, As Value = 15 As String = SNMP Manager, As Value = 16 As String = PeopleSoft Connection, As Value = 17 As String = Bundle, As Value = 18 As String = Promotion Target, As Value = 19 As String = OMS Server, As Value = 20	Y
`sysId`	n/a	System ID field in the database for a record.	Persisted only if retainSysIds is set to true.	N

Command Permissions

Permission Type	Commands
Agent	ALL resume_agent suspend_agent
Agent Cluster	ALL resolve_agent_cluster resume_agent_cluster suspend_agent_cluster resume_agent_cluster_membership suspend_agent_cluster_membership
Application	ALL appl_start appl_stop appl_query
Bundle	ALL promote_bundle
Calendar	ALL copy_calendar
Credential
Database Connection	ALL copy_database_connection database_connection_test
Email Connection	ALL copy_email_connection email_connection_test
Email Template	ALL copy_email_template
OMS Server	ALL resume_oms_server suspend_oms_server
PeopleSoft Connection	ALL copy_peoplesoft_connection
Promotion Target	ALL refresh_target_agents
SAP Connection	ALL copy_sap_connection
Script	ALL copy_script
SNMP Manager	ALL copy_snmp_manager
Task	ALL copy_task launch recalculate_forecast reset_statistics reset_zos_override_statistics set_execution_restriction
Task Instance	ALL cancel clear_all_dependencies clear_exclusive clear_resources clear_timewait force_finish force_finish_cancel hold insert_task rerun release release_recursive retrieve_output set_edge_satisfied (Mark as Satisfied in UI) set_edges_satisfied (Clear Predecessors in UI) set_priority_low set_priority_medium set_priority_high set_manual_completed set_manual_started skip unskip
Trigger	ALL assign_trigger_execution_user copy_trigger disable_trigger enable_trigger recalculate_forecast set_skip_count trigger_now
Variable
Virtual Resource	ALL copy_virtual_resource

User Preference Properties

See User Preferences for more information on each user preference.

Property Name	UI Name	Valid Values	Allow Empty Value
`uc.activity.monitor_automatically`	`Activity Monitor Automatically`	Yes No	N
`uc.activity.refresh_rate`	`Activity Refresh Rate`	As String = 5 seconds, As Value = 5000 As String = 10 seconds, As Value = 10000 As String = 15 seconds, As Value = 15000 As String = 20 seconds, As Value = 20000 As String = 25 seconds, As Value = 25000 As String = 30 seconds, As Value = 30000 As String = 45 seconds, As Value = 45000 As String = 1 minute, As Value = 60000	N
`uc.activity.results_per_page`	`Activity Results Per Page`	As String = 15 per page, As Value = 15 As String = 20 per page, As Value = 20 As String = 25 per page, As Value = 25 As String = 30 per page, As Value = 30 As String = 35 per page, As Value = 35 40 per page, As Value = 40 As String = 45 per page, As Value = 45 As String = 50 per page, As Value = 50	N
`uc.activity.time_window`	`Activity Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.agent.task_instances.tab.time_window`	`Agent Task Instances Tab Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.audit.time_window`	`Audit Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.grid.column.boolean.format`	`Boolean Column Display Format`	As String = Yes/No, As Value = 1 As String = Checkbox, As Value = 2	N
`uc.console.location`	`Console Location`	As String = Browser Top, As Value = 1 As String = Browser Bottom, As Value = 2 As String = Top, As Value = 3 As String = Bottom, As Value = 4	N
`uc.console.error.fadeout_delay`	`Console Error Fade Out Delay`	Integer: 1-15	Y
`uc.console.info.fadeout_delay`	`Console Info Fade Out Delay`	Integer: 1-15	Y
`uc.console.info.open`	`Console Open For Info`	Yes No	N
`uc.dashboard.refresh_on_focus`	`Dashboard Force Refresh On Focus`	Yes No	N
`uc.dashboard.refresh_on_focus.threshold`	`Dashboard Force Refresh On Focus Threshold`	As String = 5 seconds, As Value = 5 As String = 10 seconds, As Value = 10 As String = 15 seconds, As Value = 15 As String = 20 seconds, As Value = 20 As String = 25 seconds, As Value = 25 As String = 30 seconds, As Value = 30 As String = 35 seconds, As Value = 35 As String = 40 seconds, As Value = 40 As String = 45 seconds, As Value = 45 As String = 50 seconds, As Value = 50 As String = 55 seconds, As Value = 55 As String = 1 minute, As Value = 60	N
`uc.grid.go_to.operator`	`Go To Operator`	As String = contains, As Value = 1 As String = starts with, As Value = 2 As String = equals, As Value = 4	N
`uc.history.time_window`	`History Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.node_time.display`	`Node Time Display`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.node_time.display.tz`	`Node Time Display Time Zone`	As String = -- System Default --, As Value = 0 As String = Server, As Value = 1 As String = User, As Value = 2	N
`uc.node_time.display.background_color`	`Node Time Display Background Color`	As String = -- System Default --, As Value = 0 As String = Black, As Value = 10 As String = Blue, As Value = 20 As String = Gray, As Value = 30 As String = Green, As Value = 40 As String = LimeGreen, As Value = 50 As String = Maroon, As Value = 60 As String = Orange, As Value = 70 As String = Purple, As Value = 80 As String = Red, As Value = 90 As String = Transparent, As Value = 100 As String = White, As Value = 110 As String = Yellow, As Value = 120	N
`uc.node_time.display.color`	`Node Time Display Color`	As String = -- System Default --, As Value = 0 As String = Black, As Value = 10 As String = Blue, As Value = 20 As String = Gray, As Value = 30 As String = Green, As Value = 40 As String = LimeGreen, As Value = 50 As String = Maroon, As Value = 60 As String = Orange, As Value = 70 As String = Purple, As Value = 80 As String = Red, As Value = 90 As String = White, As Value = 110 As String = Yellow, As Value = 120	N
`uc.tabs.pin_automatically`	`Pin Tabs Automatically`	Yes No	N
`uc.reference.picker.display_columns`	`Reference Picker Display Columns`	As String = 1, As Value = 1 As String = 2, As Value = 2 As String = 3, As Value = 3 As String = ALL, As Value = 10	N
`uc.form.show_metadata`	`Show Metadata`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.show_variables.fetch_global`	`Show Variables Fetch Global Automatically`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.task_instances.time_window`	`Task Instances Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.task_instances.tab.time_window`	`Task Instances Tab Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.dashboard.use_visibility_icons`	`Use Dashboard Visibility Icons`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.home.use_default_dashboard`	`Use Default Dashboard For Home`	Yes No	N
`uc.target_task_instances.tab.time_window`	`Target Task Instances Tab Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.trigger_task_instances.tab.time_window`	`Trigger Task Instances Tab Time Constraint`	As String = Last 5 minutes, As Value = 5 As String = Last 15 minutes, As Value = 15 As String = Last 30 minutes, As Value = 30 As String = Last hour, As Value = 60 As String = Last 12 hours, As Value = 720 As String = Last 24 hours, As Value = 1440 As String = Last 48 hours, As Value = 2880 As String = Last week, As Value = 10080 As String = Last 2 weeks, As Value = 20160 As String = Last 3 weeks, As Value = 30240 As String = Last 4 weeks, As Value = 40320 As String = Last 30 days, As Value = 43200 As String = Last 60 days, As Value = 86400 As String = Last 90 days, As Value = 129600	N
`uc.user_interface.theme`	`User Interface Theme`	As String = -- System Default --, As Value = 0 As String = Light, As Value = 6 As String = Dark, As Value = 7	N
`uc.user_interface.density`	`User Interface Density`	As String = -- System Default --, As Value = 0 As String = Dense, As Value = 2 As String = Compact, As Value = 4 As String = Standard, As Value = 6 As String = Expanded, As Value = 8 As String = Spacious, As Value = 10	N
`uc.services.recently_visited.limit`	`Services Recently Visited Limit`	Integer: 1-30	Y
`uc.services.show_animations`	`Services Show Animations`	Yes No	N
`uc.lists.expand_automatically`	`Expand Lists Automatically`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.navigation.auto_collapse`	`Navigation Auto Collapse`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.navigation.bar.auto_collapse`	`Navigation Bar Auto Collapse`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.reference.open_in_tab`	`Reference Open In Tab`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.record.open_in_tab`	`Record Open In Tab`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.reference.new_in_tab`	`Reference New In Tab`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.record.new_in_tab`	`Record New In Tab`	As String = -- System Default --, As Value = 0 As String = Yes, As Value = 1 As String = No, As Value = 2	N
`uc.task.zos.view_edit_jcl.credentials`	`View/Edit JCL Credentials`		Y

User Role Properties

Property	UI Field Name	Description	Specifications	Required
`role`	n/a	Role assigned to this user.		N
`sysId`	n/a	System ID field in the database for a record.		N

Create Personal Access Token

	Description
URI	http://host_name/uc/resources/user/token
HTTP Method	POST
Description	Create the personal access token
Example URI	http://localhost:8080/uc/resources/user/token
Authentication	HTTP Basic
Produces Content-Type	text/plain
Consumes Content-Type	Application/XML, Application/JSON
Example Responses	Status 200 ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifX Status 400 Error message. Status 403 Operation prohibited due to security constraints. Status 404 A user with name “{name}” does not exist. A user with id "{uuid}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

Create Personal Access Token: Payload Properties (XML, JSON)

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`userId`	N/A	UUID of the user	UUID of the user	N	userName
`userName`	N/A	User Name	String value of User name	N	userId
`name`	Name	Token Name	Specifies the name of the application that will access the Universal Controller Web Service APIs using the personal access token.	Y
`expiration`	Expiration	Description of property.	Specifies when the personal access token expires. If left unspecified, the token never expires. Valid Value: yyyy-mm-dd	N (Y if Web Service Personal Access Token Maximum Expiration In Days system property is specified.)

Create Personal Access Token: XML and JSON Examples

XML

JSON

Example Request

XML

 <token>
        <expiration>2022-07-30</expiration>
        <name>test1</name>
        <userId></userId>
        <userName>sha</userName>
    </token>

JSON

{
        "expiration": "2022-07-30",
        "name": "test1",
        "userName": "ops.admin",
        "userId": ""
    }

Example Response

XML

ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifP

JSON

ucp_taUFeDdhrlpn8Gc5Vu9IO2LRQ29pbvBRJUSPvifP

List Personal Access Tokens

	Description
URI	http://host_name/uc/resources/user/token/list
HTTP Method	GET
Description	List the user tokens
Example URI	http://localhost:9090/uc/resources/user/token/list http://localhost:9090/uc/resources/user/token/list?username=test http://localhost:9090/uc/resources/user/token/list?userid=1234567
Authentication	HTTP Basic
Produces Content-Type	Application/XML, Application/JSON
Consumes Content-Type
Example Responses	Status 200 Successful token list Status 400 Error message. Status 403 Operation prohibited due to security constraints. Status 404 A user with name “{name}” does not exist. A user with id "{uuid}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

List Personal Access Tokens: Query Parameters

The following request parameters can be used to filter the results of this service.

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
userid	N/A	UUID of the user	UUID of the user	N	username
username	N/A	User Name	String value of User name	N	userid

List Personal Access Tokens: XML and JSON Examples

XML

JSON

Example Response

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tokens>
    <token>
        <createTime>2022-07-28 17:11:35 -0400</createTime>
        <expiration>20220730</expiration>
        <lastUsed>Never</lastUsed>
        <name>test2</name>
        <userName>ops.admin</userName>
    </token>
    <token>
        <createTime>2022-07-29 12:39:20 -0400</createTime>
        <expiration>20220730</expiration>
        <lastUsed>Never</lastUsed>
        <name>test3</name>
        <userName>ops.admin</userName>
    </token>
    <token>
        <createTime>2022-07-28 17:08:07 -0400</createTime>
        <expiration>20220730</expiration>
        <lastUsed>Never</lastUsed>
        <name>test4</name>
        <userName>ops.admin</userName>
    </token>
    <token>
        <createTime>2022-07-29 12:56:33 -0400</createTime>
        <expiration>20220730</expiration>
        <lastUsed>Never</lastUsed>
        <name>test5</name>
        <userName>ops.admin</userName>
    </token>
</tokens>

JSON

[
    {
        "createTime": "2022-07-28 17:11:35 -0400",
        "expiration": "20220730",
        "lastUsed": "Never",
        "name": "test2",
        "userName": "ops.admin"
    },
    {
        "createTime": "2022-07-29 12:39:20 -0400",
        "expiration": "20220730",
        "lastUsed": "Never",
        "name": "test3",
        "userName": "ops.admin"
    },
    {
        "createTime": "2022-07-28 17:08:07 -0400",
        "expiration": "20220730",
        "lastUsed": "Never",
        "name": "test4",
        "userName": "ops.admin"
    },
    {
        "createTime": "2022-07-29 12:56:33 -0400",
        "expiration": "20220730",
        "lastUsed": "Never",
        "name": "test5",
        "userName": "ops.admin"
    }
]

Revoke Personal Access Token

	Description
URI	http://host_name/uc/resources/user/token
HTTP Method	DELETE
Description	Delete the personal access token(s)
Example URI	http://localhost:9090/uc/resources/user/token?tokenname=test1&username=abc http://localhost:9090/uc/resources/user/token?tokenname=test1&userid=1234567
Authentication	HTTP Basic
Produces Content-Type
Consumes Content-Type
Example Responses	Status 200 Personal access token revoked successfully. Status 400 Error message. Status 403 Operation prohibited due to security constraints. Status 404 A user with name “{name}” does not exist. A user with id "{uuid}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

Revoke Personal Access Token: Query Parameters

The following request parameters will be needed for the service.

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
userid	N/A	UUID of the user	UUID of the user	Y	username
username	N/A	User Name	String value of User name	N	userid
tokenname	token name	Token Name	Specifies the name of the application that will access the Universal Controller Web Service APIs using the personal access token.	Y

Universal Controller 7.7.x

User Web Services

Analytics

Overview

Permissions

Create a User

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

Delete a User

Delete a User: URI Parameters

List Users

List Users: URI Parameters

List Users: XML and JSON Examples

Modify a User

Read a User

Read a User: URI Parameters

List User Preferences

List User Preferences: URI Parameters

List User Preferences: XML and JSON Examples

Read a User Preference

Read a User Preference: URI Parameters

Read a User Preference: XML and JSON Examples

Update a User Preference

Update a User Preference: URI Parameters

Properties

User Properties

User Permission Properties

Command Permissions

User Preference Properties

User Role Properties

Create Personal Access Token

Create Personal Access Token: Payload Properties (XML, JSON)

Create Personal Access Token: XML and JSON Examples

List Personal Access Tokens

List Personal Access Tokens: Query Parameters

List Personal Access Tokens: XML and JSON Examples

Revoke Personal Access Token

Revoke Personal Access Token: Query Parameters

Related content