Simployer-integrasjon¶

Simployer Classic er et HR-system (tidligere Infotjenester). ePortal har to separate adaptere mot Simployer: én for ansatt-master-data (SimployerEmployeeImport) og én for godkjente fravær (SimployerAbsenceImport). Begge er REST-imports som hentes via Bearer-token mot https://api.simployer.com.

Type: REST-import (pull), batch Modul i ePortal: Konfigureres i Konti Connect, oppdaterer Brukere/Ansatte og Time-modulen Karakteristisk: Bearer-token-auth (manuelt hentet fra Simployer Admin Center); fraværsimport krever periode-parametere (fromDate/toDate); ansatt-import slår sammen Person- og Employee-objekter

To adaptere — én leverandør¶

TypeCode	Adapter	Hva den gjør
`SimployerEmployeeImport`	SimployerEmployeeImportAdapter.cs	Importerer ansatte (navn, ansattnr, kontaktinfo, ansettelsesdatoer) til `wv_User` + ansettelseshistorikk til `wv_user_Employment`
`SimployerAbsenceImport`	SimployerAbsenceImportAdapter.cs	Importerer godkjente fravær (ferie, sykdom, permisjon) som lønnsregistreringer (`wv_Time_WageReg`), én rad per dag

De to settes opp som separate integrasjoner i Konti Connect, men deler JwtToken og OrganizationUnitId.

Hva integrasjonen synker¶

Retning	Entitet	Frekvens
Simployer → ePortal	Ansatte (Person + Employee) → `wv_User`	Daglig/per behov
Simployer → ePortal	Ansettelseshistorikk → `wv_user_Employment`	Sammen med ansatt-import
Simployer → ePortal	Godkjente fravær → `wv_Time_WageReg` (én rad per dag)	Daglig/per behov, krever `fromDate`/`toDate`

Tilgang¶

Hvem	Hva trengs
Hos kunden	Aktiv Simployer-konto; admin-tilgang til Simployer Admin Center for å generere JWT-token
Hos Konti	Administrator-tilgang til Konti Connect

Forutsetninger¶

JWT Bearer-token fra Simployer Admin Center (kontakt Simployer support hvis du ikke har tilgang)
OrganizationUnitId (GUID) for organisasjonsenheten i Simployer
For fraværsimport: en mapping mellom Simployer fraværstyper og ePortal lønnsarter (wtNo) er definert
ePortal-ansatte har userEmplNo satt likt Simployer EmployeeNumber (matching-nøkkel)

Konfigurasjon — feltforklaring¶

Felles felter (begge adaptere)¶

Felt	Type	Påkrevd	Hva det betyr
`JwtToken`	String (hemmelighet)	Ja	Bearer-token fra Simployer Admin Center. Krypteres ved lagring
`OrganizationUnitId`	String (GUID)	Ja	Simployer organisasjonsenhet å hente data fra. Finn ID via `GET /v1/organizations`
`ApiBaseUrl`	URL	Nei (default `https://api.simployer.com`)	API-base. Endres kun for test/sandbox
`TimeoutSeconds`	Integer	Nei (default `60`)	HTTP-timeout per request
`DebugLogging`	Boolean	Nei (default `false`)	Detaljert logging (masker JwtToken)

Ekstra felter for `SimployerEmployeeImport`¶

Felt	Type	Påkrevd	Hva det betyr
`OnlyActiveEmployees`	Boolean	Nei (default `true`)	Hvis `true`: legger `?isActive=true` på API-spørringen og henter kun aktive
`UpdateExistingEmployees`	Boolean	Nei (default `true`)	Tillat oppdatering av eksisterende `wv_User`-rader
`CreateNewEmployees`	Boolean	Nei (default `true`)	Tillat opprettelse av nye brukere
`SyncEmploymentHistory`	Boolean	Nei (default `true`)	Skriv start/slutt-dato til `wv_user_Employment`
`DefaultUserLevelId`	Integer	Nei (default `2`)	Brukernivå for nye brukere. Eksisterende beholder sitt nivå
`DefaultUserLevelIntra`	Integer	Nei (default `2`)	Intranett-nivå (kun nye brukere)
`DefaultUserLevelExtra`	Integer	Nei (default `2`)	Ekstranett-nivå (kun nye brukere)
`DefaultUserIntra`	Boolean	Nei (default `true`)	Intranett-tilgang for nye brukere
`DefaultUserExtra`	Boolean	Nei (default `false`)	Ekstranett-tilgang for nye brukere
`DefaultUserAdmin`	Boolean	Nei (default `false`)	Admin-flagg for nye brukere
`FieldMappings`	Liste	Nei	Tilleggsmapping. Source-felter: `EmployeeNumber`, `FirstName`, `LastName`, `IdentityNumber`, `DateOfBirth`, `StartDate`, `EndDate`, `IsActive`, `Email`, `Phone`. Target: `UserFullname`, `UserName`, `UserEmail`, `UserMobile`, `UserEmployeeDate`, `UserEmployeeEndDate`, `UserDeActive`, `UserPercent`

Ekstra felter for `SimployerAbsenceImport`¶

Felt	Type	Påkrevd	Hva det betyr
`OnlyImportApproved`	Boolean	Nei (default `true`)	Hopper over fravær med `Status != "Approved"`
`SkipWeekends`	Boolean	Nei (default `true`)	Lager ikke registrering for lør/søn ved flerdagsfravær
`DefaultWorkHoursPerDay`	Double	Nei (default `7.5`)	Basis for å regne ut timer per dag: `hours = DefaultWorkHoursPerDay × (employmentPercentage/100) × (absencePercentage/100)`
`AbsenceTypeMapping`	JSON-objekt	Anbefalt	Kobling fra Simployer fraværstype til ePortal `wtNo`. Støtter to nøkler: GUID (anbefalt — stabil) eller navn (fallback). Tom mapping = ingen fravær importeres

Parameter (sendes ved kjøring, ikke i ConfigurationJson):

Parameter	Type	Påkrevd	Hva det betyr
`fromDate`	Dato (`yyyy-MM-dd`)	Ja	Start på perioden som hentes
`toDate`	Dato (`yyyy-MM-dd`)	Ja	Slutt på perioden

Parameterne settes i scheduler-konfigurasjonen eller ved "Kjør nå".

Eksempel AbsenceTypeMapping (hentet fra Konti Connect-malen):

{
  "AbsenceTypeMapping": {
    "3fa85f64-5717-4562-b3fc-2c963f66afa6": 8401,
    "Ferie": 8401,
    "Sykdom (egen) 1-24 dager": 6401,
    "Sykdom (egen) over 24 dager": 6411,
    "Sykdom (barn)": 6451,
    "Permisjon med lønn": 6701,
    "Permisjon uten lønn": 8301,
    "Sykdom egenmelding": 902,
    "Sykdom sykemelding": 903,
    "Sykdom barn": 904
  }
}

Bytt ut GUID-en og wtNo-tallene med dine egne. Skru på DebugLogging ved første kjøring og se etter linjer som "Absence type not found - ID: <guid>, Name: '<navn>'" — kopiér disse til mappingen.

Eksempel ConfigurationJson (ansatt-import):

{
  "JwtToken": "<bearer-token-fra-Simployer-admin-center>",
  "OrganizationUnitId": "<din-org-unit-guid>",
  "ApiBaseUrl": "https://api.simployer.com",
  "TimeoutSeconds": 60,
  "OnlyActiveEmployees": true,
  "UpdateExistingEmployees": true,
  "CreateNewEmployees": true,
  "SyncEmploymentHistory": true,
  "DefaultUserLevelId": 2,
  "DebugLogging": false
}

Hemmelig håndtering: JwtToken krypteres ved lagring. Skru på DebugLogging kun midlertidig — adapteren maskerer riktignok tokenet i loggen, men reduserer eksponering ved å skru av igjen etter feilsøking.

Slik gjør du — oppsett¶

1. Generer JWT-token i Simployer Admin Center¶

Logg inn på Simployer Admin Center som administrator
Generer eller hent ut Bearer-tokenet for API-tilgang (kontakt Simployer support hvis du ikke har feltet)
Finn organizationUnitId ved å kalle GET /v1/organizations med tokenet, eller spør Simployer

2. Opprett ansatt-import-integrasjon¶

I Konti Connect:

Innstillinger → Konti Connect → Ny integrasjon
Type: Simployer Employee Import
Fyll inn JwtToken, OrganizationUnitId, og default-nivåer for nye brukere
Klikk Test tilkobling — adapteren henter første side av ansatte og verifiserer 200-respons
Sett scheduler (typisk daglig om natten)
Lagre

3. (Valgfritt) Opprett fraværsimport-integrasjon¶

Ny integrasjon → Simployer Absence Import
Samme JwtToken og OrganizationUnitId som ansatt-importen
Bygg AbsenceTypeMapping ut fra ePortal-lønnsartene (se eksempel over)
Sett scheduler med fromDate/toDate-parametere, f.eks. fromDate = "i går", toDate = "i dag" for rullerende import

4. Test første kjøring¶

For ansatt-import:

Bruk Kjør nå. Følg kjøringsloggen
Verifiser at brukere har riktig userEmplNo, navn, e-post og ansettelsesdatoer

For fraværsimport:

Sett fromDate/toDate til en kort historisk periode
Verifiser at lønnsregistreringer er opprettet på riktig dato og lønnsart
Sjekk at wrDesc inneholder "Simployer Absence Import - <type> (Simployer ID: <guid>)" — denne brukes til duplikatsjekk

Mapping-detaljer¶

Ansatt-import¶

Nøkkel: Simployer EmployeeNumber ↔ ePortal userEmplNo
Navn: Person.FirstName + " " + Person.LastName → userFullname
Brukernavn (kun ved opprettelse): default = EmployeeNumber. Beholdes uendret ved oppdatering
E-post: først EmailAddresses med type work, ellers første tilgjengelige
Mobil: først PhoneNumbers med type mobile, ellers første tilgjengelige. Bare siffer (maks 15) lagres i userMobile
Deaktivert: IsActive = false → userDeActive = 1
Stillingsprosent: beholdes fra eksisterende bruker eller default 100 % ved opprettelse — Simployer leverer ikke prosent via dette API-et
Ansettelseshistorikk: ny periode opprettes hvis ingen finnes. Eksisterende periode oppdateres bare når EndDate endres (sluttet/reaktivert)

Begrensning: /v1/employees-endepunktet støtter ikke filter på organizationUnitId. Adapteren henter ALLE ansatte og logger en warning ved første side. Filtrering må gjøres lokalt hvis du har flere org-enheter.

Fraværsimport¶

Nøkkel for fraværstype: Simployer AbsenceType.Id (GUID) først, deretter AbsenceType.Name (case-insensitive) som fallback — wtNo lokal lønnsart
Ansattnummer: hentes fra Employee.EmployeeNumber (separat API-kall, caches lokalt for ytelse)
Periode-utvidelse: ett fravær med start–slutt blir til én wv_Time_WageReg-rad per dag (kan hoppes over for helger via SkipWeekends)
Timer per dag: DefaultWorkHoursPerDay × (userPercent/100) × (absencePercentage/100). userPercent hentes fra wv_User
Duplikatsjekk: før lagring sjekkes mot eksisterende rader med samme wrEmplNo + wrDate + wtNo + wrDesc LIKE '%Simployer ID: <guid>%'. Idempotent — kan kjøres flere ganger trygt
wrDesc-format: Simployer Absence Import - <type-navn> (Simployer ID: <guid>) — denne strengen brukes som duplikatnøkkel og må ikke endres manuelt
RegistrationBy: SimployerImport (sporbart i audit-loggen)

Frekvens og volum¶

Ansatt-import: paginering 100 per side. Typisk 100–1000 ansatte
Fraværsimport: paginering 100 per side, krever fromDate/toDate. Volum varierer
Person-data caches i minnet under én kjøring (ansatt-import) — første og siste rad i samme kjøring trenger ikke separat GET /v1/persons/<id>-kall
Employee-data caches under fraværsimport
3 retries med eksponentiell backoff (2s, 4s) ved 429 Too Many Requests eller timeout

Sikkerhet¶

JwtToken lagres kryptert (AES via EncryptionService)
Tokenet maskeres i debug-logger som ***MASKED***
Bruk en dedikert Simployer-API-konto (ikke personlig konto) — token-rotasjon må håndteres manuelt når Simployer roterer
RegistrationBy = "SimployerImport" gir sporbarhet i Time-loggen
Ansettelseshistorikk-feil blokkerer ikke bruker-opprettelse (warning, ikke error)

Vanlige problemer¶

`Authentication failed - check JwtToken`¶

Token er utløpt eller feil. Generer nytt token i Simployer Admin Center og oppdater integrasjonen.

Alle ansatte importeres — også fra andre org-enheter¶

Kjent begrensning. Simployer /v1/employees støtter ikke organizationUnitId-filter (adapteren logger en warning). Hvis kunden har flere org-enheter må man filtrere lokalt eller bruke en dedikert API-konto med begrenset tilgang.

`AbsenceTypeMapping not configured - no absence types will be imported`¶

Mappingen er tom eller mangler. Skru på DebugLogging, kjør én gang for å se hvilke ID-er/navn som finnes i kundens Simployer, og fyll inn mapping.

Fravær kommer på feil lønnsart¶

Simployer har endret navnet på fraværstypen. Bytt fra navn-basert til ID-basert mapping (GUID) — det er stabilt.

Fravær registreres dobbelt¶

Adapteren sjekker wv_Time_WageReg.wrDesc LIKE '%Simployer ID: <guid>%' for å unngå duplikater. Hvis noen har endret wrDesc manuelt brytes denne sjekken. Aldri rediger Simployer-genererte registreringer — slett og kjør på nytt.

Timer per dag stemmer ikke¶

Adapteren regner: defaultHours × (userPercent/100) × (absencePercentage/100). Sjekk wv_User.userPercent (stillingsprosent) — feil verdi her gir feil timer. Default DefaultWorkHoursPerDay = 7.5.

Ansattnummer i Simployer matcher ikke ePortal¶

Adapteren bruker userEmplNo som unik nøkkel. Hvis Simployer bruker f.eks. 1001 og ePortal 00001001 — synker ikke. Fiks: oppdater userEmplNo i ePortal eller importer på nytt.

"Employee X has no employee number — skipping"¶

Simployer-ansatten mangler ansattnummer. Legg inn i Simployer først.

Ansettelseshistorikk feiler men bruker er opprettet¶

Adapteren logger warning og fortsetter. Feilen påvirker wv_user_Employment — sjekk loggen for SQL-feilen.