Overview

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

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

Create a Group

	Description
URI	http://host_name/uc/resources/usergroup
HTTP Method	POST
Description	Creates a new User Group.
Example URI	http://localhost:8080/uc/resources/usergroup
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example	See Create and Modify a Group: XML and JSON Examples, below.
Group Properties	See Group Group Properties, below.
Group Member Properties	See Group Group Member Properties, below.
Group Permission Properties	See Group Group Permission Properties, below.
Group Role Properties	See Group Group Role Properties, below.
Example Response	Status 200 /OK Successfully created the group with sysId {sysId}.

Create and Modify a Group: XML and JSON Examples

The excludeRelated and retainSysIds properties are specified as attributes in the <userGroup> element of XML web services.

XML

JSON

XML

<userGroup retainSysIds="true">
  <ctrlNavigationVisibility>true</ctrlNavigationVisibility>
  <description>Description</description>
  <email>test@stonebranch.com</email>
  <groupMembers>
     <groupMember>
        <sysId>1fe28873315d4316ad8fec7c89477723</sysId>
        <user>userc</user>
     </groupMember>
     <groupMember>
        <sysId>361f995ad8f04a2ab39ee112e4a1301a</sysId>
        <user>userb</user>
     </groupMember>
  </groupMembers>
  <groupRoles>
     <groupRole>
	<role>ops_report_admin</role>
	<sysId>9c0d5e987a5847668c0182abf03c01e7</sysId>
     </groupRole>
  </groupRoles>
  <manager />
  <name>test</name>
  <navigationVisibility>
     <navigationNode>Reports</navigationNode>
  </navigationVisibility>
  <parent />
  <permissions>
     <permission>
	<allGroups>true</allGroups>
	<commands />
	<defaultGroup>true</defaultGroup>
	<nameWildcard>*</nameWildcard>
	<opCreate>true</opCreate>
	<opDelete>true</opDelete>
	<opExecute>false</opExecute>
	<opRead>true</opRead>
	<opUpdate>true</opUpdate>
	<opswiseGroups />
	<permissionType>Task</permissionType>
	<sysId>48eb7ec0c0a8026e0da9406feb022f4e</sysId>
     </permission>
		...
  </permissions>
  <sysId>920ef061ff4d498abe6e7ef883b1b5e1</sysId>
</userGroup>

JSON

{
  "ctrlNavigationVisibility": true,
  "description": "Description",
  "email": "test@stonebranch.com",
  "groupMembers": [ {
    "sysId": "b6fd058ee3db424ea374109299949b18",
    "user": "userc"
  },{
    "sysId": "c54e8898f3bb493e9f5ed7f030007e2e",
    "user": "userb"
  } ],
  "groupRoles": [ {
    "role": "ops_report_admin",
  "sysId": "4112408600e947b89d051d36bf9cf6b3"
  } ],
  "manager": null,
  "name": "test",
  "navigationVisibility": [ "Reports" ],
  "parent": null,
  "permissions": [ {
    "allGroups": true,
    "commands": null,
    "defaultGroup": true,
    "nameWildcard": "*",
    "opCreate": true,
    "opDelete": true,
    "opExecute": false,
    "opRead": true,
    "opUpdate": true,
    "opswiseGroups": [],
    "permissionType": "Task",
    "sysId": "48eb7ec0c0a8026e0da9406feb022f4e"
  } ],
  "retainSysIds": true,
  "sysId": "920ef061ff4d498abe6e7ef883b1b5e1"
}

Delete a Group

	Description
URI	http://host_name/uc/resources/usergroup
HTTP Method	DELETE
Description	Deletes a Group.
URI Parameters	See Group Delete a Group URI Parameters, below.
Example URI	http://localhost:9080/uc/resources/usergroup?groupname=Test_Group http://localhost:9080/uc/resources/usergroup?groupid=f93b9403aec546bcbef1c2c06cf26e3c
Example Response	Status 200 /OK User group {groupname} deleted successfully. Status 400 /Bad Request Mutual exclusion violation. Cannot specify groupid and groupname at the same time. Status 404 /Not Found User group with {groupname/groupid} does not exist.

Delete a Group: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`groupid`	ID used within the Controller to identify this group.	String; URI parameter.	Y (unless `groupname` is specified)	`groupname`
`groupname`	Name used within the Controller to identify this group.	String; URI parameter.	Y (unless `groupid` is specified)	`groupid`

List Groups

	Description
URI	http://host_name/uc/resources/usergroup/list
HTTP Method	GET
Description	Retrieves information on all Groups.
Example URI	http://localhost:8080/uc/resources/usergroup/list
Authentication	HTTP Basic
Produces Content-Type	application/xml, application/json
Example	See Read a Group: XML and JSON Examples.
Group Properties	See Group Group Properties.
Group Member Properties	See Group Group Member Properties.
Group Permission Properties	See Group Group Permission Properties.
Group Role Properties	See Group Group Role Properties.

List Groups XML and JSON Examples

XML

JSON

XML

<userGroups>
  <userGroup>
     <ctrlNavigationVisibility>true</ctrlNavigationVisibility>
     <description>Description</description>
     <email>test@stonebranch.com</email>
     <groupMembers>
        <groupMember>
           <sysId>1fe28873315d4316ad8fec7c89477723</sysId>
           <user name="User C">userc</user>
        </groupMember>
        <groupMember>
           <sysId>361f995ad8f04a2ab39ee112e4a1301a</sysId>
           <user name="User B">userb</user>
        </groupMember>
     </groupMembers>
     <groupRoles>
        <groupRole>
	   <role description="report admin role">ops_report_admin</role>
	   <sysId>9c0d5e987a5847668c0182abf03c01e7</sysId>
        </groupRole>
     </groupRoles>
     <manager />
     <name>test1</name>
     <navigationVisibility>
        <navigationNode>Reports</navigationNode>
     </navigationVisibility>
     <parent />
     <permissions>
        <permission>
	   <allGroups>true</allGroups>
	   <commands />
	   <defaultGroup>true</defaultGroup>
	   <nameWildcard>*</nameWildcard>
	   <opCreate>true</opCreate>
	   <opDelete>true</opDelete>
	   <opExecute>false</opExecute>
	   <opRead>true</opRead>
	   <opUpdate>true</opUpdate>
	   <opswiseGroups />
	   <permissionType>Task</permissionType>
	   <sysId>48eb7ec0c0a8026e0da9406feb022f4e</sysId>
        </permission>
     </permissions>
     <sysId>920ef061ff4d498abe6e7ef883b1b5e1</sysId>
   </userGroup>
   <userGroup>
     <ctrlNavigationVisibility>true</ctrlNavigationVisibility>
     <description>Description</description>
     <groupMembers />
     <groupRoles>
        <groupRole>
	   <role description="report admin role">ops_report_admin</role>
	   <sysId>9c0d5e987a5847668c0182abf03c01e7</sysId>
        </groupRole>
     </groupRoles>
     <manager />
     <name>test2</name>
     <navigationVisibility>
        <navigationNode>Reports</navigationNode>
     </navigationVisibility>
     <parent />
     <permissions>
        <permission>
	   <allGroups>true</allGroups>
	   <commands />
	   <defaultGroup>true</defaultGroup>
	   <nameWildcard>*</nameWildcard>
	   <opCreate>true</opCreate>
	   <opDelete>true</opDelete>
	   <opExecute>false</opExecute>
	   <opRead>true</opRead>
	   <opUpdate>true</opUpdate>
	   <opswiseGroups />
	   <permissionType>Task</permissionType>
	   <sysId>48eb7ec0c0a8026e0da9406feb022f4e</sysId>
        </permission>
     </permissions>
     <sysId>920ef061ff4d498abe6e7ef883b1b5e1</sysId>
   </userGroup>

JSON

[ 
  {
     "ctrlNavigationVisibility": true,
     "description": "Description",
     "email": "test@stonebranch.com",
     "groupMembers": [ 
        {
          "sysId": "b6fd058ee3db424ea374109299949b18",
          "user": {
            "name": "USERC",
            "value": "userc"
          }
        } 
     ],
     "groupRoles": [ 
        {
           "role": {
              "description": "The report administrator role.",
              "value": "ops_report_admin"
           },
           "sysId": "4112408600e947b89d051d36bf9cf6b3"
        } 
     ],
     "manager": null,
     "name": "test1",
     "navigationVisibility": [ "Reports" ],
     "parent": null,
     "permissions": [], 
     "sysId": "920ef061ff4d498abe6e7ef883b1b5e1"
   },
   {
     "ctrlNavigationVisibility": true,
     "description": "Description",
     "groupMembers": [], 
     "groupRoles": [ 
        {
           "role": {
              "description": "The report administrator role.",
              "value": "ops_report_admin"
           },
           "sysId": "4112408600e947b89d051d36bf9cf6b3"
        } 
     ],
     "manager": null,
     "name": "test2",
     "navigationVisibility": [ "Reports" ],
     "parent": null,
     "permissions": [ 
        {
           "allGroups": true,
           "commands": null,
           "defaultGroup": true,
           "nameWildcard": "*",
           "opCreate": true,
           "opDelete": true,
           "opExecute": false,
           "opRead": true,
           "opUpdate": true,
           "opswiseGroups": [],
           "permissionType": "Task",
           "sysId": "48eb7ec0c0a8026e0da9406feb022f4e"
        } 
      ],
      "sysId": "920ef061ff4d498abe6e7ef883b1b5e1"
   }
]

Modify a Group

	Description
URI	http://host_name/uc/resources/usergroup
HTTP Method	PUT
Description	Modifies the Group specified by the `sysId` in the request. To modify Group properties without modifying related records, see the excludeRelated property, below.
Example URI	http://localhost:8080/uc/resources/usergroup
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Create and Modify a Group: XML and JSON Examples.
Group Properties	See Group Group Properties.
Group Member Properties	See Group Group Member Properties.
Group Permission Properties	See Group Group Permission Properties.
Group Role Properties	See Group Group Role Properties.
Example Response	Status 200 /OK Successfully updated the user group with sysId <sysId>.

Read a Group

	Description
URI	http://host_name/uc/resources/usergroup
HTTP Method	GET
Description	Retrieves information on a specific Group.
URI Parameters	See Read a Group: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/usergroup?groupname=test.group http://localhost:8080/uc/resources/usergroup?groupid=c489750500d444eca9325559d0ef9673
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	Status 200 /OK (See Read a Group: Example XML and JSON Examples, below.) Status 404 /Not Found A user group with id "f87848b00a0001037f43e7c81c8ec969" does not exist.
Response Group Member Properties	See Group Group Member Properties.
Response Group Permission Properties	See Group Group Permission Properties.
Response Group Role Properties	See Group Group Role Properties.

Read a Group: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`groupid`	ID used within the Controller to identify this group.	String; URI parameter.	Y (unless `groupname` is specified)	`groupname`
`groupname`	Name used within the Controller to identify this group.	String; URI parameter.	Y (unless `groupid` is specified)	`groupid`

Read a Group XML and JSON Examples

The retainSysIds property is specified as an attribute in the <userGroup> element of the XML response.

XML

JSON

XML

<userGroup retainSysIds="true">
  <ctrlNavigationVisibility>true</ctrlNavigationVisibility>
  <description>Description</description>
  <email>test@stonebranch.com</email>
  <groupMembers>
     <groupMember>
        <sysId>1fe28873315d4316ad8fec7c89477723</sysId>
        <user name="User C">userc</user>
     </groupMember>
     <groupMember>
        <sysId>361f995ad8f04a2ab39ee112e4a1301a</sysId>
        <user name="User B">userb</user>
     </groupMember>
  </groupMembers>
  <groupRoles>
     <groupRole>
	<role description="report admin role">ops_report_admin</role>
	<sysId>9c0d5e987a5847668c0182abf03c01e7</sysId>
     </groupRole>
  </groupRoles>
  <manager />
  <name>test</name>
  <navigationVisibility>
     <navigationNode>Reports</navigationNode>
  </navigationVisibility>
  <parent />
  <permissions>
     <permission>
	<allGroups>true</allGroups>
	<commands />
	<defaultGroup>true</defaultGroup>
	<nameWildcard>*</nameWildcard>
	<opCreate>true</opCreate>
	<opDelete>true</opDelete>
	<opExecute>false</opExecute>
	<opRead>true</opRead>
	<opUpdate>true</opUpdate>
	<opswiseGroups />
	<permissionType>Task</permissionType>
	<sysId>48eb7ec0c0a8026e0da9406feb022f4e</sysId>
     </permission>
		...
  </permissions>
  <sysId>920ef061ff4d498abe6e7ef883b1b5e1</sysId>
</userGroup>

JSON

{
  "ctrlNavigationVisibility": true,
  "description": "Description",
  "email": "test@stonebranch.com",
  "groupMembers": [ {
    "sysId": "b6fd058ee3db424ea374109299949b18",
    "user": {
      "name": "USERC",
      "value": "userc"
    }
  }, {
    "sysId": "c54e8898f3bb493e9f5ed7f030007e2e",
    "user": {
      "name": "USERB",
      "value": "userb"
    }
  } ],
  "groupRoles": [ {
    "role": {
      "description": "The report administrator role.",
      "value": "ops_report_admin"
    },
    "sysId": "4112408600e947b89d051d36bf9cf6b3"
  } ],
  "manager": null,
  "name": "test",
  "navigationVisibility": [ "Reports" ],
  "parent": null,
  "permissions": [ {
    "allGroups": true,
    "commands": null,
    "defaultGroup": true,
    "nameWildcard": "*",
    "opCreate": true,
    "opDelete": true,
    "opExecute": false,
    "opRead": true,
    "opUpdate": true,
    "opswiseGroups": [],
    "permissionType": "Task",
    "sysId": "48eb7ec0c0a8026e0da9406feb022f4e"
  } ],
  "retainSysIds": true,
  "sysId": "920ef061ff4d498abe6e7ef883b1b5e1"
}

Properties

Group Properties

Property	UI Field Name	Description	Specifications	Required
`ctrlNavigationVisibility`	Control Navigation Visibility	Indication of whether or not to control the visibility of navigation pane entries in the Controller Navigator, via the `navigationVisibility` property, for members of this Group. If `ctrlNavigationVisibility` is false, all entries are visible.	Boolean. Valid values: true/false. Default is false.	N
`description`	Description	Description of the group.		N
`email`	Email	Email address of this group.		N
`excludeRelated`	n/a	For the Modify Group web service; specification for whether or not to exclude related records (Group Roles, Group Members, Group Permissions) from the update, even if they are provided in the request. Note In XML, `excludeRelated` is specified as an attribute in the <userGroup> element.	Valid values: true/false (default is false).	N
`groupMembers`	n/a	Users in this group. Note Universal Controller only supports a user being a member of 1,000 groups or less.	Format: XML <groupMembers> <groupMember> <user>userc</user> </groupMember> </groupMembers> JSON "groupMembers": [ { "user": "userc" } ]	N
`groupRoles`	n/a	Roles assigned to this group.	Format: XML <groupRoles> <groupRole> <role>ops_report_admin</role> </groupRole> </groupRoles> JSON "groupRoles": [ { "role": "ops_report_global" } ]	N
`manager`	Manager	ID of the Universal Controller user that is the manager of this group.		N
`name`	Name	Name of the group.		Y
`navigationVisibility`	Navigation Visibility	List of all Controller Navigator entries.	Format: XML <navigationVisibility> <navigationNode>Reports</navigationNode> </navigationVisibility> To include all values, set the `navigationNode` to All <navigationVisibility> <navigationNode>All</navigationNode> </navigationVisibility> JSON "navigationVisibility": [ "Reports", "Support Portal" ] Valid values: (see `navigationNode` Valid Values, below)	N
`parent`	Parent	Name of this group's parent group, if any.		N
`permissions`	n/a	Permissions assigned to this group.		N
`retainSysIds`	n/a	For Create and Read web services; specification for whether or not the web service should persist the sysId property. If `retainSysIds` is true and `sysId` is included in the request/response, `sysId` will be persisted to the database. If `retainSysIds` is 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 <userGroup> 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

navigationNode Valid Values

Values	Navigation Panel
All	All navigation panels
Activity Task Instances History All Triggers Active Triggers Cron Triggers Time Triggers Manual Triggers Temporary Triggers File Monitor Triggers Task Monitor Triggers Variable Monitor Triggers Email Monitor Triggers Application Monitor Triggers Composite Triggers Forecasts Forecast Calendar All Tasks Workflow Tasks Linux/Unix Tasks Windows Tasks z/OS Tasks Universal Command Tasks SAP Tasks PeopleSoft Tasks File Transfer Tasks Manual Tasks Timer Tasks SQL Tasks Stored Procedure Tasks Email Tasks Web Service Tasks Task Monitors File Monitors FTP File Monitors System Monitors Variable Monitors Email Monitors Application Control Tasks Calendars Custom Days Variables Scripts Virtual Resources Credentials	Automation Center
Dashboards Reports Widgets Colors	Reporting
All Agents Linux/Unix Agents Windows Agents z/OS Agents Linux/Unix Agent Clusters Windows Agent Clusters OMS Servers Cluster Nodes Email Templates Email Connections Database Connections PeopleSoft Connections SAP Connections SNMP Managers Applications	Agents & Connections
Bundles Promotion Targets Promotion History Promotion Schedules	Bundles & Promotion
Properties LDAP Settings Data Backup / Purge Server Operations Universal Templates Filters Users Groups Business Services Audits Support Portal Video Classroom	Administration

Group Member Properties

Property	UI Field Name	Description	Specifications	Required
`sysId`	n/a	System ID field in the database for this record.		N
`user`	User	User name of a group member.		Y

Group 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 Group 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 members of the group to create records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. Cannot be set to true if `permissionType` is Agent or Task Instance.	N
`opDelete`	Delete	Allows members of the group to delete records of the specified `permissionType`.	Boolean. Valid Values: true/false. Default is false. Cannot be set to true if `permissionType` is Agent.	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 members of the group 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).	Format: XML <opswiseGroups> <opswiseGroup>test</opswiseGroup> </opswiseGroups> JSON "opswiseGroups": ["test"]	N
`permissionType`	Type	Type of permission for this group.	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 this 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

Group Role Properties

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

Group Web Services

Overview

Create a Group

Create and Modify a Group: XML and JSON Examples

Delete a Group

Delete a Group: URI Parameters

List Groups

List Groups XML and JSON Examples

Modify a Group

Read a Group

Read a Group: URI Parameters

Read a Group XML and JSON Examples

Properties

Group Properties

navigationNode Valid Values

Group Member Properties

Group Permission Properties

Command Permissions

Group Role Properties

Related content