/
User Web Services

User Web Services

Owned by Stonebranch (Deactivated)
Last updated: Oct 17, 2024 by Alec Berger

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.

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

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

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


Read a User: URI Parameters

Name

Description

Specifications

Required

Mutually Exclusive With

userid

Unique ID for this User.


Y
(unless username
is specified)

username

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

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

  • 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

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