Dokumentera integrationerna innan utvecklaren slutar
Av CodexierPublicerad 4 min läsning
Webbshoppen skickar order till Fortnox, formuläret på hemsidan skapar affärer i CRM:et och ett nattligt jobb uppdaterar lagret. Allt fungerar – tills frilansaren som byggde det går vidare och ett lösenord går ut. Då vet ingen var integrationen körs, vilket konto den använder eller vad den skulle göra. Här får du en mall med en sida per integration och en rutin för att hålla den aktuell.
Därför försvinner kunskapen om integrationer
Integrationer sitter mellan system, så ingen äger dem naturligt. CRM-leverantören supportar CRM:et och redovisningskonsulten kan Fortnox, men limmet emellan finns i en persons huvud och en persons konton. Det går tyst i månader, så ingen tänker på det. När det går sönder – ofta för att en token gått ut, ett API ändrats eller kortet på driftskontot slutat gälla – är kunskapen som behövs för att laga det borta.
En mall med en sida per integration
| Fält | Vad du skriver |
|---|---|
| Namn och syfte | En mening: vilket verksamhetsproblem den löser |
| System som ingår | Källa och mål, till exempel Shopify till Fortnox |
| Dataflöde | Vilka uppgifter som flyttas, åt vilket håll och vad som startar det |
| Var den körs | Automationsverktyg, serverlös funktion, server eller tillägg, med länk |
| Schema eller utlösare | I realtid via webhook, varje timme, varje natt |
| Inloggningar | Vilka konton och nycklar den använder och var de förvaras |
| Beroenden | Betaltjänster, API-versioner, allt som går ut |
| Felhantering | Vad som händer när den fallerar och vem som larmas |
| Ansvarig | Verksamhetsansvarig och teknisk kontakt |
| Senast granskad | Datum och av vem |
Lägg till en enkel skiss om det hjälper: rutor för system och pilar för data. Ett foto av en whiteboardskiss duger.
Inloggningar och var de förvaras
Den vanligaste krisen handlar inte om kod utan om åtkomst. Integrationen körs på utvecklarens privata Zapier- eller Make-konto, API-nyckeln skapades i hens namn eller driften betalas med hens kort.
- Flytta varje konto i automationsverktyg, molntjänster och domäner till företaget, med minst två administratörer.
- Skapa API-nycklar under ett tjänstekonto eller en företagsanvändare, inte en person.
- Förvara nycklar och lösenord i ett delat valv i en lösenordshanterare för företag.
- Notera när tokens och certifikat går ut i en delad kalender.
- När någon slutar: byt de nycklar hen hade tillgång till.
Felscenarier och åtgärder
Token eller lösenord har gått ut
Symtom: inget kommer fram, eller fel i loggen. Åtgärd: förnya inloggningen i valvet och koppla om. Skriv på sidan hur det görs.
API:et har ändrats
Symtom: delvis data eller nya fel efter en uppdatering hos leverantören. Åtgärd: uppdatera mappningen – sidan ska ange vilken API-version som används.
Dubbla eller saknade poster
Symtom: två fakturor för en order, eller en lucka. Åtgärd: vet var du ska titta och hur du kör om säkert utan dubbletter.
Betalningen har upphört
Symtom: hela verktyget stannar. Åtgärd: företagets kort på varje tjänst och fakturamejl till en gemensam adress.
Skriv för varje integration hur någon som inte är utvecklare ser att den fungerar – till exempel att gårdagens order finns i Fortnox – och sätt upp ett larm för när den inte gör det. Guiden om webhooks eller schemalagd synk förklarar varför svaret skiljer sig mellan olika typer av integrationer.
Ansvariga och granskningsdatum
- Ge varje integration en verksamhetsansvarig som märker när resultatet blir fel.
- Utse en teknisk kontakt, internt eller hos en byrå, med ett supportavtal om integrationen är kritisk.
- Gå igenom varje sida två gånger per år: behövs den fortfarande, stämmer den, gäller inloggningarna?
- Uppdatera sidan som en del av varje ändring, inte i efterhand.
- Samla alla sidor på ett gemensamt ställe som överlever personalbyten.
När du inte behöver hjälp: har ni två eller tre enkla integrationer och den som byggde dem går att nå, räcker några timmar med hen och den här mallen. Har kunskapen redan försvunnit, eller har ni många kopplingar som ingen helt förstår, kartlägger och dokumenterar vår tjänst för optimering av integrationer och automation dem. Se prissidan eller boka ett kort samtal.
Vanliga frågor
Utvecklaren har redan slutat. Var börjar vi?
Lista de system du vet utbyter data och kontrollera sedan varje system efter anslutna appar, API-nycklar och automationskonton. Fakturor och gamla mejl avslöjar ofta verktyg ni glömt. Återta administratörsåtkomsten först, dokumentera sedan.
Hur detaljerad ska dokumentationen vara?
Så detaljerad att en kunnig utvecklare som aldrig sett integrationen kan hitta den, förstå syftet och åtgärda ett vanligt fel. En sida per integration räcker oftast; detaljer på kodnivå hör hemma i kodförrådet.
Var ska vi spara dokumentationen?
På ett gemensamt ställe i företaget, som en wiki, en delad enhet eller ärendesystemet – inte i ett personligt dokument. Inloggningarna ligger i lösenordshanteraren och sidan pekar dit.
Ska byrån som byggde integrationen skriva dokumentationen?
Ja, helst som en del av leveransen. Skriv in det i avtalet, tillsammans med överlämning av alla konton och nycklar till företaget.
Kartlägg integrationerna innan de går sönder
Lista de system du tror är ihopkopplade. På 15 minuter hjälper vi dig att hitta de riskabla och vad som ska dokumenteras först.
Boka ett kostnadsfritt 15-minuterssamtal