1 Overview
2 Create a Group
3 Create and Modify a Group: XML and JSON Examples
4 Delete a Group
- 4.1 Delete a Group: URI Parameters
5 List Groups
- 5.1 List Groups XML and JSON Examples
6 Modify a Group
7 Read a Group
- 7.1 Read a Group: URI Parameters
- 7.2 Read a Group XML and JSON Examples
8 Properties
- 8.1 Group Properties
  - 8.1.1 navigationNode Valid Values
- 8.2 Group Member Properties
- 8.3 Group Permission Properties
  - 8.3.1 Command Permissions
- 8.4 Group Role Properties

Overview

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

Create a Group
Delete a Group
List Groups
Modify a Group
Read a Group

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

Create a Group

	Description

	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

JSON

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

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

	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

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

	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

JSON

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

[ {
  "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

	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

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

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

JSON

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

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

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

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