Introduction

This installation manual guides you through the installation of the Tableau Server MailScheduler. The MailScheduler can connect to your (on-premise) Tableau Server or your Tableau Online instance. The MailScheduler needs to be installed on your premises (or private cloud). This manual elaborates on the installation of the Mail Scheduler solution for the Windows platform.

Skill level

To follow along, knowledge of installing and configuring of databases and web servers on windows is required.

Operating System

This manual is written for Windows Server 2016 and up.

Scope

The following topics will be outside the scope of this manual: Configuring the firewall Webserver: 80/443 MySQL: 3306 Points of attention Avoid using passwords containing a period “.” This might break connections and result in unexpected behaviour.

01. Requirements

To succesfully install the Tableau Server MailScheduler you have to pass these requirements:

• Windows Server
• Fixed IP address
• Internal DNS
• At least 8gb RAM
• 2 cpu or more (preferred)
• 50gb hdd space on the server

The installation of the Tableau Server MailScheduler includes the installation of a XAMPP server to host the application.

Download your copy of XAMPP over here: https://www.apachefriends.org/download.html

With this download you are able to proceed the general installation process described in chapter 1-5 of this manual.

The files and license key needed during the installation will be provided via our Enterprise Customer portal once you purchased a subscription. These files allow you to complete the chapters 6-9 of this manual.

02. Overview Installation process

The Tableau Server Mail Scheduler can connect to either Tableau Server (Based on Trusted Ticket Mechanism) or to Tableau Online (Based on Personal Access Token). Both installation procedures are described in this chapter.

02.1 Tableau Server

The installation involves multiple steps. These are:

1. Add the IP address of your MailScheduler Server to your Tableau Trusted hosts
2. Install XAMPP
3. Configure Windows Task Scheduler
4. Install Mail Scheduler Application on XAMPP
5. Configure
   • Database
   • Environment
   • Users

02.2 Tableau Online

The installation for Tableau Online involves multiple steps. These are:

1. Obtain a Personal Access token of a user that is able to at least view all the dashboards you want to send with the MailScheduler (Read Only service account)
2. Install XAMPP
3. Configure Windows Task Scheduler
4. Install Mail Scheduler Application on XAMPP
5. Configure
   • Database
   • Environment
   • Users

03. Tableau Server: Trusted host

The MailScheduler uses the Tableau Server Trusted ticket mechanism to access the published dashboards. The hostname or IP address of the Mail Scheduler server (as installed in step 2) must be added to the list of trusted hosts on the Tableau Server.

More information on the Trusted Ticket mechanism can be found at Tableau Online Help:

https://onlinehelp.tableau.com/current/server/en-us/trusted_auth_trustIP.htm

The Trusted Ticket Mechanism uses either IP addresses or hostnames. The trusted hosts must have a static IP address in both cases. IP Addresses can be found by using the ipconfig command in a command box on the Mail Scheduler server.

03.1 Enable trusted tickets (tabadmin)

The first step in setting up trusted authentication is to configure Tableau Server to recognize and trust requests from one or more web servers:

Open a command prompt as an administrator on your Tableau Server (right click and select “Run as Administrator”) and navigate to your Tableau Server bin directory (for example, C:Program FilesTableauTableau Server10.5bin).

First have a look what IP’s are already trusted. The SET command we will use later on will overwrite your current config so better backup/store your trusted hosts in a text file!

tabadmin get wgserver.trusted_hosts

This will echo the content of your trusted hosts configuration.

tabadmin get wgserver.trusted_hosts >> currentconfig.txt

will store all trusted hosts in a text file called currentconfig.txt

03.2 Stop Tableau Server

In order to change the content of your trusted hosts configuration you have to stop the Tableau Server. Note that all activities and processes on the Tableau Server will be discontinued during this step! It is best to execute these steps during service hours for your server to minimize end user disruptions. The process of stopping and starting the Tableau Server can take up to several minutes, depending on number and size of workbooks and datasources. To stop the Tableau server type the following command to stop Tableau Server:

tabadmin stop

03.3 Set trusted IP addresses

After stopping the Tableau Server successfully it is time to add our new MailScheduler Server to the list of trusted hosts. You can use the currentconfig.txt file we saved in previous steps with the GET command to copy the already present trusted hosts to your command below! The format of the command you have to run is:

tabadmin set wgserver.trusted_hosts ""

In the command above, should be a comma-separated list of the IPv4 addresses or host names of your web server(s).

Note: The values you specify completely overwrite any previous setting. Therefore, you must include the full list of hosts in the set command every time you run it. (You cannot append the list of hosts by running the set command repeatedly.) For example:

tabadmin set wgserver.trusted_hosts "192.168.1.101, 192.168.1.102, 192.168.1.103"

or

tabadmin set wgserver.trusted_hosts "webserv1, webserv2, webserv3"

Notes:

• The comma separated list should be in quotes, with one space after each comma.
• The web servers you specify must use static IP addresses, even if you use host names.

If you have one or more proxy servers between the computer that is requesting the trusted ticket (one of those configured in step 2, above) and Tableau Server, you also need to add them as trusted gateways.

03.4 Save configuration and start Tableau Server

Type the following command to save the changes to all the server configuration files:

tabadmin config

Finally, type the following command to start the server again:

tabadmin start

03.5 Trusted tickets using TSM

Check Tableau Help online for further information

• Open TSM in a browser: https://:8850. For more information, see: https://onlinehelp.tableau.com/current/server/en-us/sign_in_tsm.htm
• Click User Identity & Access on the Configuration tab and then click Trusted Authentication.
• Under Trusted Authentication, for each trusted host, enter the name or IP address and then click Add:

Notes:

The values you specify completely overwrite any previous setting. Therefore, you must include the full list of hosts if you want to amend an existing list.

Static IP addresses are required: The web servers you specify must use static IP addresses, even if you use host names.

If you have one or more proxy servers between the computer that is requesting the trusted ticket (one of those configured in Step 2 as shown at Trusted Authentication) and Tableau Server, you also need to add them as trusted gateways using the tsm configuration set gateway.trusted option. See Configuring Proxies for Tableau Server for steps.

• Enter a value in Token Length (Optional). The token length determines the number of characters in each trusted ticket. The default setting of 24 characters provides 144 bits of randomness. The value can be set to any integer between 9 and 255, inclusive.
• Click Save Pending Changes after you’ve entered your configuration information.
• Click Apply Changes and Restart.

04. Tableau Online: Personal Access Token

The Personal Access Token enables the Mail Scheduler to connect to Tableau with the permissions of the user with the Personal Access Token. Best practice is to use the Personal Access token of a service user with at least read permissions on the entire Tableau Server. The personal access token will not be available for anybody operating the Mail Scheduler it is securely stored in the system settings file.

04.1 Retrieve the Personal Access Token

Steps to be taken:

• Log in your Tableau Online environment with the user you want to use for accessing the dashboards.

• Open the dropdown in the right top corner and select “My Account Settings”

• Scroll down to the section “Personal Access Tokens”

• Create a new token by entering a name (for instance “MailScheduler”)

• When you click the button “Create new token” you will be shown a modal window (pop-up) with the token. Be aware that this is the only moment you have access to the “secret” of the token so make sur you copy it to your clipboard and/or save it in a plain text file.

  Press the “Copy to clipboard” button to copy the Token Secret to the clipboard. The image shown has a blanked space for security reasons.

• To store the Personal Access Token click the close button in the top right cornor of the pop-up. Do NOT use the “Discard”. Button since this will erase your personal access token. After closing the modal (pop-up) with the x button your token is stored and visible like shown below.

The Personal Access Token’s Name and Secret will be used in the configuration steps of the Mail Scheduler, section 6.2.env where we configure the environmental settings for the Mail Scheduler.

05. Install XAMPP

The Tableau Server Mail Scheduler is a solution that uses a Laravel basic platform to run on. In this step of the installation we provide/install the basic platform Apache/PHP/MySQL in order to run the Mail Scheduler.

We use the default XAMPP installation by apachefriends.org. Download the latest Windows version from:

https://www.apachefriends.org/download.html.

From the XAMPP install we only use Apache and MySQL, these are the only XAMPP components you have to install and start.

05.1 Start XAMPP installation

In the next window enter the path for installation e.g. C:xampp
It is best to use paths without spaces and special characters.

After selection of the install path a screen shows up asking you to learn more about Bitnami for XAMPP. Deselct the checkbox and continue with the installation process. After succesfull installation the control panel will be started. (In the screenshot below you notice the Apache runs on port 8000).

The XAMPP installation of Apache and MySQL might conflict with existing installations on the server/machine (port numbers already in use). You can change the default port numbers to free port numbers following next steps.

05.2 Change default port numbers Apache & MySQL

The default port used by Apache is port 80.
Take a look at all your used ports with Netstat (integrated to XAMPP Control Panel).

Then you can see all used ports and here we see that the 80 port is already used by System.

Choose a free port number (8012, for this example).

05.3 Edit the file “httpd.conf”

This file should be found in C:xamppapacheconf on Windows :
Listen 80
ServerName localhost:80

Replace them by:
Listen 8000
ServerName localhost:8000

Save the file.

Try to access the url in your browser using the port number set: http://localhost:8000 
If not, you must to edit the http-ssl.conf file as explain in step 3 below. ↓

05.4 Edit the file “http-ssl.conf”

This file should be found in C:xamppapacheconfextra on Windows.
Locate the following lines:

Listen 443

ServerName localhost:443

Replace them by with a other port number (8013 for this example) :

Listen 8013

ServerName localhost:8013

Save the file.

Restart the XAMPP Apache Server.
Access to : https://localhost:8000 for check if it’s work.

05.5 Change MySQL root password

For security purposes we change the root password of the MySQL server. Point your browser to: http://localhost:8000/phpmyadmin/

You will automatically be logged in as root user. Select the tab “User accounts” as shown below.

Click the “Change password” button on top of the page and change the password in a safe difficult to guess password. The root user will not be used on a regular basis, it will be used for installation and support purposes. Please write down or safe the password in a safe place!

After changing and saving the password your acces to PHPMyAdmin will be broken. You will have to edit the PHPMyAdmin config file which can be found at:

C:xamppphpMyAdminconfig.inc.php

Change the section on authentication type and info as stated below:

/* Authentication type and info */
$cfg['Servers'][$i]['auth_type'] = 'cookie';
$cfg['Servers'][$i]['user'] = 'root';
$cfg['Servers'][$i]['password'] = '';
$cfg['Servers'][$i]['extension'] = 'mysqli';
$cfg['Servers'][$i]['AllowNoPassword'] = false;
$cfg['Lang'] = '';

This will force the use of passwords on PHPMyAdmin

06. Database and Database user

Use a browser window to navigate to: http://localhost/phpmyadmin/ again

Login as root with your created password from the previous step.
Select the tab “user accounts” in PHPMyAdmin

Next Click “Add user account”

Please remember the password we entered, we have to set it in the Mail Scheduler environment file later on.

07. Install the Scheduler application

As mentioned before, the Tableau Server Mail Scheduler is a Laravel app using PHP scripts and a MySQL database.

07.1 Install script folders & files

This step covers the installation of the PHP scripts in the proper folders.

Use your windows explorer to navigate to the htdocs folder in your XAMPP installation and remove all files and folders.

Next create a folder named “scheduler” in the XAMPP htdocs folder. For example

C:xampphtdocsscheduler

Download the ZIP file from the Enterprise Customer portal (contact support via [email protected] if you don’t know how to obtain the files). Copy the pdfscheduler.zip archive to this new folder. Right click the archive and select “Extract here”. The necessary folder structure is already present in the archive.

07.2 Change the .env file

The root of the folder now contains a file called “.env.example”.

c:xampphtdocsscheduler

This file has to be edited and modified for the situation we just created. There is a slight difference in the .env setup for the “Tableau Server” and the “Tableau Online” platform both are shown below.

07.2.1 Tableau Server

Edit your .env.example file like the example below using your personal values for the red fields:

APP_NAME=Infotopics Tableau Server Mail Scheduler
APP_ENV=local
APP_DEBUG=false
APP_LOG_LEVEL=debug
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=scheduler
DB_USERNAME=schedule
DB_PASSWORD=my_password

BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
SESSION_LIFETIME=120
QUEUE_DRIVER=sync

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=smpt.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
[email protected]
#MAIL_PASSWORD=my_password
[email protected]
MAIL_FROM_NAME=Mailer

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=

TAB_SERVER_URL=http://tableauserver.nl
SAVE_FOLDER=”C:downloads”

When done editing the file, we save it with the name:”.env” including the point

07.2.2 Tableau Online

Edit your .env.example file like the example below using your personal values for the red fields:

APP_NAME=Infotopics Tableau Server Mail Scheduler
APP_ENV=local
APP_DEBUG=false
APP_LOG_LEVEL=debug
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=scheduler
DB_USERNAME=schedule
DB_PASSWORD=my_password

BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
SESSION_LIFETIME=120
QUEUE_DRIVER=sync

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=smpt.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
[email protected]
#MAIL_PASSWORD=my_password
[email protected]
MAIL_FROM_NAME=Mailer

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=

TABLEAU_PAT_NAME=MailScheduler
TABLEAU_PAT_SECRET=f9rsuD876234bh35kM47UG8HA==:tax6fkwehrwe55m9frNDIxAZD7oG6

When done editing the file, we save it with the name:”.env” including the point

07.3 Application Key

In Windows explorer start a powershell window (Shift right click and select powershell window) in the folder

c:xampphtdocsscheduler

Now run an artisan command to generate an application key that will be stored in the .env file we just created.

Command to generate an application key:

C:xamppphpphp.exe artisan key:generate

A key is generated that is stored in the .env file we just created

07.4 Create tables and Mail Scheduler admin user

In Windows explorer start a powershell window (Shift right click and select powershell window) in the folder

c:xampphtdocsscheduler

Use the Artisan command to create the proper tables in the scheduler database:

C:xamppphpphp.exe artisan migrate

With this command all tables will be created in the application database (scheduler)

In the same powershell window use the Artisan command to create the admin user:

C:xamppphpphp.exe artisan make:user

You will be prompted to enter the username, email address and password for the administrative user of the Mail Scheduler.

Change the and variables to your preferred admin username, email address and password when promted.

07.5 Add virtual host

We now need to address the virtual host. Pointy your windows explorer to

C:xamppapacheconfextrahttpd-vhosts.conf

And change it to your convenience

ServerAdmin [email protected]
DocumentRoot "C:/xampp/htdocs/scheduler/public"
ServerName localhost
ServerAlias localhost
ErrorLog "logs/scheduler-error.log"
CustomLog "logs/scheduler-access.log" common

In the file C:xamppapacheconfextrahttpd-ssl.conf search for the section where example.com is configured as a virtual host in the ssl configuration. Enter your server and certificate properties for ssl configuration. For ssl configuration there are a lot of ways to accomplish your desired situation. The online XAMPP community has lots of articles please use google if you are not satisfied by the description below.

# General setup for the virtual host
DocumentRoot "C:/xampp/htdocs"
ServerName localhost:443
ServerAdmin [email protected]
ErrorLog "C:/xampp/apache/logs/error.log"
TransferLog "C:/xampp/apache/logs/access.log"

# SSL Engine Switch:
# Enable/Disable SSL for this virtual host.
SSLEngine on

SSLCertificateFile "conf/ssl.crt/STAR_infotopics_nl.crt"
SSLCertificateKeyFile "conf/ssl.key/STAR_infotopics_nl.key"
SSLCertificateChainFile "conf/ssl.crt/STAR_infotopics_nl_Intermediates_en_Root.crt"

08. Scheduling

Open Windows Task Scheduler and create a new task

Click Create Task.

Enter Task name and descrition (For example Mail Scheduler)

Select SYSTEM user to run the task:

Run with highest privileges and check hidden:

Select tab “Triggers” Create new trigger:

Select tab “Action” and create a new action (use the path to the PHP folder in XAMPP):

Click tab “settings” and check: – Enter the path to the php.exe file in your xampp installation – Add the arguments: “artisan schedule:run” – Enter the scheduler site directory in the Start in Folder in our case: “c:xampphtdocsscheduler” without a trailing slash

The server tasks schedule is now set and can be saved/ started.

09. Run on Windows startup

Try to run Your XAMPP Control Panel as Run as administrator then install apache and Mysql.

 

When Xampp will open then ensure that apache and mysql service stopped.

Now just check/tick on Apache and Mysql service module.

Now Apache and Mysql will added in window services you can set these services as start on window startup.

10. Install openssl certificate

In the PHP.INI file you can edit the path to a openssl certificate file. Use your XAMPP configuration (see image) to edit this file or open the php.ini file in the xamppphp folder with your favourite editor.

In the php.ini file search for “openssl.cafile” and change the path and filename to the crt file you wold like to use. For example:

openssl.cafile="D:xamppapachebinInfotopics.crt"

Make sure the line is not commented out with a semicolon (;)

Stop and start your apache server to make sure these settings are applied.

11. Standard update procedure

Updates to the Tableau Server Mail Scheduler generally consist of 2 steps.

1. Extract ZIP file in xampphtdocsscheduler folder
2. Run migrate command in xampphtdocsscheduler folder (use powershell or command line in administrative mode)

Use this command to migrate the database to the latest version. In Windows explorer start a powershell window (Shift right click and select powershell window) in the folder

c:xampphtdocsscheduler

Use the Artisan command to create the proper tables in the scheduler database and apply other changes:

C:xamppphpphp.exe artisan app:update