Grænseflade til afhentning af FTU-ansøgninger på Optagelse.dk

Transkript

1 Grænseflade til afhentning af FTU-ansøgninger på Optagelse.dk Dato Version Status 1.0 Gældende Ansvarlig Tobias Thisted

2 Side 2 af 13 Ændringshistorik Version Kapitel/afsnit Beskrivelse 1.0 Hele dokumentet Ny beskrivelse baseret på eksisterende beskrivelser hidtil publiceret på Optagelse.dk.

3 Side 3 af 13 Indhold 1 Introduktion Adgang og sikkerhed Operationer/metoder Metoden echo() Metoden findftuapplicationids(...) Metoden findftuapplicationbyid(...) Metoden findftuapplicationpdfbyid(...) Metoden findftuapplicationenclosurezipurlbyid(...) Eksempler Hent FTU-ansøgninger Eksempel på søgning ved hjælp af findftuapplicationids(...) Eksempel på søgning ved hjælp af findftuapplicationbyid(...) Eksempel på søgning ved hjælp af findftuapplicationpdfbyid(...) Eksempel på udsnit af en XML FTU-uddannelsesplan med digitale bilag Eksempel på søgning ved hjælp af findftuapplicationenclosurezipurlbyid(...) Fejlrapportering... 13

4 Side 4 af 13 1 Introduktion Optagelse.dk udstiller en webservice, som giver uddannelsesinstitutioner på ungdomsuddannelsesområdet muklighed for løbende afhentning af ansøgninger til ungdomsuddannelser (FTU-ansøgninger) på Optagelse.dk. 2 Adgang og sikkerhed Servicen på Optagelse.dk kan findes via følgende links (kræver login): Test: Produktion: Servicen er beskyttet af UNI-Login. I webservice-sammenhæng betyder det, at brugernavn og kodeord skal udfyldes som basic authentication i forespørgslens httpheader. Desuden skal den pågældende institution give den afhentende bruger (kalderen af webservicen) ret til at afhente ansøgninger. Rettigheden tildeles af institutionens lokale administrator. 3 Operationer/metoder Tjenesten består af følgende operationer/metoder: 1. echo 2. findftuapplicationids 3. findftuapplicationbyid 4. findftuapplicationpdfbyid 5. findftuapplicationenclosureziplinkbyid 3.1 Metoden echo() Metoden echo er en simpel operation til afprøvning af en klient. Operationen er opsat med samme restriktioner som find-operationerne, men returnerer blot et simpelt svar på en hello-parameter. Parametre: Navn Type Beskrivelse hello String* Simpel parameter til test formål (* = krævet felt).

5 Side 5 af Metoden findftuapplicationids(...) Metoden 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. Parametre: Navn Type Beskrivelse institutionnumber String* Modtagende institution/postkasse for ansøgningerne. Hvis der også ønskes ansøgninger for underinstitutioner, markeres det med flaget also- SubInstitutions, som beskrevet nedenfor. fromdate Date Hvis datoen angives, hentes kun ansøgninger fra og med denne dato og fremad. todate Date Hvis datoen angives, hentes kun ansøgninger frem til og med denne dato. educationtype Enum Beskriver den type af uddannelser, man kan forespørge efter. Hvis værdien udelades, spørges efter alle typer. Læg mærke ti,l at kun værdierne TENTH_GRADE, UPPER_SECONDARY, VOCATIO- NAL og OTHER_ACTIVITIES understøttes. onlynew boolean Hvis værdien er TRUE, hentes kun ikke allerede afhentede ansøgninger. Standardværdien er FAL- SE. alsosubinstitutions boolean Hvis værdien er TRUE, hentes også ansøgninger for underinstitutioner. Standardværdien er FAL- SE. (* = krævet felt). 3.3 Metoden findftuapplicationbyid(...) Metoden 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(...). Parametre: Navn Type Beskrivelse institutionnumber String* Modtagende institution for ansøgningerne. ftuapplicationid Integer* Det unikke ID for en FTU-ansøgning. (* = krævet felt).

6 Side 6 af Metoden findftuapplicationpdfbyid(...) Metoden 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(...). Parametre: Navn Type Beskrivelse institutionnumber String* Modtagende institution/postkasse for ansøgningerne. ftuapplicationid Integer* Det unikke ID for en FTU-ansøgning. (* = krævet felt). 3.5 Metoden findftuapplicationenclosurezipurlbyid(...) Metoden returnerer en url til afhentning af en zip-fil med bilagene til en uddannelsesplan. Zip-filen vil også indeholde selve ansøgningen i hhv. pdf-format og xmlformat. Samtidig vil ansøgningen også blive markeret som afhentet, hvis brugeren (kalderen af denne webservice-metode) er berettiget til det. Parametre: Navn Type Beskrivelse institutionnumber String* Modtagende institution/postkasse for ansøgningerne. ftuapplicationid Integer* Det unikke ID for en FTU-ansøgning (* = krævet felt). De ovennævnte filnavne genereres ud fra følgende oplysninger: cpr: ansøgerens cpr nummer applicantid: ansøgerens id appid: uddannelsesplanens unikke id (se under 'Eksempel på et udsnit af en XML ftu-uddannelse plan med digitale bilag') bid: bilagens unikke id (også benyttet som fil id). Bilagene har filformatet <cpr>-<applicantid>-<bid>.pdf. Ansøgningerne har filformatet <cpr>-<appid>.pdf og <cpr>-<appid>.xml. Endeligt har zip-filen filformatet <cpr>- <appid>.zip. Eksempel på filnavnsformat for bilag: XXXX pdf. Eksempel på filnavnsformat for ansøgning: XXXX pdf og XXXX xml. Eksempel på filnavnsformat for zip-fil: XXXX zip.

7 Side 7 af 13 For FTU-ansøgninger vil applicantid og appid være det samme. Dette vil ikke gælde KOT-ansøgninger (ansøgninger til videregående uddannelser), da disse ansøgninger behandles enkeltvis. 4 Eksempler 4.1 Hent FTU-ansøgninger For at hente FTU-ansøgninger skal man først hente en liste af FTU-ansøgnings-ID'er (findftuapplicationids(...)). Herefter hentes hver ansøgning på baggrund af et FTUansøgnings-ID (findftuapplicationbyid(...)) Eksempel på søgning ved hjælp af findftuapplicationids(...) <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> Resultat: <soap:envelope xmlns:soap=" <soap:body> <ns1:findftuapplicationidsresponse xmlns:ns1=" <return xmlns=" <listofapplicationids>70700</listofapplicationids> <listofapplicationids>93519</listofapplicationids> <listofapplicationids>45323</listofapplicationids> <listofapplicationids>75596</listofapplicationids> <listofapplicationids>89188</listofapplicationids> </return> </ns1:findftuapplicationidsresponse> </soap:body> </soap:envelope> Eksempel på søgning ved hjælp af findftuapplicationbyid(...) <soapenv:envelope xmlns:soapenv=" xmlns:ns=" <soapenv:header/> <soapenv:body>

8 Side 8 af 13 <ns:findftuapplicationbyidrequest> <ns:ftuapplicationid> </ns:ftuapplicationid> <ns:institutionnumber>101151</ns:institutionnumber> </ns:findftuapplicationbyidrequest> </soapenv:body> </soapenv:envelope> Resultat: Et svar som enten er en fejlmarkering eller en FTU-ansøgning opbygget efter følgende skema: <xs:complextype name="ftuapplicationservicefindresult"> <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...): <soap:envelope xmlns:soap=" <soap:body> <findftuapplicationbyidresponse xmlns:ns6=" xmlns:ns5=" xmlns:ns4=" xmlns:ns3=" xmlns:ns2=" xmlns=" <ftueducationplanresponse> <FtuInSchoolEducationPlan> <ApplicationType>FULLY_DIGITAL</ApplicationType> <ModifiedDate> T17:09: :00</ModifiedDate> <SchoolYear>2015/2016</SchoolYear> <WishList> <WishListCount>1</WishListCount> <EducationWish> <WishOtherActivities> <PriorityNumber>1</PriorityNumber> <OtherActivity> <OtherActivity>Ungdomshøjskole eller højskole</otheractivity> <FromDate> T00:00: :00</FromDate> <ToDate> T00:00: :00</ToDate> <Description>Krabbesholm Højskole (779300)</Description> </OtherActivity> <Remarks>Ingen bemærkninger</remarks> <CommentList/>

9 </WishOtherActivities> <ExtraEducationPlanFields/> </EducationWish> </WishList> <FtuApplicantGuardian> <CivilRegistrationNumber> </CivilRegistrationNumber> <ns3:persongivenname>jane</ns3:persongivenname> <ns3:personsurnamename>test</ns3:personsurnamename> <Address> <ns2:streetaddress>testvej 3</ns2:StreetAddress> <ns2:postalcode>2830</ns2:postalcode> <ns2:postaldistrict>testby</ns2:postaldistrict> <ns2:countrycode>dk</ns2:countrycode> <ns2:country>danmark</ns2:country> </Address> <PhoneNumber> </PhoneNumber> </FtuApplicantGuardian> <FtuApplicantGuardian> <CivilRegistrationNumber> </CivilRegistrationNumber> <ns3:persongivenname>john</ns3:persongivenname> <ns3:personsurnamename>test</ns3:personsurnamename> <Address> <ns2:streetaddress>testvej 3</ns2:StreetAddress> <ns2:postalcode>2830</ns2:postalcode> <ns2:postaldistrict>testby</ns2:postaldistrict> <ns2:countrycode>dk</ns2:countrycode> <ns2:country>danmark</ns2:country> </Address> <PhoneNumber> </PhoneNumber> </FtuApplicantGuardian> <UUCenter> <ns2:institutionnumber>209201</ns2:institutionnumber> <ns2:institutionname>uu Vest Region Hovedsten</ns2:InstitutionName> <ns2:principal>test person</ns2:principal> <ns2:address>testvej 4B</ns2:Address> <ns2:cityname>testby2</ns2:cityname> <ns2:postalcode>3600</ns2:postalcode> <ns2:postaldistrict>region Hovedstaden</ns2:PostalDistrict> <ns2:phonenumber> </ns2:phonenumber> </UUCenter> <InSchoolApplicant> <CivilRegistrationNumber>1111vvvv111</CivilRegistrationNumber> <ns3:persongivenname>test</ns3:persongivenname> <ns3:personsurnamename>person</ns3:personsurnamename> <Address> <ns2:streetaddress>testvej 3</ns2:StreetAddress> <ns2:postalcode>2830</ns2:postalcode> <ns2:postaldistrict>testby</ns2:postaldistrict> Side 9 af 13

10 <ns2:countrycode>dk</ns2:countrycode> <ns2:country>danmark</ns2:country> <ns2:municipalitycode>0250</ns2:municipalitycode> <ns2:municipalityname>testby</ns2:municipalityname> </Address> <PhoneNumber> </PhoneNumber> </InSchoolApplicant> <OtherCompetenceComments> <FtuComment> <required>true</required> <CreatedDate> T17:06: :00</CreatedDate> <Name>Test test</name> <UserRole>Skolemedarbejder</UserRole> <Comment>gkgjkagoaogihak</Comment> </FtuComment> </OtherCompetenceComments> <NameOfClass> <ClassName>9A</ClassName> <ClassLevel>9</ClassLevel> </NameOfClass> <EducationReadinessAssessmentList> <UpperSecondaryEducationReadinessAssessment> <Assesment>Not assessed</assesment> <UuEmployeeAssesment>Not assessed</uuemployeeassesment> <PersonalSupport>false</PersonalSupport> <EducationReadinessAssessor> <AssessorAssessment>Not assessed</assessorassessment> </EducationReadinessAssessor> <EducationReadinessAssessmentCommentList/> </UpperSecondaryEducationReadinessAssessment> <VocationalEducationReadinessAssessment> <Assesment>Not assessed</assesment> <UuEmployeeAssesment>Not assessed</uuemployeeassesment> <PersonalSupport>false</PersonalSupport> <EducationReadinessAssessor> <AssessorAssessment>Not assessed</assessorassessment> </EducationReadinessAssessor> <EducationReadinessAssessmentCommentList/> </VocationalEducationReadinessAssessment> </EducationReadinessAssessmentList> <PresentSchool> <ns2:institutionnumber>101151</ns2:institutionnumber> <ns2:institutionname>kildevældsskolen</ns2:institutionname> <ns2:address>bellmansgade 5a</ns2:Address> <ns2:cityname>københavn Ø</ns2:CityName> <ns2:postalcode>2100</ns2:postalcode> <ns2:phonenumber> </ns2:phonenumber> </PresentSchool> <State>Afhentet</State> Side 10 af 13

11 Side 11 af 13 <FtuBackground/> <FtuMarks> <EighthGradeProficiencyMarkSet/> <NinthGradeProficiencyMarkSet/> <NinthGradeExamMarkSet/> <TenthGradeProficiencyMarkSet/> </FtuMarks> <InSchoolSignatureList> <GuardianOneSignature> <SignatureDate> T17:07: :00</SignatureDate> <SignatureName>TESTLOGIN-ENABLED</SignatureName> </GuardianOneSignature> <GuardianTwoSignature> <SignatureDate> T17:07: :00</SignatureDate> <SignatureName>TESTLOGIN-ENABLED</SignatureName> </GuardianTwoSignature> <CounsellorSignature> <SignatureDate> T17:09: :00</SignatureDate> <SignatureName>TESTLOGIN-ENABLED</SignatureName> </CounsellorSignature> </InSchoolSignatureList> </FtuInSchoolEducationPlan> </ftueducationplanresponse> </findftuapplicationbyidresponse> </soap:body> </soap:envelope> Eksempel på søgning ved hjælp af 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> Resultat: Et svar, som enten er en fejlmarkering eller en 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...):

12 Side 12 af 13 <soap:envelope xmlns:soap=" <soap:body> <ns1:findftuapplicationbyidresponse xmlns:ns1=" <return xmlns=" <ftuapplicantpdf>jvbe...</ftuapplicantpdf> </return> </ns1:findftuapplicationbyidresponse> </soap:body> </soap:envelope> Eksempel på udsnit af en XML FTU-uddannelsesplan 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 findftuapplicationenclosurezipurlbyid(...) <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: <soap:envelope xmlns:soap=" <soap:body> <findftuapplicationenclosurezipurlbyidresponse xmlns=" <return> <fileurl> service/services/fileservice/file?token=cbb19969-a5e ca9-8fa7d28895ac</fileurl> </return>

13 Side 13 af 13 </findftuapplicationenclosurezipurlbyidresponse> </soap:body> </soap:envelope> 5 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> Parametre: Code NO_DATA INVALID_INPUT ILLEGAL_ACCESS INSTITUTION_NOT_FOUND SYSTEM_ERR Beskrivelse Hvis søgningen intet finder. Hvis inputdata ikke er gyldige. Hvis autentifikation eller autorisation 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 institutionsnummer i Optagelse.dk Fejl i servicen.