<commit_before>Tableau – VizAlerts Installation Guide

# Table of Contents
-  [What is VizAlerts?](#what-is-vizalerts)
-  [What does it do?](#what-does-it-do)
-  [How does it work?](#how-does-it-work)
-  [Upgrading from VizAlerts 2.1.1](#upgrading-from-vizalerts-2_1_1)
-  [Installation Prerequisites](#installation-prerequisites)
	- [Tableau Server](#tableau-server)
	- [Tableau Desktop](#tableau-desktop)
	- [Host Machine](#host-machine)
	- [SMTP (Mail) Server](#smtp-mail-server)
- [Installation](#installation)
	- [Configure Tableau Server](#configure-tableau-server)
		- [Trusted Tickets](#trusted-tickets)
		- [Repository Access](#repository-access)
		- [Restart](#restart)
		- [Custom Subscription Schedules](#custom-subscription-schedules)
	- [Open the VizAlertsConfig Workbook](#open-the-vizalertsconfig-workbook)
	- [Configure the VizAlertsScheduledTriggerView Viz](#configure-the-vizalerts-scheduledtriggerview-viz)
		- [Calculated Fields](#calculated-fields)
		- [Regex Notation](#regex-notation)
	- [Publish the VizAlertsConfig Workbook](#publish-the-scheduledtriggerviews-viz)
	- [Install Python & Required Modules](#install-python-required-modules)
	- [Configure VizAlerts](#configure-vizalerts)
	- [Testing](#testing)
		- [Can VizAlerts Connect? Test](#can-vizalerts-connect-test)
		- [Simple Alert Test](#simple-alert-test)
		- [Put VizAlerts Through Its Paces Test](#put-vizalerts-through-its-paces-test)
		- [Optional: Send Yourself Some SMS Messages Test](#optional-send-yourself-some-sms-messages-test)
	- [Final Steps](#final-steps)
		- [Set up a Scheduled Task](#set-up-a-scheduled-task)
		- [Starter Workbook](#starter-workbook)
- [FAQ](#faq)
- [Common Errors](#common-errors)
- [Getting VizAlerts Help](#getting-vizalerts-help)
- [Contributing to VizAlerts](#contributing-to-vizalerts)
- [Appendix A.](#appendix-a)
	- [Installing Python modules with no Internet access](#installing-python-modules-with-no-internet-access)


What is VizAlerts?<a id="what-is-vizalerts"></a>
==================

VizAlerts is an automation platform intended to seamlessly integrate
with Tableau Server. The idea behind it is that **anyone** should be
able to easily build, share, and customize nearly **any** any email or
SMS **automation** based on their own Tableau Server viz data. In the
future, VizAlerts will be able to perform even more actions than these.

In its current form, VizAlerts exists simply as an application that is
set up by a system administrator to run at frequent and regular
intervals. All of the information it needs to enable data-driven email
and SMS alerting is derived from the Tableau Server PostgreSQL
repository, and the published views of the Tableau Server it is set to
run against.

What does it do? <a id="what-does-it-do"></a>
================

VizAlerts has been designed to support many use cases:

-   Sending notifications to subscribers when a condition has been met
    (or not!) like extract refresh failures, meeting or missing target
    thresholds, etc.

-   Halting emails from being sent to the group unless the data is up to
    date (while the workbook owner does get an email that the data isn’t
    up to date).

-   Notify data owners when data is corrupt in some way (extraneous
    values, too many Null values, too large a change, etc.)

-   Sending a one line email notification that could be forwarded
    through an email-to-sms gateway such as \#\#\#\#\#\#\#\#@txt.<EMAIL>
    or a messaging provider such as Twilio.

-   Batch reporting to distribution lists of non-Tableau users, for
    example emailing a weekly operations report to front-line staff who
    aren’t on Tableau.

-   Combining images and text into an HTML email for a more customized,
    professional look.

-   Merge multiple views into a single consolidated PDF, for example
    sending a company overview and per-region detail.

-   Blend views from separate workbooks in the same email, for example a
    view from the operations dashboard and a view from the
    finance dashboard.

-   Bursting reports, for example sending to a manager a dashboard for
    each of her direct reports.

-   Send SMS messages to escalate an issue to your support staff.

-   Whatever combinations of the above you can imagine!

How does it work? <a id="how-does-it-work"></a>
=================

While the details on how to *set up* alerts will be left in the User
Guide, it’s important for Administrators to know how things are working
behind the scenes.

The general flow of a single execution of VizAlerts goes like this:

1.  Connect to the PostgreSQL repository database of Tableau Server, and
    query it for a list of Views subscribed to on specially configured,
    disabled Schedules

2.  Compare Schedule information to last runtime information stored in a
    local text file—based on this, determine which Views are due for
    alert testing

3.  For each View found due for testing:

    1.  Generate a Trusted Ticket on behalf of the Subscriber of the
        View

    2.  Redeem the Trusted Ticket to export the CSV data for the View,
        impersonating the Subscriber

    3.  If one or more rows are found in the CSV:

        1.  For a “Simple Alert”, generate a new Trusted Ticket, export
            the PNG of the View, and email it to the Subscriber.

        2.  For an “Advanced Alert”, iterate through each row of the
            CSV, sending emails or performing other actions as
            instructed by the data itself.


Upgrading from VizAlerts 2.1.1<a id="upgrading-from-vizalerts-2_1_1"></a>
=====================================

**NOTE** The primary change in this version is the shift to Python 3 from Python 2. If you are running VizAlerts with the binary EXE file, there is little reason to upgrade to 2.2.0. However, if you are running it as a Python script, you will first need to upgrade to Python 3. My own experience was that it is best that you first remove Python 2 from your system by uninstalling it, and removing all references to it from your environment variables. Then, you need to [install Python 3](#install-python-required-modules). Please be aware that uninstalling Python 2 will begin a VizAlerts outage, so please TEST on a seperate server first, and plan your deployment accordingly.

1. Backup your current VizAlerts directory to a separate location.

2. Download version 2.2.0 from <https://github.com/tableau/VizAlerts/releases>, and unzip to a *new* folder alongside your existing VizAlerts folder. You should have three folders at this point: The live, current installation, the backup of the current installation, and a new folder you unzipped v2.2.0 into.

3. Copy config files
	- Copy the \config\vizalerts.yaml file from your *current* VizAlerts folder *over* the same file in the *new* VizAlerts folder
		- No changes were made to this file, so it will work just fine the way it is
	- If you're using SSL to connect to Tableau Server, and have a certificate file you're storing in the VizAlerts folder, make sure it's copied to the new location
	- If you've referenced any other files for passwords or anything else, make sure they're copied as well.
<br><br>
4. In Task Scheduler, disable the existing VizAlerts scheduled task.

5. <font color='red'>**VizAlerts outage begins**</font>

6. Uninstall Python 2, and remove references to it from your environmental variables (again, this is optional, but should make things simpler--if you're a power user that knows Python inside and out, feel free to disregard)

7. Download and install Python 3 and [required modules](#install-python-required-modules)

8. If you didn't already publish the updated version of VizAlertsConfig, publish it now, ensuring that you embed the password when you publish it!

9. Rename folders
	- Rename the existing VizAlerts folder with something like "-old" at the end of it
	- Rename the new VizAlerts folder whatever the old one was called
<br><br>
10. Testing
	- Open a command prompt, navigate to the VizAlerts folder, and execute VizAlerts one time. Ensure it runs properly, and review the logs if there are any errors.
	- Test a single alert by adding a test\_alert comment to a viz, and then run it again in the command prompt, again ensuring that no errors are logged.
<br><br>
11. **Optional**: If you want to ensure that no alerts were skipped during the upgrade, copy the \ops\vizalerts.state file from the -old VizAlerts folder to the current one.

12. In Task Scheduler, enable the VizAlerts task

13. <font color='green'>**VizAlerts outage ends**</font>

14. Remove the -old VizAlerts folder and any backups you made, whenever you feel comfortable


Installation Prerequisites <a id="installation-prerequisites"></a>
=====================================

Tableau Server <a id="tableau-server"></a>
--------------

The Tableau Server instance that you wish to run VizAlerts against must
fulfill the following requirements:

-   Must be v8.3 or higher.

-   The [readonly<commit_msg>-Updating documentation for (Issue #175)<commit_after>Tableau – VizAlerts Installation Guide

# Table of Contents
-  [What is VizAlerts?](#what-is-vizalerts)
-  [What does it do?](#what-does-it-do)
-  [How does it work?](#how-does-it-work)
-  [Upgrading from VizAlerts 2.1.1](#upgrading-from-vizalerts-2_1_1)
-  [Installation Prerequisites](#installation-prerequisites)
	- [Tableau Server](#tableau-server)
	- [Tableau Desktop](#tableau-desktop)
	- [Host Machine](#host-machine)
	- [SMTP (Mail) Server](#smtp-mail-server)
- [Installation](#installation)
	- [Configure Tableau Server](#configure-tableau-server)
		- [Trusted Tickets](#trusted-tickets)
		- [Repository Access](#repository-access)
		- [Restart](#restart)
		- [Custom Subscription Schedules](#custom-subscription-schedules)
	- [Open the VizAlertsConfig Workbook](#open-the-vizalertsconfig-workbook)
	- [Configure the VizAlertsScheduledTriggerView Viz](#configure-the-vizalerts-scheduledtriggerview-viz)
		- [Calculated Fields](#calculated-fields)
		- [Regex Notation](#regex-notation)
	- [Publish the VizAlertsConfig Workbook](#publish-the-scheduledtriggerviews-viz)
	- [Install Python & Required Modules](#install-python-required-modules)
	- [Configure VizAlerts](#configure-vizalerts)
	- [Testing](#testing)
		- [Can VizAlerts Connect? Test](#can-vizalerts-connect-test)
		- [Simple Alert Test](#simple-alert-test)
		- [Put VizAlerts Through Its Paces Test](#put-vizalerts-through-its-paces-test)
		- [Optional: Send Yourself Some SMS Messages Test](#optional-send-yourself-some-sms-messages-test)
	- [Final Steps](#final-steps)
		- [Set up a Scheduled Task](#set-up-a-scheduled-task)
		- [Starter Workbook](#starter-workbook)
- [FAQ](#faq)
- [Common Errors](#common-errors)
- [Getting VizAlerts Help](#getting-vizalerts-help)
- [Contributing to VizAlerts](#contributing-to-vizalerts)
- [Appendix A.](#appendix-a)
	- [Installing Python modules with no Internet access](#installing-python-modules-with-no-internet-access)


What is VizAlerts?<a id="what-is-vizalerts"></a>
==================

VizAlerts is an automation platform intended to seamlessly integrate
with Tableau Server. The idea behind it is that **anyone** should be
able to easily build, share, and customize nearly **any** any email or
SMS **automation** based on their own Tableau Server viz data. In the
future, VizAlerts will be able to perform even more actions than these.

In its current form, VizAlerts exists simply as an application that is
set up by a system administrator to run at frequent and regular
intervals. All of the information it needs to enable data-driven email
and SMS alerting is derived from the Tableau Server PostgreSQL
repository, and the published views of the Tableau Server it is set to
run against.

What does it do? <a id="what-does-it-do"></a>
================

VizAlerts has been designed to support many use cases:

-   Sending notifications to subscribers when a condition has been met
    (or not!) like extract refresh failures, meeting or missing target
    thresholds, etc.

-   Halting emails from being sent to the group unless the data is up to
    date (while the workbook owner does get an email that the data isn’t
    up to date).

-   Notify data owners when data is corrupt in some way (extraneous
    values, too many Null values, too large a change, etc.)

-   Sending a one line email notification that could be forwarded
    through an email-to-sms gateway such as \#\#\#\#\#\#\#\#@<EMAIL>
    or a messaging provider such as Twilio.

-   Batch reporting to distribution lists of non-Tableau users, for
    example emailing a weekly operations report to front-line staff who
    aren’t on Tableau.

-   Combining images and text into an HTML email for a more customized,
    professional look.

-   Merge multiple views into a single consolidated PDF, for example
    sending a company overview and per-region detail.

-   Blend views from separate workbooks in the same email, for example a
    view from the operations dashboard and a view from the
    finance dashboard.

-   Bursting reports, for example sending to a manager a dashboard for
    each of her direct reports.

-   Send SMS messages to escalate an issue to your support staff.

-   Whatever combinations of the above you can imagine!

How does it work? <a id="how-does-it-work"></a>
=================

While the details on how to *set up* alerts will be left in the User
Guide, it’s important for Administrators to know how things are working
behind the scenes.

The general flow of a single execution of VizAlerts goes like this:

1.  Connect to the PostgreSQL repository database of Tableau Server, and
    query it for a list of Views subscribed to on specially configured,
    disabled Schedules

2.  Compare Schedule information to last runtime information stored in a
    local text file—based on this, determine which Views are due for
    alert testing

3.  For each View found due for testing:

    1.  Generate a Trusted Ticket on behalf of the Subscriber of the
        View

    2.  Redeem the Trusted Ticket to export the CSV data for the View,
        impersonating the Subscriber

    3.  If one or more rows are found in the CSV:

        1.  For a “Simple Alert”, generate a new Trusted Ticket, export
            the PNG of the View, and email it to the Subscriber.

        2.  For an “Advanced Alert”, iterate through each row of the
            CSV, sending emails or performing other actions as
            instructed by the data itself.


Upgrading from VizAlerts 2.1.1<a id="upgrading-from-vizalerts-2_1_1"></a>
=====================================

**NOTE** There are two important changes in this release: 

-   A fix to the VizAlertsConfig workbook for Tableau Server 2020.4.1

-   Switch from Python 2 to Python 3

If you are running VizAlerts with the binary EXE file, and are not using Tableau Server 2020.4 or higher, there is little reason to upgrade to 2.2.0.
If you are running it as a Python script, it is recommended that you upgrade, as Python 2 has been discontinued.
If you are upgrading to Tableau Server 2020.4 or higher, you can choose to upgrade VizAlerts, or [edit your VizAlertsConfig workbook](https://github.com/tableau/VizAlerts/issues/175) instead (the simpler solution).

Upgrading to VizAlerts 2.2.0 when running as a Python script will require installing Python 3. My own experience was that it is best that you first remove Python 2 from your system by uninstalling it, and removing all references to it from your environment variables. Then, you need to [install Python 3](#install-python-required-modules). Please be aware that uninstalling Python 2 will begin a VizAlerts outage, so please TEST on a separate server first, and plan your deployment accordingly.

1. Backup your current VizAlerts directory to a separate location.

2. Download version 2.2.0 from <https://github.com/tableau/VizAlerts/releases>, and unzip to a *new* folder alongside your existing VizAlerts folder. You should have three folders at this point: The live, current installation, the backup of the current installation, and a new folder you unzipped v2.2.0 into.

3. Merge VizAlertsConfig changes into new workbook
	- There is a new version of \config\VizAlertsConfig.twb that contains an edit to the _is_valid_schedule_ calc. It's easiest to simply drop this minor change into your existing VizAlertsConfig workbook. To do so, here are the steps:
		- Download your existing VizAlertsConfig workbook from Tableau Server and open it in Tableau Desktop
		- Edit the _is_valid_schedule_ calc in your VizAlertsConfig workbook so that the first line is **[subscription_id] < 0** rather than **ISNULL(schedule_id)**
		- Now re-publish the current VizAlertsConfig workbook to Tableau Server, **making sure** that you are embedding the password in the connection. This will _not_ break v2.1.1 of VizAlerts.
<br><br>

4. Copy other config files
	- Copy the \config\vizalerts.yaml file from your *current* VizAlerts folder *over* the same file in the *new* VizAlerts folder
		- No changes were made to this file, so it will work just fine the way it is
	- If you're using SSL to connect to Tableau Server, and have a certificate file you're storing in the VizAlerts folder, make sure it's copied to the new location
	- If you've referenced any other files for passwords or anything else, make sure they're copied as well.
<br><br>

5. In Task Scheduler, disable the existing VizAlerts scheduled task.

6. <font color='red'>**VizAlerts outage begins**</font>

7. Uninstall Python 2, and remove references to it from your environmental variables (again, this is optional, but should make things simpler--if you're a power user that knows Python inside and out, feel free to disregard)

8. Download and install Python 3 and [required modules](#install-python-required-modules)

9. If you didn't already publish the updated version of VizAlertsConfig, publish it now, ensuring that you embed the password when you publish it!

10. Rename folders
	- Rename the existing VizAlerts folder with something like "-old" at the end of it
	- Rename the new VizAlerts folder whatever the old one was called
<br><br>
11. Testing
	- Open a command prompt, navigate to the VizAlerts folder, and execute VizAlerts one time. Ensure it runs properly, and review the logs if there are any errors.
	- Test a single alert by adding a test\_alert comment to a viz, and then run it again in the command prompt, again ensuring that no errors are logged.
<br><br>
12. **Optional**: If you want to ensure that no alerts were skipped during the upgrade, copy the \ops\vizalerts.state file from the -old VizAlerts folder to the current one.

13. In Task Scheduler, enable the VizAlerts task

14. <font color='green'>**VizAlerts outage ends**</font>

15. Remove the -old VizAlerts folder and any backups you made, whenever you feel comfortable


Installation Prerequisites <a id="installation-prerequisites"></a>
=====================================

Tableau Server <a id="tableau-server"></a>
--------------

The Tableau Server instance that you wish to run VizAlerts against must
fulfill the following requirements:

-   Must be v8.3 or higher.

-   The [readonly
{'fraction_non_alphanumeric': 0.08851587342959913, 'fraction_numerical': 0.007715164468539853, 'mean_word_length': 4.043112513144059, 'pattern_counts': {'":': 0, '<': 54, '<?xml version=': 0, '>': 53, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 5, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6920446', 'n_tokens_mistral': 5713, 'n_tokens_neox': 5351, 'n_words': 2502}