Table of Contents
This installer allows deploying in minutes everything you need to get started right away with all Write-back awesome capabilities. This is thus a simplified setup met for trials, if you want a full production installation please use the Manual Installation guide.
Start trying right away by downloading the latest version.
This manual provides guidelines on all software that is installed through the installation executable. The components installed through this executable are:
- Write-Back Extension App
- Write-Back Extension Trex
This executable will also create and initialize two services that are described in the table below.
|WritebackServer||Tomcat instance for Write-Back Extension App||8180/8143|
|WritebackDatabase||Postgres instance that supports the database needed for the application||5435|
Note: A redirect is defined to redirect 8180 port requests to the 8143 port.
To proceed with the installation make sure you have the following prerequisites:
- Operating System: Windows 10 or Windows Server 2016
- Available Disk Space: 900MB
- No applications running on ports: 8190 , 8143 and 5435 (none of these are standard)
- System Variables (Java): You need to add to PATH system variable the corresponding path to the javapath folder. If you're missing this one it should prompt when starting the installation a dialog for you to download it, anyway, this should be the url https://www.java.com/en/download/ to download this content which will setup the PATH automatically.
Visual C++ 2013 Redistributable Package: Additionally, as the installer sets up a PostgreSQL database, PostgreSQL requires the Visual C++ 2013 Redistributable Package, you can get it from here: https://support.microsoft.com/en-us/help/4032938/update-for-visual-c-2013-redistributable-package - In here you will be able to download vcredist_x64.exe or x86 depending on your system architecture, please choose a link from the first table that suits your locale. There is an alternative download link for the Visual C++ 2013 Redistributable Package https://www.microsoft.com/en-us/download/details.aspx?id=40784
- When installing on a separate box if possible please use a fixed ip, this will allow testing the extension from different PCs using the self-signed certificate.
If you don't have yet a valid license key go to https://writeback4t.com/ and click on "Let me try now >", this will take you through the process of getting a trial license.
When you are using the installer for the first time the Windows will prompt a warning claiming that the publisher is not of a trusted source. This is due to our Write-Back extension is not signed digitally by Microsoft.
To be able to proceed with the installation you need to:
After this, the installation will proceed as normal, follow the steps below!
Let's now follow the installer step by step for a new installation.
1. Double-click on Write-Back-64bit-X_X_X.exe. This will open a Welcome Page, click next to continue. If a Windows Defender page shows up please ensure you have downloaded the Write-Back extension from Xpand IT site and allow the program to run.
2. Agree with the terms of service and click next.
3. Choose the installation location and click next.
4. After checking the components that will be installed, click next.
5. On this screen you will do the necessary configuration:
Place the license key provided (mandatory). Click next.
6. The installation will start now. When finished press next.
7. You now have Write-Back successfully installed, press Done to finish the installer.
Let's start "Writing Back"!
You should be able to open now the Write-Back Extension in your Tableau Desktop, if you want to learn how to use it check our User Guide.
Logging into Write-Back
When you first start using the extension, you will need to log in. The default users that come with the installer are the following:
Connecting to the data you just inserted
After inserting data, you can find how to connect to the data you just inserted by using this section of the user guide. In the pop-form that shows up when connecting, find below a screenshot with the information to fill to connect to installed PostgreSQL instance.
- Server: localhost
- Database: writeback
- Username: writeback
- Password: writeback
With the release of Write-Back 2.0.1 we also added a new property to configure which is the external-url. The installer defaults the external URL to Configuring the external url - and change the external url to according to your network IP. Following the example in the previously linked page, you need to go to your writeback.trex file and retrieve the information needed to update the property. Be aware if you have dynamic IP attribution this address will eventually change when connecting to a different network. so it will only be possible to use locally. To enable other people to use it you'll need to follow the instructions - To solve this you need to find your new IPv4 address and edit writeback.trex file and this configuration property. Next, generate and install a new certificate (You can find more about this in the Troubleshooting section below).
After this, if you want your colleagues to use your Write-Back instance just pass them these 3 files:
They just need to double-click the cert.bat on an explorer window, in the same folder as cert.cer file. After this, they can start using the extension with the writeback.trex file. Share with them the User Guide!
To uninstall simply go to subdirectory Uninstaller and run the file uninstall.bat in admin mode.
Details About What is Installed
The installation takes place in a directory inserted by the user in the installer interface. If that directory does not exist, the installer creates it.
User setup is made with the configuration:
- hostname: localhost
- port: 5435
- database: writeback
- username: writeback
- password: writeback
In terms of postgresql the installer creates the following folders:
In terms of tomcat the installer creates the following folders:
For OpenJDK the installation creates a folder in the directory previously designated with the name jdk-13 containing the binaries to run tomcat instance.
An instance of the Write-Back Extension application is created with the following user-configured fields in the installer interface:
- Tableau Server URL
- License Key
In terms of Write-Back Extension the installer creates the following folder:
Trex file to use in Tableau with your current IPv4 address. Be aware if you have dynamic IP attribution this address will eventually change when connecting to a different network.
To solve this you need to find your new IPv4 address and edit writeback.trex file. Next, generate and install a new certificate (You can find more about this in the Troubleshooting section below).
|writeback.trex||%INSTALL_PATH%||Trex file to use in Tableau with the localhost. Use this if you are having trouble with your dynamic IP addresses but be aware that this one only works on your personal computer.|
For Uninstall the installation creates a folder in the directory previously designated with the name Uninstaller containing a bat and jar file. To uninstall run the file uninstall.bat in admin mode, this process will stop and delete both services and will delete all folders created by the installation.
The installation process also creates a few additional files to ease the processes of generating more certificates and the respective installation on other machines.
|cert_generator.bat||%INSTALL_PATH%||Executable file to generate certificate for your ip with the filename cert.cer|
|cert_install.bat||%INSTALL_PATH%||Executable file to install in your machine a certificate file with the filename cert.cer|
|cert.cer||%INSTALL_PATH%||Certificate file installed by the Write-Back installer in your local machine|
This is a simplified installation that uses non-standard ports to avoid conflicts, nevertheless, if you can across a port conflict you can still change the settings as per below.
Change Authentication Method
If you want to change the authentication method that the extension uses, follow the instructions under this section.
The methods that are available are:
If you use sites, you will have to specify which site you are using in the default.yml file, eg:
tableauServer: site: YourSite
- The Tableau Server authentication method is suitable if you login with username and password (on Tableau Server), but if you use SSO (SAML, Kerberos, OpenID) it will not be possible to use this method and we recommend using SSO as well for the extension. Regardless, it will be necessary to have a fall back authentication option as it is not possible to use SSO on Tableau Desktop, so the fall back allows users of Tableau Desktop to still log in to Write-Back. Possible options are ldap (AD) or inmemory.
Support for SAML and OpenID is on the roadmap.
Change PostgreSQL port
- Go to %INSTALL_PATH%/pgsql/data/ folder.
- Open postgresql.conf file in a text editor.
- Change the setting port for your desire port. (Ex: port = 5435).
- Restart the service WritebackDatabase.
- Go to %INSTALL_PATH%/apache-tomcat-8.5.45/webapps/twbe/WEB-INF/classes/ folder.
- Open config.yml file in a text editor.
- Change the setting database/url for the same desire port. (Ex: url: jdbc: postgresql://localhost:5435/).
- Restart the service WritebackServer.
Change tomcat port
- Go to %INSTALL_PATH%/apache-tomcat-8.5.45/conf/ folder.
- Open server.xml file in a text editor.
- Change the connector port.
- Restart the service.
- Go to %INSTALL_PATH% folder.
- Open writeback.trex file in a text editor.
- Change url port to new port that you previously defined.
Note: In file server.xml there are two connectors defined, the first one is http that is being redirected to the second one defined. The second connector is for https.
- Generate a new certificate (keystore type).
- Go to %INSTALL_PATH%/apache-tomcat-8.5.45/ folder.
- Overwrite the file keystore.keystore.
- Restart the service WritebackServer.
The current version already retains and installs the certificate automatically, but if you had a problem and could not install the certificate, follow these steps. You can identify that there is a certificate issue if you try to access Write-Back in Tableau Desktop for example and give a security error trying to access the url (see image below).
1. Go to the installation directory, open the writeback.trex file and get the link you have in the url attribute.
2. Open a browser and go to the link. It will give a warning that it is not safe to proceed. Click the "not secured" button on the left side of the url and then click on "Certificate".
3. This will open a popup, go to the second tab, Details. Click on "Copy the file ...".
4. Choose the Base-64 encoded X.509 format.
5. Save the certificate wherever you wish.
6. Double-click the saved file.
7. Click on "Install Certificate..."
8. Choose the "Local Machine" option and then click "Next".
9. Choose "Place all certificates in the following store" and click "Browse..."
10. Choose "Trusted Root Certification Authorities" option and click "Ok" After that click on"Next".
11. Click Finish in the next panel.
You should be able to open now the Write-Back Extension in your Tableau Desktop if you want to learn how to use it check our User Guide.
Change from HTTP to HTTPS
- In <installation_path>/apache-tomcat/conf/web.xml, at the bottom of the document, you need to add (see image below):
- Then, you have to go to the command prompt and type in ipconfig and take note of our ipv4 address
- You will need to place this address under the config.yml as below (please notice that the port also changes as well as http to https):
- Then, you need to run the following files:
- First, run the generator, then the install
- This will create a self-signed certificate so you can use the extension over HTTPS.
- Finally, just restart the WritebackServer service and you should now be able to access the extension over HTTPS.
The trex file you are using will also have to be updated, instead of localhost (if this was the case) you also need to change to your current IP address.
Bear in mind that if you have dynamic IP attribution the IP of your computer will change every time it connects to the network, therefore you'll have to repeat steps 3 to 6 again.
Add Tableau Server certificate to Java truststore
If you are getting an error when login in using Tableau Server Authentication that is related with SSL handshake, please follow the following steps. It is necessary to add the Tableau Server certificate to the java truststore.
- First, we need to get the Tableau Server certificate.
- An easy way to do that is to 2 to 5 of the Validate Certificate section. Be sure to remember the location of the certificate.
- After getting the certificate we need to add it to the truststore:
- Navigate to the installation folder
- Then navigate to: <installation_folder>\openjdk-8u252-b09\jre\lib\security
Notice that we have a cacerts file in here
- Open a command prompt as an administrator on this location
The following command imports the certificate to the cacerts truststore:
Code Block language bash
keytool -import -trustcacerts -alias tableaucert -file <path\to\the\tableau_certificate> -keystore <installation_folder>\openjdk-8u252-b09\jre\lib\security\cacerts
- When it prompts for a password, by default it is "changeit" (without the quotes)
- When it asks to trust the certificate, type "yes" (without the quotes)
- Now with the certificate in the truststore, we need to tell Tomcat to use that truststore
- Navigate to: <installation_folder>\apache-tomcat-8.5.45\bin
- Double click on WriteBackServerw.exe
- Go to the Java tab
- Under Java options, scroll to the bottom and add these two lines (changing the installation path to your own):
(again, by default, the cacerts password is changeit)
Code Block language bash
- It should look similar to this:
- Click Apply and OK.
After performing these actions, go to the services, restart WriteBackServer and you should now be able to login.