Trimble-integrasjon

ePortal har tre separate Trimble-adaptere som kjøres via Konti Connect-modulen. Hver adapter er sin egen integrasjonstype og settes opp som en egen integrasjon med egen konfigurasjon og kjøreplan.

Adapter (TypeCode)	Retning	Protokoll	Datakilde / mål
TrimbleProjectSync	ePortal → Trimble NIS	SOAP (NIS Plan Service, port 7900)	wv_Time_Proj → NIS CreateProject/UpdateProject
TrimbleWorkOrderCostSync	ePortal → Trimble NIM	SOAP (NIM Service, port 7800)	wv_WorkOrder_ExternalCost → NIM AddKeyFigureValue
TrimbleMaterialImport	Trimble Cityworks → ePortal	REST (Cityworks API)	Cityworks uttak/mottak → wv_Stock_Transaction (+ EXEC wv_Stock_Balance_Update per transaksjon)

Type-koder og registrering: Migration_20260310120000.cs.

Autentisering: Adapterne mot NIS og NIM bruker brukernavn/passord direkte i SOAP-kallet. Cityworks-adapteren bruker en egen LoginName/Password-autentisering som returnerer en sesjonstoken som sendes som Authorization: cityworks {token}. Det er ingen OAuth mot Trimble — den eneste OAuth-en i bildet er KontiConnect sin egen OAuth dersom adapteren går via Integration API v2.

---

Tilgang

Hvem	Hva trengs
Konti-administrator i ePortal	Tilgang til Konti Connect-modulen (modul KontiConnect) for å opprette og kjøre integrasjoner
Hos kunden	Aktivt Trimble-abonnement, samt en eller flere tjenestebrukere — én for NIS, én for NIM og/eller én for Cityworks avhengig av hvilke adaptere som er aktivert
Nettverk	ePortal-API må nå NIS-/NIM-endepunkt over HTTPS og Cityworks-URL over HTTPS

---

TrimbleProjectSync — prosjekter fra ePortal til NIS

Sender prosjekter fra wv_Time_Proj til Trimble NIS. Nye prosjekter opprettes med CreateProject, og NIS returnerer en prosjekt-ID som lagres i projExtId. Eksisterende prosjekter (de hvor projExtId er satt) oppdateres med UpdateProject. Sporing skjer i wv_Time_Proj via projExtSyncStatus (0=venter, 1=synkronisert, 2=feil), projExtLastSynced og projSyncError.

Status 2 (feil) plukkes opp på neste kjøring og forsøkes på nytt. Når et prosjekt settes som skjult (projHidden=1), oppdateres status i NIS til 0 (lukket) — men kun hvis prosjektet allerede har en projExtId. Helt nye prosjekter som er skjult fra start, sendes ikke.

Konfigurasjon

Nøkkel	Påkrevd	Standard	Beskrivelse
NisUrl	Ja	—	URL til NIS SOAP-endepunkt, f.eks. https://host:7900/NISPlanService
NisUsername	Ja	—	NIS-brukernavn (sendes i SOAP-headeren)
NisPassword	Ja	—	NIS-passord
DefaultPlanType	Nei	Plan	Plan-itemtype som settes på nye prosjekter
DefaultAreaId	Nei	(tomt)	Settes som AREAID-extension på prosjektet
DefaultNetworkType	Nei	(tomt)	Settes som NETWORKTYPE-extension på prosjektet
DebugLogging	Nei	false	Skriver mer detaljert log per rad

Implementasjon: TrimbleProjectSyncAdapter.cs.

Eksempel ConfigurationJson:

{
  "NisUrl": "https://nisplan.example.no:7900/NISPlanService",
  "NisUsername": "<nis-tjenestebruker>",
  "NisPassword": "<passord>",
  "DefaultPlanType": "Plan",
  "DefaultAreaId": "OMRADE-1",
  "DefaultNetworkType": "LV",
  "DebugLogging": false
}

Feltmapping

Kilde i ePortal	Felt mot NIS	Påkrevd
wv_Time_Proj.projNo	externalname	Ja
wv_Time_Proj.projName	name	Ja
DefaultAreaId (konfig)	AREAID (extension)	Nei
DefaultNetworkType (konfig)	NETWORKTYPE (extension)	Nei
Retur fra NIS	lagres i projExtId	—

---

TrimbleWorkOrderCostSync — kostnader fra ePortal til NIM

Eksporterer eksterne kostnader fra wv_WorkOrder_ExternalCost til Trimble NIM som AddKeyFigureValue. Adapteren aggregerer alle kostnadsrader per arbeidsordre per konto og sender én samlet sum per gruppe. Fordi NIM sitt AddKeyFigureValue er idempotent — siste verdi erstatter forrige — kan adapteren trygt sende totalsummen på nytt etter at en kostnadsrad er slettet, lagt til eller endret.

Tracking ligger i wv_Integration_SyncTracking per individuell kostnadsrad. Status 2-rader plukkes opp igjen hvis RetryFailed=true. Når rader slettes lokalt, regner adapteren ut den nye totalsummen og sender oppdatert sum til NIM.

Rader som ikke kan sendes blir hoppet over:

• Arbeidsordre uten woExternalOrderNo (ingen ekstern kobling til NIM) → markeres som hoppet over.
• Kostnad uten kontonummer → markeres som hoppet over (NIM krever konto som KeyFigureKeyId).

Konfigurasjon

Nøkkel	Påkrevd	Standard	Beskrivelse
NimUrl	Ja	—	URL til NIM SOAP-endepunkt
NimUsername	Ja	—	NIM-brukernavn
NimPassword	Ja	—	NIM-passord
InvertAmount	Nei	true	Multipliserer aggregert beløp med -1 (kompatibel med PortalConnector som sendte negative tall)
RetryFailed	Nei	true	Tar med rader som tidligere feilet i neste kjøring
StartDate	Nei	(tomt)	Filtrerer kostnader til Date >= StartDate. Format yyyy-MM-dd eller yyyyMMdd
DebugLogging	Nei	false	Verbose logging

Implementasjon: TrimbleWorkOrderCostSyncAdapter.cs.

Eksempel ConfigurationJson:

{
  "NimUrl": "https://nim.example.no:7800/NimService",
  "NimUsername": "<nim-tjenestebruker>",
  "NimPassword": "<passord>",
  "InvertAmount": true,
  "RetryFailed": true,
  "StartDate": "2026-01-01",
  "DebugLogging": false
}

---

TrimbleMaterialImport — materialer fra Cityworks til ePortal

Henter materialuttak (Issue) og — valgfritt — materialmottak (Receive) fra Trimble Cityworks via REST og importerer dem i ePortal. For hvert lager (storeroom) hentes alle transaksjoner siden StartDate/DaysBack, anriket med materialinformasjon (produktkode, beskrivelse, enhet, kost) via Cityworks MaterialCosts-endepunkt.

Lagermapping skjer i tre nivåer:

1. JSON-mapping i konfignøkkelen StoreRoomMapping, f.eks. {"EKSTERNT":0,"HØYDALSMO":1,"MÅLERLAGER":2,"TREUNGEN":3}. StockNo=0 betyr at lageret hoppes over.
2. wv_Extcache_Stock.ExtCode — kobling fra Cityworks-kode til intern StockNo.
3. DefaultStockNo brukes hvis ingen av de to over treffer.

Sporing skjer i wv_Integration_SyncTracking. Transaksjoner uten WorkOrderId hoppes over og logges som warning.

Konfigurasjon

Nøkkel	Påkrevd	Standard	Beskrivelse
CityworksBaseUrl	Ja	—	Cityworks API-base, f.eks. https://acme.cityworks.com
CityworksUsername	Ja	—	Cityworks LoginName
CityworksPassword	Ja	—	Cityworks-passord
DaysBack	Nei	7	Hvor langt tilbake i tid det skal hentes (brukes hvis StartDate ikke er satt)
StartDate	Nei	(tomt)	Fast startdato yyyy-MM-dd. Overstyrer DaysBack
DefaultStockNo	Nei	1	Fallback-StockNo når lager ikke ligger i mapping
StoreRoomMapping	Nei	{}	JSON {"<CityworksCode>": <StockNo>, ...}. 0 = hopp over
ImportReceives	Nei	true	Hent også Receive-transaksjoner (mottak)
MaxPageSize	Nei	200	Paginering mot Cityworks
CreatedBy	Nei	1	Bruker-ID som skrives i wv_Stock_Transaction.CreatedBy
EnableWoDimensionLookup	Nei	false	Slår opp WoDepNo/WoProjNo fra wv_WorkOrder for hver transaksjon
DebugLogging	Nei	false	Skriver rå JSON for transaksjoner og MaterialInfo til loggen

Implementasjon: TrimbleMaterialImportAdapter.cs. REST-klient: TrimbleCityworksApiService.cs.

Eksempel ConfigurationJson:

{
  "CityworksBaseUrl": "https://acme.cityworks.com",
  "CityworksUsername": "<cityworks-tjenestebruker>",
  "CityworksPassword": "<passord>",
  "DaysBack": 7,
  "DefaultStockNo": 1,
  "StoreRoomMapping": "{\"EKSTERNT\":0,\"LAGER1\":1,\"LAGER2\":2}",
  "ImportReceives": true,
  "MaxPageSize": 200,
  "EnableWoDimensionLookup": false,
  "DebugLogging": false
}

Auth-flyt for Cityworks: I motsetning til NIS/NIM (som bruker Basic Auth direkte i SOAP-headeren) gjør Cityworks først et POST /Services/General/Authentication/Authenticate med LoginName/Password, mottar en sesjons-token, og sender deretter Authorization: cityworks {token} på alle påfølgende REST-kall (TrimbleCityworksApiService.cs).

---

Slik gjør du — sette opp en Trimble-adapter

1. Be Trimble-leverandøren om endepunkt-URL og en tjenestebruker for den/de aktuelle modulene (NIS, NIM, Cityworks).
2. For materialimport: kartlegg hvilke Cityworks-lagerkoder som skal mappes til hvilke StockNo i ePortal. Sjekk eksisterende lagre med SELECT StockNo, StockName FROM wv_Extcache_Stock.
3. I ePortal: åpne Konti Connect → Integrasjoner og opprett en ny integrasjon. Velg adaptertype (TrimbleProjectSync, TrimbleWorkOrderCostSync eller TrimbleMaterialImport).
4. Fyll inn konfigurasjonsnøklene fra tabellen for den valgte adapteren. Bruk Test tilkobling for å verifisere brukernavn/passord (kun ProjectSync har en TestConnectionAsync som faktisk pinger NIS).
5. Kjør første gang manuelt via Kjør manuelt og verifiser at loggen er grønn før du legger på en kjøreplan.
6. Repeter for de andre adapterne hvis flere skal være aktive samtidig — hver adapter er en egen integrasjon med eget konfig-sett.

---

Vanlige problemer

"Mangler påkrevd konfigurasjon: NisUrl/NisUsername/NisPassword …"

Vises i integrasjonsloggen og er hard stopp. Alle tre verdiene må stå før kjøring. Samme prinsipp for NimUrl/NimUsername/NimPassword (CostSync) og CityworksBaseUrl/CityworksUsername/CityworksPassword (Material).

"CreateProject returnerte ikke prosjekt-ID"

Adapteren satte status 2 på prosjektet og lagret feilen i projSyncError. Sjekk:

• At NIS-brukeren har skriverettigheter til området.
• At DefaultPlanType matcher en gyldig plan-itemtype i NIS.
• Loggen i Konti Connect for SOAP-responsen.

"{n} kostnader hoppet over — arbeidsordre mangler ekstern kobling (woExternalOrderNo)"

Arbeidsordrene mangler woExternalOrderNo i ePortal, slik at NIM ikke vet hvilket prosjekt kostnaden hører til. Fyll inn ekstern ordrenummer på arbeidsordren og kjør på nytt.

"{n} kostnader har null kontonummer — hoppes over"

wv_WorkOrder_ExternalCost-raden mangler kontonummer. NIM krever konto som KeyFigureKeyId — uten det hoppes raden over. Korriger kontonummer på kostnadsraden.

"Cityworks autentisering feilet: {melding}"

Returnert av Cityworks Authenticate-endepunktet. Sjekk CityworksUsername/CityworksPassword, samt at base-URL er riktig (skal være rot-URL, ikke en spesifikk service-sti).

"Transaksjon TM-{id} fra '{lager}' mangler WorkOrderId — hoppes over"

Cityworks-transaksjonen mangler tilknyttet arbeidsordre i Cityworks. Korriger i Cityworks og kjør på nytt — neste kjøring vil plukke opp raden.

"Ugyldig StoreRoomMapping JSON"

Verdien i konfignøkkelen er ikke gyldig JSON. Adapteren faller tilbake til tom mapping og bruker DefaultStockNo for alt. Rett opp JSON-syntaksen (gyldig eksempel: {"EKSTERNT":0,"LAGER1":1}).

---

Relaterte sider

• Konti Connect-modulen
• Sette opp ny integrasjon
• Kjøre integrasjon manuelt
• Lese kjøringslogg
• Integrasjoner — oversikt