MailScheduler Product Guide

MailScheduler

For the installation we refer to the enterprise installation manual overview page.

With the Tableau MailScheduler you can schedule tasks at multiple moments. With mailing lists, we can generate user-specific dashboards in a few easy steps. Enjoy many features like XLS export, landscape exports, and mailing lists.

Export crosstabs in Excel format

The MailScheduler runs on a network-enabled machine (either a laptop, desktop, or server). To create, maintain and monitor the schedules, you only need a modern browser.

The tasks you configure are stored by the MailScheduler in your database and fire automatically at the scheduled time. No need to trigger it manually at that moment.

You are able to send a single page or multipage PDF reports, inline images, or attach CSV, XLS, or PNG files. A schedule runs on a specified time and can consist of many tasks for different departments, stores, or regions.

Basics

To configure the MailScheduler, open your browser. The URL can depend on the installation procedure. In general, it is https://localhost:8080. Here localhost is the server/URL and 8080 is the port.

When you open this in the browser, you will see the MailScheduler home page.

MailScheduler homepage

Create a Schedule

It’s now time to create your first schedule! Click the button “New in the upper right corner and you will be served a form to fill in the details of your schedule.

Description

The name or description of the schedule you are creating.

Site

The site the task is performed from.  This site also comes with mailing lists and recipients when they are specified.

Status

With the status set to inactive, you can temporally deactivate a schedule and its tasks.

Frequencies

Specify when the schedule should be sent. For example, daily at a certain time or on specific days of the week.

Start and end on

This way you can schedule in advance and set the start date. After the end date, the schedule will automatically be deactivated.

Admin email

An email will be sent to the admin if a task fails. Also, in the test mode, this email address will be used.

Test mode

In the test mode, the email will only be sent to the admin. This way you can test if the schedule works properly.

Click Save to store the schedule.

Notify on failure

Notify all recipients when a task fails. This way, the users will know something went wrong, and you will work on a solution. This feature ensures that all recipients know you are aware of the failed task and don’t need to contact support. 

 

Import and export schedules

It is wise to export an existing task to understand the formatting quickly. The formatting is shown below.

importSchedule

 

To edit an existing task, leave the task_id in place. To create a new task, Leave it empty to create a single view in a task. When using multiple views in one task, please give it a fake id that does not yet exist in the database.

editandImportSchedule

 

Task_id, task_name, filename, emails, mailing_lists, and save are settings that apply to one task. So multiple views within the same task should be similar. Otherwise, the MailScheduler will take the final row into account.

The view_id will be empty for new tasks. To update an existing view, leave the id the same. We recommend using each view in only 1 task and do not reuse a view. By filling the view_url (case sensitive!), the MailScheduler will search for the exact name match on your Tableau. You can put filtering queries in the query column, and multiple export types are supported: pdf-v, xls, csv, image.

When you are done editing the CSV file, import it again. Select choose file, select the CSV file, and hit upload.

 

Create a Task

A schedule can consist of multiple tasks. We already know when to send it, now we need to specify what to send in the email.

In the tasks pane, click the ‘new’ button to create a new task.

First, provide a description for the task to create an initial instance of the task. Use a date-time format in the description field of the task. This will end up in the subject of the email, perfect for recipients to easily identify the moment of the update. IE: {yyyy-mm-dd hh:mm:ss}

Status

Status can be set to inactive to temporarily disable this task.

MailScheduler status

After that, you can add mailing lists, views, and message. 

Mailing Lists

Attach a mailing list to this task to send the mail to all recipients on the list.

Filter Task

A task can be filtered. To apply a filter to the whole task, app a filter here.

When leaving the filter value empty, but specifying the key, the scheduler will look in the mailing list if there is a matching filter that will be used.

Filtering

The query builder now supports setting a parameter. To do that, prepend the parameter name with “Parameters.” (week_number => Parameters.week_number). This works for all filtering in a task, view or for a recipient.

MailScheduler Filter tasks

Views

Click the Add button to add a view. A modal will show where you can search for the workbook and the dashboard.

MailScheduler views

Save the view you want to add. 

By selecting the checkbox, the corresponding export format is attached to the mail.
All PDFs that are exported will be merged before they are attached.
You can edit and delete the view by clicking the buttons in front of the view.

A filter can be applied on the view level. If you want to use the filter only on this view, specify it here.
When leaving the filter value empty, but specifying the key, the scheduler will look in the mailing list if there is a matching filter that will be used. 

 

MailScheduler Filter tasks

Show folders of workbook

When adding a view, workbooks may have the same name but are in different folders. Switch the ‘Show Location of Workbook’ setting to list the folders in the select dropdown.

 

Then instead of:

Workbook1

Workbook1

Workbook1

 

We will see the folder name between brackets after the workbook name:

Worbook1 (Region North)

Worbook1 (Region South)

Worbook1 (Region West)

MailScheduler Filter tasks

Message

In the message, we can create the email content, this will be the message your users will receive in their email.  You can use rich text and inline images. Just use the tag <img:1>. Where 1 is the id of the view in this task.

Each container can contain richtext, a place holder (for example {YYYY-MM-DD} or {name}), a date or an image. A template can be used in multiple tasks. Hence, when it is edited it changes for all tasks that are using this template.

MailScheduler message
Images are only for header/footer, these cannot be added to the body text but you’re able to add an inline images of the dashboard. Use the <img:id> tag ( <img:65> ) for example.  There are 3 columns evenly spaced that can be filled. You can reuse templates for multiple tasks. Templates can be linked to a task via the import/export schedule tool. You cannot create a new template from the csv file, that you have to do before in the MailScheduler Extension

Rich text

MailScheduler message

Rich text allows you to add a label for you to reuse in another task as a template. If you have a standard message you wish to use in multiple tasks, you can create here and use the ‘reuse template’. Add your content in the rich text box, you can format your message such as changing the style, linking websites and adding inline images. Below the text box you will see helpful tips to help you creating a beautiful message accompanying your dashboards. 

We start to introduce placeholders to be used in the email
– Date: {yyyy-MM-dd} -> 2023-04-17
– Date with a time diff, for example yesterday: {yyyy-MM-dd:-1 day}
– The recipient name: {name} =>only this one for now, list to be extended upcoming months

Image

MailScheduler message

Add an image which is placed in the folder img, next to the phar file on the server. Be sure to specify the size of the image.

Here you can also format the image you’re attaching to your task, this can be a company logo for example. Create a label so you can reuse in another task, a filename which will be the name where the file is saved in your folder. Decide on the size and alignment of the image to give your message the best look. 

Reuse Template

MailScheduler message

Reuse a template from the list. Here will show all the labels of your stored text and images, simply choose one to import the template to use in your task.

Emails

Besides the mailing list, separate email addresses can be used. In this case a recipient filter is not possible and only the filters from the task or the view will be used.

How to send

Determine how to send whether it’s CC or as BCC

From Email

Email address which the email is sent from. This only works when the authentication account in the .env has permission to send as this email address.

Name of the sender

This will be the name shown as the sender of the mail. 

Reply to Email

When users wish to reply to the mail, this address will be used.

Reply to Name

The name of the reply to mail.

PDF filename

The filename of the attached PDF. Use a format like my-filename- {yyyy-mm-dd}, to get a filename my-filename-2022-03-01. If the same filename is used twice, the file will be replaced.

Include a folder name in the filename field, this will store the the files in your chosen location. This is useful when organizing your files in a specific folder structure. 

Store PDF

Store the pdf on the server on the defined path on the server settings. 

Empty CSVs

If a CSV is empty, should it be sent? If selected yes, also empty CSVs will be sent. 

CSV Delimiter

Which is the separator within your CSV file

CSV Extension

The extension of your file name. EG: .csv

Notify on failure

When the task fails, send an email to the recipients.

MailingList

MailScheduler mailing list

The mailing list has a name and description. MailingLists are connected to sites. Users with access to that site can see the attached mailing lists.
Then add Recipients to the mailing list.

Recipients

Recipients have a name and email. They are attached to a site, such that they are only visible on the sites they are attached to. Hence, different departments don’t have to see recipients that are not part of their department. Furthermore, we can specify filters per recipient. This way we can easily send the same dashboard to multiple recipients, each with its own required filters.

MailScheduler recipients

Give a name, email and a filter if required.

Mailing Lists and Filters

Name – Email address – Filter

This filter is used for recipient specific filter

Example:

John Doe – [email protected] – Region=North
Thomas Toe – [email protected] – Region=South

Furthermore, the task or a specific view can be filtered, say the task is about Consumers
On the task we specify:

Segment=Consumer

Then we want one view of the Overview Dashboard that applies the filter of the Recipients in the Mailing Lists, but also one with the general overview with all regions

We add a view without any additional filters for the total overview of all regions.
We add a second overview with the filter Region, but we leave the value empty (no North or South). Then we will check the mailing list for any filter values.

Caution: When there is no filter applied all data from the dashboard will be visible.

Filtering can be done in the dashboard. Set your workbook filter to all unselected.

Filters are case sensitive

For admins

Permissions

Sites are separated

In MailScheduler2 we now have sites. For Tableau Online, each site needs its own PAT with the right permissions.
Sites in the MailScheduler2 are separated: When a user has access to only site1, he cannot see site2, or schedules and mailing lists connected to site2.
Recipients are connected to a site, so only when a (non admin) user has access to that site, he can see the corresponding recipients.

Server

MailScheduler default server

Name

A label to easily know what server you are using. Specify any name of the server for reference you like. 

Server URL

Add a server. Provide the name and the exact URL:

https://abc01.online.tableau.com/ for example

CSV delimiter

Specify the CSV delimiter, used at your tableau server.

Remove enclosures

Remove the enclosures of the CSV if you want.

Absolute Server path

A copy of the PDF is stored on your server if you enable the save function on the task. Define here the absolute path to the folder where the files should be stored?

Default Server

Use the default server in general when creating a new schedule and task. 

Site

MailScheduler site

Give the name and select the server. The site name should exactly match the site name of on your server. If you don’t use a site name, default suffices or leave the field empty.

Name

Site label. Give the site a recognizable name for reference.

Server

Select here on what server this site is available. The Server has to be set up in the Server Tab.

Site Name

The exact site name found in the URL when visiting the dashboard in the browser
When visiting the dashboard in the browser:

https://abc01.online.tableau.com/#/site/sitename/views/workbookname/dashboardname

Token Name and Token Secret

A user with permission to the site and required dashboards should have (or create) a Personal Access Token (PAT). The Token name and secret should be entered here. Personal access tokens will expire if they are not used after 15 consecutive days. If they are used more frequently than every 15 days, an access token will expire after 1 year. After a year, you must create a new token. 

Test Connection

Use the test connection button to verify all is working before saving, you will be prompted with a message in green if the connection is valid, or red if there’s an issue. Double check all fields to see if there’s an obvious mistake such as an empty field, if there’s an error you do not recognise you can contact us through support through email at [email protected].

MailScheduler user

Users

Users have a name and email. They can be assigned to multiple sites they can create mailing lists and schedules for or maintain when they are an admin. When a user is added, he will get an invitation to add a password and log in to the MailScheduler.

Queue

In the queue admins can see the scheduled tasks when they are sent to the queue. Any failed tasks will also show up here. From here it is easy to add the failed tasks to the queue again. Also some error message can be obtained from here to help finding the error. 

License

To be able to use the MailScheduler a LICENSE file is required.

Obtain the license file from your portal and place it in the code folder or paste it in the about tab in the MailScheduler.

MailScheduler license

Otherwise you can go to the About tab and paste the License key.

We love to make solutions and help Tableau users to do things more efficiently. If you have feedback, ideas, questions or need support, please share them with us! Also, don’t forget to follow us on social media for our latest news and updates.