Nyckeltalsintegration

Nyckeltalsintegration

Artikeln beskriver integrationsprodukten Nyckeltalsintegration.

💡Använder ni inte nyckeltalsintegration idag, vänligen kontakta er kundansvarig på Stratsys för vidare dialog då det är en Enterprise/tilläggstjänst.

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

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

Felsökning

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, Unit4, Cognos, Heroma, Power BI, Mercur, Skola24, Unikum och DF Respons.

Tekniker

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

Filinläsning är det ena alternativet och det vanligaste bland våra kunder. Ni lägger filer i en SFTP-katalog som sedan läses in till Stratsys. Inläsningen till Stratsys sker vid följande tidpunkter 05:00, 06:00, 07:35, 13:30 och 17:00, 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 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.

💡API-endpoints för nyckeltalsinläsning stödjer i dagsläget endast ett nyckeltalsvärde per anrop. Endpoint för "bulk"-inläsning är under utveckling. Ska ni skicka data till ett stort antal enheter eller nyckeltal rekommenderar vi er att använda filinläsning tills dess att den nya endpointen är färdigutvecklad.

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åttkolumn 
  • 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.

    Stratsys stödjer encoding ”ANSI”, ”UTF-8 utan BOM” och ”UTF-8 med BOM”. 

    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åttkolumner 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åttkolumn 
    • Värde (decimalavdelare .) 

      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åttkolumner filen avser. Antalet måttkolumner begränsas av header-radens måttkolumnnamn eller externa kod. 

      Om filen inte innehåller header-rad kommer måttkolumnerna 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 .) 
      • Värde (decimalavdelare .) 
      • … 

      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åttkolumner 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åttkolumner

      Ni kommer med hjälp från Stratsys integrationskonsult fram till vilka externkoder som ska användas för enheter, mått och måttkolumner. 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

      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>Källsystem. Välj skiftnyckeln för källsystemet och sedan skiftnyckeln igen för Filimport måttdata och aktivitetskostnader

      🚫Den generella importen för mått uppdaterar endast mått i aktuell version, ej i planeringsversion.

      💡Både manuell inläsning och automatisk inläsning visas i importloggen. 

      Manuell_Inlasning

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

      Externkod för enheter

      Scenario – ”Vi vill integrera data till en ny enhet i organisationsträdet

      1. Skapa enheten i Stratsys
      2. Lägg till externkod på enheten i Stratsys
      3. 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.

      ExternkodEnhet

      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.

      🚫Du kan inte använda samma externkod på två enheter, då får du ett felmeddelande.

      ExternkodEnhet2

      Externkoder för nyckeltal

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

      Lösning:

      1. Skapa måttet i Stratsys
      2. Lägg till externkod på måttet i Stratsys
      3. Se till att data för det nya måttets läggs på filen från källsystemet

      För att skapa ett nytt mått väljer ni plustecknet i en vy. Om alternativen "Lägg till mått" och "välj in" finns så väljer ni alternativet "Lägg till mått". Därefter fyller ni i de obligatoriska fälten och korrekta enheterna. Under fliken "Inställningar" scrollar ni ner till "externkod". Klickar ni på rutan får ni upp en pop-up ruta där ni har möjlighet att fylla i en externkod och spara.

      ExternkodKPI

      Externkoder för måttkolumner

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

      1. Se till att kolumnen finns på nyckeltalet
      2. Lägg till externkod på kolumnen
      3. Se till att data för den nya kolumnen läggs på filen från källsystemet

      För att lägga till en måttkolumn i ett mått öppnar du upp måttet med skiftnyckeln (ändrafönstret). Därefter väljer du fliken Inställningar för att se måttkolumnerna. Välj +Lägg till kolumn för att lägga till en ny måttkolumn. Måttkolumnen kommer att läggas till specifikt för måttet du arbetar i. Om du önskar att måttkolumnen blir en standard för nyskapade mått så kan du lägga till måttkolumnen i en måttmall. Måttmallen finner du under Administration>Måttmallar. I måttkolumnen kan du bland annat välja kolumntyp, beskrivning, decimaler och postfix.

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

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

      ExternkodKPI2-1

      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. 

      1. 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.  
      2. Du även välja att filtrera på status beroende på vad du önskar se i loggen: Information, Varningar och Fel. 
      3. Du kan även välja att filtrera på datum om du är intresserad av att se en specifik filinläsning som gjorts. 

          ⚠️Varningar indikerar ofta att viss data inte kunnat läsas in. Kontrollera därför alltid de varningar som genererats. 

          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åttkolumner. 

          Checklista vid möjligt fel 

          • Säkerställ att enheten, måttet och måttkolumnen 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åttkolumnen.
          • Undersök händelsehistoriken för aktuellt mått. Poster som är markerade med “Automatjobb system” är uppdaterade från filimporten.

          💡Om felet kvarstår vänligen kontakta support@stratsys.se