Group Web Services

Owned by Stonebranch (Deactivated)
Last updated: Jul 15, 2024
15 min read

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 Properties, below.

Group Member Properties

See Group Member Properties, below.

Group Permission Properties

See Group Permission Properties, below.

Group Role Properties

See 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>false</ctrlNavigationVisibility>
    <description />
    <email />
    <groupMembers>
        <groupMember>
            <sysId>386bf68d82a74a9e94eab18c1b1844c2</sysId>
            <user name="stone b branch">stonebranch-user-02</user>
        </groupMember>
        <groupMember>
            <sysId>792aa1dc1a1b4decb0b02d82ed7e9422</sysId>
            <user name="stone c branch">stonebranch-user-03</user>
        </groupMember>
        <groupMember>
            <sysId>b78079e1166d4c5180d7e42443de44a0</sysId>
            <user name="stone a branch">stonebranch-user-01</user>
        </groupMember>
    </groupMembers>
    <groupRoles>
        <groupRole>
            <role description="The administrator role.">ops_admin</role>
            <sysId>b80e78a42589435f92f3e176af6dc542</sysId>
        </groupRole>
    </groupRoles>
    <manager />
    <name>stonebranch-group-01</name>
    <navigationVisibility/>
    <parent />
    <permissions>
        <permission>
            <allGroups>true</allGroups>
            <commands />
            <defaultGroup>true</defaultGroup>
            <nameWildcard>*</nameWildcard>
            <notGroups>false</notGroups>
            <opCreate>false</opCreate>
            <opDelete>false</opDelete>
            <opExecute>false</opExecute>
            <opRead>true</opRead>
            <opUpdate>false</opUpdate>
            <opswiseGroups/>
            <permissionType>Task Instance</permissionType>
            <sysId>59e5565c9f6a45ed8633d05a91ac1019</sysId>
        </permission>
    </permissions>
    <sysId>b39b2b8eac644e068a68f92f325b0c74</sysId>
</userGroup>
 JSON
{
  "ctrlNavigationVisibility" : false,
  "description" : null,
  "email" : null,
  "groupMembers" : [ {
    "sysId" : "386bf68d82a74a9e94eab18c1b1844c2",
    "user" : {
      "name" : "stone b branch",
      "value" : "stonebranch-user-02"
    }
  }, {
    "sysId" : "792aa1dc1a1b4decb0b02d82ed7e9422",
    "user" : {
      "name" : "stone c branch",
      "value" : "stonebranch-user-03"
    }
  }, {
    "sysId" : "b78079e1166d4c5180d7e42443de44a0",
    "user" : {
      "name" : "stone a branch",
      "value" : "stonebranch-user-01"
    }
  } ],
  "groupRoles" : [ {
    "role" : {
      "description" : "The administrator role.",
      "value" : "ops_admin"
    },
    "sysId" : "b80e78a42589435f92f3e176af6dc542"
  } ],
  "manager" : null,
  "name" : "stonebranch-group-01",
  "navigationVisibility" : [ ],
  "parent" : null,
  "permissions" : [ {
    "allGroups" : true,
    "commands" : null,
    "defaultGroup" : true,
    "nameWildcard" : "*",
    "notGroups" : false,
    "opCreate" : false,
    "opDelete" : false,
    "opExecute" : false,
    "opRead" : true,
    "opUpdate" : false,
    "opswiseGroups" : [ ],
    "permissionType" : "Task Instance",
    "sysId" : "59e5565c9f6a45ed8633d05a91ac1019"
  } ],
  "retainSysIds" : true,
  "sysId" : "b39b2b8eac644e068a68f92f325b0c74"
}

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

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

Group Member Properties

See Group Member Properties.

Group Permission Properties

See Group Permission Properties.

Group Role Properties

See Group Role Properties.

List Groups XML and JSON Examples

XML

JSON

 XML
<userGroups>
    <userGroup>
        <ctrlNavigationVisibility>false</ctrlNavigationVisibility>
        <description/>
        <email/>
        <groupMembers>
            <groupMember>
                <sysId>386bf68d82a74a9e94eab18c1b1844c2</sysId>
                <user name="stone b branch">stonebranch-user-02</user>
            </groupMember>
            <groupMember>
                <sysId>792aa1dc1a1b4decb0b02d82ed7e9422</sysId>
                <user name="stone c branch">stonebranch-user-03</user>
            </groupMember>
            <groupMember>
                <sysId>b78079e1166d4c5180d7e42443de44a0</sysId>
                <user name="stone a branch">stonebranch-user-01</user>
            </groupMember>
        </groupMembers>
        <groupRoles>
            <groupRole>
                <role description="The administrator role.">ops_admin</role>
                <sysId>b80e78a42589435f92f3e176af6dc542</sysId>
            </groupRole>
        </groupRoles>
        <manager />
        <name>stonebranch-group-01</name>
        <navigationVisibility/>
        <parent />
        <permissions>
            <permission>
                <allGroups>true</allGroups>
                <commands/>
                <defaultGroup>true</defaultGroup>
                <nameWildcard>*</nameWildcard>
                <notGroups>false</notGroups>
                <opCreate>false</opCreate>
                <opDelete>false</opDelete>
                <opExecute>false</opExecute>
                <opRead>true</opRead>
                <opUpdate>false</opUpdate>
                <opswiseGroups/>
                <permissionType>Task Instance</permissionType>
                <sysId>59e5565c9f6a45ed8633d05a91ac1019</sysId>
            </permission>
        </permissions>
        <sysId>b39b2b8eac644e068a68f92f325b0c74</sysId>
    </userGroup>
</userGroups>
 JSON
[ {
  "ctrlNavigationVisibility" : false,
  "description" : null,
  "email" : null,
  "groupMembers" : [ {
    "sysId" : "386bf68d82a74a9e94eab18c1b1844c2",
    "user" : {
      "name" : "stone b branch",
      "value" : "stonebranch-user-02"
    }
  }, {
    "sysId" : "792aa1dc1a1b4decb0b02d82ed7e9422",
    "user" : {
      "name" : "stone c branch",
      "value" : "stonebranch-user-03"
    }
  }, {
    "sysId" : "b78079e1166d4c5180d7e42443de44a0",
    "user" : {
      "name" : "stone a branch",
      "value" : "stonebranch-user-01"
    }
  } ],
  "groupRoles" : [ {
    "role" : {
      "description" : "The administrator role.",
      "value" : "ops_admin"
    },
    "sysId" : "b80e78a42589435f92f3e176af6dc542"
  } ],
  "manager" : null,
  "name" : "stonebranch-group-01",
  "navigationVisibility" : [ ],
  "parent" : null,
  "permissions" : [ {
    "allGroups" : true,
    "commands" : null,
    "defaultGroup" : true,
    "nameWildcard" : "*",
    "notGroups" : false,
    "opCreate" : false,
    "opDelete" : false,
    "opExecute" : false,
    "opRead" : true,
    "opUpdate" : false,
    "opswiseGroups" : [ ],
    "permissionType" : "Task Instance",
    "sysId" : "59e5565c9f6a45ed8633d05a91ac1019"
  } ],
  "sysId" : "b39b2b8eac644e068a68f92f325b0c74"
} ]

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

Group Member Properties

See Group Member Properties.

Group Permission Properties

See Group Permission Properties.

Group Role Properties

See 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

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

Response Group Member Properties

See Group Member Properties.

Response Group Permission Properties

See Group Permission Properties.

Response Group Role Properties

See 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>false</ctrlNavigationVisibility>
    <description />
    <email />
    <groupMembers>
        <groupMember>
            <sysId>386bf68d82a74a9e94eab18c1b1844c2</sysId>
            <user name="stone b branch">stonebranch-user-02</user>
        </groupMember>
        <groupMember>
            <sysId>792aa1dc1a1b4decb0b02d82ed7e9422</sysId>
            <user name="stone c branch">stonebranch-user-03</user>
        </groupMember>
        <groupMember>
            <sysId>b78079e1166d4c5180d7e42443de44a0</sysId>
            <user name="stone a branch">stonebranch-user-01</user>
        </groupMember>
    </groupMembers>
    <groupRoles>
        <groupRole>
            <role description="The administrator role.">ops_admin</role>
            <sysId>b80e78a42589435f92f3e176af6dc542</sysId>
        </groupRole>
    </groupRoles>
    <manager />
    <name>stonebranch-group-01</name>
    <navigationVisibility/>
    <parent />
    <permissions>
        <permission>
            <allGroups>true</allGroups>
            <commands />
            <defaultGroup>true</defaultGroup>
            <nameWildcard>*</nameWildcard>
            <notGroups>false</notGroups>
            <opCreate>false</opCreate>
            <opDelete>false</opDelete>
            <opExecute>false</opExecute>
            <opRead>true</opRead>
            <opUpdate>false</opUpdate>
            <opswiseGroups/>
            <permissionType>Task Instance</permissionType>
            <sysId>59e5565c9f6a45ed8633d05a91ac1019</sysId>
        </permission>
    </permissions>
    <sysId>b39b2b8eac644e068a68f92f325b0c74</sysId>
</userGroup>
 JSON
{
  "ctrlNavigationVisibility" : false,
  "description" : null,
  "email" : null,
  "groupMembers" : [ {
    "sysId" : "386bf68d82a74a9e94eab18c1b1844c2",
    "user" : {
      "name" : "stone b branch",
      "value" : "stonebranch-user-02"
    }
  }, {
    "sysId" : "792aa1dc1a1b4decb0b02d82ed7e9422",
    "user" : {
      "name" : "stone c branch",
      "value" : "stonebranch-user-03"
    }
  }, {
    "sysId" : "b78079e1166d4c5180d7e42443de44a0",
    "user" : {
      "name" : "stone a branch",
      "value" : "stonebranch-user-01"
    }
  } ],
  "groupRoles" : [ {
    "role" : {
      "description" : "The administrator role.",
      "value" : "ops_admin"
    },
    "sysId" : "b80e78a42589435f92f3e176af6dc542"
  } ],
  "manager" : null,
  "name" : "stonebranch-group-01",
  "navigationVisibility" : [ ],
  "parent" : null,
  "permissions" : [ {
    "allGroups" : true,
    "commands" : null,
    "defaultGroup" : true,
    "nameWildcard" : "*",
    "notGroups" : false,
    "opCreate" : false,
    "opDelete" : false,
    "opExecute" : false,
    "opRead" : true,
    "opUpdate" : false,
    "opswiseGroups" : [ ],
    "permissionType" : "Task Instance",
    "sysId" : "59e5565c9f6a45ed8633d05a91ac1019"
  } ],
  "retainSysIds" : true,
  "sysId" : "b39b2b8eac644e068a68f92f325b0c74"
}

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

Business Service Criteria

  • Member of Any Business Service or Unassigned

Specification for whether or not this permission applies both to records that belong to any Business Service and to records that do not belong to any Business Service.

If allGroups is specified as true, defaultGroup is set to true, notGroups is set to false, and opswiseGroups is cleared, regardless of what you specify in the payload.

Boolean. Valid Values: true/false. Default is false.

N

commands

Commands

Commands that are associated with each permission.

Valid values: see Group Command Permissions, below.

N

defaultGroup

Unassigned to Business Service

Business Service Criteria

  • Member of Specific Business Services or Unassigned

  • Unassigned

  • Not Member of Specific Business Services or Unassigned

Specification for whether or not this permission applies to records that do not belong to any Business Service.

Boolean. Valid Values: true/false. Default is false.

N

nameWildcard

Name

Specification to apply this permission to records whose name matches the string specified here.

Wildcards (*'s) can be used.

Y

notGroups

Not Member of Business Services

Business Service Criteria

  • Not Member of Specific Business Services or Unassigned

  • Not Member of Specific Business Services

Specification for whether or not this permission applies to records that are a member of opswiseGroups or not a member of opswiseGroups.Boolean. Valid Values: true/false. Default is false.N

opCreate

Create

Allows 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

Specific 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