Import och export av schemadata via API

På Royal Schedule använder vi oss av ett olika lärplattformar för att läsa in er grunddata. Varje plattform fungerar på liknande sätt, men skiljer sig åt när det kommer till vilken data som hämtas in från respektive. Nedan förklaras vad som gäller för varje enskild plattform.

Import och export av data

API Import av data

För att läsa in data till Royal Schedule via API har vi för närvarande stöd för följande plattformar:

• Admentum
• SchoolSoft
• IST
• Edlevo
• Progress (Edukatus)
• GotIt (Alvis)
• Unikum
• Quiculum

Pågående integrationer:

• Plan Digital

API Export av data

Förutom ovan stöder vi också att exportera schemat till:

• Vklass

Detaljerad information - API-plattformar

Nedan kan du se vilken data som går att läsa in och uppdatera från respektive plattform. Tanken är att när data ändras i något utav dessa system kan Royal Schedule läsa in uppdaterad data på ert schema automatiskt, detta för att undvika dubbelarbete och att systemen är i synk med varandra. För att läsa mer hur du synkroniserar din data manuellt eller automatiskt läs denna artikel - LÄNK

Detaljerad information per plattform

För att läsa in data från en plattform måste en admin först ha lagt in era egna API uppgifter för skolan, detta görs ofta innan införandet men är bra att känna till. 

Beroende på vilken plattform ni har kan det fungera något olika. Nedan går vi igenom varje plattform för sig och dess begränsningar när det kommer till synkronisering av data. 

När du skapar ett nytt schema i Royal Schedule har du ett startdatum och slutdatum på ditt schema. När Royal Schedule importerar data från en annan plattform skickas datum som schemat är giltigt med i förfrågan dvs start- och slutdatum på schemat avgör vilken data som returneras. Det innebär att om du förbereder på våren schemat inför nästa läsår måste du i plattformen som data hämtas från ha öppnat upp kommande läsår och tillgängliggjort data för att hämta över. Ofta finns funktioner att "hoppa" mellan olika läsår i och således förbereda data för kommande läsår.

SchoolSoft

Royal Schedule (och AI Schema) importerar data från SchoolSoft lärplattform. Följande data måste komma från SchoolSoft behöver och kan inte skapas upp i Royal Schedule och sedan läsas över till SchoolSoft.

• Lärare
• Elever

Gällande undervisningsgrupper och klasser är det bästa att skapa upp dessa i SchoolSoft och läsa över till Royal Schedule. 

Import av data till Royal Schedule (synkronisera)

1. Det finns två sätt att importera ny data från SchoolSoft det ena är att gå till till startsidan för scheman klicka på ikonen med tre prickar och sedan synkronisera. Då skriver SchoolSoft över den data som finns i Royal Schedule. Ny data läggs till samt att klasser och undervisningsgrupper kommer att uppdateras med elever så som det ser ut i SchoolSoft. Det görs en inläsning med det som ändrats från den senaste inläsningen av data (synkroniseringen). 

Ibland behövs en "full inläsning". Toggla högra hörnet och sedan under rubriken "Enbart ändrad efter" välj "Alla" och sedan synkronisera. Om du är mitt i läsåret behöver då då även ändra datum till dagens datum som startdatum på rubriken under "Välj Period".

2. Det andra alternativet är att automatiskt Automatisk synkronisering då läses ny data in automatiskt varje natt. Det är det rekommenderade alternativet. Håll musen över integrationer och välj sedan 'Automatisk Synk', därefter väljer du schema som ska uppdateras, du kan välja flera scheman. Dina scheman kommer nu uppdateras automatiskt. Om det är valt som "inaktiv" kontakta din administratör eller support för att aktivera funktionen på din skola.

Du kan även skapa undervisningsgrupper och klasser direkt i Royal Schedule samt ändra medlemmarna dvs eleverna i dessa men innan du gör det bör du ha förståelse för hur det påverkar synkroniseringen. I korta drag så skriver SchoolSoft över det som görs i Royal Schedule gällande hantering av undervisningsgrupper, klasser och dess medlemmar. Royal Schedule har även möjlighet att skriva över grupper och klasser i SchoolSoft (läs mer under rubrik "Exportera schemat" nedan).

Förbereda klasser och undervisningsgrupper i förväg i SchoolSoft

Det går att förbereda nästa läsår dvs det går redan i innevarande läsår flytta upp elever till nästa års klasser och undervisningsgrupp. Läs mer här för att se hur du går tillväga i SchoolSoft - SchoolSoft-Läsårsuppflyttning-Grupper-(2025-02-07).pdf eller ta kontakt med SchoolSoft support.

Exportera schemat

För att exportera schemat går du ut till vyn där du ser 'alla scheman' och sedan går till integrationer och 'API-Export', se bild nedan. Klicka sedan på 'Välj Schema' för att välja det schema som du vill att SchoolSoft ska kunna läsa in. Notera att i denna vy ska du endast ha ett schema valt. När du väl har läst över ett schema så behöver du fortsätta arbeta i det schemat och läsa över samma schema. Om du byter till ett annat schema skapas dubbla lektioner upp i SchoolSoft. Om du behöver schema under terminen läs nedan 'Byta schema under läsåret'.

Schemat exporteras inte automatiskt till SchoolSoft. För att exportera ditt schema från Royal Schedule -> SchoolSoft behöver du förutom att göra stegen ovan även gå in i SchoolSoft gå till Admin → Underhåll → AI Schema och importera ditt schema till SchoolSoft.

Där finns två alternativ:

Alternativ 1 (standard): ”Lägg endast till nya elever i grupperna”
Detta är det förvalda alternativet. Royal Schedule lägger då endast till nya elever i dina klasser och undervisningsgrupper. Befintliga grupper och elevkopplingar i SchoolSoft ändras inte. Använd detta alternativ om SchoolSoft är ditt källsystem och den primära sanningen.

Alternativ 2: ”Ersätt befintliga elever med elever från AI Schema-importen”
Här skriver Royal Schedule över den information som finns i SchoolSoft. Elevkopplingar i klasser och undervisningsgrupper ersätts med de som finns i Royal Schedule. Använd detta alternativ med försiktighet och endast om Royal Schedule är din primära sanning.

Validering av schemat i RS

RS validerar det schema du har valt som aktivt för att upplysa dig som schemaläggare eller administratör om eventuella fel innan SchoolSoft läser in schemat. Syftet är att du snabbt ska kunna identifiera och rätta till problem tidigt i processen. Felkoder visas även i SchoolSoft för objekt som inte kan läsas in (detta är dock inte relaterat till denna validering).

Hur fungerar det?
Det schema som du har valt som aktivt i API Export valideras automatiskt. Om något flaggas upp visas en röd ruta, som på bilden nedan. Systemet visar vilka delar av schemat som kan innehålla problem på rubriknivå. Klicka på rubriken för att läsa mer, och därefter på den underrubriken för att komma direkt in i schemat med en filtrering för det valda objektet tex en kurs, så att du enkelt kan åtgärda problemet.

Följande fall valideras

Tolka error i SchoolSoft

I SchoolSoft går du in på Admin - Underhåll - AI Schema och välj sedan den senaste under "Genomförda importer". Då får du fram "Importstatus" med tre olika fält. Det översta är import av grupper och klasser. Den andra är import av salar. Den tredje är import av lektioner. Kolla på "Error" på samtliga för att se vad som inte kunnat läsas över i SchoolSoft. Se nedan vart du hittar error i SchoolSoft. 

Ett error från SchoolSoft ser ofta ut såhär:

Ogiltig subject. subjectid/subject måste anges.
{
 "externalid": "Anf5Q0Oz.SSuQTIUB",
 "subject": "SL",
 "day": "onsdag",
 "starttime": "14:25:00",
 "endtime": "15:40:00",
 "teacherid": "null",
 "groupexternalid": "Anf5Q0Oz.qTLbpF9iG",
 "roomguid": "",
 "groupguid": ""
}

name måste anges.

{
 "studentid": "",
 "name": "",
 "classtype": "0",
 "externalid": "dbaa05d4-9dfa-4915-86d2-8ea9d4bc5af8",
 "guid": "dbaa05d4-9dfa-4915-86d2-8ea9d4bc5af8"
}

Rubriken talar om vart man ska leta efter felet. Rubriken i fallet ovan nämner 'Subject' dvs Ämne. Sedan syns det vilken lektion den gäller i detta fall är Ämnet 'SL' och det är en lektion som är på onsdag 14:25 - 15:40. I det andra exemplet så finns det ett så kallat 'guid' ett ID, error talar om vilket ID som inte kan läsas in, detta ID kan vara en lektion, en person, en grupp eller sal det beror på vilken av error som du kollar på som sagt finns det tre filer en för grupper, en för rum och en för lektioner. Se denna film för att se hur du kan hitta 'guid' för att se vilken person/sal eller lektion som ej kan läsas in.

Vanliga misstag /error

• Ogiltig subject. subjectid/subject måste anges.

Ett vanligt problem som kan uppstå är att man upptäcker fel på ett specifikt ämne i schemaunderlaget. Detta beror oftast på att ämnet inte finns registrerat i Schoolsoft eller att de inte matchar exakt med det som står i AI Schema. För att undvika detta behöver det ämnesnamn som anges i Royal Schedule, under Schemaunderlag → Kurser → Ämnen, också finnas i Schoolsoft. Namnet ska där motsvara det som i Schoolsoft kallas kortnamn. 

Lösningen på detta problem är att göra ett av följande:

• Gå in i Schoolsoft och skapa det saknade ämnet, eller kontrollera stavning.
• Att i Royal Schedule ändra ämnesnamnet till ett som redan finns i Schoolsoft, så att namnen överensstämmer.

När det är åtgärdat läser du in schemat på nytt till SchoolSoft.

Andra vanliga error och rubriker är:

• Ogiltig teacherid: null.

Beror på att lärare har skapats upp i Royal Schedule och kan då inte lösas över till SchoolSoft. Åtgärda genom att lägga till lärare i SchoolSoft med personnummer och sedan läs över från SchoolSoft -> Royal Schedule för att få in personalen. Då uppstår dubbletter på lärare i Royal Schedule, du kan nu kontakta support för att hjälpa dig ta bort dubletterna. 

• Ogiltig groupexternalid: Anf5Q0Oz.ZrlMVBi5G.

Beror på dubbletter av klasser eller undervisningsgrupper. Troligtvis har klasser eller undervisningsgrupper skapats upp i Royal Schedule för att också ha skaptas upp i SchoolSoft. Sedan har grupperna lästs in till Royal Schedule och då skapas dubletter. För att undvika följ regeln att alltid skapa undervisningsgrupper i SchoolSoft och läs över till Royal Schedule. 

• Starttid måste anges i timmar och minuter (hh:mm) mellan 8:00 och 16:59.

I SchoolSoft är standarden för när lektioner kan ligga mellan 08:00 - 16:59 om inget annat ställts in och varningen innebär att du har lektioner som ligger utanför denna tidsram. Åtgärda genom att i SchoolSoft ändra inställningar för när start och sluttid är tillåtet, om du inte vet vart, kontakta SchoolSofts support. 

Fel beror oftast på något av följande: 

• Ämne matchar inte med vad som finns som kortnamn i SchoolSoft
• Lärare är skapad i Royal Schedule. Ta då bort läraren och läs in från ditt källsystem.
• Elev är skapad i Royal Schedule. Ta då bort eleven och läs in från ditt källsystem.
• Grupper/klasser är skapade både i Royal Schedule och i SchoolSoft vilket skapar error och konflikt. Skriv till Royal Schedule support.
• Elevundantag är inte gjorda korrekt. Elevundantag görs enklast genom att ni skapar up en specifik undervisningsgrupp som ni använder i er schemaläggning för elevundantaget för den sammansättningen elever. SchoolSoft kräver alltid att en lektion är kopplad till en undervisningsgrupp eller klass. 

Byta schema under läsåret

Om du under läsåret behöver byta schema behöver du först "avsluta" ditt tidigare schema. Då behöver du göra följande steg (i denna ordning)

• Ändra datum på schemat som du har lagt i vyn API-Export så att schemat slutar på en fredag och det nya schemat börjar på en måndag. För att ändra datum på ditt schema klickar du på de tre prickarna bredvid schemat och sedan på 'Inställningar' där byter du datum.
• Gå in i SchoolSoft och läs in schemat med nytt datum då kommer lektionerna avslutas den fredagen som du har valt. 
• Gå in i Royal Schedule och vyn API-Export och ta bort schemat. Välj sedan ditt nya schema som startar efterföljande måndag så att du endast har ditt nya schema valt.
• Gå in i SchoolSoft och läs in ditt nya schema och då kommer lektionerna att skapas upp enligt ditt nya schema. Om du behöver byta schema igen upprepar du processen. Historik så som uppgifter och närvaro finns kvar på dina gamla lektioner i SchoolSoft. 

 Progress

För att integrationen med Progress ska fungera korrekt behöver följande punkter följas:

• Kurser, lärare, elever och grupper ska alltid skapas i Progress och därefter importeras till Royal Schedule. Dessa får inte skapas direkt i Royal Schedule.
• Kopplingen mellan lärare och kurs görs i Progress och styr vilka lärare som kan kopplas till kurser i Royal Schedule. Det går inte att i Royal Schedule (under Schemaunderlag – Kurser) ändra eller lägga till lärare och sedan få ändringarna att synas i Progress.
• Raster och luncher som skapas under Schemaunderlag – Grupper överförs inte till Progress. Om dessa ska överföras måste de istället skapas som kurser (kurserna ska då komma från Progress).
• Sal-information överförs som text. Om flera salar anges kommer de att visas som en sammanhängande textsträng. För schemaläggning med flera salar rekommenderas korta salnamn.
• En händelse, det vill säga en enskild lektion som bara gäller vid ett tillfälle (till exempel ett prov) och som skapas under Schema, måste alltid kopplas till en kurs. Lektioner utan kurs kan inte överföras till Progress.
• Progress läser in schemat från Royal Schedule varje timme mellan 08.00 och 23.00.

Vklass

För att exportera data till Vklass behöver följande punkter följas:

• Kurser, lärare, elever och grupper ska alltid skapas i källsystemet och därefter exporteras till Vklass. Dessa får inte skapas direkt i Royal Schedule.
• Kopplingen mellan lärare och kurs görs i källsystemet (eller Vklass) och styr vilka lärare som kan kopplas till kurser i Royal Schedule. Det går inte att i Royal Schedule (under Schemaunderlag – Kurser) ändra eller lägga till lärare och sedan få ändringarna att synas i Vklass.
• Schemaläggning måste ske på undervisningsgrupper (klasser får ej användas för schemaläggningen). Varje undervisningsgrupp får endast användas på en kursrad dvs en undervisningsgrupp kan inte återanvändas till flera kurser/ämnen.
• Lektioner som skapas och inte har en koppling mellan lärare och kurs i Vklass kommer ej läsas in, tex lunch, raster, planeringsmöten etc
• Vklass läser in schemat automatiskt från Royal Schedule varje natt. Det går även att "trigga" en manuell import av schemat till Vklass direkt i deras gränssnitt. Ta kontakt med Vklass för mer information. 

Filimport till Royal Schedule: