GroupService er ein webservice hos Cerebrum for å få ut informasjon om grupper som er større enn kva bofhd kan gje ut. Målgruppa for tenesta er lokal-IT som har behov for medlemslister til grupper som er for store til å visast i bofh. Dette er dokumentasjon for å få kobla seg opp mot denne tenesta.
Kom i gang
WSDL-en til SOAP-servicen: https://cerebrum-uio.uio.no:8997/SOAP/?wsdl
For å få ut medlemskap i gitte grupper:
- Køyr kommandoen: authenticate(username, password). Svaret skal gje deg ein session-ID, som er samme session-ID som ligg i SOAP-headers.
- Køyr kommandoen: get_members(groupname), hugs å legge med session-ID i SOAP-headeren. Svaret er ei liste med medlem, som har attributta: uname, member_type og member_id. Merk at SOAP-headeren må innehalde session-ID'en som kom i svaret frå authenticate. Merk at session-ID kom både i svaret og i SOAP-headeren i svaret. TODO: Merk at du må vere moderator av gruppa for å få lista ut informasjon om den.
- Når du er ferdig, køyr: deauthenticate(). Dette logger deg ut av tenesta. Om du ikkje køyrer denne kommandoen vil sesjonen din bli automatisk logga ut etter omtrent 15 minuttar.
Om GroupService
GroupService er ei lita teneste i Cerebrum for å liste ut medlemskap til grupper. Tenesta vart bygd for å kunne liste ut medlemskap til store grupper, sidan bofhd har ei sperre på kor store grupper den kan liste ut. Ein må kunne forvente at det kan ta ei stund å få lista ut svære grupper, spesielt om mange køyrer spørringar mot den samtidig.
Tenesta kan utvidast med fleire kommandoar etter ønske.
Tenesta er laga i python og er oppbygd av Cerebrum, twisted (serveren), og rpclib (som tek seg av SOAP-kommunikasjonen).
Protokollen
GroupService køyrer standard SOAP versjon 1.1. Årsaken til at vi bruker SOAP er fordi vi vil måtte bruke denne protokollen mot andre tenester i framtida.
Ein kan sjå WSDL-definisjonen på: https://cerebrum-uio.uio.no:8997/SOAP/?wsdl
WSDL-en inkluderer også kommentarar for kva dei ulike kommandoane gjer. Kommunikasjonen er kryptert vha. standard SSL. Vi anbefaler at ein autentiserer tenaren mot sertifikatet sitt.
TODO: Legg ut tenar-sertifikatet her.
Tilgang til tenesta er sperra ned til UiO-nettet.
Feilmeldingar
I SOAP vil ein kunne få tilbake meldingar i såkalte faults. Desse består av ein faultcode og ein faultstring, med ei lenger forklaring på kva som er feil.
Dei feilmeldingane som kan dukke opp, lista opp etter faultcode:
- senv:client.NotAuthenticated - Denne får du om du ikkje er pålogga før du prøver å få ut ei medlemsliste.
- senv:client.NotAuthorized - Dette skjer dersom du ikkje er moderator av gruppa du vil ha lista ut.
- senv:client.UserError - Dette er ymse feil frå klienten, til dømes at gruppenamnet er ukjendt.
- senv:server.UnknownError - Denne får du om det er ein bøgg på tenarsida. Feilen vert sett på av Cerebrum drift, men det kan likevel vere greit å informere om slike feil til cerebrum-uio@usit.uio.no.
Klientar
Vi har ein eigen PHP-klient: cerebrum/clients/web/phplib/model/CICom.php for Cerebrum webservices. Denne brukast av gløymd-passordtenesta, til dømes på sida for å hente ut brukarnanm: cerebrum/clients/web/individuation/www_docs/username/index.php
Elles skal ein kunne bruke kva som helst av klientar som støtter SOAP 1.1 og der ein kan sette inn sin eigen SOAP-header. Vi har ikkje nokon klient som kan brukast direkte frå kommandolinja, med mindre ein vil køyre php cli.
Author: jokim