Sette opp ny integrasjon

Når du skal koble en ny leverandør eller datakilde mot ePortal er det administrator som setter opp integrasjonen i Konti Connect. Skjemaet er delt i fem faner — Grunnleggende, Frekvens & Parametere, Konfigurasjon, Feltmapping og Avansert — og du fyller dem ut i tur og orden. Når du lagrer opprettes integrasjonen. Du kan deretter trigge en kjøring manuelt med Kjør-knappen, eller la den gå automatisk på den frekvensen du satte.

Tilgang

Hvem	Hva trengs
Rolle	Administrator (modulen sjekker tilgang ved oppstart — KontiConnect.AccessDenied vises ved manglende tilgang)
Modul	Konti Connect (moduleId: 27) — beskyttet av ActivateService + ModuleGuard (konti-connect-routing.module.ts:16-18)

Hvor finner du skjemaet

1. Naviger til Konti Connect → Integrasjoner (/konti-connect/integrations).
2. Klikk Opprett ny integrasjon øverst til høyre i lista (integration-list.component.html:64-67).
3. Du ledes til /konti-connect/integrations/new.

For å redigere en eksisterende integrasjon: åpne integrasjonen i lista og klikk Rediger, eller gå til /konti-connect/integrations/:id/edit.

Fane 1 — Grunnleggende

Inneholder generell informasjon om integrasjonen (integration-editor.component.html:71-148).

Felt	Påkrevd	Validering / standard	Notater
Integrasjonstype	Ja	Lastes fra databasen via getIntegrationTypes	Velger hvilken adapter som skal kjøre. Bestemmer hvilke konfigurasjonsfelt som vises i fane 3.
Navn	Ja	Maks 200 tegn	Beskrivende navn, f.eks. «Abax Kjørebok Import — Daglig».
Beskrivelse	Nei	Maks 1000 tegn	Fritekst for hva integrasjonen gjør.
Aktiver integrasjon	Nei	Standard true	Toggle. Kun aktive integrasjoner kjøres automatisk på schedule eller via manuell Kjør.

Beskrivelsen av valgt integrasjonstype vises som hjelpetekst under nedtrekksmenyen.

Fane 2 — Frekvens & Parametere

Definerer når integrasjonen skal kjøre, og hvilken datoperiode den skal hente data fra (integration-editor.component.html:150-279).

Planlegging (frekvens)

Bruker den gjenbrukbare app-cron-builder-komponenten. Følgende frekvenser er tilgjengelige (integration-editor.component.ts:68-75):

Frekvens	Når kjøres den
Manuell	Kjøres kun når du klikker Kjør. Forhåndsvisning: «Kjøres kun manuelt».
Daglig	Hver dag kl. det klokkeslettet du velger. Cron: m h * * *.
Ukedager (man-fre)	Mandag til fredag kl. valgt tid. Cron: m h * * 1-5.
Ukentlig	Valgte ukedager kl. valgt tid. Cron: m h * * <dager>.
Månedlig	Valgt dag i måneden (1-31) kl. valgt tid.
Tilpasset (cron)	Fritt 5-felts cron-uttrykk (minutt time dag måned ukedag). Klient validerer at det er fem felt via cronPattern (integration-editor.component.ts:193-201); backend bruker Cronos for full parsing (IntegrationRepository.cs:414).

Tidsfelt valideres mot mønsteret HH:mm (00:00–23:59). Dag-i-måned valideres til 1–31. Cron-uttrykk valideres mot Validators.required når frekvens er «Tilpasset».

Datoperiode (parametertype)

Begrenser hvilket tidsvindu data hentes for (integration-editor.component.html:180-211):

• Ingen (henter alt) — standard
• Forrige måned
• Forrige uke
• Siste N dager — viser ekstra felt for antall dager (1–365)
• Tilpasset

Parameter Mapping

Vises kun når parametertype er noe annet enn «Ingen». Lar deg koble ePortal-datoer ({{fromDate}} / {{toDate}}) til feltnavn som det eksterne API-et forventer. To moduser (integration-editor.component.html:214-278):

• GUI — radbasert: feltnavn + nedtrekk for fra-/til-dato. Toggle «Vis JSON» for å bytte.
• JSON — direkte JSON-redigering.

Standardmapping for nye integrasjoner: { "StartDate": "{{fromDate}}", "EndDate": "{{toDate}}" }. Mappingen tilpasses automatisk når du velger en kjent adaptertype (f.eks. NXT bruker fromDate/toDate) (integration-editor.component.ts:501-520).

Fane 3 — Konfigurasjon

Her legger du inn adapterspesifikke verdier (API-nøkler, OAuth-credentials, batch-størrelser, debug-flagg osv.).

To redigeringsmoduser (integration-editor.component.html:281-565):

• Skjema — autogenererte felt (tekst, passord, tall, boolean, dato, select, JSON-textarea) basert på en mal for valgt adapter. Passordfelt har «vis/skjul»-knapp.
• JSON — fri redigering av råkonfigurasjon. Knappene Last mal og Formater JSON hjelper deg å komme i gang og holde rent.

Lagrede hemmeligheter vises aldri i noen av modusene. Alle konfigurasjonsfelt med et hemmelighets-navn — Client Secret, passord, token, API-nøkkel — tømmes i svaret før integrasjonen sendes til nettleseren, sammen med OAuth-tokenene. På en integrasjon som allerede finnes står feltet derfor tomt selv om en verdi er lagret, og tomt betyr «behold den lagrede verdien»: du kan redigere og lagre uten å skrive inn nøkkelen på nytt. Skriv inn en verdi kun når du faktisk vil bytte den (IntegrationController.cs).

For adaptertypen VismaBusinessNXT_Actors vises i tillegg et eget Relasjonsmapping-kort i skjema-modus: koble en ePortal-relasjonstype (fra Innstillinger → CRM → Relasjonstyper) til NXT-feltet som skal fylle den under aktørsynk (invoiceCustomerNo / official / seller) — rad-basert nøkkel→verdi-GUI, samme mønster som Parameter Mapping (integration-editor.component.html:459-502).

Kopier konfigurasjon fra en annen integrasjon

Oppretter du flere like integrasjoner slipper du å skrive inn de samme verdiene om igjen. Øverst i skjema-modus velger du en eksisterende integrasjon under Kopier fra … og trykker Kopier.

Bare felt som finnes i begge integrasjonene fylles ut. Resten står urørt, og du får en melding som sier hvor mange felt som ble kopiert og hvor mange som ble hoppet over — slik at en uventet liten kopiering ikke går ubemerket hen.

Fire ting kopieres aldri:

Hva	Hvorfor
Felt som ikke finnes i den nye typen	Ikke relevant for adapteren — hoppes over stille
Verdier typen ikke godtar	F.eks. SyncDirection: Import fra en Kontoplan-integrasjon til en ordre-integrasjon, som bare kan eksportere. Ville gitt en konfigurasjon som feiler ved lagring
Hemmeligheter (Client Secret, passord, token, API-nøkkel)	Alle felt med et hemmelighets-navn skjules for nettleseren før integrasjonen sendes ut, så det finnes ingen verdi å kopiere. Skriv den inn én gang
Synkroniseringsposisjon (checkpoints)	En kopiert delta-posisjon ville fortalt den nye integrasjonen at alt frem til det tidspunktet allerede var behandlet — første kjøring ville hoppet over dataene

Du kan kopiere på tvers av integrasjonstyper: felles felt som Client ID og Firmanummer følger med, mens det typespesifikke hoppes over.

Kan listen over integrasjoner ikke hentes, står det en melding med Prøv igjen i stedet for nedtrekket, slik at en feilet henting ikke ser ut som «det finnes ingen andre integrasjoner å kopiere fra» (integration-editor.component.html:322-336).

Last mal legger inn standardverdier for valgt adapter. Hvis du allerede har en konfigurasjon, beholdes eksisterende verdier — bare manglende nøkler legges til. Du får toast som forteller hvor mange nye felt som ble lagt inn. På en integrasjon som allerede finnes legges ikke hemmelighets-felt inn (Client Secret, passord, token, API-nøkkel) — den lagrede verdien er skjult for nettleseren, så et malfelt der ville vært en eksempelverdi. Feltet står tomt, og tomt betyr «behold den lagrede nøkkelen». Skriv inn en verdi kun når du faktisk vil bytte den (integration-editor.component.ts:950-1000).

For adaptertypen VismaBusinessNXT_Orders er Ordretype et nedtrekk med to valg — 1 eller 2. Begge er ordretyper i Visma Business NXT; forskjellen er at den ene har logistikk aktivert og den andre ikke. Velg den typen firmaet bruker (integration-editor.component.ts:2259-2268).

Tallfelt

Tallfelt lagres som ekte tall i konfigurasjonen. Tømmer du et valgfritt tallfelt, fjernes nøkkelen fra konfigurasjonen og adapteren bruker sin egen standardverdi — det er den tiltenkte måten å tilbakestille et slikt felt på.

Hvilke verdier som godtas, avhenger av adapteren. Desimaler og null er gyldige for flere felt — for eksempel er DefaultMarkupPercent et prosentpåslag der 0 betyr «ingen påslag», og DefaultWorkHoursPerDay har standardverdien 7,5.

Visma Business NXT-integrasjonene har derimot en egen validering ved lagring. Der må disse feltene være hele tall som er 1 eller høyere: firmanummer (CompanyNo), DeltaSyncLookbackDays, ExportBatchSize, MaxRowsPerRun, BatchSize og AlertDigestMinutes. Feilmeldingen navngir hvilket felt det gjelder (NxtIntegrationConfigurationPolicy.cs:233-237).

Ordretype og nivå for organisasjonsenhet er strengere igjen: de bestemmer hvilke poster adapteren skriver i Visma Business NXT, så bare de gyldige kodene godtas (Ordretype 1 eller 2, nivå 1–12).

Uansett adaptertype sjekker skjemaet feltene før det sendes: en verdi som fortsatt er en mal-plassholder avvises, og et påkrevd felt som står tomt — eller er et tall lavere enn 1 — blokkerer lagringen og navngir feltet. Det er dette minimumskravet på ≥ 1 som gjelder utover Visma Business NXT, og det treffer bare påkrevde tallfelt. Valgfrie tallfelt, som prosentpåslaget over, er ikke omfattet.

Varsling ved feilede kjøringer

Vil du ha e-post når en integrasjon feiler, legger du inn tre nøkler i konfigurasjonen (JSON-fanen fungerer på alle typer): NotificationEmails (mottakere som tekst, komma- eller semikolonseparert), AlertLevel (None, Error, Warning eller All) og AlertDigestMinutes (minste antall minutter mellom varsler, helt tall som er 1 eller høyere, standard 60).

På Visma Business NXT-typene kontrolleres verdiene ved lagring: et ukjent varselnivå eller en mottakerverdi som ikke er tekst avvises med en feilmelding som navngir feltet, nøkkelnavnene rettes til riktig skrivemåte, og en tallverdi skrevet som tekst gjøres om til et ekte tall (NxtIntegrationConfigurationPolicy.cs:181-216). Varselet sendes også når kjøringen stopper før adapteren kommer i gang — for eksempel ved ugyldig konfigurasjon eller en uventet feil — ikke bare når selve kjøringen feiler (IntegrationService.cs:1082-1089). Se detaljene i Visma Business NXT-integrasjon.

I redigeringsmodus vises en Debug-logging-bryter i headeren. Når den er på, postes et advarsels-banner og DebugLogging-flagget settes til true i konfigurasjonen — alle GraphQL-spørringer, payloads og API-responser logges til kjøringsloggen. Husk å skru av etter feilsøking.

Adaptere med ferdige skjema-maler inkluderer (per integration-editor.component.ts:522-933): Abax, Visma Payroll (import/eksport), WorkOrderMaterialVoucherExport, Visma Business NXT (Products / Accounts / Actors / OrgUnits / TimeRegs / Vouchers / Orders), KontiConnect (Visma Business kostnadsimport), Simployer (fravær / ansatte), Digpro (Activity / Time / Project). Andre adaptertyper bygger malen dynamisk fra adapterens metadata-felt.

Fane 4 — Feltmapping

Bruker komponenten app-field-mapper til å velge hvilke datafelt som skal hentes fra det eksterne systemet og hvordan de skal mappes til ePortal (integration-editor.component.html:567-588). Hvilke mappinger som er relevante avhenger av integrasjonstype.

Fane 5 — Avansert

Fanen viser synkroniseringsstatus. I redigeringsmodus står «Siste vellykket sync» og «Antall poster» fra forrige kjøring her, begge read-only (integration-editor.component.html:610-645).

Delta sync settes ikke her. Fanen hadde tidligere to brytere for delta sync og fallback, men de skrev til en kolonne ingen adapter leser, og lagringen tok dem aldri med — de gjorde altså ingenting uansett hvordan de sto. De er fjernet. Delta sync styres per integrasjon med nøkkelen EnableDeltaSync (og DeltaSyncLookbackDays der adapteren støtter det) i Konfigurasjon-fanen.

Skjemastatus og lagring

Høyre kolonne viser kontinuerlig statussidekort (integration-editor.component.html:650-712):

• Progress-bar med prosent fullført
• Sjekkliste: Integrasjonstype valgt, Navn utfylt, Frekvens satt, Konfigurasjon utfylt, Antall feltmappinger
• Opprett / Oppdater-knapp (mørk primær)
• Avbryt-knapp

Konfigurasjon utfylt lister feltene som fortsatt mangler. Et påkrevd felt må ha en verdi, et påkrevd tall må være større enn null (0 er malens uendrede standard, ikke et ekte firmanummer), og et felt som fortsatt inneholder malens eksempelverdi (your-…) regnes som utfylt av malen, ikke av deg.

Når du klikker Opprett / Oppdater valideres alle krav før skjemaet sendes:

• Påkrevde felt må være utfylt (warning-toast vises)
• Konfigurasjonsfelt må være utfylt. Mangler noe, listes alle manglende felt i én melding og du sendes til Konfigurasjon-fanen — i stedet for at serveren avviser ett felt om gangen
• Konfigurasjon må være gyldig JSON (toast: «Ugyldig konfigurasjon»)
• Parameter Mapping må være gyldig JSON hvis parametertype er annet enn «Ingen» (toast: «Ugyldig Parameter Mapping JSON-format»)

Avviser serveren likevel et felt (for eksempel ved redigering av rå JSON), navngir feilmeldingen nå feltet og hva som forventes av det.

Etter vellykket lagring sendes du til integrasjonens detaljside (/konti-connect/integrations/:id).

Slik gjør du

1. Gå til Konti Connect → Integrasjoner og klikk Opprett ny integrasjon.
2. Fane Grunnleggende: velg Integrasjonstype, fyll inn Navn (maks 200 tegn) og evt. beskrivelse. La Aktiver integrasjon stå på.
3. Fane Frekvens & Parametere: velg ønsket frekvens i cron-builderen. For schedulert kjøring må du sette klokkeslett (og dag-i-måned / ukedager om aktuelt). Velg parametertype hvis integrasjonen skal hente et bestemt datointervall.
4. Fane Konfigurasjon: klikk Last mal for å fylle ut skjema hvis du står i skjemamodus, eller bytt til JSON-modus og lim inn konfigurasjonen direkte. Fyll inn API-credentials og andre adapterspesifikke verdier.
5. Fane Feltmapping: velg hvilke felt som skal synkroniseres (avhengig av adapter).
6. Fane Avansert: kun synkroniseringsstatus. Skal integrasjonen kjøre delta sync, settes EnableDeltaSync i Konfigurasjon-fanen (steg 4).
7. Følg med på Skjemastatus i høyre kolonne. Når alt er grønt, klikk Opprett.
8. Etter at integrasjonen er opprettet havner du på detaljsiden. Klikk Kjør (knapp øverst til høyre) for å trigge første kjøring manuelt — knappen er aktiv kun når integrasjonen er aktiv (integration-detail.component.html:22-27).
9. Følg med på Historikk-fanen for å se kjøringsstatus og eventuelle feilmeldinger.

Vanlige problemer

Valideringsfeil-toast når du klikker Opprett

Ett eller flere påkrevde felt mangler eller har ugyldig verdi. Skjemastatus-listen i høyre kolonne viser hva som gjenstår: Integrasjonstype, Navn eller Frekvens. Felter som mangler markeres rødt.

«… is still the configuration template's placeholder value»

Konfigurasjonen inneholder en eksempelverdi som your-visma-connect-client-secret i et hemmelighets-felt. Lagringen stoppes med vilje: hadde den gått gjennom, ville eksempelverdien erstattet den ekte nøkkelen, og integrasjonen ville feilet med autentiseringsfeil ved neste kjøring. Tøm feltet for å beholde den lagrede nøkkelen, eller lim inn den ekte.

«Ugyldig konfigurasjon»

JSON-en i Konfigurasjon-fanen kan ikke parses. Bytt til JSON-modus, klikk Formater JSON, og se etter komma som mangler, manglende anførselstegn eller ekstra , før }/].

«Ugyldig Parameter Mapping JSON-format»

Parameter Mapping må være gyldig JSON når parametertype er noe annet enn «Ingen». Bytt til JSON-modus i Parameter Mapping-seksjonen og verifiser strukturen, f.eks. { "StartDate": "{{fromDate}}", "EndDate": "{{toDate}}" }.

«Kunne ikke laste integrasjonstyper»

Backend ga feil ved kall til integrasjonstyper. Sjekk at API-en kjører og at brukeren har gyldig token. Refresh siden.

«Integrasjonen må være aktiv for å kjøres»

Knappen Kjør på detaljsiden er disabled når isActive = false. Sett Aktiver integrasjon til på i fane Grunnleggende, lagre, og prøv igjen.

«Lagringen ble avvist … Manglende eller tomme felt: …»

Lagring av en eksisterende integrasjon erstatter hele integrasjonen, ikke bare feltene du endret. Derfor avvises en lagring som ikke sender med alle feltene som erstattes: integrasjonstype, navn, konfigurasjon, frekvens, parametertype, aktiv-status, beskrivelse, cron-uttrykk, antall dager og parameter-mapping. Tidligere ble felt som manglet skrevet tomme, slik at integrasjonen mistet type, oppsett eller tidsplan uten at noe sa fra.

Et felt som kan stå tomt — beskrivelse, cron-uttrykk, antall dager, parameter-mapping — må sendes med som eksplisitt tomt for å tømmes. Å utelate det er ikke det samme som å tømme det, og avvises. Passord og nøkler er unntaket: de sendes ikke tilbake fra skjemaet, og lagringen beholder de lagrede verdiene.

Feilmeldingen navngir feltene som mangler. Skjer dette fra ePortals egen redigering, er det en feil i klienten og ikke noe du kan rette i skjemaet: meld fra med integrasjonens navn og feltene som nevnes.

Cron-feltet er rødt etter du valgte «Tilpasset»

Klienten krever at uttrykket har fem felt adskilt med mellomrom (m h dom mon dow). Eksempel: 0 9 * * 1 = hver mandag kl. 09:00.

Konsekvenser for andre

• Brukere av relevante moduler får tilgang til synket data — varsle dem om ny kilde
• Andre integrasjoner mot samme leverandør deler ofte rate limits — koordiner frekvens
• Synket data lagres i ePortal-databasen og påvirker lagringsforbruk for store integrasjoner

Relaterte sider

• Kjøre integrasjon manuelt — trigge ekstra kjøring etter oppsett
• Se status på integrasjoner — daglig oppfølging
• Lese kjøringslogg — feilsøking
• Rotere utløpt OAuth-token — vedlikehold
• Pause integrasjon — midlertidig stans
• Integrasjoner — leverandør-spesifikke detaljer
• For administratorer