Rå ↓ — Rå Markdown for AI-assistenter

Exsitec Data Link — bruk

Exsitec Data Link er en liten Windows-companion som lar et lokalt program — en Excel-arbeidsbok, et skript eller ditt eget verktøy — kjøre Visma Business NXT GraphQL- spørringer og mutasjoner uten å håndtere Visma-pålogging eller token selv. Den logger deg på Business NXT og eksponerer en styrt GraphQL-gateway på din egen maskin (localhost): du sender et GraphQL-dokument, Data Link kontrollerer Data Link- rettighetene dine for hvert selskap dokumentet berører, og videresender det til Business NXT under din egen Visma-pålogging. Svaret fra Business NXT kommer uendret tilbake.

Leser du dette med en KI-assistent? Denne siden er den komplette bruksreferansen. Du kan lime den inn i assistenten, eller gi den rå Markdown på /docs/usage.md?lang=nb (samme innhold, uten styling). Be den skrive forespørslene i språket du foretrekker — alt den trenger (endepunkter, headere, rettighetsregler, request- og response-formater og feilformatet) finnes nedenfor. For selve Business NXT-skjemaet (tabeller, felter, filtre) kan du vise den til Vismas Business NXT GraphQL-dokumentasjon eller be den kjøre en introspection-query gjennom gatewayen.

1. Kom raskt i gang

1. Installer og logg på. Installer Data Link, høyreklikk deretter på tray-ikonet (nede til høyre, ved klokken) → Sign in. Nettleseren åpner Visma Connect; logg på der.

2. Finn porten og nøkkelen. Les %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json — den inneholder loopback-port og en key per oppstart.

3. Si hei. GET http://127.0.0.1:{port}/v1/status med headeren X-DataLink-Key: {key}. Du får versjonen og om du er logget på.

4. Velg et selskap. GET /v1/companies lister selskapene du har tilgang til, med hva Data Link-tilgangen og tillatelsene dine lar deg gjøre i hvert av dem.

5. Kjør GraphQL. POST /v1/nxt/graphql med en standard GraphQL-body:

   { "query": "{ useCompany(no: 4926238) { generalLedgerAccount(first: 5) { items { accountNo name } } } }" }
   

   Svaret er Business NXTs egen { "data": …, "errors": … }.

2. Slik kjører den

• Data Link installeres per bruker og starter automatisk når du logger på Windows. Den kjører stille i bakgrunnen og viser et lite system-tray-ikon (nede til høyre på oppgavelinjen, ved klokken).
• Høyreklikk tray-ikonet for å:
  • se om du er Signed in eller Signed out,
  • Sign in / Sign out (pålogging åpner nettleseren til Visma Connect),
  • Open logs folder, Check for updates…, åpne denne bruksdokumentasjonen, og Quit.
• Du må være logget på før en GraphQL-forespørsel kan lykkes. Pålogging er interaktiv (et nettleservindu); etterpå fornyes sesjonen automatisk og overlever omstarter av Data Link.
• Companionen har ikke noe «gjeldende selskap». Hvert GraphQL-dokument navngir selskapene det arbeider med (useCompany(no: …)), så én kjørende companion betjener dem alle.
• Oppdateringer: tray → Check for updates… laster ned og installerer en ny versjon i ett trinn og starter Data Link på nytt (en varsling bekrefter den nye versjonen). En omstart gir ny port og nøkkel — se omstartssignalet i seksjon 3.

Hvor ting ligger

3. Snakke med det lokale API-et

Oppdagelse — finn porten og nøkkelen

Companionen velger en ledig loopback-port ved oppstart og skriver en liten oppdagelsesfil slik at betrodde lokale kallere kan finne den:

%LOCALAPPDATA%\Exsitec\DataLink\endpoint.json

{
  "port": 51234,
  "key": "b3d1…a9f0",
  "instanceId": "3f2a…",
  "processId": 18244,
  "protocol": "v1",
  "version": "2.0.0",
  "startedUtc": "2026-10-07T07:15:00.0000000+00:00"
}

• port — loopback-porten. API-base-URL-en er http://127.0.0.1:{port}.
• key — den delte hemmeligheten per oppstart. Send den på hver forespørsel (nedenfor). Den endres hver gang companionen starter på nytt, så les den på nytt — aldri lagre den. Tolk filen med en JSON-parser: tegn som + kan være skrevet som \u002B escapes.
• instanceId — identifiserer denne kjøringen av companionen («omstartssignalet»; se nedenfor).

Base-URL og versjonering

http://127.0.0.1:{port}/v1/…

Alle endepunkter ligger under prefikset /v1 (protocol-feltet i oppdagelsesfilen); GraphQL-gatewayen er /v1/nxt/graphql. Koble til 127.0.0.1 (loopback) — companionen lytter bare der.

Obligatoriske request-headere

Det finnes ingen selskapsheader: selskapet navngis inne i GraphQL-dokumentet.

Svarheadere

Omstartssignal. Hvis verdien av X-DataLink-Instance endres mellom kall, startet companionen på nytt. Les endpoint.json på nytt — både porten og nøkkelen kan ha endret seg.

Tidsavbrudd

• POST /v1/auth/login venter på at du fullfører nettleserpåloggingen (opptil 5 minutter).
• POST /v1/nxt/graphql tar så lang tid som Business NXT bruker; store lesinger kan ta mange sekunder. Gi HTTP-klienten en romslig timeout (minutter, ikke sekunder).

Sikkerhetsbegrensninger (hvorfor en nettleser-fetch avvises)

Companionen håndhever en loopback-tillitsgrense:

• Forespørsler med en Origin-header avvises (403) — derfor kan ikke en nettsides fetch() nå den. Kall den fra en lokal prosess (WinHTTP, HttpClient, curl, Python, PowerShell, en VBA WinHttp.WinHttpRequest), ikke fra nettleser- JavaScript.
• Host-headeren må være 127.0.0.1, localhost eller ::1.
• Manglende eller feil nøkkel returnerer 401.

4. Endepunktreferanse

Hver forespørsel trenger X-DataLink-Key. Response-bodyer fra selve Data Link er JSON med feltnavn i camelCase; POST /v1/nxt/graphql returnerer Business NXTs body uendret.

GET /v1/status

Helse og påloggingsstatus. Den fungerer når du er logget ut.

{
  "status": "ok",
  "instanceId": "3f2a…",
  "protocol": "v1",
  "version": "2.0.0",
  "provider": { "id": "business-nxt", "authenticated": true },
  "startedUtc": "2026-10-07T07:15:00+00:00"
}

POST /v1/auth/login

Starter den interaktive nettleserpåloggingen og returnerer når den er ferdig. Ingen body. Den åpner alltid nettleseren, også når du allerede er logget på — sjekk GET /v1/status først hvis du bare vil logge på ved behov.

{ "authenticated": true }

Hvis nettleserflyten ikke fullføres innen 5 minutter, feiler kallet med 503 unavailable (retryable: true); en pålogging som Visma Connect avviser, returnerer 401 unauthorized.

POST /v1/auth/logout

Avslutter Business NXT-sesjonen. Returnerer { "authenticated": false }.

GET /v1/companies

Selskapene gjeldende pålogging har tilgang til (Business NXTs availableCompanies), hvert med sin tenant (Visma.net-kunden det tilhører) og Data Link-tilgangen og -tillatelsene som gjelder der — slik kan du slå opp et selskaps navn til nummeret og se hva du kan gjøre før du prøver.

{
  "available": [
    { "id": "4926238", "name": "Exsitec BNXT Demo",         "tenantId": "4926230", "canRead": true, "canWrite": false, "canDelete": false },
    { "id": "6307615", "name": "Demo - Junge Byg Aps 9999", "tenantId": "2728812", "canRead": true, "canWrite": true,  "canDelete": false }
  ]
}

Et selskap listet med canRead: false er et selskap Visma-påloggingen din kan se, men som Data Link ikke åpner for deg (se seksjon 5).

POST /v1/nxt/graphql — gatewayen

Kjører hvilken som helst Business NXT GraphQL-query eller mutation. Bodyen er standard GraphQL-over-HTTP:

{
  "query": "query Accounts($company: Int!) { useCompany(no: $company) { generalLedgerAccount(first: 5) { items { accountNo name } } } }",
  "variables": { "company": 4926238 },
  "operationName": "Accounts"
}

Dette skjer:

1. Data Link parser dokumentet og finner ut hvert selskap det leser, skriver eller sletter i (seksjon 6).
2. Den kontrollerer Data Link-tilgangen og -tillatelsene dine for hvert av dem. Hvis noe ikke er tillatt, avvises hele dokumentet, og ingenting når Business NXT.
3. Ellers videresender den request-bodyen din uendret til Business NXT under Visma-påloggingen din og returnerer Business NXTs HTTP-status og body ordrett — inkludert Business NXTs egne errors og extensions (for eksempel extensions.vbnxt-trace-id).

{
  "data": {
    "useCompany": {
      "generalLedgerAccount": {
        "items": [ { "accountNo": 1010, "name": "Varesalg DK" }, { "accountNo": 1020, "name": "Anden omsætning" } ]
      }
    }
  },
  "extensions": { "vbnxt-trace-id": "…" }
}

Data Link fornyer Visma-tokenet ditt selv og venter og prøver på nytt når Business NXT svarer 429 Too Many Requests — begge deler er trygt fordi forespørselen ikke ble kjørt. Den prøver aldri på nytt ellers, så en mutation kan aldri kjøres to ganger; en 5xx fra Business NXT sendes tilbake til deg som den er.

5. Data Link-tilgang og tillatelser

Hva du kan gjøre gjennom Data Link administreres av Exsitec i NxtPlatform admin. Den gamle portalen for Config API-tildelinger er borte; docs/download-verten gir ikke tilgang.

Data Link begrenser bare hva din egen Visma-bruker kan gjøre — den gir aldri tilgang som Visma ikke ville gitt. Et selskap utenfor dine availableCompanies avvises selv om du har tilgang til tenanten.

Når du ikke har Skrive-tillatelse noe sted, ber Data Link også Visma om en skrivebeskyttet pålogging neste gang du logger på, slik at Business NXT selv også avviser mutations.

Tilgangen og tillatelsene dine hentes fra NxtPlatform når du logger på og oppdateres med noen minutters mellomrom, og lagres bare i minnet. Hvis NxtPlatform ikke kan nås, fortsetter siste svar å gjelde en kort nådeperiode; etter det — eller hvis Data Link aldri har nådd NxtPlatform siden den startet — avviser gatewayen med 503 unavailable (retryable: true) i stedet for å kjøre ukontrollert.

6. Hvordan rettighetssjekken leser et dokument

Sjekken arbeider på det parsede dokumentet, aldri på teksten, så aliaser, fragments og variabler kan ikke skjule noe. Den er bevisst streng:

Navngi selskapet: useCompany(no: {companyNo})

Alle selskapsavgrensede lesinger eller skrivinger ligger under en rot- useCompany(no: …). no er selskapsnummeret fra GET /v1/companies — en literal, en variabel eller en variabeldefault:

query Projects($company: Int!) {
  useCompany(no: $company) {
    orgUnit2(filter: { orgUnit2No: { _eq: 2130 } }) { items { orgUnit2No name } }
  }
}

(Business NXTs organisatoriske enheter får nye navn per selskap; i Demo - Junge Byg Aps 9999 er prosjekter orgUnit2.)

• Et dokument kan navngi flere selskaper, vanligvis med aliaser (demo: useCompany(no: 4926238) { … } junge: useCompany(no: 6307615) { … }). Hvert kontrolleres; én avvisning avviser hele dokumentet.
• no må løses til et heltall. Manglende no, null, en string eller en udefinert variabel avvises med 400 invalid_request.
• Hver operasjon i dokumentet kontrolleres, ikke bare den operationName velger.
• Fragments og inline fragments utvides; @skip og @include ignoreres, så en betinget selection teller fortsatt.

Hva hver del av et dokument trenger

Sikker skriving

Business NXT har ingen transaksjoner på tvers av tabeller. To vaner gjør en skriving forutsigbar:

• Sett onError: FAIL_TABLE på hver tabelloperasjon, slik at en dårlig rad avviser hele tabelloperasjonen i stedet for å skrive deler av den.
• For å få flere tabelloperasjoner til å lykkes eller feile samlet, bruk Business NXTs edit cache: kjør dem med useCompany(no: N, persistEditCache: true, partialRequestId: "…") og avslutt med finishEditCache(action: SAVE) (eller DISCARD). Hver forespørsel rettighetssjekkes for seg, som alle andre mutations.

7. Feil

Det finnes to typer feil, og begge bruker GraphQLs feilformat.

Business NXTs egne feil — en GraphQL-feil, en verdi Business NXT avviser, en rate limit — kommer tilbake nøyaktig slik Business NXT sendte dem: HTTP-statusen og bodyen { "data": …, "errors": [ … ] }.

Avvisninger fra selve Data Link (forespørselen nådde aldri Business NXT) har extensions.code:

{
  "errors": [
    {
      "message": "You have no Data Link Write permission for company 'Exsitec BNXT Demo' (4926238).",
      "extensions": { "code": "forbidden", "retryable": false, "instanceId": "3f2a…", "company": "4926238" }
    }
  ]
}

GET /v1/status, /v1/auth/* og GET /v1/companies rapporterer feilene sine i Data Links enkle envelope i stedet:

{ "code": "unauthorized", "message": "…", "retryable": false, "instanceId": "3f2a…" }

En ukjent path får en ren 404.

8. Forholdet til Business NXT GraphQL API

Data Link er Business NXTs GraphQL API, nådd gjennom din egen maskin:

• Samme schema, samme dokumenter. Alt du kan sende til https://business.visma.net/api/graphql, sender du til /v1/nxt/graphql, underlagt rettighetssjekken. Bruk Vismas Business NXT-dokumentasjon, eller introspection gjennom gatewayen, for tabeller, felter og filtre.
• Ingen token å håndtere. Data Link holder Visma Connect-påloggingen din og legger den på hver videresendte forespørsel; programmet ditt ser aldri et token.
• Styrt. Hvert dokument kontrolleres mot Data Link-tilgangen og -tillatelsene dine før det forlater maskinen, så Exsitec kan bestemme per tenant hvem som kan lese, skrive og slette gjennom Data Link.
• Ingenting formes om. Svaret er Business NXTs, byte for byte.

9. Bruke den fra Excel

Last ned og importer de to VBA-modulene nedenfor (Alt+F11 -> File -> Import File...). De er standardmoduler og bruker bare late binding, så ingen endringer i Tools -> References trengs.

Offentlig VBA-API

Knappemakromønster

Legg selskapsspesifikke innstillinger og knappemakroer i ExsitecDataLinkCustom.bas:

Public Const COMPANY_NO As Long = 4926238

Public Sub ListAccounts()
    On Error GoTo Failed
    Dim data As Object
    Set data = NxtQuery("query Accounts($company: Int!) { useCompany(no: $company) { generalLedgerAccount(first: 20) { items { accountNo name } } } }")
    WriteRows NxtItems(data, "useCompany.generalLedgerAccount"), ActiveSheet.Range("A1"), Array("accountNo", "name")
    Exit Sub
Failed:
    ShowNxtError
End Sub

For mutations kaller du samme NxtQuery-funksjon med et mutation-dokument. SDK-en prøver aldri mutations på nytt etter portendring eller transportfeil.

Autostart og pålogging

SDK-en leser %LOCALAPPDATA%\Exsitec\DataLink\endpoint.json. Hvis filen mangler eller /v1/status ikke svarer, starter den %LOCALAPPDATA%\Exsitec.DataLink\Exsitec Data Link.exe (eller current\DesktopDataLink.Host.exe) og venter opptil 30 sekunder.

Før hvert kall sjekker den /v1/status. Hvis du er logget ut, forteller Excel at nettleseren åpnes, kaller /v1/auth/login, og kaster deretter en feil som ber deg kjøre handlingen på nytt når påloggingen er fullført. Den opprinnelige GraphQL-forespørselen kjøres ikke automatisk etter pålogging.

VBA-feilnumre

Meldinger bruker språkinnstillingen i Data Link-tray (ui-settings.json) for engelsk, dansk, svensk og norsk, med engelsk som standard.

10. Eksempler i andre språk

PowerShell

# 1. Finn den kjørende companionen.
$ep   = Get-Content "$env:LOCALAPPDATA\Exsitec\DataLink\endpoint.json" | ConvertFrom-Json
$base = "http://127.0.0.1:$($ep.port)/v1"
$hdr  = @{ "X-DataLink-Key" = $ep.key }

# 2. Sjekk status / pålogging.
Invoke-RestMethod "$base/status" -Headers $hdr

# 3. Slå opp et selskapsnavn til nummeret, og se rettighetene dine der.
$companies = (Invoke-RestMethod "$base/companies" -Headers $hdr).available
$company   = $companies | Where-Object { $_.name -eq "Exsitec BNXT Demo" }

# 4. Kjør GraphQL.
$body = @{
    query     = 'query A($c: Int!) { useCompany(no: $c) { generalLedgerAccount(first: 5) { items { accountNo name } } } }'
    variables = @{ c = [int]$company.id }
} | ConvertTo-Json -Depth 5

$result = Invoke-RestMethod "$base/nxt/graphql" -Method Post -Headers $hdr `
    -ContentType "application/json" -Body $body
$result.data.useCompany.generalLedgerAccount.items

Python

Kun standardbiblioteket:

import json, os, urllib.request

path = os.path.join(os.environ["LOCALAPPDATA"], "Exsitec", "DataLink", "endpoint.json")
with open(path, encoding="utf-8-sig") as f:
    ep = json.load(f)
base = f"http://127.0.0.1:{ep['port']}/v1"

def call(method, path, body=None):
    headers = {"X-DataLink-Key": ep["key"]}
    data = None
    if body is not None:
        data = json.dumps(body).encode("utf-8")
        headers["Content-Type"] = "application/json"
    request = urllib.request.Request(base + path, data=data, headers=headers, method=method)
    with urllib.request.urlopen(request, timeout=300) as response:   # HTTPError inneholder GraphQL-feilene
        return json.load(response)

def graphql(query, **variables):
    return call("POST", "/nxt/graphql", {"query": query, "variables": variables})

companies = call("GET", "/companies")["available"]
junge = next(c for c in companies if c["name"] == "Demo - Junge Byg Aps 9999")

result = graphql(
    "query P($c: Int!, $p: Int!) { useCompany(no: $c) { orgUnit2(filter: { orgUnit2No: { _eq: $p } }) { items { orgUnit2No name } } } }",
    c=int(junge["id"]), p=2130)
print(result["data"]["useCompany"]["orgUnit2"]["items"])

11. Feilsøking

Fortsatt fast? Tray → Open logs folder og send den nyeste loggfilen til Exsitec-kontakten din — den inneholder ingen GraphQL-dokumenter, beløp, nøkler eller token.

12. Ordliste

Dette dokumentet beskriver det lokale v1-API-et. Companionen rapporterer kjørende versjon i GET /v1/status og på tray-menyen.