Abax-integrasjon¶

Abax er en elektronisk kjørebok som registrerer turer automatisk via GPS-utstyr i kjøretøy. ePortal importerer turene fra Abax og oppretter timeregistreringer (typisk kjøregodtgjørelse i km eller varighet i timer) per sjåfør.

Type: REST-import (pull), batch Modul i ePortal: Konfigureres i Konti Connect, oppretter rader i Time-modulen (wv_Time_WageReg) Karakteristisk: OAuth2 Client Credentials Flow mot Abax Identity Server; in-memory filter på turklasse (BusinessTrip/PrivateTrip/UnknownTrip); strikt duplikatsjekk via wrExtId

Hva integrasjonen synker¶

Retning	Entitet	Frekvens
Abax → ePortal	Turer (kjøreposter) → `wv_Time_WageReg`	Konfigurerbar (typisk daglig, lookback `importFromDays`)

Implementasjon: AbaxAdapter.cs

Tilgang¶

Hvem	Hva trengs
Hos kunden	Aktiv Abax-konto, Abax Developer Portal-tilgang for å registrere en API-klient (Client Credentials/Machine-to-Machine)
Hos Konti	Administrator-tilgang til Konti Connect

Forutsetninger¶

Abax Developer Portal-konto med tillatelse til å aktivere Client Credentials Flow (kontakt Abax hvis ikke aktivert)
Scopes open_api og open_api.trips (eller open_api.sandbox + open_api.sandbox.trips for sandbox)
ePortal-ansatte er opprettet og har minst én av disse identifikatorene satt: UserEmployeeNo (matchet via Driver.ExternalId), e-post, mobil eller fullt navn — adapteren prøver disse i nevnte rekkefølge
En WageTypeNo (lønnsart, wtNo) er definert for Abax-kjøregodtgjørelse i ePortal

Konfigurasjon — feltforklaring¶

Konfigurer i Konti Connect → "Ny integrasjon" → velg type Abax. Alle felter ligger i ConfigurationJson.

Felt	Type	Påkrevd	Hva det betyr
`clientId`	String	Ja	OAuth2 client_id fra Abax Developer Portal (Machine-to-Machine-klient)
`clientSecret`	String (hemmelighet)	Ja	OAuth2 client_secret. Krypteres ved lagring via `IntegrationService`
`UseSandbox`	Boolean	Nei (default `false`)	Hvis `true`: bruker `https://api-test.abax.cloud` og sandbox-scopes
`WageTypeNo`	String	Ja	ePortal-lønnsart (`wtNo`) som importerte turer plasseres på (kjøregodtgjørelse). Tur hoppes over hvis tom
`importFromDays`	Integer	Nei (default `30`)	Hvor mange dager tilbake i tid det skal hentes turer fra ved hver kjøring. ABAX tillater maks 3 måneder per API-kall, så perioder over 89 dager deles automatisk i flere fortløpende delperioder
`PageSize`	Integer	Nei (default `1500`, klampes 1–1500)	Antall turer per API-side (sendes som `page_size`). ABAX Open API v1 default og maksimum er 1500
`CommercialClass`	String	Nei (default `BusinessTrip` via fallback)	Filter på turklasse. Trips-endepunktet har ingen klassefilter-parameter, så filteret håndheves in-memory etter henting. Aksepterer både `Commercial`/`BusinessTrip`, `Private`/`PrivateTrip`, `Unknown`/`UnknownTrip`. Sett til `All`/`Alle`/`*` eller blank for å beholde alle klasser
`AllowedTripClasses`	String (komma-separert)	Nei	In-memory filter på turklasse. Hvis tom: faller tilbake til `CommercialClass`, deretter `BusinessTrip`. Sett til `All`/`Alle`/`*` for å beholde alle
`QuantitySource`	String	Nei (default `Distance`)	Hva som lagres som kvantum: `Distance` = km, `DurationHours` = timer (basert på `trip.Duration` sekunder)
`DistanceUnit`	String	Nei (default `meters`)	Hvilken enhet ABAX returnerer i. `meters` (standard for Open API v1) deles på 1000; `km`/`kilometer`/`kilometers` brukes som-er
`DefaultDepartment`	String	Nei	Avdelingskode som settes på alle lønnsregistreringer
`DefaultProject`	String	Nei	Prosjektkode som settes på alle lønnsregistreringer
`DescriptionTemplate`	String	Nei	Mal for `wrDesc`-feltet. Placeholders: `{DriverName}`, `{VehicleName}`, `{Distance}`, `{From}`, `{To}`. Hvis tom: bygges automatisk
`DebugLogging`	Boolean	Nei (default `false`)	Logger rå JSON-respons fra Abax og filtreringsbeslutninger. Skru kun på ved feilsøking
`FieldMappings`	Liste	Nei	Tilleggsmapping fra ABAX-trip-felt til `WageReg`-properties. Tillatte target-felter: `Description`, `Department`, `Project`, `Quantity`, `Date`, `WorkOrder`, `Activity`, `Part`, `Extra1`–`Extra3`, `ExtR6`–`ExtR10`, `ResponseNo`, `ExternalQuantity`, `Start`, `End`, `Accex`, `CustomerNo`, `ActObjectID`. Andre target-felter blir avvist
`FilterCriteria.StartDate`	DateTime	Nei	Eksplisitt start-dato (overstyrer `importFromDays`)
`FilterCriteria.EndDate`	DateTime	Nei	Eksplisitt slutt-dato (default `DateTime.Now`)
`FilterCriteria.VehicleIds`	String (komma-separert)	Nei	Begrenset til disse Abax-kjøretøy-ID-ene
`FilterCriteria.EmployeeNumbers`	String (komma-separert)	Nei	Begrenset til disse Abax driver `externalIds`/ansattnumrene. Håndheves in-memory etter henting (endepunktet har ingen slik parameter)

Eksempel ConfigurationJson:

{
  "clientId": "<din-abax-client-id>",
  "clientSecret": "<din-abax-client-secret>",
  "UseSandbox": false,
  "WageTypeNo": "8501",
  "importFromDays": 7,
  "PageSize": 1500,
  "CommercialClass": "BusinessTrip",
  "QuantitySource": "Distance",
  "DistanceUnit": "meters",
  "DescriptionTemplate": "Abax kjøring: {DriverName} {Distance} ({From} → {To})",
  "DebugLogging": false
}

Hemmelig håndtering: clientSecret krypteres ved lagring og eies av det krypterte autentiseringslageret (AuthenticationJson); lagring fjerner den fra konfigurasjons-JSON-en. Ved kjøring leser adapteren hemmeligheten fra det dekrypterte autentiseringslageret først, med fallback til eldre konfigurasjonslagring. Tjenester som leser config må bruke GetDecryptedConfigAsync (ikke FromIntegration direkte). Se Sette opp ny integrasjon i Konti Connect.

Slik gjør du — oppsett¶

1. Opprett en M2M-klient i Abax Developer Portal¶

Logg inn på Abax Developer Portal som administrator
Opprett en ny applikasjon med Machine-to-Machine (Client Credentials Flow)
Aktiver scopes open_api og open_api.trips
Kopier client_id og client_secret — du får dem kun én gang

Hvis Abax svarer unauthorized_client i ePortal-loggen, må Abax aktivere Client Credentials-flyt for klienten.

2. Opprett integrasjon i Konti Connect¶

I ePortal:

Innstillinger → Konti Connect → Ny integrasjon
Type: Abax Trip Import
Fyll inn clientId, clientSecret og WageTypeNo som minimum
Sett ønsket lookback med importFromDays
Sett scheduler (typisk daglig)
Klikk Test tilkobling — adapteren henter et token og kaller /v1/api-capabilities. 200 = OK
Lagre

3. Mapping av sjåfører¶

Adapteren prøver i denne rekkefølgen for å finne ePortal-ansatt:

Driver.ExternalId → wv_User.userEmplNo (anbefalt — sett ABAX externalId til ansattnummeret)
Driver.Email → wv_User.userEmail
Driver.PhoneNumber → wv_User.userMobile (normaliserer ved å fjerne +47/landskode)
Driver.Name → wv_User.userFullname

Deaktiverte brukere (userDeActive = 1) som matches via e-post/mobil/navn fanges som feil og turen hoppes over (ingen utilsiktet "vekking" av sluttede ansatte). Beste praksis: sett externalId = ansattnummer i Abax.

4. Test første kjøring¶

Bruk Kjør nå i Konti Connect → integrasjonen
Følg kjøringsloggen:
Antall turer hentet vs. behandlet vs. hoppet over
Hvis mange "Sjåfør ikke funnet" — sjekk ExternalId-mapping hos Abax
Hvis "Allerede importert" — duplikatsjekk fungerer som forventet
Verifiser i Time-modulen at lønnsregistreringer har riktig wrEmplNo, wtNo, wrDate (fra start.location.timestamp), wrQty (km eller timer)

Duplikatsjekk¶

Adapteren lagrer ABAX trip-id i wv_Time_WageReg.wrExtId (trunkert til 20 tegn). Før hver lagring sjekkes om en rad allerede finnes med samme wrEmplNo + wrExtId. Hvis ja: turen hoppes over. Hvis trip.id mangler eller er tom: turen hoppes over for å unngå duplikater uten id.

Frekvens og volum¶

Default lookback: 30 dager (konfigurerbart via importFromDays)
Maks 3 måneder per API-kall (ABAX-grense): lengre perioder deles automatisk i delperioder på inntil 89 dager som hentes etter hverandre
Sidestørrelse: 1500 (ABAX default og maks, sendes som page_size)
200 ms forsinkelse mellom sider for å unngå throttling
Pagineringssikring: stopper ved 10 000 sider
Token-forespørsel: 3 retries med eksponentiell backoff (2s, 4s)

Sikkerhet¶

clientSecret krypteres ved lagring (AES via EncryptionService)
Bruk en dedikert Abax M2M-klient for ePortal — ikke gjenbruk personlige credentials
Sandbox vs. produksjon styres av UseSandbox og endrer scopes + base-URL automatisk
Adapteren skriver kun til wv_Time_WageReg med RegistrationBy = "ABAX_INTEGRATION" — sporbart i audit-loggen

Vanlige problemer¶

`unauthorized_client` ved token-forespørsel¶

Client Credentials Flow er ikke aktivert for klienten. Kontakt Abax-support og be om M2M-aktivering for client_id. Se developer.abax.cloud.

`invalid_client`¶

Feil clientId eller clientSecret, eller du har blandet sandbox- og produksjons-credentials. Verifiser at UseSandbox matcher hvilket miljø klienten ble opprettet i.

`invalid_scope`¶

Klienten har ikke tilgang til open_api/open_api.trips. Aktiver i Developer Portal.

Ingen turer importeres selv om Abax har data¶

Sjekk AllowedTripClasses/CommercialClass — standard er kun BusinessTrip. Sett til All for å hente private/ukjente også
Sjekk at importFromDays dekker perioden
Skru på DebugLogging og se hvilke turklasser API-en returnerer

"Sjåfør ikke funnet"¶

Abax-driveren matcher ingen ePortal-bruker via ExternalId, e-post, mobil eller navn. Anbefalt fiks: sett driver.externalId = ansattnummer i Abax-administrasjonen, eller suppler ePortal-brukerens e-post/mobil.

Sjåfør matches mot deaktivert bruker — turen hoppes over¶

Adapteren stopper bevisst når e-post/mobil/navn matcher en bruker med userDeActive = 1. Reaktiver brukeren i ePortal eller fjern e-post fra den deaktiverte brukeren slik at en aktiv bruker matches.

Alle turer kommer på samme dato (dagens dato)¶

trip.start.location.timestamp mangler eller er ugyldig. Adapteren faller tilbake til dagens dato med en varsel-logg. Kontakt Abax-support hvis konsistent over flere turer.

`SqlDateTime overflow` i loggen¶

Bug i tidligere versjoner. Adapteren normaliserer nå alltid wrDate via NormalizeWageRegDate til dd.MM.yyyy før lagring. Hvis det fortsatt skjer: meld inn med eksempel tripStartTimestamp-verdi.