Date: Fri, 29 Mar 2024 08:34:14 +0000 (UTC) Message-ID: <1647780325.7709.1711701254703@ip-10-10-7-29.ec2.internal> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_7708_1299283342.1711701254701" ------=_Part_7708_1299283342.1711701254701 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
These examples are for getGroups, examp=
le URL and headers:
POST ht= tps://grouper-ws.school.edu/grouperWs/servicesRest/v4_0_000/subjects/source= s/pennperson/subjectId/10021368/groups Content-Type: application/x-www-form-urlencoded
Request first page (pick a sort field a=
nd if ascending, in this case getting all so just use id)
wsLiteO= bjectType=3DWsRestGetGroupsLiteRequest&sortString=3Did&ascending=3D= true&pageSize=3D3&pageNumber=3D1
Request next page (note the page last c=
ursor field is the last id sent in previous request (cursor)
wsLiteO= bjectType=3DWsRestGetGroupsLiteRequest&sortString=3Did&ascending=3D= true&pageSize=3D3&pageLastCursorFieldType=3Dstring&pageCursorFi= eldIncludesLastRetrieved=3Dfalse&pageIsCursor=3Dtrue&pageLastCursor= Field=3D00ffd24ae5f84e6ebb68b1779577c0cd
Request first page
wsLiteO= bjectType=3DWsRestGetGroupsLiteRequest&sortString=3Did&ascending=3D= true&pageSize=3D3&pageNumber=3D1
Request next page
wsLiteO= bjectType=3DWsRestGetGroupsLiteRequest&sortString=3Did&ascending=3D= true&pageSize=3D3&pageNumber=3D2
Here is an example from a JDBC2 subject=
source
# now y= ou can count up from 0 to N of attributes for various cols. The name is ho= w to reference in subject.getAttribute() subjectApi.source.pennperson.param.subjectAttributeCol0.value =3D pennname # you can count up from 0 to N of attributes for various cols. The name is= how to reference in subject.getAttribute() subjectApi.source.pennperson.param.subjectAttributeName0.value =3D PENNNAME=
You can test this from GSH
groovy:= 000> grouperSession =3D GrouperSession.startRootSession(); =3D=3D=3D> 4a29e140d3b346558c7c23ed996d1d8a,'GrouperSystem','application= ' groovy:000> subject =3D SubjectFinder.findByIdOrIdentifier("mchyzer", tr= ue); =3D=3D=3D> Subject id: 10021368, sourceId: pennperson, name: Chris Hyzer groovy:000> subject.getAttributeValue("pennname") =3D=3D=3D> mchyzer
Subject attributes are exposed via web =
service in the grouper-ws.properties
# subje= ct attribute names to send back when a WsSubjectResult is sent, comma separ= ated =20 # e.g. name, netid = =20 # default is none = =20 ws.subject.result.attribute.names =3D # subject result attribute names when extended data is requested (comma sep= arated) =20 # default is name, description = =20 # note, these will be in addition to ws.subject.result.attribute.names = =20 ws.subject.result.detail.attribute.names =3D PENNNAME
Then when a subject is returned, since =
ws.subject.result.attribute.names is blank, no custom attribute are returne=
d by default
[mchyze= r@flash pennGroupsClient-2.4.0]$ java -jar grouperClient.jar --operation=3D= getSubjectsWs --subjectIdentifiers=3Dmchyzer --debug=3Dtrue Reading resource: grouper.client.properties, from: /home/mchyzer/grouper/pe= nnGroupsClient-2.4.0/grouper.client.properties WebService: connecting as user: 'someuser' WebService: connecting to URL: 'https://server.school.edu/grouperWs/service= sRest/v2_4_000/subjects' ################ REQUEST START (indented) ############### POST /grouperWs/servicesRest/v2_4_000/subjects HTTP/1.1 Connection: close Authorization: Basic xxxxxxxxxxxxxxxx User-Agent: Jakarta Commons-HttpClient/3.1 Host: somehost.school.edu:-1 Content-Length: 171 Content-Type: text/xml; charset=3DUTF-8 <WsRestGetSubjectsRequest> <wsSubjectLookups> <WsSubjectLookup> <subjectIdentifier>mchyzer</subjectIdentifier> </WsSubjectLookup> </wsSubjectLookups> </WsRestGetSubjectsRequest> ################ REQUEST END ############### ################ RESPONSE START (indented) ############### HTTP/1.1 200 OK Date: Wed, 17 Apr 2019 18:12:37 GMT Set-Cookie: JSESSIONID=3Dxxxxxxxxxxxx; HttpOnly X-Grouper-resultCode: SUCCESS X-Grouper-success: T X-Grouper-resultCode2: NONE Content-Type: application/xml;charset=3DUTF-8 Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked <WsGetSubjectsResults> <wsSubjects> <WsSubject> <identifierLookup>mchyzer</identifierLookup> <resultCode>SUCCESS</resultCode> <success>T</success> <id>10021368</id> <name>Chris Hyzer</name> <sourceId>pennperson</sourceId> </WsSubject> </wsSubjects> <resultMetadata> <resultCode>SUCCESS</resultCode> <resultMessage>Queried 1 subjects</resultMessage> <success>T</success> </resultMetadata> <responseMetadata> <resultWarnings></resultWarnings> <millis>11</millis> <serverVersion>2.4.0</serverVersion> </responseMetadata> </WsGetSubjectsResults> ################ RESPONSE END ############### Output template: Index: ${index}: success: ${success}, code: ${wsSubject.re= sultCode}, subject: ${wsSubject.id}, available variables: wsGetSubjectsResu= lts, grouperClientUtils, index, wsSubject, wsGroup, success Index: 0: success: T, code: SUCCESS, subject: 10021368 Elapsed time: 957ms [mchyzer@flash pennGroupsClient-2.4.0]$
If you request the subject detail (attr=
s in ws.subject.result.detail.attribute.name), then they will be returned
[mchyze= r@flash pennGroupsClient-2.4.0]$ java -jar grouperClient.jar --operation=3D= getSubjectsWs --subjectIdentifiers=3Dmchyzer --debug=3Dtrue --includeSubjec= tDetail=3Dtrue Reading resource: grouper.client.properties, from: /home/mchyzer/grouper/pe= nnGroupsClient-2.4.0/grouper.client.properties WebService: connecting as user: 'user' WebService: connecting to URL: 'https://server.school.edu/grouperWs/service= sRest/v2_4_000/subjects' ################ REQUEST START (indented) ############### POST /grouperWs/servicesRest/v2_4_000/subjects HTTP/1.1 Connection: close Authorization: Basic xxxxxxxxxxxxxxxx User-Agent: Jakarta Commons-HttpClient/3.1 Host: fastprod-medium-a-01.apps.upenn.edu:-1 Content-Length: 217 Content-Type: text/xml; charset=3DUTF-8 <WsRestGetSubjectsRequest> <includeSubjectDetail>T</includeSubjectDetail> <wsSubjectLookups> <WsSubjectLookup> <subjectIdentifier>mchyzer</subjectIdentifier> </WsSubjectLookup> </wsSubjectLookups> </WsRestGetSubjectsRequest> ################ REQUEST END ############### ################ RESPONSE START (indented) ############### HTTP/1.1 200 OK Date: Wed, 17 Apr 2019 18:16:55 GMT Set-Cookie: JSESSIONID=3Dxxxxxxxxxxxx; HttpOnly X-Grouper-resultCode: SUCCESS X-Grouper-success: T X-Grouper-resultCode2: NONE Content-Type: application/xml;charset=3DUTF-8 Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked <WsGetSubjectsResults> <subjectAttributeNames> <string>name</string> <string>description</string> <string>PENNNAME</string> <string>EMAIL</string> </subjectAttributeNames> <wsSubjects> <WsSubject> <identifierLookup>mchyzer</identifierLookup> <resultCode>SUCCESS</resultCode> <success>T</success> <id>10021368</id> <name>Chris Hyzer</name> <sourceId>pennperson</sourceId> <attributeValues> <string>Chris Hyzer</string> <string>Chris Hyzer (mchyzer, 10021368) (active) Staff - Isc-= applications & Information Services - Application Architect (also: Alum= ni)</string> <string>mchyzer</string> <string>mchyzer@upenn.edu</string> </attributeValues> </WsSubject> </wsSubjects> <resultMetadata> <resultCode>SUCCESS</resultCode> <resultMessage>Queried 1 subjects</resultMessage> <success>T</success> </resultMetadata> <responseMetadata> <resultWarnings></resultWarnings> <millis>121</millis> <serverVersion>2.4.0</serverVersion> </responseMetadata> </WsGetSubjectsResults> ################ RESPONSE END ############### Output template: Index: ${index}: success: ${success}, code: ${wsSubject.re= sultCode}, subject: ${wsSubject.id}, available variables: wsGetSubjectsResu= lts, grouperClientUtils, index, wsSubject, wsGroup, success Index: 0: success: T, code: SUCCESS, subject: 10021368 Elapsed time: 1106ms [mchyzer@flash pennGroupsClient-2.4.0]$
Or you can request individual attribute=
s
[mchyze= r@flash pennGroupsClient-2.4.0]$ java -jar grouperClient.jar --operation=3D= getSubjectsWs --subjectIdentifiers=3Dmchyzer --debug=3Dtrue --subjectAttrib= uteNames=3DPENNNAME Reading resource: grouper.client.properties, from: /home/mchyzer/grouper/pe= nnGroupsClient-2.4.0/grouper.client.properties WebService: connecting as user: 'user' WebService: connecting to URL: 'https://server.school.edu/grouperWs/service= sRest/v2_4_000/subjects' ################ REQUEST START (indented) ############### POST /grouperWs/servicesRest/v2_4_000/subjects HTTP/1.1 Connection: close Authorization: Basic xxxxxxxxxxxxxxxx User-Agent: Jakarta Commons-HttpClient/3.1 Host: fastprod-medium-a-01.apps.upenn.edu:-1 Content-Length: 243 Content-Type: text/xml; charset=3DUTF-8 <WsRestGetSubjectsRequest> <subjectAttributeNames> <string>PENNNAME</string> </subjectAttributeNames> <wsSubjectLookups> <WsSubjectLookup> <subjectIdentifier>mchyzer</subjectIdentifier> </WsSubjectLookup> </wsSubjectLookups> </WsRestGetSubjectsRequest> ################ REQUEST END ############### ################ RESPONSE START (indented) ############### HTTP/1.1 200 OK Date: Wed, 17 Apr 2019 18:26:29 GMT Set-Cookie: JSESSIONID=3Dxxxxxxxxxxxx; HttpOnly X-Grouper-resultCode: SUCCESS X-Grouper-success: T X-Grouper-resultCode2: NONE Content-Type: application/xml;charset=3DUTF-8 Vary: Accept-Encoding Connection: close Transfer-Encoding: chunked <WsGetSubjectsResults> <subjectAttributeNames> <string>PENNNAME</string> </subjectAttributeNames> <wsSubjects> <WsSubject> <identifierLookup>mchyzer</identifierLookup> <resultCode>SUCCESS</resultCode> <success>T</success> <id>10021368</id> <name>Chris Hyzer</name> <sourceId>pennperson</sourceId> <attributeValues> <string>mchyzer</string> </attributeValues> </WsSubject> </wsSubjects> <resultMetadata> <resultCode>SUCCESS</resultCode> <resultMessage>Queried 1 subjects</resultMessage> <success>T</success> </resultMetadata> <responseMetadata> <resultWarnings></resultWarnings> <millis>207</millis> <serverVersion>2.4.0</serverVersion> </responseMetadata> </WsGetSubjectsResults> ################ RESPONSE END ############### Output template: Index: ${index}: success: ${success}, code: ${wsSubject.re= sultCode}, subject: ${wsSubject.id}, available variables: wsGetSubjectsResu= lts, grouperClientUtils, index, wsSubject, wsGroup, success Index: 0: success: T, code: SUCCESS, subject: 10021368 Elapsed time: 1180ms [mchyzer@flash pennGroupsClient-2.4.0]$
To get a list of groups that A is a member of, call getGroups, there is a soap example there. Note: jus= t use g:gsa as the subject source, and the group name as the subjectIdentif= ier, or the group uuid as the subjectId. You can change the query to ask ab= out immediate, effective, nonimmediate, etc. I think you can get similar in= formation from getMemberships (using the same subject call as described abo= ve)
No, you should use the version of Grouper bundled in the web services.&n= bsp; This makes it a little complicated if you have a UI / GSH / etc runnin= g against your Grouper DB. You will need to keep them in sync...
SOAP is supported since many schools required it. REST-Lite is sup= ported because many schools required it. XML-HTTP is supported becaus= e Axis2 gives it for free when building a SOAP web service. This way = the same SOAP interface can be accessed by clients who only want to talk HT= TP and XML and not SOAP.
The URL for ramprt or not is the same. Inside the services.xml in = the .aar files, it configures the app name. grouper-ws will not work = if you change this (unless to do other build activities also)
The non-simple operations are batchable if the client wants to do one op= eration multiple times with one request. The simple operations are fo= r if the client only needs to do one thing (e.g. assign a member to a group= and not assign multiple members to a group). Also, there is a valuab= le side effect that for the XML-HTTP, if the operation only has scaler inpu= t params (and not complex types or arrays), that the input does not need XM= L, it can be in the query string for GET or in the http form param pairs in= the body for POST.
It is confusing that there are so many different ways to call grouper vi= a web service. The documentation will be improved to make it easier t= o find the best strategy.
This is an unfortunate "feature" by axis, the default element is named "= return" which is a keyword in many programming languages, so if the languag= e automatically converts the xml to an object graph, then it will be broken= . Chris will followup with Axis to see if there is a fix for this
For two of three of the flavors of web services SOAP faults are not an o= ption since they are not SOAP. Also, for SOAP batched, the status of = each line item needs to be returned for the client to process, and a SOAP f= ault would preclude that. Also, the fewer SOAP specific features that= are used, the more widespread the compatibility will be. All three f= lavors of web service use the same underlying logic, so the more consistent= the better.
Yes, this will be added