Introduction
This manual describes the steps required to connect Zenvoices to a local Exact Multivers installation.
To realise the integration, Exact Multivers WebAPI must be installed on a server of the customer. This is a software component of Exact. The Zenvoices platform communicates via the internet with this software to exchange data with Multivers. Exact Multivers WebAPI is hosted in IIS.
Do you want to know more about how the integration is secured and which data is exchanged? Then read this article with more information about this.
Questions, comments or tips? Contact us via chat, support@zenvoices.com or +31 (0)85 3038853.
Preparation
Installation requirements
Check in advance whether the following requirements are met:
Check whether the customer works with Exact Multivers 10.8.1 or higher.
Check whether the customer has a server on which Exact Multivers WebAPI can be installed (if not already available).
Check whether the system administrator can open a WAN TCP port in the firewall/router for a range of IP addresses.
Check whether the system administrator can provide access to the server (via TeamViewer, AnyDesk or similar), so that the installation can be carried out remotely (optional).
Is the Multivers API already installed? Then consult with the system administrator whether this installation can be adjusted or whether a new installation is required. If the existing installation is adjusted, then it is no longer usable for other applications due to the ZenvoicesSecurityTokenHttpModule.
Preparation by system administrator
See Preparation by system administrator for Exact Multivers locally
Installation
Log in to the server of the customer and go through the steps below.
Requirements
From the system administrator:
WAN IP or hostname
Forwarded port (if this deviates from default 4430)
Access to the server on which the installation must be performed
From the customer:
Multivers version
Multivers login details of a user with full rights
Zenvoices login details
Multivers WebAPI installation
Download Multivers WebAPI from the customer portal of Exact. please note that the version used is compatible with the Multivers version of the customer. Use at least version 2.2.1.1
Follow the steps from chapter 2 of these instructions to perform the installation. please note that the WEBAPI database must be created manually in SQL Server. Step 2.6 can be skipped.
Install a valid SSL certificate and create an HTTPS binding with this certificate. If the customer does not have an SSL certificate, then a certificate from Zenvoices can be used. Contact support to request this certificate. View the manual for installing an SSL certificate here.
Open IIS manager, create an https binding for the Multivers WebAPI website for port 4430 and configure an SSL certificate for this.
Then remove the http binding.
Add the following line in web.config from the WebAPI directory (normally C:\Program Files (x86)\Exact\Multivers API\WebApi\Server) to the appSettings node:
<add key="Zenvoices.SecretToken" value="randomkey"/>
Replace randomkey with a random password. Use a minimum length of 32 characters and generate a password that only consists of letters and numbers to prevent XML encoding errors.
Download and open the refresh token generator, change the server address to the address of the Multivers WebAPI website and click on ‘Get Refreshtoken’. Click Yes on a warning about the SSL certificate and log in in Multivers with a user with full rights. After this, a new window appears with the generated refresh token. Save this for the remainder of the installation. Does the window not appear? Then an error occurs in the background. Open the API website in the browser, log in and perform an action via API help to determine the error.
Download ZenvoicesSecurityTokenHttpModule.dll and place this in the WebAPI bin directory (normally C:\Program Files (x86)\Exact\Multivers API\WebApi\Server\Bin).
Add the following line in web.config (see step 6) under the node modules of system.WebServer:
<add name="ZenvoicesSecurityTokenHttpModule" type="Zenvoices.Modules.ZenvoicesSecretTokenSecurityHttpModule, ZenvoicesSecurityTokenHttpModule" />
After that verify via a browser that the website is no longer accessible and shows a 403 error. This confirms that the additional security works.
Create accounting integration in Zenvoices
Go in Zenvoices to Manage / Environment / Accounting integrations, New accounting system integration, choose Exact Multivers and click on “Configure on-premise integration”.
Enter the requested data:
a. API url: the URL on which the Multivers WebAPI is reachable via the internet. For example: https://customeripaddress:4430/API/
b. Secret token: the secret token set in web.config.
c. OAuth refresh token: the generated refresh token (see step 7).
Click Next to test the integration. If the integration works, then a list with administrations is shown.
a. If error 403 appears, then the secret token is invalid.
b. If error 400 appears, then the OAuth refresh token is invalid.
c. Other errors: see the chapter Known issues.
Document installation
Document the data of the installation and any special details. Use for this for example this template. Provide this documentation also to the system administrator of the customer.
Documentation
Known issues
“In the dialog window WebApiServer the control ExistingSiteCombo has a possible value […] This is an invalid or duplicate value.” message during installing the Multivers WebAPI
Check whether the bindings of the default IIS website are correct. The solution is often removing these bindings. Only do this if they are not used.
IIS HTTP error 500.19 with error code 0x800700c1
This is a general error message, but this specific error message indicates that there is an x86 vs x64 architecture problem. During an earlier installation this was caused by the Static and Dynamic compression modules. By unlocking these on server level and then removing them at the IIS website this was solved.
See also:
“The access token’s private signing key must be set” error
Check whether the Exact Multivers WebAPI certificates are installed correctly. please note that you must install the .pfx files and not the .crt files.
“CryptographicException ‘Keyset does not exist’” error
Assign the correct rights to the Exact Multivers WebAPI certificates, see step 6 in chapter 2.5 of the manual of Exact.
Frequently asked questions
If I visit the IIS website, an HTTP 403 error appears. Is this correct?
Yes, this is correct. The additional security module of Zenvoices requires that a secret token is sent as http header. If you open the website via a browser this is not sent and an http 403 error appears.
How can I test the integration locally?
Make a backup of web.config from the installation directory. Then open web.config and remove the line:
<add name="ZenvoicesSecurityTokenHttpModule" type="Zenvoices.Modules.ZenvoicesSecretTokenSecurityHttpModule, ZenvoicesSecurityTokenHttpModule" />
Save the file and then open the IIS website. After this the page below must be shown:
Contact us if this page does not appear or does not appear correctly. Restore the original web.config file after testing.
Is it correct that an SSL certificate warning appears when opening the website?
Yes, this is correct and expected.
Can Exact Multivers be updated to a higher version without problems?
Yes, the Exact Multivers WebAPI is according to Exact (for now) compatible with higher versions. If in doubt, contact us.