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 Ændringsbeskrivel se PISK CLFR Officiel version 1(Release 21) Introduktion Side1

2 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() echo findftuapplicationids findftuapplicationbyid findftuapplicationpdfbyid findftuapplicationenclosureziplinkbyid findkotapplicationids findkotapplicationbyid findkotapplicationpdfbyid findkotapplicationenclosurezipurlbyid findkotapplicationenclosureurlbyfileid Side2

3 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 * = Krævet felt 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. educationtype Enum Beskriver den type af uddannelser man kan forespørge efter. Hvis værdien udelades spørges der efter alle typer. Læg mærke til at kun TENTH_GRADE, UPPER_SECONDARY, VOCATIONAL og OTHER_ACTIVITIES værdierne understøttes. onlynew boolean Hvis true så hentes kun ikke allerede afhentede ansøgninger. Standardværdi er false. Side3

4 alsosubinstitutions boolean Hvis true så hentes også ansøgninger for underinstitutioner. Standardværdi er false. * = Krævet felt 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 * = Krævet felt 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 * = Krævet felt 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. Side4

5 ftuapplicationis Integer* Det unikke ID for en FTU-ansøgning Bilagene følger fil formattet <cpr> - <applicantid> - <bid>.pdf og ansøgning <cpr> - <appid>.pdf og <cpr> - <appid>.xml. Endeligt følger zip filen formattet <cpr>-<appid>.zip, hvor cpr: ansøgerens cpr nummer applicantid: ansøgerens id 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). For ftu vil applicantid og appid være det samme. Dette vil ikke gælde kot, da ansøgninger betragtes enkeltvis. Eksempel for bilag: pdf. Eksempel for ansøgning: pdf og xml. Eksempel for zip filen: zip. 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. onlynew boolean Hvis true så hentes kun ikke allerede afhentede ansøgninger. Standardværdi er false. Side5

6 alsosubinstitutions boolean Hvis true så hentes også ansøgninger for underinstitutioner. Standardværdi er false. * = Krævet felt 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 * = Krævet felt 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 * = Krævet felt 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. Side6

7 kotapplicationid String Det unikke ID for en KOT-ansøgning Bilagene følger fil formattet <cpr> - <applicantid> - <bid>.pdf og ansøgning <cpr> - <appid>.pdf og <cpr> - <appid>.xml. Endeligt følger zip filen formattet <cpr>-<appid>.zip, hvor cpr: ansøgerens cpr nummer applicantid: ansøgerens id 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. Eksempel for zip filen: zip. findkotapplicationenclosureurlbyfileid Denne metode returnerer en url til afhentning af en enkelt bilag i pdf format. FileId findes i den XML der hentes via findkotapplicationbyid(...) 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(...): Side7

8 <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findftuapplicationids> <ns:institutionnumber>101206</ns:institutionnumber> <ns:fromdate> </ns:fromdate> <ns:todate> </ns:todate> <ns:educationtype>upper_secondary</ns:educationtype> <ns:onlynew>false</ns:onlynew> <ns:alsosubinstitutions>true</ns:alsosubinstitutions> </ns:findftuapplicationids> </soapenv:body> </soapenv:envelope> Resultatet: <ns1:findftuapplicationidsresponse xmlns:ns1=" <return xmlns=" <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>101206</ns:institutionnumber> </ns:findftuapplicationbyid> </soapenv:body> </soapenv:envelope> Format på resultatet: Et svar som enten er en fejlmarkering eller en FTU-ansøgning opbygget efter følgende skema: Side8

9 <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=" <return xmlns=" <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(...): <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findftuapplicationbyid> <ns:ftuapplicationid>70700</ns:ftuapplicationid> <ns:institutionnumber>101206</ns:institutionnumber> </ns:findftuapplicationbyid> </soapenv:body> </soapenv:envelope> Format på resultatet: Et svar som enten er en fejlmarkering eller FTU-ansøgning som PDF opbygget efter følgende skema: Side9

10 <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=" <return xmlns=" <ftuapplicantpdf>jvbe...</ftuapplicantpdf> </ns1:findftuapplicationbyidresponse> 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(...): Side10

11 <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findftuapplicationenclosurezipurlbyid> <ns:ftuapplicationid> </ns:ftuapplicationid> <ns:institutionnumber>157027</ns:institutionnumber> </ns:findftuapplicationenclosurezipurlbyid> </soapenv:body> </soapenv:envelope> Resultat: <findftuapplicationenclosurezipurlbyidresponse xmlns=" <return> <fileurl> 69-a5e ca9-8fa7d28895ac</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(...): <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findkotapplicationids> <ns:institutionnumber>147406</ns:institutionnumber> <ns:admissionareanumber></ns:admissionareanumber> <ns:onlynew>false</ns:onlynew> <ns:alsosubinstitutions>true</ns:alsosubinstitutions> </ns:findkotapplicationids> </soapenv:body> </soapenv:envelope> Resultatet: Side11

12 <ns1:findkotapplicationidsresponse xmlns:ns1=" <return xmlns=" <listofapplicationidandstates> <id>85375#262578</id> <state>original</state> </listofapplicationidandstates> <listofapplicationidandstates> <id> # </id> <state>updated</state> </listofapplicationidandstates> <listofapplicationidandstates> <id>77077#244838</id> <state>enclosure_updated</state> </listofapplicationidandstates> <listofapplicationidandstates> <id>94065#285232</id> <state>original</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...) Side12

13 <ns1:findkotapplicationbyidresponse xmlns:ns1=" <return xmlns=" <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=" ormwrapper><... Eksempel på søgning ved hjælp af operationen findkotapplicationpdfbyid(...): <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findkotapplicationpdfbyid> <ns:kotapplicationid>43714#1</ns:kotapplicationid> <ns:institutionnumber>751470</ns:institutionnumber> </ns:findkotapplicationpdfbyid> </soapenv:body> </soapenv:envelope> Format på resultatet: Et svar som enten er en fejlmarkering eller KOT-ansøgning som PDF opbygget efter følgende skema: Side13

14 <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=" <return xmlns=" <kotapplicantpdf>jvberi0xljcnj...</kotapplicantpdf> </ns1:findkotapplicationpdfbyidresponse> 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(...): Side14

15 <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findkotapplicationenclosurezipurlbyid> <ns:kotapplicationid> # </ns:kotapplicationid> <ns:institutionnumber>101604</ns:institutionnumber> </ns:findkotapplicationenclosurezipurlbyid> </soapenv:body> </soapenv:envelope> Resultat: <findkotapplicationenclosurezipurlbyidresponse xmlns=" <return> <fileurl> ba-0a8b-4bad-870c-60f008cff064</fileurl> </findkotapplicationenclosurezipurlbyidresponse> Eksempel på søgning ved hjælp af operationen findkotapplicationenclosureurlbyfileid(...): <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body> <ns:findkotapplicationenclosureurlbyfileid> <ns:kotapplicationid> # </ns:kotapplicationid> <ns:institutionnumber>101604</ns:institutionnumber> <ns:fileid>121212</ns:fileid> </ns:findkotapplicationenclosureurlbyfileid> </soapenv:body> </soapenv:envelope> Resultat: Side15

16 <ApplicationServiceDownloadFileURLResult xmlns=" <return> <fileurl> ba-0a8b-4bad-870c-60f008cff064</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 Side16