Grouper Training Developers and Architects Web Services - Part 2

1. Grouper TrainingDevelopers and Architects Web Services - Part 2 Chris Hyzer Internet2 University of Pennsylvania This work licensed under a Creative Commons Attribution-NonCommercial 3.0 Unported License.

2. Contents Introduction Common features in operations Result code Metadata Sorting/paging Act As Lookups Transaction types Include detail? Subject attribute names WsParams Timestamps / booleans

3. Introduction to WS for developers 3

4. Result code • Grouper WS returns the result code is if success in HTTP header and in the body • If exception, there might not be a valid body • Enum in SVN linked from documentation 4

5. Metadata • Result code • Success? • Result message • Elapsed server time • Warnings • Metadata on each assignment in batch 5

6. Sorting and Paging • Certain operations support it (e.g. find groups) • Page number (1 indexed) • Page size • Sort string (column to sort on) • Ascending (T|F) 6

7. Act As • All operations support this • Subject to Act As instead of authenticating user • e.g. To build a Grouper UI • Must be authorized in grouper-ws.properties • Can be authorized by who an authenticating used is allowed to Act As (e.g. to restrict GrouperSysAdmin) 7

8. Lookups • Many structures in Grouper can be referred to multiple ways • e.g. GroupLookup • Can pass in Group UUID or name • e.g. SubjectLookup • Can pass in Subject ID, or Subject Identifier • Can optionally pass in a Source ID • See addMember SOAP for example 8

9. Transaction types • Many batched operations support transactions • If blank, defaults to NONE • Can either set txType to NONE or READ_WRITE_NEW • other values of GrouperTransactionType enum do not make sense • If NONE then the operation will commit as much of the request as it can • If READ_WRITE_NEW then any failure in batch of operations will roll the entire request back 9

10. Include detail • If operation returns groups or subjects, you can include detail • For Groups this means legacy types and attributes, composite details, etc • For Subjects, the detail is whatever attributes are configured at your institution • includeGroupDetail = T|F • includeSubjectDetail = T|F 10

11. Subject attribute names • Subjects might have attributes at your institution which are not configured to be returned by default or in Detail • If the WS caller is allowed, the required attribute names can be requested • XML REST example: <subjectAttributeNames> <string>emailAddress</string> <string>preferredFirstName</string> </subjectAttributeNames> 11

12. WsParams • Operations optionally take this map • Name/value pairs • Intended to take one/off switches to maintain backwards compatibility • Not used that frequently • Documented in each operation's docs 12

13. Timestamp / boolean inputs • SOAP only uses Strings, arrays, and types • Timestamps are represented in a couple ways: • yyyy/MM/dd HH:mm:ss.SSS • yyyy/MM/dd_HH:mm:ss.SSS • Booleans can have these values (not case sensitive): • T|F • true|false • yes|no • Y|N 13

14. Quiz • Click on the quiz link in the video description to reinforce your knowledge of this topic 14

15. Thanks! • Further information: • Infosheets, mailing lists, wiki, downloads, etc.:www.internet2.edu/grouper • Grouper demo server:grouperdemo.internet2.edu/ • Grouper Online Training Home:spaces.internet2.edu/x/IIGfAQ This work licensed under a Creative Commons Attribution-NonCommercial 3.0 Unported License.