Dokumentation af optagelse.dk

Transkript

1 ApplicationService Indhold Versionsstyring Introduktion Navn URL Formål Sikkerhed Operationer echo() findftuapplicationids(...) findftuapplicationbyid(...) findkotapplicationids(...) findkotapplicationbyid(...) Eksempler hent FTU-ansøgninger Eksempel på søgning ved hjælp af operationen findftuapplicationids(...): Eksempel på søgning ved hjælp af operationen findftuapplicationbyid(...): hent KOT-ansøgninger Eksempel på søgning ved hjælp af operationen findkotapplicationids(...): Eksempler på søgning ved hjælp af operationerne findkotapplicationbyid(...) : Eksempel på søgning ved hjælp af operationen findkotapplicationbyid(...): Fejlrapportering Versionsstyring Bruges til at skrive betydelige ændringer til dokumentationen Dato Version Udarbejdet af Godkendt af Ændringsbeskrivelse CLFR MIHA TDAB CLFR CLFR LAHA TDAB MIHA THLE MPE Dokument oprettet. Servicen er flyttet til projekt security-proxy og har derfor fået ny URL. Af performance hensyn er servicen grundlæggende splittet op, således at man først skal hente en liste af ID'er for derefter at hente den modsvarende ansøgning. Tilføjet afsnit om autorisationskontrollen under sikkerhed og fejlrapporting. Tilføjet * ved Echo() service. Tilføjet at det er fra og med fromdate for henholdsvis KOT og FTU. Fjernet SLA. Fjernet det rå eksempel under "Eksempel på søgning ved hjælp af operationen findftuapplicationbyid" Opdateret ud fra DE THLE Opdateret ud fra DE1651. Gjort kravene til Kot/FtuApplicationIds mere strikse LAHA MIHA Opdateret i forhold til ny eksamensdatabase Introduktion Gennemgang af service der henter FTU og KOT-ansøgninger i Optagelse.dk. Navn ApplicationService er implementeret i ApplicationServiceImpl, som findes i modulet security-proxy. URL Tjenesten på Optagelse.dk kan findes via følgende webservice beskrivelse (kræver også login): Side1

2 Test: Produktion: Formål Tjeneste til udlæsning af ansøgninger fra Optagelse.dk. Tjenesten er forsøgt opbygget efter samme mønster som den oprindelige tjeneste i det gamle optagelse.dk, hvor svaret er en tekststreng indeholdende XML. Den største forskel ligger i autentifikationen og opsplitningen mellem KOT og FTU. Sikkerhed Tjenesten er beskyttet af UNI-Login og kræver rollen opt_receiver_applications. I webservice sammenhæng betyder det, at brugernavn og kodeord skal udfyldes som basic authentication i forespørgslens http-header. Derudover kræver adgang til metoderne, at brugeren har ret til at afhente ansøgninger for den angivne institution. En ret som tildeles af institutionens lokale administrator. Operationer Tjenesten består af 6 operationer: echo, findftuapplicationids, findftuapplicationbyid, findkotapplicationids, findkotapplicationbyid og findkotapplicationstadsbyid echo() echo operationen er en simpel operation til at afprøve en klient. Den er opsat med samme restriktioner som find* operationerne, men returnerer blot et simpelt svar på en hello parameter. Paramter: hello String* Simpel parameter til test formål findftuapplicationids(...) Denne metode vil ændre sig i forbindelse med release 17 Denne metode fremsøger en liste af FTU-ansøgnings-ID'er. Fremsøgningen foregår primært via institutionsnummer. De returnerede ID'er kan derefter benyttes til at kalde metoden findftuapplicationbyid(...) for at få returneret hver enkelt ansøgning. institutionnumber String* Modtagende institution for ansøgningerne. Hvis der også ønskes ansøgninger for underinstitutioner, markeres det med flaget alsosubinstitutions, som beskrevet nedenfor. fromdate Date Hvis sat hentes kun ansøgninger fra og med denne dato og fremad. Må ikke være tom. todate Date Hvis sat hentes kun ansøgninger frem til og med denne dato. Må ikke være tom. onlynew boolean Hvis true så hentes kun ikke allerede afhentede ansøgninger. Standardværdi er false. alsosubinstitutions boolean Hvis true så hentes også ansøgninger for underinstitutioner. Standardværdi er false. findftuapplicationbyid(...) Denne metode vil ændre sig i forbindelse med release 17 Side2

3 Denne metode fremsøger en FTU-ansøgning på baggrund af et ansøgnings-id og et institutionsnummer. Dette institutionsnummer repræsenterer den institution, der er ved at afhente ansøgninger. Listen af FTU-ansøgnings-ID'er hentes ved at kalde metoden findftuapplicationids(...). institutionnumber String* Modtagende institution for ansøgningerne. ftuapplicationid Integer* Det unikke ID for en FTU-ansøgning findkotapplicationids(...) Denne metode fremsøger en liste af KOT-ansøgnings-ID'er. Fremsøgningen foregår primært via institutionsnummer. De returnerede ID'er kan derefter benyttes til at kalde metoden findkotapplicationbyid(...) eller findkotapplicationstadsbyid(...) for at få returneret hver enkelt ansøgning. institutionnumber String* Modtagende institution for ansøgningerne. Hvis der også ønskes ansøgninger for underinstitutioner, markeres det med flaget alsosubinstitutions, som beskrevet nedenfor. admissionareanumber String Filtrering på KOT-nummer. fromdate Date Hvis sat hentes kun ansøgninger fra og med denne dato og fremad. Må ikke være tom. todate Date Hvis sat hentes kun ansøgninger frem til og med denne dato. Må ikke være tom. onlynew boolean Hvis true så hentes kun ikke allerede afhentede ansøgninger. Standardværdi er false. alsosubinstitutions boolean Hvis true så hentes også ansøgninger for underinstitutioner. Standardværdi er false. findkotapplicationbyid(...) Denne metode fremsøger en KOT-ansøgning i standardformat på baggrund af et ansøgnings-id og et institutionsnummer. Dette institutionsnummer repræsenterer den institution, der er ved at afhente ansøgninger. Listen af KOT-ansøgnings-ID'er hentes ved at kalde metoden findkotapplicationids(...). institutionnumber String* Modtagende institution for ansøgningerne. kotapplicationid String* Det unikke ID for en KOT-ansøgning Eksempler hent FTU-ansøgninger For at hente FTU-ansøgninger skal man først hente en liste af FTU-ansøgnings ID'er( findftuapplicationids(...) ) og herefter hentes hver ansøgning på baggrund af et FTU-ansøgnings-ID ( findftuapplicationbyid(...) ). Eksempel på søgning ved hjælp af operationen findftuapplicationids(...): Side3

4 <soapenv:envelope xmlns:soapenv = " xmlns:ns= " <soapenv:header/> <soapenv:body> <ns:findftuapplicationids> <ns:institutionnumber> </ns:institutionNumber> <ns:fromdate> </ns:fromDate> <ns:todate> </ns:toDate> <ns:onlynew> false</ns:onlynew> <ns:alsosubinstitutions> true</ns:alsosubinstitutions> </ns:findftuapplicationids> </soapenv:body> </soapenv:envelope> Resultatet: <ns1:findftuapplicationidsresponse xmlns:ns1 = " > <listofapplicationids> 70700</listOfApplicationIds> <listofapplicationids> 93519</listOfApplicationIds> <listofapplicationids> 45323</listOfApplicationIds> <listofapplicationids> 75596</listOfApplicationIds> <listofapplicationids> 89188</listOfApplicationIds> </ns1:findftuapplicationidsresponse> Eksempel på søgning ved hjælp af operationen findftuapplicationbyid(...): <soapenv:envelope xmlns:soapenv = " xmlns:ns= " <soapenv:header/> <soapenv:body> <ns:findftuapplicationbyid> <ns:ftuapplicationid> 70700</ns:ftuApplicationId> <ns:institutionnumber> </ns:institutionNumber> </ns:findftuapplicationbyid> </soapenv:body> </soapenv:envelope> Format på resultatet: Et svar som enten er en fejlmarkering eller liste af FTU-ansøgninger opbygget efter følgende skema: <xs:complextype name= "applicationservicefindresult" > <xs:sequence> <xs:element minoccurs= "0" name= "error" type= "tns:error"/> <xs:element minoccurs= "0" name= "ftuapplicantforms" type= "xs:string"/> </xs:sequence> </xs:complextype> Operationen returnerer en FTU-ansøgning som tekst indeholdende XML specificeret i XML-skemaet FTUApplicantCollection.xsd. Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) Side4

5 <ns1:findftuapplicationbyidresponse xmlns:ns1 = " > <ftuapplicantforms> <![CDATA[<?xml version= "1.0" encoding= "UTF-8"?> <ListOfJEPE xmlns= " > <Application>... </Application></ListOfJEPE> ]]> </ftuapplicantforms> </ns1:findftuapplicationbyidresponse> hent KOT-ansøgninger For at hente KOTansøgninger skal man først hente en liste af KOT-ansøgnings-ID'er( findkotapplicationids(...) ) og herefter hentes hver ansøgning på baggrund af et KOT-ansøgnings-ID ( findkotapplicationbyid(...) ). Eksempel på søgning ved hjælp af operationen findkotapplicationids(...): <soapenv:envelope xmlns:soapenv = " xmlns:ns= " <soapenv:header/> <soapenv:body> <ns:findkotapplicationids> <ns:institutionnumber> </ns:institutionNumber> <ns:admissionareanumber></ns:admissionareanumber> <ns:onlynew> false</ns:onlynew> <ns:alsosubinstitutions> true</ns:alsosubinstitutions> </ns:findkotapplicationids> </soapenv:body> </soapenv:envelope> Resultatet: <ns1:findkotapplicationidsresponse xmlns:ns1 = " > <listofapplicationids> 30700#2</listOfApplicationIds> <listofapplicationids> 33519#3</listOfApplicationIds> <listofapplicationids> 35323#1</listOfApplicationIds> <listofapplicationids> 35596#2</listOfApplicationIds> <listofapplicationids> 39188#1</listOfApplicationIds> </ns1:findkotapplicationidsresponse> Eksempler på søgning ved hjælp af operationerne findkotapplicationbyid(...) : Format på resultatet: Et svar som enten er en fejlmarkering eller liste af KOT-ansøgninger opbygget efter følgende skema: <xs:complextype name= "applicationservicefindresult" > <xs:sequence> <xs:element minoccurs= "0" name= "error" type= "tns:error"/> <xs:element minoccurs= "0" name= "kotapplicantforms" type= "xs:string"/> </xs:sequence> </xs:complextype> Eksempel på søgning ved hjælp af operationen findkotapplicationbyid(...): Operationen returnerer en KOT-ansøgning som tekst indeholdende XML specificeret i XML-skemaet ApplicantForms.xsd Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) Side5

6 <ns1:findkotapplicationbyidresponse xmlns:ns1 = " > <kotapplicantforms> <![CDATA[<?xml version= "1.0" encoding= "UTF-8"?> <ApplicantForms> <ApplicantFormWrapper> <ApplicantForm xmlns= " >... </ApplicantForm> <Certificates>... </Certificates> </ApplicantFormWrapper> </ApplicantForms>]]> </kotapplicantforms> </ns1:findkotapplicationbyidresponse> I svaret ovenfor er data indkapslet med CDATA tags, men det er afhængig af klienten, man laver forespørgslen med. Med en helt rå http forespørgsel ser data således ud: <kotapplicantforms><?xml version="1.0" encoding="utf-8"?> <ApplicantForms xmlns=" Fejlrapportering Ved fejlsituationer returneres fejlelement efter følgende skema: <xs:complextype final= "extension restriction" name= "error" > <xs:sequence> <xs:element minoccurs= "0" name= "code" type= "xs:string"/> <xs:element minoccurs= "0" name= "text" type= "xs:string"/> </xs:sequence> </xs:complextype> Eksempelvis: <error> <code> INVALID_ADMISSION_AREA_NUMBER</code> <text> Invalid AdmissionAreaNumber</text> </error> Code NO_DATA INVALID_INPUT ILLEGAL_ACCESS Beskrivelse Hvis søgningen intet finder Hvis input data ikke er gyldigt Hvis authentifikation eller autorisationen ikke lykkes. Dette er ekstra kontrol som foretages efter UNI-Login. Denne fejl angiver, at brugeren enten ikke har den korrekte rolle eller ikke har adgang til at afhente den angivne institutions ansøgninger. INSTITUTION_NOT_FOUND SYSTEM_ERR Det angivne institutionsnummer matcher ikke institution i Optagelse.dk Fejl i tjenesten Side6