/
Group Web Services

Group Web Services

Jun 29, 2023

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



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

JSON

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

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



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

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

JSON

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

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



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



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