Dokumentation af optagelse.dk

Transkript

1 ApplicationService Indhold Versionsstyring Introduktion Navn URL Formål Sikkerhed Operationer echo() findftuapplicationids(...) findftuapplicationbyid(...) findftuapplicationpdfbyid(...) findftuapplicationenclosurezipurlbyid(...) findkotapplicationids(...) findkotapplicationbyid(...) findkotapplicationpdfbyid findkotapplicationenclosurezipurlbyid findkotapplicationenclosureurlbyfileid 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(...): Eksempel på et udsnit af en XML ftu uddannelses plan med digitale bilag Eksempel på søgning ved hjælp af operationen findftuapplicationenclosurezipurlbyid(...): 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(...): Eksempel på et udsnit af en XML kot ansøgning med digitale bilag Eksempel på søgning ved hjælp af operationen findkotapplicationenclosurezipurlbyid(...): Eksempel på søgning ved hjælp af operationen findkotapplicationenclosureurlbyfileid(...): Fejlrapportering Versionsstyring Bruges til at skrive betydelige ændringer til dokumentationen Dato Version Udarbejdet af Godkendt af Ændringsbeskrivelse PISK CLFR Officiel version 1 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: Side1

2 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 findkotapplicationenclosurezipurlbyid findkotapplicationenclosureurlbyfileid 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 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. Side2

3 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 returnerer en url til afhentning af en zip fil med bilagene til en uddannelses plan. Zip filen vil også indeholde selve ansøgning i pdf og xml format. Samtidig vil ansøgningen også blive markeret som afhentet, hvis brugeren (kalderen af denne web service metode) er berettiget til det. institutionnumber String* Modtagende institution/postkasse for ansøgningerne. ftuapplicationis Integer* Det unikke ID for en FTU-ansøgning Bilagene følger fil formattet <cpr> - <appid> - <bid>.pdf <appid> og ansøgning <cpr>.pdf og <cpr>.xml, hvor cpr: ansøgerens cpr nummer. appid: uddanelses plan unikke id (se under 'Eksempel på et udsnit af en XML ftu uddannelses plan med digitale bilag'). bid: bilagens unikke id (også benyttet som fil id). Eksempel for bilag: pdf. Eksempel for ansøgning: pdf og xml. findkotapplicationids(...) Denne metode fremsøger en liste af KOT-ansøgnings-ID'er og tilstande. 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. 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. Side3

4 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 findkotapplicationenclosurezipurlbyid Denne metode returnerer en url til afhentning af en zip fil med bilagene til en ansøgning. Zip filen vil også indeholde selve ansøgning i pdf og xml format. Samtidig vil ansøgningen også blive markeret som afhentet, hvis brugeren (kalderen af denne web service metode) er berettiget til det. Navn Type Besskrivelse institutionnumber String Modtagende institution/postkasse for ansøgningerne. kotapplicationid String Det unikke ID for en KOT-ansøgning Bilagene følger fil formattet <cpr> - <appid> - <bid>.pdf <appid> og ansøgning <cpr>.pdf og <cpr>.xml, hvor cpr: ansøgerens cpr nummer. appid: ansøgnings unikke id. bid: bilagens unikke id (også benyttet som fil id, se under 'Eksempel på et udsnit af en XML kot ansøgning med digitale bilag'). Eksempel for bilag: pdf. Eksempel for ansøgning: pdf og xml. findkotapplicationenclosureurlbyfileid Denne metode returnerer en url til afhentning af en enkelt bilag i pdf format. Side4

5 institutionnumber String Modtagende institution/postkasse for ansøgningerne. kotapplicationid String Det unikke ID for en KOT-ansøgning fileid String Bilagens unikke fil id. 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(...): <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: Side5

6 Et svar som enten er en fejlmarkering eller en FTU-ansøgning 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 FtuEducationPlanList.xsd. Eksempel på svar fra tjenesten (hvor indmaden er fjernet og erstattet med...) <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:sequence> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="ftuapplicantpdf" type="xs:base64binary"/> </xs:sequence> </xs:complextype> 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> Side6

7 Eksempel på et udsnit af en XML ftu uddannelses plan med digitale bilag <EnclosureList> <Enclosure> <EnclosureType>DIGITAL_FILE</EnclosureType> <EnclosureName> pdf</EnclosureName> <ApplicantsEnclosureName>bilag1</ApplicantsEnclosureName> <UploadDate> </UploadDate> </Enclosure> <Enclosure> <EnclosureType>DIGITAL_FILE</EnclosureType> <EnclosureName> pdf</EnclosureName> <ApplicantsEnclosureName>bilag2</ApplicantsEnclosureName> <UploadDate> </UploadDate> </Enclosure> </EnclosureList> Eksempel på søgning ved hjælp af operationen findftuapplicationenclosurezipurlbyid(...): <ns:findftuapplicationenclosurezipurlbyid> <ns:ftuapplicationid> </ns:ftuapplicationid> <ns:institutionnumber>157027</ns:institutionnumber> </ns:findftuapplicationenclosurezipurlbyid> Resultat: <findftuapplicationenclosurezipurlbyidresponse xmlns=" <return> <fileurl> </findftuapplicationenclosurezipurlbyidresponse> 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(...): Side7

8 <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=" <listofapplicationidandstates> <id>85375#262578</id> <state>original ansøgning</state> </listofapplicationidandstates> <listofapplicationidandstates> <id> # </id> <state>ansøgning opdateret</state> </listofapplicationidandstates> <listofapplicationidandstates> <id>77077#244838</id> <state>bilag opdateret</state> </listofapplicationidandstates> <listofapplicationidandstates> <id>94065#285232</id> <state/> </listofapplicationidandstates> </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: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...) Side8

9 <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:sequence> <xs:element minoccurs="0" name="error" type="tns:error"/> <xs:element minoccurs="0" name="kotapplicantpdf" type="xs:base64binary"/> </xs:sequence> </xs:complextype> 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> Side9

10 Eksempel på et udsnit af en XML kot ansøgning med digitale bilag <EnclosureList> <Enclosure> <EnclosureType>DIGITAL_FILE</EnclosureType> <FileId> </FileId> <EnclosureName> pdf</EnclosureName> <ApplicantsEnclosureName>bilag1</ApplicantsEnclosureName> <UploadDate> </UploadDate> </Enclosure> <Enclosure> <EnclosureType>DIGITAL_FILE</EnclosureType> <FileId> </FileId> <EnclosureName> pdf</EnclosureName> <ApplicantsEnclosureName>bilag2</ApplicantsEnclosureName> <UploadDate> </UploadDate> </Enclosure> </EnclosureList> Eksempel på søgning ved hjælp af operationen findkotapplicationenclosurezipurlbyid(...): <ns:findkotapplicationenclosurezipurlbyid> <ns:kotapplicationid> # </ns:kotapplicationid> <ns:institutionnumber>101604</ns:institutionnumber> </ns:findkotapplicationenclosurezipurlbyid> Resultat: <findkotapplicationenclosurezipurlbyidresponse xmlns=" <return> <fileurl> </findkotapplicationenclosurezipurlbyidresponse> Eksempel på søgning ved hjælp af operationen findkotapplicationenclosureurlbyfileid(...): <ns:findkotapplicationenclosureurlbyfileid> <ns:kotapplicationid> # </ns:kotapplicationid> <ns:institutionnumber>101604</ns:institutionnumber> <ns:fileid>121212</ns:fileid> </ns:findkotapplicationenclosureurlbyfileid> Resultat: Side10

11 <ApplicationServiceDownloadFileURLResult xmlns=" <return> <fileurl> </findkotapplicationenclosurezipurlbyidresponse> 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> Code NO_DATA INVALID_INPUT ILLEGAL_ACCESS INSTITUTION_NOT_FOUND SYSTEM_ERR 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 Side11