Koppel-plugin testen als teamlid

Aan het einde van deze gids heb je toegang tot de gedeelde Exact-sandbox, staat de juiste variant van de Koppel-plugin in je eigen Outlook, heb je de testmails in je inbox, en weet je hoe je na een testronde opruimt en waar je kijkt als de plugin niet verschijnt of niet laadt.

Deze gids gaat over het opzetten en doorlopen van een testronde. Voor de checklist van de elf functionaliteiten (welke testmail hoort bij welke functie, en welke voorwaarde daarvoor in Exact moet staan) zie Reference: Koppel try-out testkit.

Wat je nodig hebt

  • Een eigen Outlook / Microsoft 365-mailbox (je persoonlijke Tapster-account volstaat).
  • Toegang tot de gedeelde Nordpass Vault van Tapster (daar staat het sandbox-wachtwoord; heb je die toegang niet, vraag het aan Roy).
  • Voor de troubleshooting-stappen: toegang tot de backoffice (Admin, Logging).

1. Toegang tot de gedeelde Exact-sandbox

We hebben een Exact Online developer-abonnement dat we als gedeelde sandbox gebruiken. Iedereen test op hetzelfde account:

  1. Ga naar https://start.exactonline.nl.
  2. Log in als info@koppel.io. Het wachtwoord staat in de Nordpass Vault (zoek op “Exact”). Zet het wachtwoord nergens anders neer, ook niet in notities of chats.
  3. Je zit nu in de sandbox-administratie. Hier mag je testdata toevoegen en opruimen.

Welke Exact-app hoort bij welke omgeving

Onder dit account zijn twee Exact Online-apps geregistreerd. De ClientId’s zijn geen geheimen; de bijbehorende secrets staan alleen in de deployment-config.

Exact-app Omgeving ClientId Redirect URI
Koppel Test dev (apiv7.dev.tapster.nl) cc45c2ec-3a6d-4ec0-abc8-2d1ad6a19f6b https://apiv7.dev.tapster.nl/exact/callback
Koppel productie (apiv7.tapster.nl) 78947938-8fbb-48e8-8da8-306367de8caf https://apiv7.tapster.nl/exact/callback

Je hoeft hier bij het testen niets mee te doen: de omgeving waar de plugin op draait bepaalt via welke app de OAuth-flow loopt. Het is wel het antwoord op de vraag “waarom werkt de Exact-login niet”: test je met de dev-plugin, dan loopt de koppeling via Koppel Test; test je met de productie-plugin, dan via Koppel.

Wat er aan testdata in hoort te staan

Om alle functionaliteiten te kunnen testen moet er in de sandbox een relatie klaarstaan met een contactpersoon (met het afzenderadres van de testmails, zie stap 3), een open verkoopkans, een project, een verkooporder, een offerte, de leverancier-vlag plus een inkooporder, en minimaal één urensoort. De volledige lijst met voorwaarden staat in Reference: Koppel try-out testkit.

Het inrichten van die vulling is belegd in issue #3091. Controleer bij je eerste login of de data er staat; ontbreekt er iets, vul het zelf aan (dat mag, het is een sandbox) of meld het op #3091.

2. De plugin installeren

Er zijn twee varianten van de plugin, met elk een eigen manifest-Id. Dit is de belangrijkste plek om fouten te maken: dev en productie door elkaar halen heeft eerder tot verkeerde testconclusies geleid (iets leek kapot in productie terwijl per ongeluk de dev-variant, of andersom, getest werd). Controleer dus altijd welke knop je in Outlook aanklikt.

  Dev (sideload) Productie (AppSource)
Naam in Outlook “Koppel (DEV)”, knop “Koppel DEV” “Koppel”
Manifest-Id 83069ba7-80d4-4179-a47f-87f0b9da6165 22bfb058-fa04-4d59-9279-df7ee1c41c82
Manifest-URL https://apiv7.dev.tapster.nl/public/assets/outlook-manifest.xml https://apiv7.tapster.nl/public/assets/outlook-manifest-production.xml
Praat met dev-API (Exact-app Koppel Test) productie-API (Exact-app Koppel)

Dev-variant sideloaden

  1. Open https://aka.ms/olksideload in de browser waarin je bent ingelogd op je Outlook-mailbox. Dit opent Outlook web met het dialoogvenster “Invoegtoepassingen voor Outlook”.
  2. Kies “Mijn invoegtoepassingen”, scroll naar “Aangepaste invoegtoepassingen” en kies “Aangepaste invoegtoepassing toevoegen”, “Toevoegen vanuit URL”.
  3. Plak de dev-manifest-URL uit de tabel hierboven en bevestig.
  4. Open een e-mail: in het lint (of het menu met de drie puntjes op de mail) staat nu de knop “Koppel DEV”.

Productie-variant installeren

De productie-variant installeer je zoals een klant dat doet: zoek “Koppel” in de AppSource-store (in hetzelfde invoegtoepassingen-dialoog onder “Alle apps”, of via https://appsource.microsoft.com).

Wil je het productie-manifest sideloaden (bijvoorbeeld om een store-distributieprobleem uit te sluiten): verwijder dan eerst de AppSource-installatie uit je postvak. Het productie-manifest heeft hetzelfde Id als de store-versie; twee installaties met hetzelfde Id in één postvak geven onvoorspelbare resultaten. Sideload daarna via dezelfde stappen als hierboven, maar met de productie-manifest-URL.

Beide varianten mogen wel naast elkaar in je postvak staan (verschillende Id’s). Dat is handig om dev en productie te vergelijken, maar let dan extra goed op welke knop je gebruikt.

3. Testmails aanvragen via /try-out

De testmails vraag je aan via de publieke try-out-pagina. Dat is dezelfde pagina die AppSource-reviewers gebruiken:

  1. Ga naar https://apiv7.tapster.nl/try-out (de pagina is tweetalig; met de NL/EN-schakelaar rechtsboven wissel je van taal).
  2. Vul je eigen Outlook / Microsoft 365-e-mailadres in.
  3. Rond de captcha af (Cloudflare Turnstile) en klik “Verstuur de voorbeeldmails”.
  4. Binnen ongeveer een minuut ontvang je elf testmails, waaronder een mail met PDF-bijlage en twee agenda-uitnodigingen. Elke mail begint met een instructieblok: wat je ermee test en welke voorwaarde daarvoor in Exact moet staan.

Goed om te weten:

  • Alle mails komen van één vast afzenderadres (de system-mailbox van de omgeving); je ziet het adres aan de ontvangen mails. Dat adres moet als contactpersoon in de sandbox staan, anders werkt het herkennen van een bestaand contact niet (rij 1 van de checklist).
  • Er zit een limiet op: maximaal 3 aanvragen per e-mailadres per 24 uur en maximaal 20 aanvragen per netwerk per 24 uur. Zit je aan de limiet, wacht dan of gebruik een ander adres.
  • Voor het testen van “nieuw contact aanmaken” is er geen testmail: stuur jezelf een mail vanaf een adres dat nog geen contactpersoon in de sandbox is (zie de checklist, sectie “Handmatig, zonder eigen mail”).

Doorloop vervolgens per mail de checklist uit Reference: Koppel try-out testkit.

4. Terugzetten na een testronde

Er is geen automatische reset. Een testronde laat sporen na op twee plekken: in de Exact-sandbox en in de plugin-status. Zo ruim je op:

In de Exact-sandbox (handmatig)

Loop in Exact de entiteiten langs die je tijdens de ronde hebt aangemaakt en verwijder ze:

  • Gearchiveerde documenten: de e-mail-PDF’s en bijlagen die je hebt opgeslagen staan als document op de relatie, contactpersoon, verkoopkans, offerte, order of het project waaraan je ze gekoppeld hebt.
  • Urenregels: verwijder ze bij voorkeur via de plugin zelf (open de betreffende testmail, tab Projecten, knop “Verwijderen”). Dat verwijdert de urenregel in Exact én onze eigen registratie in één keer. Verwijder je ze rechtstreeks in Exact, dan blijft de plugin voor die mail “al geregistreerd” tonen.
  • Activiteiten die je op de verkoopkans hebt aangemaakt.
  • Testcontacten en testorganisaties die je zelf hebt aangemaakt (bij het testen van “nieuw contact aanmaken”).

Laat de basisvulling uit stap 1 (de relatie met contactpersoon, verkoopkans, project, orders en urensoort) gewoon staan; die is voor de volgende testronde.

Wees erop voorbereid dat dit handwerk is: Exact heeft geen “verwijder alles van vandaag”-knop, dus je klikt de aangemaakte items stuk voor stuk weg. Houd tijdens het testen bij wat je aanmaakt, dat scheelt zoeken achteraf.

Plugin-status

De gearchiveerd-status van een mail is persistent: die staat in onze eigen database (collectie outlook_archived_emails, per Outlook-item), niet in Exact. Het document in Exact verwijderen reset de plugin dus niet. Zolang die status er staat is de archiveerkaart verborgen en staat de mail gemarkeerd in “Documenten” (die sectie klapt daarvoor automatisch open). Wil je dezelfde mail opnieuw archiveren, gebruik dan het ketting-icoon op die regel; dat wist alleen onze koppeling, het document in Exact blijft staan.

Voor een nieuwe testronde is dit meestal geen probleem: nieuwe testmails zijn nieuwe Outlook-items, dus de plugin begint er schoon mee.

5. Troubleshooting

De Koppel-knop verschijnt niet

  • Check welke variant je verwacht. De dev-knop heet “Koppel DEV”, de productieknop “Koppel”. Staat de variant die je zoekt wel geïnstalleerd in dit postvak (stap 2)?
  • Manifest-cache. Outlook cachet manifests agressief. Verwijder de add-in, voeg hem opnieuw toe, herlaad Outlook web (of herstart Outlook desktop) en geef het een paar minuten.
  • Gedeelde mailbox: “Ander postvak openen” laadt geen add-ins. Open je een gedeelde mailbox via “Ander postvak openen” (aparte browsertab of apart venster), dan verschijnen add-ins daar nooit. Voeg de gedeelde mailbox in plaats daarvan toe aan je eigen mappenlijst via “Gedeelde map of postvak toevoegen”. De add-in draait dan onder jouw eigen account: die moet zelf gelicentieerd zijn en Koppel geïnstalleerd hebben.
  • Oude Outlook-client. Op clients onder Mailbox 1.8 valt het manifest terug op een minimale variant: geen knop bij het opstellen van een mail (compose) en geen ondersteuning voor gedeelde mailboxen. Zie de sectie “Manifest: Mailbox 1.8-ondergrens” in de plugin-README.

De knop is er wel, maar het taskpane laadt niet (of blijft hangen)

  • Browser devtools. In Outlook web is het taskpane een iframe in de pagina: open devtools (F12) en kijk in de console en het netwerk-tabblad naar geblokkeerde of falende requests naar apiv7.tapster.nl of apiv7.dev.tapster.nl.
  • Reproduceer buiten Outlook. De plugin-UI kan in een gewone browser geopend worden met testparameters; dat maakt debuggen met devtools veel makkelijker. Zie Outlook-plugin testen buiten Outlook (werkt alleen op dev, niet op productie).
  • Serverlogs. In de backoffice staat het logvenster onder Admin, Logging (gevoed door het /logs-endpoint van de API). Zoek op outlook. voor de plugin-events. Let op: de buffer is kort en bevat alleen recente info/warn-regels, kijk dus meteen na het reproduceren.
  • Exact-koppeling kapot (“koppel opnieuw”-melding, steeds opnieuw moeten inloggen): volg Outlook-plugin: token-refresh debuggen.
  • Geen administratie (divisie) zichtbaar na het inloggen op Exact: dit is eerder veroorzaakt door een ontbrekende organization.administration-scope op de gebruikte Exact-app, niet door een codefout. Controleer de app-configuratie in het Exact App Center voor de app die bij jouw omgeving hoort (stap 1).

Kom je er niet uit, noteer dan: welke variant (DEV of productie), welke mail of stap, wat je zag in devtools en het tijdstip (voor de logs), en maak er een issue van.

Gerelateerd