Webserviceintegration

I dette afsnit er det muligt at finde generel information om datastrømmen og hvordan data synkroniseres mellem kundens eget system og Digital Eksamen. Der kan findes information om hvad der synkroniseres og hvordan og generelle oplysninger om formatet.

For en detaljeret beskrivelse af hele datastrømmen se den gældende XSD. XSD er beskrevet her: XSD. I tilfælde af uoverensstemmelser mellem denne artikel og XSD vil XSD altid have forrang.

Indhold på denne side

  1. Overordnet indhold som synkroniseres
  2. Generelt om dataformaterne
  3. Synkroniseringsstrategier
  4. Komponenter
  5. Metoder
  6. Fejlhåndtering
  7. WSDL og webservice til pull
  8. SyncService

Overordnet indhold som synkroniseres

Brugere

  • Ansatte
  • Studerende
  • Eksterne Censorer
  • Tilsyn

Organisation

Administrative enheder i hierarkisk struktur

Det er praktisk at kunne opdele de forskellige eksaminer efter organisatorisk enhed. Her vil man typisk ønske, dels at kunne opdele på samme måde som i STADS, dels at kunne samle disse enheder i lidt større klumper, så sekretærerne kan få rettighed til at administrere en enhed af gangen. (F.eks for et helt fakultet, som består af flere administrative enheder).

Prøver

Fordelt på prøvetyperne:

  • Prøve uden tilsyn
  • Stedprøve
  • Prøve uden aflevering
  • ITX-prøver
  • Afsluttende prøver

Herunder: Data til prøver (Link til data til prøver) Tilmeldinger til prøver (link til tilmeldinger)

Relationer mellem datatyper

Diagrammer over relationerne mellem datatyperne kan bruges til at hjælpe med at finde ud af rækkefølgen, data skal synkroniseres i.

Diagram: Prøve, Studerende og Tilsyn
Diagram: Ansatte

Diagram: Censorer

Generelt om dataformaterne

Vores navngivningsstandard er, at alle navne på data, der synkroniseres, er på dansk. Dog benyttes eksisterende navne fra eksterne systemer i stedet for at oversætte dem, f.eks. får feltet EK_GRP_KODE fra STADS lov at stå som det er, med underscores, casing osv., for ikke at skulle finde på en oversættelse. Alle andre navne holdes på engelsk, dvs. f.eks. ArrayOfAnsat og metodenavne GetAnsatte osv.

Felter som både kan vedligeholdes via datastrøm og webinterface, oprettes som to felter. Disse er suffixet med enten ”Integration” eller ”DE” (for ”Digital eksamen” – altså systemet selv). Begge felter kan hentes ud via webservices, men kun ”Integration”-feltet kan opdateres denne vej. Tilsvarende kan begge felter i princippet vises i webinterfacet, men kun ”DE”-feltet kan redigeres denne vej.

Dataudvekslingsformater kan også findes i XSDén, hvor der er indlejret datatyper og kommentarer.

Synkroniseringsstrategier

Der er to strategier, som kunden kan vælge at bruge:

  • Push, hvor kunden selv kalder en webservice hos Arcanic, når sker ændringer.
  • Pull, hvor kunden stiller en webservice til rådighed, og så har Arcanic et job, som henter ændringerne og synkroniserer med data hos Arcanic.

Til formålet har Arcanic lavet nogle komponenter:

  • En webservice til push med tilhørende WSDL. Den udstiller data fra DigitalEksamen og muliggør ændring af dataene. Vi kalder den PushService.
  • En WSDL, som definerer, hvordan en webservice til pull skal se ud.
  • Et eksempel på en webservice, som implementerer WSDL’en til pull. Vi kalder den PullService.
  • Et job, som givet en URL, hvorpå der er implementeret en webservice som beskrevet af webservicen til pull, automatisk kan synkronisere data mellem kunden og DigitalEksamen.

Pushsynkronisering

Med pushsynkronisering laver kunden selv noget kode, som kan hente data fra sin datakilde og synkronisere, ”pushe”, data til DigitalEksamen.

Pullsynkronisering

En for kunden nem måde at få synkronisering til at fungere, opsætter kunden PullService.svc, laver et datatræk fra STADS og lægger disse data i nogle XML-filer. URL’en, som webservicen er sat op på gives til Arcanic og Arcanic opsætter SyncService til at synkronisere dataene. Det kræver ingen ændring af koden i PullService.

Alternativt kan koden i PullService ændres, så den trækker data direkte fra STADS.

Hvis kunden vælger selv at implementere en webservice, som overholder WSDL’en til pull, så skal Arcanic, som ovenfor, blot have URL’en at vide.

Komponenter

Webservices laves i SOAP. Versionen af SOAP kan ses i WSDL’en for de to webservices. De to webservices understøtter kun UTF-8. Sikkerheden består af SSL og username/password, der sendes med som argumenter på de enkelte metoder. Der adskilles mellem kunder og miljøer ved at hver webservice lægges på én URL per kunde per miljø.

Webservice til push

Webservicen til push ligger på en separat URL per kunde, per miljø. På adressen kan man desuden finde WSDL’en.

URL’en, brugernavn og kodeord udleveres af Arcanic.

PushService indeholder metoder til insert, update og query for de forskellige datatyper. Det gør det muligt at lave kode, som kun synkroniserer ændringer. For enkelte datatyper findes også metoder til at slette elementer. Der er datatyper, som ikke kan slettes i systemet, f.eks. kan man ikke slette brugere, da det vil skabe kaos i resten af systemet, hvis brugeren f.eks. allerede har besvaret eller rettet en opgave. Men man kan godt slette en relation mellem en censor og en censorliste. Desuden er datatyperne Resultat og Fejlkode lidt specielle og beskrives længere nede i denne artikel.

Som udgangspunkt kan man opdatere alle slags datatyper fra XSDén, gennem PushService, men der er undtagelser: ProeveFriGruppe_Censor og ProeveFriGruppe_Eksaminator oprettes gennem brugergrænsefladen i DigitalEksamen og kan hentes ud gennem PushService, men kan ikke opdateres den vej.

Webservicen omregner selv datoer til CET og disse gemmes internt i DigitalEksamen. Dog er YYYY-MM-DDT24:00:00Z en del af datostandarden for XSD, men det tidspunkt understøtter vi ikke og man må i stedet benytte YYYY-MM-DDT00:00:00Z, hvis man støder ind i det problem. Datoer/tidspunkter, som returneres af webservicen, er altid i CET.

Metoder

Get

Metoder, som bare hedder GetX, tager ingen parametre, ud over logininfo, og henter alle elementer af typen X ud. De fleste Get-metoder har en ekstra parameter, som gør, at man kan filtrere på noget af dataene. De hedder sådan noget som:

  • GetAnsatByBrugerId – henter den Ansat ud, som har det angivne brugernavn
  • GetAnsatListeByListeId – henter den AnsatListe ud, som har et bestemt ListeId
  • GetAnsatListeByIntern – henter de AnsatLister ud, som har en bestemt værdi i feltet Intern

De er meget selvforklarende, så de vil ikke blive gennemgået i detaljer. Det noteres, at der ikke gøres forskel på store og små bogstaver ved tekstsammenligning. For visse datatyper findes der en metode ved navn – GetXByBrugernavnStarterMed Det kan bruges til at trække mindre grupper af brugere ud ad gangen, f.eks. først dem, der starter med a, derefter dem med b osv.

Insert

Der kan indsættes flere elementer ad gangen, når man bruger Insert.

Update

Der findes felter på datatyperne, som ikke er obligatoriske. Når man foretager en update af data, som allerede findes i DigitalEksamen, fungerer det sådan, at alle felter overskrives i DigitalEksamen. Selvom ikke-obligatoriske felter indeholder en null-værdi, så opdateres felter til null i DigitalEksamen, uanset om feltet i DigitalEksamen har en værdi i forvejen. Dette gør sig gældene for alle datatyper i datastrømmen.

Fejlhåndtering

I Insert og Update-metoderne kan man oprette eller opdatere mange elementer ad gangen. PushService gemmer elementerne enkeltvis og altså ikke som én stor transaktion. Dvs., at selvom et enkelt af elementerne ikke kan gemmes, så forhindrer det ikke resten i at blive gemt.

Når man kalder Insert eller Update, så returneres et array af elementer af typen Resultat. Der returneres et Resultat per element, man prøvede at oprette eller opdatere. Hvert Resultat har et id, som passer sammen med id’et på det element, man prøvede at oprette eller opdatere. Desuden indeholder Resultat et ResultatKode-felt, som fortæller, om det gik godt eller ej, og i så fald, hvad der gik galt. Det kan f.eks. være, at der var konflikt med en unik nøgle, at man prøvede at indsætte data, som peger på noget andet, der ikke findes, at man prøvede at opdatere et element, som ikke findes, el.lign. Den kan altså fortælle om fejl i dataene, men ikke om fejl i selve servicen, som f.eks. at databasen er nede. Hvis den slags sker, får man i stedet enten et svar tilbage, som slet ikke er SOAP, eller man får et SOAP-svar med et Fault-element som beskrevet af W3C

For at få den gældende liste af mulige ResultatKoder og en beskrivelse af, hvad hver af dem betyder, kaldes PushServicens metode GetFejlkoder.

WSDL og webservice til pull

Kunden vælger selv, hvor webservicen til pull skal lægges. Koden vedligeholdes og driftes af kunden selv. Eksempel på en webservice til pull udleveres af Arcanic. Ved at køre webservicen, kan man se WSDL’en. Som udgangspunkt kan man hente alle slags datatyper fra XSDén gennem PullService,Desuden er datatyperne Resultat og Fejlkode lidt specielle og bruges kun af PushService.

SyncService

Synkroniseringen kan køre om natten og/eller en gang i timen. Det er muligt for hver kunde at definere hvornår de ønsker data trukket og hvilken data. Nye værdier tilføjes, ændrede overskrives. Værdier som er forsvundet i datastrømmen får lov at blive stående, undtagen for de datatyper, hvor PushService understøtter sletning