Introductie

Deze handleiding beschrijft de stappen die nodig zijn om Zenvoices te koppelen aan een lokale Exact Multivers installatie.

Om de koppeling te realiseren dient Exact Multivers WebAPI geïnstalleerd te worden op een server van de klant. Dit is een software onderdeel van Exact. Het Zenvoices platform communiceert via het internet met deze software om gegevens uit te wisselen met Multivers. Exact Multivers WebAPI wordt gehost in IIS.

Wil je meer weten over hoe de koppeling beveiligd is en welke gegevens uitgewisseld worden? Lees dan dit artikel met meer informatie hierover.

Vragen, opmerkingen of tips? Neem contact met ons op via de chat, support@zenvoices.com of +31 (0)85 3038853.

Voorbereiding

Installatie eisen

Controleer vooraf of aan onderstaande eisen voldaan wordt:

Controleer of de klant werkt met Exact Multivers 10.8.1 of hoger.
Controleer of de klant beschikt over een server waarop Exact Multivers WebAPI geïnstalleerd kan worden (indien nog niet aanwezig).
Controleer of de systeembeheerder een WAN TCP poort open kan zetten in de firewall/router voor een reeks IP-adressen.
Controleer of de systeembeheerder toegang kan geven tot de server (via TeamViewer, AnyDesk of vergelijkbaar), zodat de installatie op afstand uitgevoerd kan worden (optioneel).
Is de Multivers API reeds geïnstalleerd? Overleg dan met de systeembeheerder of deze installatie aangepast kan worden of dat een nieuwe installatie nodig is. Als de bestaande installatie aangepast wordt, dan is deze niet meer bruikbaar voor andere applicaties wegens de ZenvoicesSecurityTokenHttpModule.

Voorbereidingen door systeembeheerder

Zie Voorbereiding door systeembeheerder voor Exact Multivers lokaal

Installatie

Benodigdheden

Van de systeembeheerder:
- WAN IP of hostnaam
- Doorgestuurde poort (indien deze afwijkt van standaard 4430)
- Toegang tot de server waarop de installatie uitgevoerd dient te worden
Van de klant:
- Multivers versie
- Multivers logingegevens van een gebruiker met volledige rechten
- Zenvoices logingegevens

Multivers WebAPI installatie

Download Multivers WebAPI uit het klantportaal van Exact. Let op dat de gebruikte versie compatible is met de Multivers versie van de klant. Gebruik minimaal versie 2.2.1.1
Volg de stappen uit hoofdstuk 2 van deze instructies om de installatie uit te voeren. Let op dat de WEBAPI database handmatig aangemaakt dient te worden in SQL Server. Stap 2.6 kan overgeslagen worden.
Installeer een geldig SSL certificaat en maak een HTTPS binding aan met dit certificaat. Indien de klant niet over een SSL certificaat beschikt, dan kan een certificaat van Zenvoices gebruikt worden. Neem contact op met support om dit certificaat op te vragen. Bekijk hier de handleiding voor het installeren van een SSL certificaat.
Open IIS-beheer, maak voor de Multivers WebAPI website een https binding aan voor poort 4430 en configureer hiervoor een SSL certificaat.
Verwijder daarna de http binding.
Voeg in web.config uit de WebAPI directory (normaal C:\Program Files (x86)\Exact\Multivers API\WebApi\Server) de volgende regel toe aan de appSettings node:

<add key=”Zenvoices.SecretToken” value=”randomkey“/>

Vervang randomkey door een willekeurig wachtwoord. Gebruik een minimale lengte van 32 tekens en genereer een wachtwoord dat alleen bestaat uit letters en cijfers om XML encoding fouten te voorkomen.
Download en open de refresh token generator, wijzig het server adres naar het adres van de Multivers WebAPI website en klik op ‘Get Refreshtoken’. Klik op Ja bij een waarschuwing over het SSL certificaat en login in Multivers met een gebruiker met volledige rechten. Hierna verschijnt een nieuw venster met het gegenereerde refresh token. Bewaar deze voor het vervolg van de installatie. Verschijnt het venster niet? Dan treedt er op de achtergrond een fout op. Open de API website in de browser, login en voer via API help een actie uit om de fout te achterhalen.
Download ZenvoicesSecurityTokenHttpModule.dll en plaats deze in de WebAPI bin directory (normaal C:\Program Files (x86)\Exact\Multivers API\WebApi\Server\Bin).
Voeg de volgende regel toe in web.config (zie stap 6) onder de node modules van system.WebServer:

<add name=”ZenvoicesSecurityTokenHttpModule” type=”Zenvoices.Modules.ZenvoicesSecretTokenSecurityHttpModule, ZenvoicesSecurityTokenHttpModule” />
Verifieer daarna via een browser dat de website niet meer toegankelijk is en een 403 foutmelding geeft. Dit bevestigt dat de extra beveiliging werkt.

Boekhoudpakket koppeling aanmaken in Zenvoices

Ga in Zenvoices naar Beheer / Omgeving / Boekhoudpakket koppelingen, Nieuw boekhoudsysteem koppelen, kies Exact Multivers en klik op “On-premise koppeling configureren”.
Vul de gevraagde gegevens in:
1. API url: de URL waarop de Multivers WebAPI bereikbaar is via het internet. Bijvoorbeeld: https://ipadresklant:4430/API/
2. Secret token: het in de web.config ingestelde secret token.
3. OAuth refresh token: het gegenereerde refresh token (zie stap 7).
Klik op Volgende om de koppeling te testen. Als de koppeling werkt, dan wordt een lijst met administraties getoond.
1. Indien fout 403 verschijnt, dan is het secret token ongeldig.
2. Indien fout 400 verschijnt, dan is het OAuth refresh token ongeldig.
3. Overige fouten: zie het hoofdstuk Bekende problemen.

Installatie documenteren

Documenteer de gegevens van de installatie en eventuele bijzonderheden. Gebruik hiervoor bijvoorbeeld dit template. Verstrek deze documentatie ook aan de systeembeheerder van de klant.

Documentatie

Bekende problemen

“In het dialoogvenster WebApiServer heeft het besturingselement ExistingSiteCombo een mogelijke waarde […] Dit is een ongeldige of dubbele waarde.” melding tijdens het installeren van de Multivers WebAPI

Controleer of de bindings van de standaard IIS website correct zijn. De oplossing is vaak het verwijderen van deze bindings. Doe dit alleen als deze niet gebruikt worden.

IIS HTTP error 500.19 met foutcode 0x800700c1

Dit is een algemene foutmelding, maar deze specifieke foutmelding geeft aan dat er een x86 vs x64 architectuur probleem is. Tijdens een eerdere installatie werd dit veroorzaakt door de Static en Dynamic compression modules. Door deze te unlocken op server niveau en daarna te verwijderen bij de IIS website werd dit opgelost.

Zie ook:

“The access token’s private signing key must be set” foutmelding

Controleer of de Exact Multivers WebAPI certificaten correct geïnstalleerd zijn. Let op dat je de .pfx bestanden dient te installeren en niet de .crt bestanden.

“CryptographicException ‘Keyset does not exist” foutmelding

Ken de juiste rechten toe aan de Exact Multivers WebAPI certificaten, zie stap 6 in hoofdstuk 2.5 van de handleiding van Exact.

Veel gestelde vragen

Als ik de IIS website bezoek verschijnt een HTTP 403 error. Is dit correct?

Ja, de aanvullende beveiligingsmodule van Zenvoices vereist dat een secret token wordt meegegeven als http header. Als je de website opent via een browser wordt deze niet mee verstuurd en verschijnt een http 403 error.

Hoe kan ik de koppeling lokaal testen?

Maak een backup van web.config uit de installatie directory. Open daarna web.config en verwijder de regel:

Sla het bestand op en open daarna de IIS website. Hierna dient onderstaande pagina weergegeven te worden:

Neem contact met ons op als deze pagina niet of niet juist verschijnt. Herstel na het testen het originele web.config bestand.

Klopt het dat een SSL certificaat waarschuwing verschijnt bij het openen van de website?

Ja, dit klopt en is volgens verwachting.

Kan Exact Multivers zonder problemen bijgewerkt worden naar een hogere versie?

Ja, de Exact Multivers WebAPI is volgens Exact (vooralsnog) compatibel met hogere versies. Neem bij twijfel contact met ons op.