User Web Services

Overview

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

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

Permissions

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

Operation

User without any role

User with ops_service_role

User with ops_user_admin or ops_admin role

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

Delete a User


Description

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

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: XML and JSON Examples

XML

JSON

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

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

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

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

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

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.

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

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.

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

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

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