Dokumentation af optagelse.dk

Transkript

1 ApplicationService Indhold Versionsstyring Introduktion Navn URL Formål Sikkerhed Operationer echo() findftuapplicationids(...) findftuapplicationbyid(...) findftuapplicationpdfbyid(...) findftuapplicationenclosurezipurlbyid(...) findkotapplicationids(...) findkotapplicationbyid(...) findkotapplicationpdfbyid 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(...): Eksempel på søgning ved hjælp af operationen findftuapplicationpdfbyid(...): 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(...): Eksempel på søgning ved hjælp af operationen findkotapplicationpdfbyid(...): 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 CLFR THLE Opdateret i forhold R17 ændringer CLFR MIHA Opdateret ud fra DE CLFR Opdateret ud fra US CHHO Opdateret ud fra DE2322 Side1

2 THLE Opdateret ud fra US2179 (FTU: Digitale Bilag) 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): Test: Præprod: 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 følgende operationer echo findftuapplicationids findftuapplicationbyid findftuapplicationpdfbyid findftuapplicationenclosureziplinkbyid findkotapplicationids findkotapplicationbyid findkotapplicationpdfbyid 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 Side2

3 findftuapplicationids(...) 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/postkasse 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 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 findftuapplicationpdfbyid(...) Denne metode fremsøger en FTU-ansøgnings-PDF 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/postkasse for ansøgningerne. ftuapplicationid Integer* Det unikke ID for en FTU-ansøgning findftuapplicationenclosurezipurlbyid(...) Denne metode fremsøger et URL link til en fil, indeholdende en uddannelsesplans digitale bilag. Fremsøgningen foregår på baggrund af et ansøgnings-id og et institutionsnummer. Dette institutionsnummer repræsenterer den institution, der er ved at afhente ansøgninger. institutionnumber String* Modtagende institution/postkasse 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 findkotapplicationpdfbyid(...) for at få returneret hver enkelt ansøgning. Side3

4 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/postkasse for ansøgningerne. kotapplicationid String* Det unikke ID for en KOT-ansøgning findkotapplicationpdfbyid Denne metode fremsøger en KOT-ansøgning i PDF-format 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/postkasse for ansøgningerne. kotapplicationid String* Det unikke ID for en KOT-ansøgning PDF returneres kun, hvis den allerede er genereret af systemet. Hvis den ikke er genereret af systemet får man fejlkoden PDF_NOT_FOUND og man må vente og forsøge senere. 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(...): Side4

5 <ns:findftuapplicationids> <ns:institutionnumber>101206</ns:institutionnumber> <ns:fromdate> </ns:fromdate> <ns:todate> </ns:todate> <ns:onlynew>false</ns:onlynew> <ns:alsosubinstitutions>true</ns:alsosubinstitutions> </ns:findftuapplicationids> 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(...): <ns:findftuapplicationbyid> <ns:ftuapplicationid>70700</ns:ftuapplicationid> <ns:institutionnumber>101206</ns:institutionnumber> </ns:findftuapplicationbyid> Format på resultatet: Et svar som enten er en fejlmarkering eller en FTU-ansøgning opbygget efter følgende skema: <xs:complextype name="applicationservicefindresult"> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="ftuapplicantforms" type="xs:string"/> Operationen returnerer en FTU-ansøgning som tekst indeholdende XML specificeret i XML-skemaet FtuEducationPlanList.xsd. Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) Side5

6 <ns1:findftuapplicationbyidresponse xmlns:ns1=" <ftuapplicantforms> <![CDATA[<?xml version="1.0" encoding="utf-8"?><ftueducationplanlist xmlns=" xmlns="urn:optagelse.dk:ftu:1.0.0">...</ftueducationplan></ftueducationplanlist>]]> </ftuapplicantforms> </ns1:findftuapplicationbyidresponse> Eksempel på søgning ved hjælp af operationen findftuapplicationpdfbyid(...): <ns:findftuapplicationbyid> <ns:ftuapplicationid>70700</ns:ftuapplicationid> <ns:institutionnumber>101206</ns:institutionnumber> </ns:findftuapplicationbyid> Format på resultatet: Et svar som enten er en fejlmarkering eller FTU-ansøgning som PDF opbygget efter følgende skema: <xs:complextype name="applicationservicefindresult"> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="ftuapplicantpdf" type="xs:base64binary"/> Operationen returnerer en FTU-ansøgning som Base64 encodede bytes. Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) <ns1:findftuapplicationbyidresponse xmlns:ns1=" <ftuapplicantpdf>jvbe...</ftuapplicantpdf> </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(...): Side6

7 <ns:findkotapplicationids> <ns:institutionnumber>147406</ns:institutionnumber> <ns:admissionareanumber></ns:admissionareanumber> <ns:onlynew>false</ns:onlynew> <ns:alsosubinstitutions>true</ns:alsosubinstitutions> </ns:findkotapplicationids> 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 en KOT-ansøgning opbygget efter følgende skema: <xs:complextype name="applicationservicefindresult"> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="kotapplicantforms" type="xs:string"/> 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...) Side7

8 <ns1:findkotapplicationbyidresponse xmlns:ns1=" <kotapplicantforms> <![CDATA[<?xml version="1.0" encoding="utf-8"?> <ApplicantForms> <ns1:applicantformwrapper> <ns1:applicantform xmlns=" <ns1:outfetch>...</ns1:outfetch> </ns1: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=" Eksempel på søgning ved hjælp af operationen findkotapplicationpdfbyid(...): <ns:findkotapplicationpdfbyid> <ns:kotapplicationid>43714#1</ns:kotapplicationid> <ns:institutionnumber>751470</ns:institutionnumber> </ns:findkotapplicationpdfbyid> Format på resultatet: Et svar som enten er en fejlmarkering eller KOT-ansøgning som PDF opbygget efter følgende skema: <xs:complextype name="applicationservicefindresult"> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="kotapplicantpdf" type="xs:base64binary"/> Operationen returnerer en KOT-ansøgning som Base64 encodede bytes. Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) <ns1:findkotapplicationpdfbyidresponse xmlns:ns1=" <kotapplicantpdf>jvberi0xljcnj...</kotapplicantpdf> </ns1:findkotapplicationpdfbyidresponse> Side8

9 Fejlrapportering Ved fejlsituationer returneres fejlelement efter følgende skema: <xs:complextype final="extension restriction" name="error"> <xs:element minoccurs="0" name="code" type="xs:string"/> <xs:element minoccurs="0" name="text" type="xs:string"/> Eksempelvis: <error> <code>pdf_not_found</code> <text>prøv igen senere.</text> </error> Code NO_DATA INVALID_INPUT ILLEGAL_ACCESS INSTITUTION_NOT_FOUND SYSTEM_ERR PDF_NOT_FOUND 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. Det angivne institutionsnummer matcher ikke institution i Optagelse.dk Fejl i tjenesten Ansøgningens PDF er endnu ikke blevet genereret og kan derfor ikke hentes (gælde kun KOT) Side9