Freshdesk-integrasjon¶

Freshdesk er Konti sitt support-system. ePortal er integrert mot Freshdesk slik at KAI sin bug-rapport-funksjon automatisk oppretter tickets med skjermbilder, kontekst og AI-analyse — uten at brukeren må forlate ePortal.

Type: Server-side REST API (Freshdesk Tickets API v2) med Basic Auth (base64(apiKey:X)) Modul i ePortal: Credentials konfigureres i Systemadministrasjon → Systeminnstillinger → Freshdesk. Schedulert synkronisering av sakslisten settes opp som Konti Connect-integrasjonen «Freshdesk: sakssynkronisering» (se eget avsnitt) Implementasjon: FreshdeskService.cs, brukes av KAIBugReportController.cs

Hva integrasjonen tilbyr¶

Funksjon	Hva	Hvor i ePortal
KAI bug-rapport → ticket	Brukerens bug-rapport (tittel, beskrivelse, AI-analyse, console-/network-feil, skjermbilder, clipboard-paste) opprettes som ticket i Freshdesk via `POST /api/v2/tickets`	"Rapporter feil"-knapp i KAI-panelet
Auto e-post-fallback	Hvis Freshdesk ikke svarer (credentials mangler eller API gir feil) sendes ticket-innholdet som e-post til `hjelp@konti.no` via SMTP (`System.Net.Mail.SmtpClient`), gjennom e-post-sikkerhetsgaten (`IEmailSafetyGate`)	Automatisk på samme controller-flyt
Supportsaker → lokal buffer	Delta-synk leser saker via `GET /api/v2/tickets` og hele agentlista via `GET /api/v2/agents` (én gang per kjøring) inn i `wv_Freshdesk_TicketCache`. Saker slettet i Freshdesk hentes via `GET /api/v2/tickets?filter=deleted` (samme vannmerke) og fjernes fra bufferen. Saks-ansvarlig (`responder_id`) løses til agent-e-post/navn og kobles videre til en ePortal-bruker på e-post — vises som «Tildelt» i sakslisten	Support → Supportsaker (`/support/freshdesk`)
Dialogtråd i detaljvisningen	Når en sak åpnes hentes dialogen live via `GET /api/v2/tickets/{id}/conversations` (kundesvar, agentsvar og interne notater, kun ren tekst). Vedlegg eksponeres med Freshdesk sine tidsbegrensede signerte URL-er (bilder som miniatyrer, øvrige som lenker) — verken tråd eller vedlegg bufres lokalt	Support → Supportsaker → detaljpanelet
Test-tilkobling	Sysadmin kan validere credentials med "Test"-knapp uten å opprette en ticket — gjør `GET /api/v2/tickets?per_page=1`	Innstillinger → Systeminnstillinger → Freshdesk

Konti Connect har én Freshdesk-adapter: «Freshdesk: sakssynkronisering» (FreshdeskTicketSync, se avsnittet Schedulert synkronisering). KAI bug-rapport-flyten er fortsatt ren systeminnstillings-konfigurasjon. Det finnes ingen runtime-config-nøkkel freshdeskUrl i ui/ePortal.ui/src/assets/config.json.

Schedulert synkronisering¶

Sakslisten på Support → Supportsaker leses fra det lokale sakslageret (wv_Freshdesk_TicketCache), som oppdateres av en delta-synk. Synken kan kjøres på to måter — begge kjører nøyaktig samme kode (IFreshdeskSyncService.RunDeltaSyncAsync):

Måte	Hvordan
Manuelt	«Oppdater»-knappen på `/support/freshdesk` (`POST api/freshdeskticket/refresh`)
Schedulert	Konti Connect-integrasjonen «Freshdesk: sakssynkronisering» (type `FreshdeskTicketSync`, adapter `FreshdeskTicketSyncAdapter`) — anbefalt frekvens: hver time

Oppsett: Innstillinger → Konti Connect → Ny integrasjon → velg «Freshdesk: sakssynkronisering», sett schedule (f.eks. hver time) og aktiver. Integrasjonen trenger ingen egne credentials — API-nøkkel og URL leses fra systeminnstillingene Freshdesk.ApiUrl/Freshdesk.ApiKey, og synk-innstillinger (Freshdesk.SyncStalenessMinutes, Freshdesk.InitialSyncDays) styrer begge kjøremåtene. Eneste konfignøkkel er DebugLogging.

Samtidighet er trygg: vannmerket flyttes bare fremover, buffer-skrivingene er idempotente upserts, og synken stopper trygt (med bevart fremdrift) når Freshdesk sin rate-limit nærmer seg — en manuell og en schedulert kjøring som overlapper kan derfor ikke ødelegge data. Merk at kjøreloggen ikke viser antall saker per kjøring — resultatobjektet fra synken eksponerer kun tidsstempel og eventuell feil.

Tilgang¶

Hvem	Hva trengs
Hos Konti	Freshdesk-administrator-tilgang for å generere API-nøkkel. ePortal-systemadministrator (rollen i `wv_Userright`) for å lagre/teste credentials
Hos kunden	Ingenting — credentials lagres på Konti-siden av ePortal-installasjonen

Forutsetninger¶

Konti Freshdesk-instans er aktiv (https://<konti-instans>.freshdesk.com)
Freshdesk API-nøkkel generert på en dedikert service-konto
ePortal Systemadministrasjon → Systeminnstillinger er tilgjengelig

Konfigurasjon — feltforklaring¶

Lagres i wv_SystemConfiguration under kategori Freshdesk. Seedet via Migration_20260311120000.cs (bug-report-tabell) og lest av FreshdeskService.cs:54-55.

ConfigKey	Type	Påkrevd	Hva det betyr
`Freshdesk.ApiUrl`	URL	Ja	Freshdesk-instans-URL, f.eks. `https://kontias.freshdesk.com`. Brukes som `BaseAddress` for alle API-kall (FreshdeskService.cs:164)
`Freshdesk.ApiKey`	Passord (kryptert)	Ja	Freshdesk API-nøkkel. Kombineres som `base64(apiKey + ":X")` til Basic Auth-header (FreshdeskService.cs:168-170). Vises som `********` i UI etter lagring

Feltdefinisjonene i admin-UI (system-settings.component.ts:110-133) gir labels og hjelpetekst i SystemAdmin.settings.freshdesk*-i18n-nøkler.

Ticket-felter (sendes per bug-rapport)¶

Felt	Hvor det kommer fra	Standard
`subject`	`BugReport.Title`	—
`description`	HTML bygget av `BuildFreshdeskDescription(...)`: tittel, beskrivelse, AI-analyse, console-/network-feil, Claude Code-prompt	—
`email`	Innloggede brukers e-post	—
`priority`	`MapSeverityToFreshdeskPriority(BugReport.Severity)` — `low`→1, `medium`→2, `high`→3, `critical`→4 (KAIBugReportController.cs:629)	medium = 2
`status`	`BugReport.Status`	`new` = 2
`type`	Fast verdi `ePortal Timemodule` — må være én av verdiene i Freshdesk-kontoens tilpassede type-liste, ellers svarer Freshdesk `400 Validation failed` og ticket opprettes ikke	`ePortal Timemodule`
`attachments[]`	Skjermbilder, clipboard-paste og file-uploads (`image/png`)	—

Det er ingen custom-fields, ingen tag-mapping og ingen group_id/product_id som standard — de sendes kun hvis caller eksplisitt fyller dem i FreshdeskCreateTicketRequest.

Slik gjør du — oppsett¶

1. Generer Freshdesk API-nøkkel¶

I Freshdesk:

Logg inn på Konti sin Freshdesk-instans som administrator
Innstillinger → Agents → velg en dedikert service-agent (f.eks. eportal-bot@konti.no)
Profile settings → "Your API Key" → kopier nøkkelen

Bruk en dedikert agent, ikke en personlig konto. Tickets opprettes med denne agenten som "requester" hvis innlogget brukers e-post ikke matcher en Freshdesk-contact.

2. Lagre credentials i ePortal¶

I ePortal → Systemadministrasjon → Systeminnstillinger → Freshdesk-fanen:

Freshdesk.ApiUrl: https://kontias.freshdesk.com (eller riktig hostname)
Freshdesk.ApiKey: lim inn nøkkelen
Klikk Lagre

API-nøkkelen lagres som IsEncrypted = 1 i wv_SystemConfiguration og krypteres med AES via EncryptionService ved skriving.

3. Test tilkoblingen¶

Klikk Test tilkobling. ePortal kaller GET /api/v2/tickets?per_page=1 mot Freshdesk for å bekrefte at credentials er gyldige. Successful = grønn melding (FreshdeskService.cs:127-156). Ingen ticket opprettes ved test.

4. Verifiser bug-rapport-flyten¶

Åpne KAI-panelet → "Rapporter feil"
Fyll ut tittel + beskrivelse, valgfritt screenshot
Send — ticket-nummer + URL vises i bekreftelsen
Sjekk Freshdesk for den nye ticketen med riktige attachments

Hvis credentials ikke er lagret eller Freshdesk er utilgjengelig, sendes innholdet automatisk som HTML-e-post til hjelp@konti.no via SMTP (System.Net.Mail.SmtpClient), gjennom e-post-sikkerhetsgaten, i stedet (KAIBugReportController.cs TrySendEmailFallbackAsync/SubmitBugReportViaEmail).

Auth-flyt¶

ePortal-API
  │  request.ApiKey + ":X"  →  base64
  ▼
Authorization: Basic <base64>
  │
  ▼
POST https://<instans>.freshdesk.com/api/v2/tickets
  Content-Type: multipart/form-data
  fields: subject, description, email, priority, status, attachments[]
  ▼
Freshdesk
  │
  ▼
201 Created  →  { "id": <ticketId>, ... }
ePortal lagrer:
  wv_KAI_BugReport.FreshdeskTicketId
  wv_KAI_BugReport.FreshdeskTicketUrl = "<apiUrl>/a/tickets/<id>"

Connection timeout: 30 sekunder per kall (FreshdeskService.cs:172)
Ingen retry — feil håndteres ved e-post-fallback
Ingen rate-limit-håndtering eksplisitt; Freshdesk har default 1000 calls/time, mer enn nok for bug-rapport-volum

Sikkerhet¶

Freshdesk.ApiKey lagres kryptert (IsEncrypted=1 i wv_SystemConfiguration)
Bruk dedikert Freshdesk-service-agent — ikke gjenbruk personlige API-nøkler
Roter API-nøkkelen i Freshdesk ved personal-endringer og oppdater i ePortal
Skjermbilder fra bug-rapporter kan inneholde sensitiv data — sjekk databehandleravtalen og Freshdesk sin databehandleravtale
Test-tilkobling oppretter ingen ticket — trygt å bruke når som helst

Vanlige problemer¶

"Freshdesk credentials not configured. Skipping ticket creation."¶

Vises i ePortal-loggen. Begge feltene Freshdesk.ApiUrl og Freshdesk.ApiKey må være satt. Bug-rapport-controlleren faller automatisk tilbake til e-post-fallback (FreshdeskService.cs:57-61).

Test-tilkobling feiler med 401¶

API-nøkkel er feil eller utløpt. Sjekk Freshdesk service-agent → Profile settings → "Your API Key" og generér på nytt om nødvendig.

Vedlegg lastes ikke opp¶

Freshdesk har størrelses-grense (typisk 20 MB per vedlegg, 25 MB total per ticket). ePortal sender skjermbilder som image/png (FreshdeskService.cs:90) — store skjermbilder bør komprimeres før send.

Ticket opprettes men har feil priority¶

Sjekk at BugReport.Severity er en av low|medium|high|critical. Ukjente verdier mappes til prioritet 2 (medium) som default (KAIBugReportController.cs:629).

Tickets opprettes med feil agent / kunde¶

email-feltet sender ePortal-brukerens e-post som ticket-requester. Hvis e-posten ikke matcher en eksisterende Freshdesk-contact, oppretter Freshdesk en ny anonym contact. Verifiser at ePortal-brukere har korrekt e-post på wv_User.userEmail.

Forhold til intern Konti-support¶

Freshdesk er Konti sitt support-system. Eksterne kunder bruker det for support-henvendelser. Intern Konti-team bruker andre verktøy (Slack, Jira) — ikke Freshdesk for intern koordinering.

Relaterte sider¶

Systemadministrasjon — der credentials lagres
Integrasjoner — oversikt
KAI-modulen — bug-rapport-funksjonen som bruker Freshdesk
For utviklere — Connect API — alternativ for tredjeparts-integrasjon