Core web service API
Grouper web services (grouper-ws) is a J2EE web application which exposes common Grouper business logic REST. See Web Services FAQ. and architectural diagram.
Note: there is a command line and java API web service client called Grouper Client. You can run all operations and see REST/JSON examples with the client.
To implement a web service client:
/grouper-ws/servicesRest/json/v2_1_000/groups/aStem%3AaGroup/members/10021368 |
Note the WS is included in the Grouper Installer.
1. The default attribute names (comma separated) sent back for each request are specified in grouper-ws.properties under the key:
ws.subject.result.attribute.names
2. If the caller sets T to retrieve subject detail, then the attributes will be appended to that list in grouper-ws.properties key:
ws.subject.result.detail.attribute.names
3. If the caller specifies subjectAttributeNames in the request (comma separated), then those will be appended to the list (independent of the detail attributes).
So there are central settings, and caller settings that you need to design for and specify...
Note if subjectId and subjectIdentifier are filled in with the same value, it will find by subject id or identifier.
You can do this via the client or a proxy. If you must do this via the server, there is an experimental way to do this in v2.1.1+. You should not do this in prod, only in a testing environment.
Set the filter logger to log at debug level
log4j.logger.edu.internet2.middleware.grouper.ws.j2ee.ServletFilterLogger = DEBUG |
You might want to log to a dedicated file instead of putting in the grouper log... in log4j2.xml
You will see log entries like this
2012-05-03 09:13:18,575: [http-8088-1] DEBUG ServletFilterLogger.logStuff(98) - - IP: 127.0.0.1, url: /grouperWs/servicesRest/v2_1_001/groups/aStem%3AaGroup/members, queryString: null, method: PUT, content-type: text/x-json; charset=UTF-8 request params: request body: {"WsRestAddMemberRequest":{"actAsSubjectLookup":{"subjectId":"GrouperSystem"},"replaceAllExisting":"F","subjectLookups":[{"subjectId":"10021368"},{"subjectId":"10039438"}]}} respone headers: (note, not all headers captured, and not in this order) X-Grouper-resultCode: SUCCESS X-Grouper-success: T X-Grouper-resultCode2: NONE HTTP/1.1 201 Content-Type: text/x-json; charset=UTF-8 response: {"WsAddMemberResults":{"responseMetadata":{"millis":"237","serverVersion":"2.1.1"},"resultMetadata":{"resultCode":"SUCCESS","resultMessage":"Success for: clientVersion: 2.1.1, wsGroupLookup: WsGroupLookup[pitGroups=[],groupName=aStem:aGroup], subjectLookups: Array size: 2: [0]: WsSubjectLookup[subjectId=10021368]\n[1]: WsSubjectLookup[subjectId=10039438]\n\n, replaceAllExisting: false, actAsSubject: WsSubjectLookup[subjectId=GrouperSystem], fieldName: null, txType: NONE, includeGroupDetail: false, includeSubjectDetail: false, subjectAttributeNames: null\n, params: null\n, disabledDate: null, enabledDate: null","success":"T"},"results":[{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10021368","name":"10021368","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}},{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10039438","name":"10039438","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}}],"wsGroupAssigned":{"description":"a group description","displayExtension":"a group","displayName":"a stem:a group","extension":"aGroup","name":"aStem:aGroup","typeOfGroup":"group","uuid":"d9094e4a7c6e4f399d7e1489c875b9f0"}}} |
At some point we can make it more granular which requests get logged and give an option to format the request/response (indent, etc)
If you want to check to see if a subject as a group permission, or to get a list of people with a certain permissions on a group, use hasMember or getMembers, and pass the name of the field (note this list depends on your configuration):
select name from grouper_fields where type != 'naming';
admins
description
displayExtension
displayName
extension
members
name
optins
optouts
readers
requireActiveEmployee
requireAlsoInGroups
updaters
viewers
See the always available client for more info on this slide