Nyckeltalsintegration

Artikeln beskriver integrationsprodukten Nyckeltalsintegration.

Innehåll

Lösningsbeskrivning

• Vad är nyckeltalsintegration?
• Från vilka system kan man integrera nyckeltalsdata till Stratsys?
• Tekniker

Förutsättningar

• Förutsättningar för nyckeltalsintegration
• Utseende på importfil
  • Radvis inläsning
  • Kolumnvis inläsning

Uppsättningsguide

• Inför uppstart
• Införande steg-för-steg

Förvaltning och underhåll

• Mejlnotifiering vid fel och varningar

• Manuell inläsning av fil
• Lägga till och ändra externkoder för enheter, nyckeltal och måttdatakolumner

Felsökning

Schema för filinläsningar

Lösningsbeskrivning

Vad är nyckeltalsintegration?

 

Från vilka system kan man integrera nyckeltalsdata till Stratsys?

Till Stratsys har vi möjlighet att läsa in nyckeltalsdata från alla system som kan leverera data i något av formaten som beskrivs här eller via Stratsys API som beskrivs här. Vi har befintlig nyckeltalsintegration från bland annat QlikView, Qlik Sense, Cognos, Heroma, Power BI, Mercur, Skola24, Vitec och DF Respons.

Tekniker

Stratsys erbjuder två olika tekniker för integration av nyckeltalsdata.

Filinläsning är det ena alternativet vilket innebär att ni lägger filer i en SFTP-katalog som sedan läses in till Stratsys. Inläsningen till Stratsys sker enligt följande schema, då körs ett schemalagt jobb på en server hos Stratsys som läser igenom dessa filer och uppdaterar nyckeltalen i Stratsys i enlighet med informationen i filen.

Adaptern installeras en gång i Stratsys genom ett införandeprojekt tillsammans med en projektledare och Integrationskonsult på Stratsys. Efter projektet lämnar vi de förutsättningar som krävs för att ni ska ha möjlighet att läsa in data till fler nyckeltal.

Det andra alternativet som erbjuds är nyckeltalsintegration via Stratsys API. Detta kräver att kund har programmeringskunskaper och kan utveckla mot REST-API. Ni får då tillgång till Stratsys API för nyckeltalsinläsning. Här kan du läsa mer om inläsning via API.

Förutsättningar

• Organisationsträdet i Stratsys behöver kunna mappas mot organisationen i systemet där data ska hämtas från. Mappningen görs med hjälp av externkoder i Stratsys. Generellt gäller 1 till 1-mappning mellan extern kod och entitet. Koden identifierar en entitet i Stratsys.
• Nyckeltalen behöver skapas upp i Stratsys, vi rekommenderar att ni samlar era nyckeltal i en nyckeltalsbank som ni sedan distribuerar nyckeltalen från till där de ska visualiseras. Detta för att underlätta administrationen av nyckeltalen. 
• Extern kod behöver kunna definieras för nyckeltalen, detta för att skapa ett gemensamt språk mellan Stratsys och det externa systemet. Finns det ingen befintlig kod på nyckeltalen hjälper Stratsys integrationskonsulter er att skapa koder.
• Kunden behöver leverera färdig-aggregerat data efter organisationsenheterna i Stratsys, nyckeltalen samt efter önskad periodicitet. Stratsys kan ej hantera datakonvertering.
• Kunden behöver leverera data i något av Stratsys filformat alternativt REST-API-anrop i enlighet med formatet som finns definierat här. 

Utseende på importfil 

Kolumnerna ska vara tabbseparerade och ska innehålla följande information: 

• Datum (styr vilken i vilken period värdet sparas)
• Extern kod för enhet 
• Extern kod för mått 
• Extern kod för måttdatakolumn 
• Själva värdet 

För att importen ska fungera måste punkt användas som decimaltecken (inte kommatecken). Dessutom får inga tusentalsavgränsare finnas. Värdet ”25 610,34” kommer alltså inte att läsas in korrekt, utan måste ändras till ”25610.34”. Negativa värden går bra. Datum ska vara på svenskt format yyyy-mm-dd t.ex. ”2020-12-24”. Decimaltecken, procenttecken och tusentalsavgränsare kan läggas till direkt i Stratsys, detta kan ni ta hjälp av er konsult för vid implementation. Filinläsningen är inte Case sensitive, det vill säga att om ni har en stor bokstav på en plats där externkoden är liten så fungerar ändå inläsningen.

Det finns två typer av utseende: 

• Radvis inläsning = En rad för varje värde som ska importeras 
• Kolumnvis inläsning = Varje rad representerar alla de måttdatakolumner som ska uppdateras för måttet.  

För båda typer av inläsning (både radvis, samt kolumnvis) krävs det att det finns ett värde i alla värdefält, inga NULL-poster tillåts. 

Radvis inläsning 

Filen ska namnges: ”kpidata_yyyy-mm-dd.txt” eller ”kpidata_yyyy-mm-dd_header.txt”. 

Om alternativet innehållande ”header” används kommer första raden i filen tolkas som en rubrikrad och ignoreras vid inläsningen. 

För att kunna hitta rätt mått och uppdatera rätt värde behöver Stratsys veta följande: 

• Datum (svenskt format yyyy-mm-dd) 
• Extern kod för enhet 
• Extern kod för mått 
• Extern kod för måttdatakolumn 
• Värde - decimalavdelare är punkt (.) 

Exempeldata radvis inläsning 

Kolumnvis inläsning 

Filen ska namnges: ” kpicolumndata_yyyy-mm-dd.txt” eller ” kpicolumndataheader_yyyy-mm-dd.txt”. 

Om alternativet innehållande ”header” används kommer första raden i filen tolkas som en rubrikrad som talar om vilka måttdatakolumner filen avser. Antalet måttdatakolumner begränsas av header-radens måttdatakolumnnamn eller externa kod. 

Om filen inte innehåller header-rad kommer måttdatakolumnerna att läsas in i den ordning de finns upplagda på måttet i Stratsys. 

För att kunna hitta rätt mått och uppdatera rätt värde behöver Stratsys veta följande: 

• Datum (svenskt format yyyy-mm-dd)  
• Extern kod för enhet 
• Extern kod för mått 
• Värde - decimalavdelare är punkt (.)  
• Värde - decimalavdelare är punkt (.) 

• … 

Exempeldata kolumnvis inläsning 

Uppsättningsguide

Inför uppstart

Reflektera och svara på dessa frågor inför uppstartsmötet. Behöver ni stöttning eller vägledning kontakta er projektledare eller kundansvarig så hjälps vi åt. 

• Vilka nyckeltal vill ni läsa in data till i Stratsys?
• Till vilka måttdatakolumner vill ni läsa in data?
  • Exempel på kolumner är: ackumulerat utfall, budget, prognos, utfall kvinnor/män.
• Till vilka organisationsenheter vill ni läsa in data inom projektet?
• Vart finns data i det externa systemet?
• Behöver aggregering/andra justeringar av data göras för att kunna läsas i Stratsys?
  • Exempelvis aggregering efter enheterna i ert organisationsträd i Stratsys, anpassningar av data som tex. summeringar av kostnadsställen eller liknande.
• Vilken teknik vill ni använda er av? Filinläsning ( och i så fall, vilket filformat föredrar ni?) eller API?
• Har ni rätt resurser allokerade till projektet? De resurser som behövs är:
  • Person med verksamhetens perspektiv, som kan agera kravställare och kvalitetssäkrare i projektet
  • Person med kunskap i hur data kan plockas ut ur det externa systemet som ska integreras med Stratsys. I de flesta fall behövs en konsult från det andra systemet deltaga i projektet.
  • Person från er IT-avdelning som kan vara konfigurera integrationsflödet på er sida, exempelvis ta emot information om SFTP-uppgifter eller API-klient.
  • Person med övergripande ansvar/projektledare från er sida

Observera att det är fullt möjligt att samma person har flera av dessa roller.

Införande steg-för-steg

Avstämningsmöten sker löpande under införandet efter behov.

1. Uppstartsmöte 

Möte för att samla projektgruppen, sätta tidsplan samt gå igenom punkterna under "Inför uppstart" för att definiera projektets mål och omfattning.

2. Definiera externkoder för enheter, mått och måttdatakolumner

Ni kommer med hjälp från Stratsys integrationskonsult fram till vilka externkoder som ska användas för enheter, mått och måttdatakolumner. Vill ni veta mer om vad externa koder är för något i Stratsys, se gärna filmen nedan.

3. Lägg in externkoderna i Stratsys

När externkoderna är definierade ska dem mejlas till Stratsys integrationskonsult som sedan ansvarar sedan för att läsa in externkoderna i Stratsys.

4. Skapa testdatabas (valfritt)

Föredrar ni att testa i en testmiljö be er integrationskonsult om en testmiljö.

5. Framtagning av data i externt system enligt Stratsys format 

Ni som kund ansvarar för att ta fram data enligt Stratsys format.

6. Skapa SFTP-area/API-klient som är kopplad mot Stratsys

Stratsys integrationskonsult skapar antingen en SFTP-area för filinläsning eller en API-klient för integration med Stratsys API beroende på teknikval. Uppgifter skickas sedan till er.

7. Test och validering i testdatabas (valfritt)

Ni testar att skicka in data till en testdatabas i Stratsys, antingen via SFTP eller API beroende på teknikval. Det är även möjligt som ett första steg att läsa in filen manuellt för att säkerställa filformatet.

8. Test och validering i produktionsmiljö

Ni testar att skicka in data till en testdatabas i Stratsys, antingen via SFTP eller API beroende på teknikval. Det är även möjligt som ett första steg att läsa in filen manuellt för att säkerställa filformatet.

9. Avslutsmöte

Möte för att samla projektgruppen och avsluta projektet, stämma av mot projektmålen och lämna över till förvaltning.

Förvaltning och underhåll

Mejlnotifiering vid fel och varningar

Det är möjligt att slå på funktionen för att få mejl om filinläsningen genererar varningar eller fel. För att aktivera den funktionen gå till Administrationen > Källsystem och Externa system. Välj skiftnyckeln för källsystemet och sedan skiftnyckeln till vänster om Filimport måttdata och aktivitetskostnader. I textrutan under Skicka e-post vid fel/varningar till dessa e-postadresser skriv in den e-postadressen som ni önskar få mejl till.

Manuell inläsning av fil

Som komplement, i felsökningssyfte eller i testsyfte så går det även att läsa in filer manuellt direkt i Stratsys. Det gör man under Administrationen > Källsystem och Externa koder > Externa system. Välj skiftnyckeln för källsystemet och sedan skiftnyckeln igen för Filimport måttdata och aktivitetskostnader. 

Lägg till och ändra externkoder för Enheter, Nyckeltal och Måttdatakolumner

Externkod för enheter

Scenario – ”Vi vill integrera måttdata för ett befintligt mått till en ny enhet i organisationsträdet”

Så här gör du:

1. Skapa enheten i Stratsys
2. Lägg till externkod på enheten i Stratsys
3. Se till att måttnoden är fördelad till den nya enheten 
   Du fördelar måttet till den nya enheten genom att föra muspekaren över måttets namn och klicka på redigeringsikonen. Gå till fliken Enheter och kryssa i den nya enheten i listan.
4. Se till att data för den nya enheten läggs på filen från källsystemet

Administration av externkoder för organisationsenheter kan göras på två sätt. Det ena alternativet är att gå till Administrationen > Organisation och göra enligt filmen nedan.

Det andra alternativet är att efter ni har skapat enheten enligt videon ovan går till Administration > Källsystem & externa koder > Externa koder för att lägga till en externkod. Välj aktuellt källsystem i rullistan "Välj källsystem" och Enheter i rullistan för "Extern kod". Bocka i "Visa alla enheter" för att även visa enheter utan extern kod. För att lägga till en ny externkod på en enhet klickar du det gröna plustecknet och skriver in externkoden i pop-up rutan och sparar (se video nedan). För att justera en befintlig extern kod väljer du skiftnyckeln för enheten, justerar externkoden i pop-up rutan och väljer spara.

Externkoder för nyckeltal

Scenario – ”Vi vill integrera data för ett nytt nyckeltal från vårt externa system”

Nya objektsfönstret

Så här gör du

1. Skapa måttet i Stratsys

2. Lägg på externkod på måttet

Du lägger till en externkod på måttet i det nya objektsfönstret genom att klicka på "Inställningar", sedan "kugghjulsikonen", därefter expandera sektionen "Integration" i måttfönstret.

3. Välj sedan "Lägg till integration" och lägg in externkoden på det aktuella källsystemet.

4. Klicka på "Spara och stäng" för att spara inställningarna.

 

Klassiska ändrafönstret

Så här gör du:

1. Skapa måttet i Stratsys
2. Lägg till externkod på måttet i Stratsys
   Du lägger till en externkod på måttet  genom att föra muspekaren över måttets namn och klicka på redigeringsikonen.
3. Gå till fliken Inställningar, scrolla ner och klicka på Extern kod, där fyller du i externkoden för måttet på raden för det källsystem som integrationen gäller och klickar på Spara.
4. Se till att data för det nya måttets läggs på filen från källsystemet

Externkoder för måttdatakolumner

Scenario – ”Vi vill integrera data till ytterligare en kolumn på ett befintligt nyckeltal, tex prognos”

Nya objektsfönstret

Så här gör du:

1. Se till att kolumnen finns på nyckeltalet.

Du lägger till en måttdatakolumn på måttet genom att först öppna måttet från vyn. Klicka därefter på "Inställningar", därefter Kugghjulsikonen.

Klicka på plus-tecknet för att lägga till en ny måttdatakolumn, lägg till kolumenn och klicka på "Spara".

Expandera därefter sektionen "Integration" i måttfönstret och klicka på "Administrera externa koder för måttdatakolumner".

1. Nu öppnas en ny flik i webbläsaren där vi kan lägga till externkod på kolumnen
   

   Välj korrekt källsystem och Måttdatakolumner under "Extern kod". Här väljer du "Lägg till" för att lägga till en externkod för en ny måttdatakolumn.

2. Stäng denna flik igen och ladda om det aktuella måttet och se att den nya externkoden lagts till.

 

Klassiska ändrafönstret

Så här gör du:

1. Se till att kolumnen finns på nyckeltalet
   Du lägger till en måttdatakolumn på måttet  genom att föra muspekaren över måttets namn och klicka på redigeringsikonen Gå till fliken Inställningar för att se måttdatakolumnerna och välj +Lägg till kolumn för att lägga till en ny måttdatakolumn. Måttdatakolumnen kommer att läggas till specifikt för måttet du arbetar i. Om du önskar att måttdatakolumnen blir en standard för nyskapade mått så kan du lägga till måttdatakolumnen i en måttmall. 
2. Lägg till externkod på kolumnen
   

   Du lägger till en externkod på en måttdatakolumn går du till Administrationen > Källsystem & Externa koder och väljer Externa koder. Välj därefter korrekt källsystem och Måttdatakolumner under "Extern kod". Här väljer du "Lägg till" för att lägga till en externkod för en ny måttdatakolumn.

   I pop-up fönstret skriver du in det korrekta namnet på måttdatakolumnen som finns i Stratsys. Under extern kod skriver du in externkoden för måttdatakolumnen.

3. Se till att data för den nya kolumnen läggs på filen från källsystemet

Felsökning

Importloggen finner du under Administrationen > Källsystem och externa koder > Importlogg

Syftet med importloggen är att den ska fungera som ett hjälpmedel för att enkelt kontrollera om en filinläsning gått igenom som den ska. Eventuella fel i importfilen fångas upp i importloggen och gör det enkelt för användare att identifiera och lösa dessa fel. 

De vanligaste typerna av fel är mappningsfel (dvs att en externkod är felaktigt uppsatt eller saknas) eller att nyckeltal, kolumner eller enheter som läses in inte finns upplagda i Stratsys. 

Börja med att välja ifrån vilket källsystem du vill kontrollera filinläsningar ifrån. Detta väljer du i första drop-down menyn.  
Du välja att filtrera på status beroende på vad du önskar se i loggen: Information, Varningar och Fel. Du kan även välja att filtrera på datum om du är intresserad av att se en specifik filinläsning som gjorts. 

Inläsning utan fel 

När inläsningen gått igenom utan fel ser det ut som nedan. Errors: 0, Warnings: 0, Successfully updated kpis: 5 (antalet kpi:er son du har i din fil med uppdaterat värde). 

Inläsning med fel 

I exemplet ovan har inläsningen genererat 5 varningar:  

Rad 2 och 3: ”Unable to find kpi” detta innebär att vi försökt läsa in ett nyckeltal som inte finns i Stratsys. Alternativt är nyckeltalet felstavat i filen eller i mappningskontexten för aktuellt nyckeltal. 

Lösning: Kontrollera så nyckeltalet finns upplagt i Stratsys. Om det finns, kontrollera då så att stavningen för nyckeltalet stämmer i mappningskontexten jämfört med vad som skickats i importfilen. 

Rad 4: ”Could not find department for code 50”. Detta innebär att det i Stratsys inte finns någon enhet mappad med externkoden 50. Alternativt kan enhetskoden vara felskriven i mappningskontexten eller i filen. 

Lösning: Kontrollera enhetsmappningen i mappningskontexten för aktuellt källsystem – är koden felskriven eller saknas den i mappningskontexten?  

Rad 5 och 6: ”Unable to find kpi column” innebär att vi skickat med en kolumn som inte finns i Stratsys. Alternativt är kolumnen felstavad i filen eller i mappningskontexten i Stratsys. 

Lösning: Kontrollera så kolumnen finns med i Stratsys för aktuellt nyckeltal. Kontrollera även så att stavningen stämmer i mappningskontexten jämfört med filen 

I dokumentet ”Manual externkodsmappning” kan du läsa hur du kontrollerar och uppdaterar era externkoder för enheter, mått och måttdatakolumner. 

Fel i Koladainläsning

Om du får fel i din Koladainläsning, exempelvis "No KpiData found in external system", så kan detta bero på att Kolada har tagit bort måttet, eller data för den enhet som du försöker läsa in.

Du kan söka på https://www.kolada.se/verktyg/fri-sokning/ för att se om externkoden fortafande existerar. Läs mer om Koladaintegrationen här: Nyckeltal från Kolada

Checklista vid möjligt fel 

• Säkerställ att enheten, måttet och måttdatakolumnen har externkoder som matchar till 100% med det som kommer in via filen.
• Gå igenom importloggen för valt källsystem och se efter följande:
  • Har det gått en körning för det aktuella källsystemet idag?
  • Verkar det vara fel på det aktuella nyckeltalet? Leta efter externkoden för måttet, enheten och/eller måttdatakolumnen.
  • Undersök händelsehistoriken för aktuellt mått. Poster som är markerade med “Automatjobb system” är uppdaterade från filimporten.

Schema för filinläsningar

Inläsningsjobbet går vid följande tidpunkter samtliga dagar:

• 05:00
• 06:00
• 07:30
• 08:00
• 08:30
• 09:00
• 09:30
• 10:00
• 10:30
• 11:00
• 11:30
• 12:00
• 12:30
• 13:00
• 13:30
• 17:00