Issue trackers (Jira, Linear, Freshdesk, Odoo, TOPdesk)

Wanneer een issue in FixControl wordt goedgekeurd, kun je 'm laten mirroren naar je bestaande tracker. De koppeling is bidirectioneel — comments en statuswijzigingen vloeien beide kanten op — zodat de tracker de source of truth blijft voor execution, en FixControl de source of truth voor intake en patch-flow.

Vandaag worden vijf trackers ondersteund: Jira (Atlassian Cloud en Server), Linear, Freshdesk (support desk), Odoo Helpdesk (odoo.com) en TOPdesk. Freshdesk, Odoo en TOPdesk gebruiken dezelfde provider-abstractie als Jira en Linear, dus alles hieronder over mirroren geldt ook — ze voegen er alleen een support-specifieke laag bovenop toe (gerelateerde-ticket-historie, gegoverneerde klant-replies en — voor Freshdesk — KB-oogst).

Jira

Auth-keuzes

• OAuth (3LO) — aanbevolen voor Atlassian Cloud. Site-admin geeft één keer consent; FixControl krijgt per-tenant tokens met refresh.
• API-token + e-mail — werkt voor zowel Cloud als self-hosted Data Center / Server.

OAuth-setup

1. In je Atlassian developer-console (developer.atlassian.com): My apps → Create → OAuth 2.0 (3LO).
2. Permissions (scopes): read:jira-work, write:jira-work, read:jira-user, manage:jira-project, offline_access.
3. Callback URL: https://<jouw-host>/api/auth/jira/callback.
4. Kopieer de Client ID en Secret en geef ze aan FixControl door tijdens de connect-flow.
5. Tenant-admin klikt Settings → Integrations → Jira → Connect, kiest de Atlassian-site, keurt het goed.
6. Na consent: kies een default project en issue type. Nieuwe gemirrorde issues gaan daarheen, tenzij overruled.

API-token-setup

1. In Atlassian: Profile → Security → API tokens → Create.
2. In FixControl: Settings → Integrations → Jira → Connect via API token, plak base URL (bv. https://acme.atlassian.net), e-mail en het token.

Wat wordt er gemirrord

• Issue-titel en -beschrijving (gerenderd als Atlassian Document Format).
• Prioriteit (gemapt van FixControl critical/high/medium/low naar Jira's prioriteitsschema).
• Labels (fixcontrol, plus eventuele FixControl-tags).
• Statuswijzigingen — wanneer FixControl het issue naar done zet, transitiet de Jira-issue naar de "done"-status die je hebt geconfigureerd.
• Comments — bidirectioneel.

Het FixControl-issue toont een deep link naar het Jira-issue. Het Jira-issue houdt een [FixControl: <id>]-referentie in de beschrijving.

Field-mapping

De default-mapping dekt de meeste teams. Heb je custom fields nodig (epic link, story points, custom enums), pas dan de field map aan in Settings → Integrations → Jira → Field mapping. Mapping is per-tenant — verschillende tenants kunnen naar verschillende schemas mappen.

Statussync terug (inbound webhook)

Jira kan issue-events pushen naar https://<jouw-fixcontrol-host>/api/integrations/jira/webhook. De endpoint authenticeert op een per-tenant webhook-token (een globale JIRA_WEBHOOK_SECRET werkt alleen als single-tenant-fallback); zonder geldige credentials weigert hij. Wat hij doet is bewust smal, hetzelfde contract als de Freshdesk-webhook:

• Hij synct alleen de gecachte tracker-status van het issue (het label dat de UI toont) — hij stuurt nooit de FixControl-workflowstatus aan.
• Een reopen (een done-issue dat terug naar een open status gaat) notificeert je managers en zet een REOPENED-vlag op het issue — opnieuw aanbieden, nooit opnieuw uitvoeren.
• Elke update ververst de gerelateerde-support-historie-cache, zodat de volgende agent-beurt de live comment-thread leest.
• Met de per-tenant-instelling JIRA_CAPTURE_LEARNING aan (standaard uit) wordt een transitie naar een done-status vastgelegd als project-gebonden learning — PII-geredigeerd, en alleen als het issue bij een project hoort.

Opgelost Jira-werk als bewijs

Voor Jira-tenants haalt triage een kleine set gerelateerde opgeloste Jira-issues op als support-context-bewijs — elk met waarom het matchte en een trust-score, bewijs om te wegen in plaats van een gezaghebbend antwoord. Op Jira Service Management worden interne comments uitgesloten van geëxtraheerde "oplossingen", zodat interne tekst nooit in agent-context lekt. De per-tenant-toggle JIRA_INGEST_CONVERSATION (standaard uit) voert daarnaast de recente comment-thread van het gekoppelde issue als AI-context op, PII-gescrubd en met JSM-interne comments gemarkeerd als notities — alleen leesrichting.

Linear

Auth-keuzes

• OAuth — aanbevolen voor teams.
• API key — per gebruiker, simpeler.

OAuth-setup

1. In Linear: Settings → API → OAuth applications → New application.
2. Redirect URI: https://<jouw-host>/api/auth/linear/callback.
3. Scopes: read, write, issues:create. Public app: uit.
4. Kopieer de Client ID en Client secret en geef ze aan FixControl door tijdens de connect-flow.
5. Tenant-admin klikt Settings → Integrations → Linear → Connect.
6. Kies een default team. Gemirrorde issues gaan daarheen, tenzij overruled.

API-key-setup

1. In Linear: Settings → API → Personal API keys → New key.
2. In FixControl: Settings → Integrations → Linear → Connect via API key, plak de key.

Wat wordt er gemirrord

Zelfde velden als Jira: titel, beschrijving (Markdown), prioriteit (gemapt naar Linear's 0–4), labels, status, comments. Statussen mappen naar Linear's workflow-states (started, completed, canceled, etc.).

Freshdesk

Freshdesk is de eerste support-desk-tracker van FixControl. Het speelt twee rollen tegelijk — het ticketsysteem waar FixControl issues naartoe mirrort, én een bron van support-kennis waar FixControl van leert — terwijl Freshdesk de source of record blijft voor het klantgesprek.

Setup

1. In Freshdesk: Profiel → Settings → Your API key (per agent) — kopieer 'm.
2. In FixControl: Settings → Integraties → Freshdesk → Verbinden, en vul in:

In productie moet het domein https zijn en een publieke host. Auth-fouten (401/403/404) zetten de verbinding op reconnect_required; tijdelijke 429/5xx worden opnieuw geprobeerd.

Wat er gemirrord wordt

• Titel → subject, body → description (omgezet naar veilige HTML), prioriteit gemapt naar Freshdesks 1–4-schaal, kind (BUG/FEATURE) naar het Freshdesk-tickettype.
• Een deep link beide kanten op: het FixControl-issue bewaart het ticket-id + de URL; het ticket draagt de FixControl-key (en, als het account-schema het toelaat, custom fields cf_fixcontrol_key / cf_fixcontrol_url).
• Een consistente tag-taxonomie zodat latere retrieval op classificatie kan matchen in plaats van trefwoorden: fixcontrol (herkomst), fc-severity-<prioriteit>, fc-type-<bug|feature>, fc-domain-<domein> (risicodomeinen), fc-system-<systeem> (geraakte componenten, automatisch geclassificeerd), en fc-source-slack als het ticket uit Slack-intake kwam. Klant-tags blijven behouden; e-mail-/telefoon-achtige tokens worden nooit getagd.

Gerelateerde support-historie (bewijs)

Wanneer FixControl een nieuw issue triageert voor een Freshdesk-tenant, haalt het een kleine, afgebakende set gerelateerde eerdere tickets op — met voorkeur voor de fc-*-tags, daarna afgeleide zoektermen, dan recent opgeloste tickets. Elk getoond ticket legt uit waarom het matchte en draagt een trust-score (opgelost + recent + inhoudelijke oplossingen scoren hoger dan verouderde of onopgeloste), zodat een operator of agent ziet "dit hebben we eerder afgehandeld, en zó liep het" — als bewijs om te wegen, nooit een gezaghebbend antwoord dat review omzeilt. Deze historie is een aparte bewijsbron van de docs-kennisbank; de twee worden nooit gemengd.

Opgeloste tickets → KB-concepten

Wanneer een ticket is opgelost (status Resolved/Closed) — automatisch wanneer een gemirrord FixControl-issue naar done gaat, of handmatig vanuit het suggesties-scherm — kan FixControl het publieke oplossingsantwoord van de agent omzetten in een concept voor de kennisbank. Kwaliteitspoorten draaien daarvóór (te kort / alleen-afsluitnotitie / generieke oplossingen worden overgeslagen), het ontdubbelt tegen bestaande kennis, en er wordt nooit automatisch gepubliceerd — een mens keurt het concept eerst goed. Support-content van klanten wordt nooit stilletjes gepubliceerde KB.

Statussync terug (inbound webhook)

Standaard leest FixControl de ticketstatus op aanvraag. Wil je dat Freshdesk updates pusht — zodat het FixControl-issue de live support-status toont en een resolve de KB-oogst meteen triggert — stel dan een inbound webhook in:

1. Zet FRESHDESK_WEBHOOK_SECRET op de FixControl-deployment (een lange willekeurige string). Zonder die secret is de endpoint uitgeschakeld (geeft 503) — hij draait nooit open.
2. Voeg in Freshdesk een Automation rule toe ("Ticket is updated" → actie "Trigger webhook") die POST't naar https://<jouw-fixcontrol-host>/api/integrations/freshdesk/webhook met een JSON-body met het ticket-id en de status, bijv. { "ticket_id": "{{ticket.id}}", "status": "{{ticket.status}}", "secret": "<de secret>" }. De secret mag ook in de header x-freshdesk-webhook-secret mee.

Wat het doet — en bewust niet doet:

• Het synct alleen de gecachte tracker-status van het issue (het label dat de UI toont). Het stuurt nooit de FixControl-workflowstatus aan: een support-agent die een ticket oplost kan het issue niet naar done duwen en governance omzeilen.
• Bij een resolve/close start het dezelfde door-mensen-goedgekeurde KB-oogst als hierboven (nog steeds pending, ontdubbeld, nooit auto-gepubliceerd).
• Versere context. Elke update ververst de gerelateerde-support-historie-cache voor dat issue, zodat de volgende agent-beurt de live ticketconversatie leest (een nieuwe klant-reply of agent-notitie) in plaats van een verouderde snapshot.
• Heropenen → opnieuw aanbieden, niet opnieuw uitvoeren. Gaat een opgelost/gesloten ticket terug naar open, dan notificeert FixControl de managers van de tenant (een issue needs review-melding, met deep-link) en zet een REOPENED-vlag zodat het opvalt in de lijst. Het draait géén agents opnieuw en heropent de governed workflow niet — het vraagt een mens om te kijken.
• Op de tijdlijn. Resolve en reopen verschijnen als mijlpalen op de operationele tijdlijn van de missie (naast intake → plan → goedkeuring → deploy), zodat de support-kant van het verhaal zichtbaar is in de replay. Gewone statuswijzigingen voegen geen ruis toe.
• De endpoint authenticeert alleen via de gedeelde secret (Freshdesk ondertekent webhooks niet), constant-time vergeleken; een onbekend ticket-id wordt bevestigd en genegeerd.

Voortgangsnotities op het ticket (outbound, opt-in)

Met de per-tenant-instelling FRESHDESK_SYNC_PROGRESS_NOTES aan (standaard uit) spiegelt FixControl missie-mijlpalen naar het gekoppelde ticket als privénotities — alleen zichtbaar voor support-agents, nooit voor de klant:

• Remediatieplan goedgekeurd — er wordt een fix voorbereid.
• Patch gereed — een patch is voorbereid en goedgekeurd.
• Fix toegepast — de wijziging is geland in de codebase.
• Deployment goedgekeurd — de fix wordt uitgerold (inclusief de rollout-promotie-uitkomst wanneer Argo Rollouts gekoppeld is).

Support ziet de remediatie-voortgang zonder Freshdesk te verlaten. De notities zijn strikt eenrichtingsverkeer en best-effort: een Freshdesk-storing blokkeert of draait nooit een FixControl-beslissing terug, afwijzingen en interne review-iteraties worden niet gespiegeld, en niets aan de notities raakt de governed workflow. Omdat de notities privé zijn (agent-only) is er geen klantgerichte communicatie — een publieke klant-reply zou via de comms-governance-goedkeuringsflow lopen, en dat doet deze feature bewust niet.

Two-way sync — het volledige plaatje (alles opt-in, alles standaard uit)

Naast de webhook en voortgangsnotities hierboven kan FixControl meer van de ticket-lifecycle in beide richtingen syncen. Elke sync is een aparte per-tenant-instelling, standaard uit, en geen ervan kan FixControls governed workflow aansturen of zonder menselijke goedkeuring iets naar de klant posten:

Inbound (Freshdesk → FixControl), via dezelfde webhook:

• FRESHDESK_INGEST_CONVERSATION — voer de recente ticketconversatie

(klant-replies + agent-notities, met e-mailadressen/telefoonnummers geredigeerd) als AI-context op het gekoppelde issue.

• FRESHDESK_SYNC_PRIORITY_INBOUND — een prioriteitswijziging op het ticket

werkt de issue-prioriteit bij.

• FRESHDESK_SYNC_TAGS_INBOUND + FRESHDESK_TAG_FLAG_ALLOWLIST — map

ticket-tags naar issue-vlaggen. Alleen tag=FLAG-paren die jij opsomt mappen ooit — een support-tag kan nooit een governance-vlag zetten die jij niet toestond.

• FRESHDESK_CSAT_RESURFACE — een negatieve tevredenheidsscore notificeert

je managers om nog eens te kijken.

• FRESHDESK_SYNC_MERGE_INBOUND — voegt support het ticket samen, dan wordt

het FixControl-issue gemarkeerd als duplicaat van het issue van het primaire ticket.

• FRESHDESK_SYNC_ASSIGNMENT_INBOUND + FRESHDESK_GROUP_ASSIGNEE_MAP —

hertoewijzing routeert het issue (responder-e-mail direct, of via jouw groep→assignee-map).

• FRESHDESK_SLA_RESURFACE — een (naderende) SLA-overschrijding notificeert

je managers — net als heropenen: opnieuw aanbieden, nooit opnieuw uitvoeren.

• FRESHDESK_CAPTURE_LEARNING — een ticket dat aan de support-kant is

opgelost wordt vastgelegd als project-gebonden learning (PII-geredigeerd; geen project ⇒ geen capture), zodat later werk op hetzelfde project het kan terugvinden.

Outbound (FixControl → Freshdesk):

• FRESHDESK_PUSH_STATUS_ON_RESOLVE — het oplossen van het issue zet het

ticket op Pending (wacht op klant). Nooit Resolved/Closed — support sluit de loop; tickets die support zelf al afhandelde blijven ongemoeid.

• FRESHDESK_REOPEN_ON_REGRESSION — een rollback of mislukte

productie-deploy van de geleverde fix heropent het ticket met een privénotitie, zodat support weet dat het klantprobleem toch niet is opgelost.

• FRESHDESK_PUSH_PRIORITY_ESCALATION — een kritieke escalatie aan de

FixControl-kant zet het ticket op Urgent (verlaagt nooit een prioriteit).

• FRESHDESK_CUSTOMER_REPLY_ON_RESOLVE — oplossen zet een

klant-reply-concept in de communicatie-reviewwachtrij. Er wordt nooit automatisch gepost: een mens keurt het concept goed (en bewerkt het meestal), en pas dan wordt het als publieke reply op het ticket geplaatst.

Grenzen

• Slack belt Freshdesk nooit rechtstreeks. De flow is altijd Slack → FixControl-intake → FixControl-issue → (optioneel) Freshdesk-ticket.
• Kubernetes / Argo en deployment-gates blijven ongewijzigd. Een Freshdesk-koppeling versoepelt geen enkele approval-gate.
• Support-geheugen en de KB blijven aparte systemen — opgehaalde ticket-historie is bewijs; de KB is door mensen goedgekeurde kennis.

Odoo Helpdesk

Odoo Helpdesk (odoo.com) wordt op dezelfde manier ondersteund als Freshdesk: de helpdesk blijft het systeem-van-record voor het klantgesprek, FixControl maakt en koppelt tickets, leest hun stage terug en leert van opgelost werk — achter dezelfde governance.

Setup

1. In Odoo: Voorkeuren → Accountbeveiliging → API-sleutels — maak een sleutel aan.
2. In FixControl: Settings → Integrations → Odoo → Connect, en vul in:

Helpdeskteams → projecten

Een Odoo-helpdeskteam kan aan een FixControl-project worden gebonden (bindingtype odoo_team, bij de integratie-bindingen van het project). De binding routeert tickets deterministisch: ziet de inbound webhook een ticket waarvan het issue nog geen project heeft, dan vult hij het project vanuit de teambinding — en alléén vanuit de binding. FixControl raadt in mirror-context nooit een project.

Wat er gemirrord wordt

• Titel → ticketnaam, body → description (omgezet naar veilige HTML), prioriteit gemapt naar Odoo's 0–3-schaal (laag … urgent), en het standaardteam als dat is geconfigureerd.
• Na het aanmaken leest FixControl de stage van het ticket terug uit Odoo — stages zijn vrij per team, dus het label wordt nooit geraden.
• Een referentie naar de FixControl-issue-key reist mee in de ticketbeschrijving; het FixControl-issue bewaart het ticket-id en de deep link.
• Odoo-tags worden niet gemirrord. Odoo-tags (helpdesk.tag) zijn databaserecords die al moeten bestaan voordat een ticket ernaar kan verwijzen; FixControl maakt geen tag-records aan, dus FixControl-labels worden geen Odoo-tags.

Outbound sync (opt-in, standaard uit)

• ODOO_SYNC_PROGRESS_NOTES — post FixControl-engineeringvoortgang (patch gereed, PR geopend, …) als interne chatter-notities op het gekoppelde ticket. Alleen voor agents, nooit voor de klant; strikt eenrichtingsverkeer en best-effort.
• ODOO_PUSH_STATUS_ON_RESOLVE + ODOO_RESOLVE_STAGE — het oplossen van het FixControl-issue zet het ticket op de stage die jij benoemt in ODOO_RESOLVE_STAGE (bijv. "Wacht op bevestiging"), case-insensitief gematcht tegen de stages van het team van het ticket. Omdat Odoo-stages vrij zijn per team, is de doelstage een expliciete operator-keuze — zonder geconfigureerde stage wordt er niets gepusht, en FixControl raadt nooit een stage. Een ticket dat support zelf al afhandelde (opgelost/gesloten) blijft ongemoeid.

Gegoverneerde klant-replies

Met ODOO_CUSTOMER_REPLY_ON_RESOLVE aan (standaard uit) zet het oplossen van een issue dat een Odoo-ticket mirrort een klant-reply-concept in de communicatie-reviewwachtrij — dezelfde goedkeuringsflow die elke AI-klantcommunicatie gebruikt. Er wordt nooit automatisch gepost: een mens keurt het concept goed, en pas dan wordt het geplaatst als klant-zichtbaar chatter-bericht (dat Odoo naar de volgers van het ticket e-mailt). Afwijzen of escaleren post niets.

Statussync terug (inbound webhook)

Wil je dat Odoo ticket-updates pusht:

1. Zet ODOO_WEBHOOK_SECRET op de FixControl-deployment (een lange willekeurige string). Zonder die secret is de endpoint uitgeschakeld (geeft 503) — hij draait nooit open.
2. Voeg in Odoo een Automatiseringsregel toe op helpdesk.ticket met een Send Webhook Notification-actie die POST't naar https://<jouw-fixcontrol-host>/api/integrations/odoo/webhook. De secret reist mee in de header x-odoo-webhook-secret of het body-veld secret, constant-time vergeleken.

Odoo's standaard webhook-payload draagt weinig meer dan het ticket-id, dus de payload is een trigger, nooit de source of truth: FixControl leest de gezaghebbende stage terug via de Odoo-API. Dezelfde bewuste grenzen als bij Freshdesk gelden:

• Alleen de gecachte tracker-status van het issue wordt gesynct — nooit de FixControl-workflowstatus.
• Heropenen → opnieuw aanbieden, niet opnieuw uitvoeren. Een afgehandeld ticket dat terug naar een open stage gaat notificeert je managers en zet een REOPENED-vlag; er worden geen agents opnieuw gedraaid.
• Elke update ververst de gerelateerde-support-historie-cache, zodat de volgende agent-beurt de live chatter leest in plaats van een verouderde snapshot.
• Met ODOO_CAPTURE_LEARNING aan (standaard uit) wordt een ticket dat een afgehandelde stage bereikt vastgelegd als project-gebonden learning — PII-geredigeerd; geen project, geen capture.

Gerelateerde support-historie (bewijs)

Voor Odoo-tenants haalt triage een kleine, afgebakende set gerelateerde afgehandelde tickets op als bewijs — elk met waarom het matchte en een trust-score, om te wegen in plaats van blind te vertrouwen. Chatter-berichten worden geclassificeerd op hun Odoo-subtype: alleen klant-zichtbare berichten van het team tellen ooit als "oplossing"; interne notities — en alles waarvan de classificatie faalt — worden uitgesloten, fail-closed, zodat interne notities nooit als oplossing in agent-context kunnen lekken. De per-tenant-toggle ODOO_INGEST_CONVERSATION (standaard uit) voert daarnaast de recente chatter van het gekoppelde ticket als AI-context op, PII-gescrubd en met interne notities gemarkeerd als notities — alleen leesrichting.

TOPdesk

TOPdesk (SaaS, https://<naam>.topdesk.net) wordt op dezelfde manier ondersteund als Freshdesk en Odoo: de servicedesk blijft het systeem-van-record voor het incident en het gesprek met de melder, FixControl maakt en koppelt incidenten, leest hun status terug en leert van opgelost werk — achter dezelfde governance.

Instellen

1. Log in TOPdesk in als de operator namens wie FixControl mag werken en maak een application password aan: Operatormenu → Mijn instellingen → Application passwords → Toevoegen. Kopieer 'm meteen; hij wordt niet opnieuw getoond. Let op de vervaldatum — TOPdesk zet die standaard op één jaar, en een verlopen wachtwoord laat de integratie om een reconnect vragen.
2. Geef die operator de rechten die FixControl nodig heeft: API-toegang, lezen/aanmaken/bewerken op eerste- en tweedelijnsincidenten, en lezen op Ondersteunende bestanden → Personen (om de melder op te zoeken).
3. In FixControl: Settings → Integrations → TOPdesk → Connect, en vul in:

FixControl verifieert de koppeling door de huidige operator terug te lezen uit TOPdesk. Een 401/403 wordt gemeld als authenticatiefout die een reconnect vraagt, niet als tijdelijke storing — dat is meestal een verlopen of ingetrokken application password.

Operatorgroepen → projecten

Een TOPdesk-operatorgroep kan aan een FixControl-project worden gebonden (bindingtype topdesk_operator_group, bij de integratie-bindingen van het project). De binding routeert incidenten deterministisch: ziet de inbound webhook een incident waarvan het issue nog geen project heeft, dan vult hij het project vanuit de groepsbinding — en alléén vanuit de binding. FixControl raadt in mirror-context nooit een project.

Wat er gemirrord wordt

• Titel → korte omschrijving (TOPdesk staat hier maximaal 80 tekens toe, dus een langere titel wordt ingekort), body → verzoek (omgezet naar de beperkte HTML die TOPdesk accepteert), en de operatorgroep uit de binding als die is geconfigureerd.
• Nieuwe incidenten worden als eerstelijnsincident aangemaakt.
• De FixControl-issuesleutel reist mee in het veld extern nummer van het incident; het FixControl-issue bewaart het incidentnummer (bijvoorbeeld I 2607 001) en een deep link.
• Na het aanmaken leest FixControl de behandelstatus van het incident terug uit TOPdesk — statusnamen zijn per instance geconfigureerd, dus het label wordt nooit geraden.
• Prioriteit en categorieën worden niet gemirrord. Prioriteit, urgentie, impact, categorie en subcategorie zijn configuratierecords in je eigen instance; FixControl maakt of raadt ze niet. De FixControl-prioriteit blijft leesbaar in de verzoektekst van het incident.
• Labels worden niet gemirrord — een TOPdesk-incident heeft geen vrij label- of tagveld.

Uitgaande sync (opt-in, standaard uit)

• TOPDESK_SYNC_PROGRESS_NOTES — plaatst FixControl-engineeringvoortgang (patch klaar, pull request geopend, …) als incidentacties die onzichtbaar zijn voor de melder. Alleen voor operators, nooit voor de melder; strikt eenrichting en best-effort.
• TOPDESK_PUSH_STATUS_ON_RESOLVE + TOPDESK_RESOLVE_STATUS — het oplossen van het FixControl-issue zet het incident op afgehandeld (completed). Benoem je in TOPDESK_RESOLVE_STATUS een behandelstatus (bijvoorbeeld "Afgemeld"), dan wordt die er ook op gezet, case-insensitief gematcht tegen de statuslijst van je eigen instance. Omdat TOPdesk-behandelstatussen van jou zijn, is de doelstatus een expliciete operator-keuze — zonder geconfigureerde status wordt alleen completed geschreven, en FixControl raadt nooit een statusnaam. Een incident dat de servicedesk zelf al afhandelde (completed of gesloten) blijft ongemoeid.

Gegoverneerde klant-replies

Met TOPDESK_CUSTOMER_REPLY_ON_RESOLVE aan (standaard uit) zet het oplossen van een issue dat een TOPdesk-incident mirrort een klant-reply-concept in de communicatie-reviewwachtrij — dezelfde goedkeuringsflow die elke AI-klantcommunicatie gebruikt. Er wordt nooit automatisch gepost: een mens keurt het concept goed, en pas dan wordt het geplaatst als incidentactie die zichtbaar is voor de melder. Afwijzen of escaleren post niets. Interne notities en melder-zichtbare replies reizen door dezelfde TOPdesk-actiestroom en verschillen alleen in die zichtbaarheidsvlag — precies waarom de zichtbare variant uitsluitend achter de goedkeuringsflow bestaat.

Een klant koppelen

De melder (caller) op het incident bepaalt wie de klant is, dezelfde rol die de requester op een Freshdesk-ticket speelt. Een klant koppelen aan een issue met een TOPdesk-koppeling zet de melder op het incident.

Status terugsync (inbound webhook)

TOPdesk kent geen webhooks die een applicatie voor je kan registreren, dus stel je de callback zelf in:

1. Zet TOPDESK_WEBHOOK_SECRET op de FixControl-deployment (een lange willekeurige string). Zonder die waarde is het endpoint uitgeschakeld (geeft 503) — het draait nooit open.
2. Ga in TOPdesk naar Modules → Gebeurtenissen en acties, voeg een gebeurtenis toe op incidentwijzigingen ("Kaart bewerken — Incident") en geef die een HTTP-actie die POST't naar https://<jouw-fixcontrol-host>/api/integrations/topdesk/webhook, met het gedeelde secret in de request-header. Aan onze kant wordt dat constant-time vergeleken.

Omdat je die payload zelf schrijft, behandelt FixControl 'm als trigger, nooit als source of truth: het leest het incident altijd terug via de TOPdesk-API voordat het handelt. Dezelfde bewuste grenzen als bij Freshdesk en Odoo gelden:

• Alleen de gecachete trackerstatus van het issue wordt gesynct — nooit de FixControl-workflowstatus.
• Heropenen → opnieuw agenderen, niet opnieuw uitvoeren. Een afgehandeld incident dat terugkeert naar een open status meldt dat aan je managers en zet een REOPENED-vlag; er worden geen agents opnieuw gedraaid.
• Elke update ververst de cache met gerelateerde supporthistorie, zodat de volgende agent-beurt de live incidentacties leest in plaats van een verouderde momentopname.
• Met TOPDESK_CAPTURE_LEARNING aan (standaard uit) wordt een incident dat een afgehandelde status bereikt vastgelegd als projectgebonden learning — PII-geredigeerd; geen project, geen vastlegging.

Er wordt niet gepolld: de webhook plus het teruglezen is de volledige inbound-route. Bijlagen worden niet gesynchroniseerd.

Gerelateerde supporthistorie (bewijs)

Voor TOPdesk-tenants haalt triage een kleine, afgebakende set gerelateerde afgehandelde incidenten op als bewijs — elk met waarom het matchte en een trust-score, om te wegen in plaats van blind te vertrouwen. Incidentacties worden geclassificeerd op hun zichtbaarheid voor de melder: alleen acties die zichtbaar zijn voor de melder kunnen ooit als "oplossing" tellen; acties die als onzichtbaar voor de melder zijn gemarkeerd — en alles waarvan de classificatie faalt — worden uitgesloten, fail-closed, zodat interne notities nooit als oplossing in agent-context kunnen lekken. De per-tenant-toggle TOPDESK_INGEST_CONVERSATION (standaard uit) voert daarnaast de recente acties van het gekoppelde incident als AI-context op, PII-gescrubd en met interne notities gemarkeerd als notities — alleen leesrichting.

Kiezen waar issues leven

Default blijft het FixControl-issue de source of truth. Mirroring is opt-in per issue op approval-moment — je kunt de project-default ook op "altijd mirroren" zetten.

Voor teams die Jira/Linear als hun primaire systeem draaien: enable mirror on creation zodat elk goedgekeurd FixControl-issue meteen in de tracker landt. De meeste engineers hoeven dan nooit rechtstreeks in FixControl in te loggen; ze werken in Jira/Linear, en FixControl regelt intake + patch-generatie achter de schermen.

Reconnect & rotatie

OAuth-tokens refreshen automatisch. Faalt een refresh (consent ingetrokken, app verwijderd), dan gaat de integratie naar reconnect_required. Het integrations health panel toont 'm; de admin klikt Reconnect en geeft opnieuw consent. Geen mirror-data gaat verloren — pending mirror-jobs queueën tijdens de downtime en replayen zodra de verbinding hersteld is.

FAQ

Kan dezelfde FixControl-tenant naar zowel Jira als Linear mirroren? Niet tegelijk voor hetzelfde issue, maar je kunt verschillende projects naar verschillende trackers configureren. Mirror-destination is een per-project setting.

Wat als mijn Jira-workflow geen "Done"-status heeft? Pas de status-mapping aan in Settings → Integrations → Jira → Status mapping. Kies de transitie die qua betekenis het dichtste komt. FixControl verzint nooit transities — 't kiest uit wat jouw workflow exposes.

Kan ik mirroring uitschakelen nadat 't is opgezet? Ja. Zet Active uit op de integratie. Reeds gemirrorde issues houden hun tracker-deep-link; nieuwe approvals maken geen tracker-issues meer. Heractiveren kan altijd.