WebGroups Edit API
The public URLs are for read-only querying. It's also possible to create, edit and delete your groups programatically through the following APIs. Unlike the query URLs, they will of course require you to be authenticated as a user. See the Authentication section for details of the best way to authenticate.
Requests should put parameters in the POST data (not in the query string). If there are any errors in the submission, the response should be an <errors> XML document containing one or more <error> elements, which contain the text of the error message. The HTTP status code will be 400.
In this article:
Authenticating
Firstly, if you are using the API as part of an application, do not use a personal ITS account, as doing so is against the Terms & Conditions and bad things will happen. Instead, you should use a dedicated user code. We can create one for you in the External Users system. Let us know you plan to use it for Webgroups access when you request one, as we'll need to give it explicit access.
Once you have a usercode, the simplest method is to take advantage of Webgroups' support for HTTP Basic Authentication. This involves sending the username and password with each request, so we only support it over HTTPS connections. Most HTTP client libraries make it quite simple to send this authentication (instructions for Apache HttpClient). Just make the request over HTTPS and it should be authenticated as the user specified.
Create group
/admin/groups/api/create
Parameters:
| name | The name for the group, without the department code on the front. The dept code will get added based on the user's department. |
| members | Optional. A semicolon-separated list of IT usercodes or library card numbers. Members can also be the names of other groups, to add them as sub-groups. |
| description | Optional. A description for the group. |
If the request was successful the response will be a 200 status and some XML that looks like this:
<?xml version="1.0"?>
<groups>
<group name="in-groupimade">
<users>
<user userId="cusebr"/>
</users>
<owners>
<owner userId="cusebr">cusebr</owner>
</owners>
<subgroups></subgroups>
<title></title>
<department code="in" faculty="Service/Admin">Information Technology Services</department>
<type>Arbitrary</type>
<lastupdateddate>2008-12-19 14:25:31</lastupdateddate>
</group>
</groups>
Edit group
/admin/groups/api/edit
When editing a group, you can omit any of the parameters (other than group) to leave its value as-is. Remember that there's a difference between not specifying a parameter, and specifying it as empty. The latter will change the value.
Parameters:
If you are using this to edit a group that you've create manually in the web interface:
| group | The complete name of the group, with the department code on the front. |
| members | Optional. A semicolon-separated list of ITS usercodes or library card numbers. Omit to create an empty group. Members can also be the names of other groups, to add them as sub-groups. |
| owners | Optional. A semicolon-separated list of ITS usercodes or library card numbers, who will be the owners of the group. |
| description | Optional. A description for the group. |
If the request was successful the response will be a 200 status and XML in the same format as described above.
Delete group
/admin/groups/api/delete
Parameters:
| group | The complete name of the group, with the department code on the front. |
If the request was successful the response will be a 200 status.
Add members
/admin/groups/api/addMembers Parameters:
| group | The complete name of the group, with the department code on the front |
| members | A semicolon-separated list of ITS usercodes or library card numbers. Members can also be the names of other groups, to add them as sub-groups. |
Thing
Remove members
/admin/groups/api/removeMembers
Parameters:
| group | The complete name of the group, with the department code on the front. |
| members | A semicolon-separated list of ITS usercodes or library card numbers. Members can also be the names of other groups. |
Related articles
Error: Access denied for the source page. from 8ac672c798e454470198e701cba8534d