The workgroup web service provides a programmatic way to perform all of the same transactions that can be done in Workgroup Manager.
This includes:
- Getting the details of a workgroup
- Creating and deleting a new group from an existing stem
- Adding and deleting members
- Adding and deleting administrators
- Updating the description of a workgroup
- Changing the filter and other properties
How to get started with the Workgroup API
Follow the Middleware and Integration Services Integration (MaIS) checklist for RESTful Web Services. If you need help, are not sure whether the Web APIs are the best method for integrating with the registry, or just have some questions, contact the MaIS team.
HTTP Status codes
| Code | Conditions | |
|---|---|---|
| 200 OK | The usual successful return code. | |
| 400 Bad Request | Missing required parameters or identifier is in wrong format. | |
| 403 Access Denied | The request was made without valid certificate. | |
| 404 Not Found | The record you're looking for doesn't exist. | |
| 500 Internal Server Error | Something broke with our code. Please tell us about it. | |
Error handling
Workgroup API sends error status via standard HTTP status codes (4xx) and always returns an XML document detailing the error. For example, when a client makes a call to update a workgroup filter with no supported filter value, the system will return the following XML error document:
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/filter
Content-Type:text/plain;charset=UTF-8
Content-Length:9
XXXX_XXXX
HTTP/1.1 400 Bad Request
Date:Sat, 01 Aug 2009 18:35:51 GMT
<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>400</code>
<message>Filter value "XXXX_XXXX" not supported</message>
</error>
Get Workgroup
| Description | Get workgroup | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name} | |
| Method | GET | |
| Query string | -none- | |
| Returns | 200 OK & workgroup XML | |
| 404 Not Found | ||
If authenticated user is an administrator of the workgroup, return XML document include public (description, filter, visibility, privgroup, and reusable) and private (members and administrators) information. If authenticated user is not an administrator of the workgroup, return XML document includes only public information of the workgroup. Please note that "authenticated user" may refer to a certificate name, in which case the certificate needs to be configured as a workgroup administrator.
GET https://workgroupsvc.stanford.edu/v1/workgroups/mais:test
HTTP/1.1 200 OK
Content-Disposition:attachment; filename="mais:test.xml"
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:534
Date:Sat, 01 Aug 2009 18:25:48 GMT
<?xml version="1.0" encoding="UTF-8"?>
<workgroup>
<description>Test workgroup</description>
<filter>FACULTY_STAFF_STUDENT</filter>
<visibility>PRIVATE</visibility>
<reusable>TRUE</reusable>
<privgroup>TRUE</privgroup>
<members>
<member name="user1" url="https://workgroupsvc.stanford.edu/v1/users/user1"/>
<member name="user2" url="https://workgroupsvc.stanford.edu/v1/users/user2"/>
<workgroup name="workgroup:mais" url="https://workgroupsvc.stanford.edu/v1/workgroups/workgroup:mais"/>
<workgroup name="workgroup:mais-dev" url="https://workgroupsvc.stanford.edu/v1/workgroups/workgroup:mais-dev"/>
</members>
<administrators>
<member name="user3" url="https://workgroupsvc.stanford.edu/v1/users/user3"/>
<member name="user4" url="https://workgroupsvc.stanford.edu/v1/users/user4"/>
<workgroup name="mais-staff" url="https://workgroupsvc.stanford.edu/v1/workgroups/mais-staff"/>
</administrators>
</workgroup>
Create workgroup
| Description | Create workgroup | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name} | |
| Method | POST | |
| Request Content Type | text/xml;charset=UTF-8 | |
| Request Body(optional): | XML Sample request body XML: <workgroup> <description>Test workgroup</description> <filter> {NONE|ACADEMIC_ADMINISTRATIVE|STUDENT|FACULTY| STAFF|FACULTY_STAFF|FACULTY_STUDENT| STAFF_STUDENT|FACULTY_STAFF_STUDENT} </filter> <visibility>{PRIVATE | STANFORD}</visibility> <reusable>{ TRUE | FALSE }</reusable> <privgroup>{ TRUE | FALSE }</privgroup> </workgroup> Following are default values:-
description={empty string}. If description contains more than 255 characters, first 255 characters used (maximum 255 characters) filter=NONE visibility=STANFORD reusable=TRUE privgroup=FALSE |
|
| Returns | 201 Created | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 409 Conflict | ||
Please note that authenticated user has to be an administrator of the workgroup, return XML document include public (description, filter, visibility, privgroup and reusable) and private (members and administrators) information. If authenticated user is not an administrator of the workgroup, return XML document includes only public information of the workgroup. Please note that "authenticated user" may refer to a certificate name, in which case the certificate needs to be configured as a workgroup administrator.
POST https://workgroupsvc.stanford.edu/v1/workgroups/mais:new
Content-Type:text/xml;charset=UTF-8
Content-Length:195
<workgroup>
<description>Test workgroup</description>
<filter>ACADEMIC_ADMINISTRATIVE</filter>
<visibility>PRIVATE</visibility>
<reusable>FALSE</reusable>
<privgroup>TRUE</privgroup>
</workgroup>
HTTP/1.1 201 Created
Server:Apache-Coyote/1.1
Location:/v1/workgroups/mais:new
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:28:35 GMT
Delete workgroup
| Description | Delete a workgroup | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name} | |
| Method | DELETE | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
Note: Deleted workgroups are marked inactive and retained in the system for future reference.
DELETE https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Add member
| Description | Add member or workgroup as a workgroup member | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/members | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/members | |
| Method | PUT | |
| Query string | user=https://workgroupsvc.stanford.edu/v1/users/{sunetid} user=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} |
|
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi/members?user=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Remove member
| Description | Remove member or workgroup from a workgroup | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/members | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/members | |
| Method | DELETE | |
| Query string | user=https://workgroupsvc.stanford.edu/v1/users/{sunetid} user=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} |
|
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
Note: Deleted workgroups and memberships are marked inactive and retained in the system for future reference.
DELETE https://workgroupsvc.stanford.edu/v1/workgroups/mais:wgapi/members?user=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Add administrator
| Description | Add member or workgroup as a workgroup administrator | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/administrators | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/administrators | |
| Method | PUT | |
| Query string | administrator=https://workgroupsvc.stanford.edu/v1/users/{sunetid} administrator=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} |
|
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/administrators?administrator=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Remove administrator
| Description | Remove member or workgroup from a workgroup administrator | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/administrators | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/administrators | |
| Method | DELETE | |
| Query string | administrator=https://workgroupsvc.stanford.edu/v1/users/{sunetid} administrator=https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name} |
|
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
DELETE https://workgroupsvc.stanford.edu/v1/workgroups/administrators?administrator=https://workgroupsvc.stanford.edu/v1/workgroups/mais:new HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Update description
| Description | Update workgroup description. If description contains more than 255 characters, first 255 characters used. |
|
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/description | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/description | |
| Method | PUT | |
| Request Content Type | text/plain;charset=UTF-8 | |
| Request Body | description | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/description
Content-Type:text/plain;charset=UTF-8
Content-Length:16
Test Description
HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Update filter
| Description | Update workgroup filter (overwrite existing filter value with new filter value) | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/filter | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/filter | |
| Method | PUT | |
| Request Content Type | text/plain;charset=UTF-8 | |
| Request Body | filter value | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
Supported filter values are:
- ACADEMIC_ADMINISTRATIVE
- STUDENT
- FACULTY
- STAFF
- FACULTY_STAFF
- FACULTY_STUDENT
- STAFF_STUDENT
- FACULTY_STAFF_STUDENT
- NONE
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/filter
Content-Type:text/plain;charset=UTF-8
Content-Length:24
ACADEMIC_ADMINISTRATIVE
HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Update reusable property
| Description | Update workgroup reusable property - this indicates whether the workgroup can be nested. | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/reusable | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/reusable | |
| Method | PUT | |
| Request Content Type | text/plain;charset=UTF-8 | |
| Request Body | reusable value i.e {TRUE | FALSE} | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
| 409 Conflict | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/reusable
Content-Type:text/plain;charset=UTF-8
Content-Length:5
FALSE
HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Update visibility property
| Description | Update workgroup visibility property | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/visibility | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/visibility | |
| Method | PUT | |
| Request Content Type | text/plain;charset=UTF-8 | |
| Request Body | visibility value i.e {PRIVATE | STANFORD} | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
| 409 Conflict | ||
Only workgroup administrators are allowed to operate on a workgroup. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/visibility
Content-Type:text/plain;charset=UTF-8
Content-Length:8
STANFORD
HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
Update privgroup property
| Description | Update workgroup privgroup property | |
|---|---|---|
| URL | https://workgroupsvc.stanford.edu/v1/workgroups/{workgroup-name}/privgroup | |
| UAT URL | https://workgroupsvc-uat.stanford.edu/v1/workgroups/{workgroup-name}/privgroup | |
| Method | PUT | |
| Request Content Type | text/plain;charset=UTF-8 | |
| Request Body | privgroup value, i.e., {TRUE | FALSE} | |
| Query string | -none- | |
| Returns | 200 OK | |
| 400 Bad Request | ||
| 401 Unauthorized | ||
| 404 Not Found | ||
| 409 Conflict | ||
Only workgroup administrators are allowed to operate on a workgroup. Note that this property affects visibility of the workgroup in downstream reports and LDAP. Please note that the certificate used to authenticate with the API needs to be configured as a workgroup administrator.
PUT https://workgroupsvc.stanford.edu/v1/workgroups/mais:new/privgroup
Content-Type:text/plain;charset=UTF-8
Content-Length:5
FALSE
HTTP/1.1 200 OK
Content-Type:text/xml;charset=UTF-8
Content-Language:en-US
Content-Length:0
Date:Sat, 01 Aug 2009 18:35:51 GMT
