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

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	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
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	http://localhost:8080/uc/resources/user?username=test.user http://localhost:8080/uc/resources/user?userid=c489750500d444eca9325559d0ef9673
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`
`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

User Web Services

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

Modify a User

Read a User

Read a User: URI Parameters

Properties

User Properties

User Permission Properties

Command Permissions

User Role Properties

Related content