ACPT: Installation and Setup

ACPT - Analytica with TableauACPT: Installation and Setup

Terminology and Requirements

Before being able to benefit from ACPT we’ll need to do some setup. It’s important to make a few terms clear in order to avoid frustration and confusion throughout this tutorial. When we refer to your model, we’re referring to the Analytica .ana model whose inputs/outputs you’d like to be embedded/displayed in Tableau. When we refer to a Dashboard, we’re referring to a Tableau Dashboard that can display multiple ACPT extensions and Tableau Sheets. Tableau Sheets are the building blocks of Tableau Dashboards and can contain maps, graphs from your model, and more. Finally, a Tableau workbook (.twb) is the file containing your Tableau dashboards and sheets.

Additionally, this tutorial assumes that you:

Have Analytica
Have the Tableau Desktop application*
Have a Tableau Server account to sign in with

If running on your own server, you’ll additionally need to:

Have access to a server with ACP and Tableau Server installed on it

* certain requirements subject to change with future improvements. Depending on time availability, the Tableau Desktop constraint can be overcome by having somebody that does have Tableau Desktop (i.e. we here at Lumina) if the user can create the rest of the model via Tableau Server (more info in “Dashboard Creation”).

Adding the ACPT Library

The first step is to get the ACPT Library here. Once downloaded, open up the model that you want to embed with Tableau. Make sure you’re in edit mode

and then go to File -> Add Module… and then navigate to wherever you downloaded the ACPT Library (ACPT Library.ana) and select it.

For more information on adding modules, see Import a module or library.

When done, you should see this module in your library:

Model Alterations

After adding the ACPT Library module to your model, it’s time to create module node(s) to represent your Tableau Dashboard(s). Each module’s contents will represent a separate Tableau Dashboard. We recommend changing the colors of these modules from the default in order to distinguish them from regular modules. For this tutorial, I’ll create a module titled “Dash Test” and color it orange. Remember this name; the module’s title will have to match the Dashboard’s title later on (not the identifier, which in this case would be “Dash_Test”).

Next, we’ll grab whatever nodes from our model we’re interested in visualizing in Tableau. For this example I’ll just grab one, titled “Loss” by right clicking and selecting “Make User Output Node”. I’ll then grab this output node and drag it into my “Dash Test” module.

You’ll notice the green decision node titled “Test_Input” right below the node output I’m interested in. Because the “Loss” node didn’t actually have any user input that changed its results, it wouldn’t have been able to have its visual update in Tableau. This doesn’t mean you couldn’t include it because you may want to include nodes that aren’t affected by a user input. However, for the sake of simplicity, I’ve chosen to add this new input as part of the “Loss” node’s Definition in order to make its results malleable.

Similar to the output, I’ll right click the decision node “Test_Input,” select “Make User Input Node,” and drag the input node into my special “Dash Test” module.

Add as many input/output nodes as you want at this stage. So far my example module looks like this:

The third step for manipulating the module is adding the ACPT Library Function “Onchange_Input_CSV()” to all inputs in our special module(s). This function makes it so that when this user input is changed, the model only recalculates the Outputs affected by this user input. To do this, first go to Object -> Attributes...

This will open a new window. Make sure “OnChange” has a checkmark next to it, then press “OK” to confirm your new attribute selection.

Now open the object window for all of your inputs and in the new “OnChange” section, add the “Onchange_Input_CSV()” function.

ACPT Add Attributes OnChange Object Window.png

After this, we’ll need to navigate to go inside the ACPT Library we imported and navigate to “ACP Save and load user inputs lib”.

We’ll then edit the Definition for the “Dashboard modules” index located in the top right.

In the ListOfHandles() function call, include the Identifiers of the modules that will be included as Dashboards in a comma separated list.

Within the same module, near the middle you’ll see a Decision node titled “Tableau_userID”. Edit this and instead of “user name goes here” to whatever your username on Tableau Server is/will be between the quotes. This will create the necessary folders for the next step.

Close to this is a node titled “Data folder path”. Show the result of this node and remember this data path for later.

We have to do one more thing before moving on. Inside the ACPT Library we have to select the button labeled “Save all user outputs as CSV files”. Note: you’ll encounter a warning. This is expected; select “Ignore Warnings”. Selecting this will generate the initial CSV files for all of the outputs we’ve specified in our special modules. The names of these csv files will match the identifiers of the result variables. These data files will serve to hold as placeholders in our Tableau Dashboard, helping us set it up and marking the file location and name to be replaced/overwritten when a user input changes. The location of these data files was indicated by the “Data folder path” node.

You can now save and close your model.

The ACPT library has many more functions that help create the necessary files on the server, detect the special modules you’ve created, and more, but the rest can be handled behind the scenes.

Dashboard Creation

The next step will be to create your Tableau Dashboard in Tableau Desktop (if you don’t have Tableau Desktop, you’ll need to mimic what is done here via Tableau Server, download the workbook and then follow the steps laid out in “File Placement and Private Server Requirements”). Open Tableau Desktop, select “Text file” and select one of the CSV files generated from the model from the directory specified by the “Data folder path” node (this will be something like C:\ACPT data\MODEL_ID_HERE\USERNAME_HERE\...).

Your data will pop up. Verify it looks correct. Then, navigate to “Sheet 1” at the bottom.

We’ll start by creating a special necessary sheet called the “userIdSheet”. Under dimensions, right click any part of the white space and select “Create Calculated Field…” to open up a new window. In this window, you’ll make the title of the calculation userId and inside the definition place the function “USERNAME()” with no arguments as shown. Then press the green “OK” button.

You’ll now see a new dimension on the left titled userId; drag this into the Rows box near the top. The sheet will then be populated with the following:

We’ll next need to fix that title. At the bottom where you navigated between tabs, right click “Sheet 1,” select “Rename” and change it to “userIdSheet” as alluded to above. You’ll see the title above has also changed but the most important point is that the tab at the bottom has changed.

This is a good time to point out the text in the userId field. For my example, we see “filst” because that is the USERNAME() I have associated with my Tableau Desktop account. However, this will change once we sign into the Tableau Server with whichever intended account to use the workbook we’re creating.

As last additional steps, if we want to hide the “Abc” text field that Tableau automatically generates, we can either click on “Abc” and then under “Marks” click “Color” and drag the opacity to 0%, drag the box from the right side all the way to the left to make the field too small for “Abc” to be seen, or both. We can also right click the title above and select “Hide Title” to remove redundant information.

Next, we’ll add our outputs as individual sheets. To add an additional sheet, press the add sheet icon at the bottom next to your “userIdSheet”.

Navigate to this new sheet. Drag in the corresponding data from under “Measures” into the “Columns” and “Rows” boxes at the top.

Assuming you’ve seen your own results in Analytica, you may notice it doesn’t look quite right. To clarify for those still learning Tableau, this is because:

1. Tableau automatically aggregates data, this time using SUM(...)

2. Tableau has different color defaults than Analytica

To fix (1), we right click on each pill shaped field and select “Dimension” instead of “Measure”.

Next, under “Marks” change it from “Automatic” to “Line”.

For (2), under “Marks” again, select “Color” and choose the correct color you had before.

Lastly, similar to the last sheet, right click the sheet at the bottom and name it with the same name of the data source but without the file type (e.g. my data source was “Loss.csv” so my title will just be “Loss”).

Feel free to make any additional changes at this point (e.g. changing axis titles, hiding/changing the title at the top, etc.)

For those with more than one output, you’ll need to go to Data -> New Data Source… and select the data sources just like the first one, creating additional sheets for each. When on a new sheet, you’ll need to click select the proper “Data” at the top.

After creating all the required sheets, you can now create your dashboards. This time click the new dashboard button at the bottom navigation bar.

The first step is to right click the dashboard at the bottom navigation bar and rename it to whatever you named the corresponding special module in your .ana model. For my example this is “Dash Test”. Next, you’ll drag the sheets you created from the left side into the canvas and arrange them as you’d like. Note: you can make use of the “Blank” object under “Objects” at the bottom to manipulate how the space is used.

At this point you’ll want to include extensions. This topic is broad and unique to each project to the point that it requires its own page ACPT Tableau Extensions. For this tutorial, I’ll be dragging the Extension button (under “Objects”) into the canvas twice, first selecting “My Extensions,” and selecting “acpSettings.trex” (acpSettings.trex can be downloaded here) and repeating the process and selecting “userInput.trex” (userInput.trex can be downloaded here). Note: If using our server, you’ll only need the .trex files from these folders. If using your own server, you’ll need the other files as well (more on this in the next section “File Placement and Private Server Requirements”). To simplify, acpSettings is an extension required in every dashboard and userInput will be tailored to our “Loss” output sheet. These extensions access the net, so you’ll be required to allow this by selecting “Ok” upon selecting your extension.

At this point you’ll see credentials are required for the ACP Setup extension.

If using our server, once you layout all of the desired userInput extension boxes (they’ll say “Waiting for model to open….” and then “Timed out. Refresh to try again.;” this is expected due to not having the ACP Settings Extension properly initialized) this is as far as you’ll need to go as far as the extensions are concerned. Once you’ve placed all of the output sheets necessary, we’ll either (a) enter the credentials and insert/specify the necessary userInput extensions ourselves upon you contacting us (for you to later be able to adjust visually) or (b) give you credentials for you to continue yourself. To get an idea what the userInput extension will look like with the ACP Settings Extension enabled, here is what the example looks like:

For those running your own private server, the ACP Settings Extension information will be obtained while following the necessary page Installing ACPT Extensions on Your Server.

After setting up all wanted dashboards as specified above, hide any unwanted titles the same way you did for Sheets, make any final stylistic changes, and save your workbook. If you right click a dashboard at the bottom, you can select “Hide All Sheets” to remove the sheets from view (this will carry over the to server version for those who want to hide the inner workings of the workbook; you can undo this via the same method but instead selecting “Unhide All Sheets”).

The following hyphenated area only applies if you followed the rest of the steps but Tableau reports an incorrect data path (if so, do the following and then repeat the steps following):

The next step requires you to open your file in a text/source code editor that has the capability to do “Find/Replace” (basically anything other than Notepad should work; Notepad++, Sublime, etc.). Do this by right clicking on the file, selecting “Open with…” and selecting the editor of your choice.

In the file, if you CTRL+F and search “C:/ACPT data” you should see a directory location. You’ll need to change this end of this path to whatever your username on Tableau Server is/will be.

Find and replace all occurrences (for my example it was only once near the top). Then save your file.

Open your new file in Tableau Desktop and go to Server -> Sign In…

Enter the server web address in the popup that appears and then sign in the the Tableau user account in the next popup window.

Swap over to your browser, go to Tableau Desktop and sign in.

Go to Explore -> Create -> Project create a folder with the same name as your user name.

Go back to Tableau Desktop, go to “Server” and select “Publish Workbook…”.

In the new popup, select the folder you just created under “Project” and set the “Generate thumbnails as user:” to your user name. Optionally, you can add a description. Finally, at the bottom under “More Options,” select “Show sheets as tabs” and “Show selections” but do not select “Include external files” (as these files will be generated by ACP). Tableau will issue a warning when you remove the selection for external files; this is fine. Then select “Publish”.

File Placement and Private Server Requirements

Regardless of whether or not you’re running on your own server or our server, all of the previous steps are required. Past this point, the instructions will vary based on which situation matches your own.

Using our server:

Email bfilstrup@lumina.com with the title “Tableau Server Request” and include the following information:
- The user name you’d like for Tableau Server
- Your modified .ana
- Your Tableau workbook*
  - If your workbook has not had its file locations altered due to not owning Tableau Desktop, this needs to be specified in the following point and will require us to have your tableau server user info to properly link the data
- Any additional requests/information (multiple users, lack of Tableau Desktop, etc.)

After that you can expect a reply generally within 24 hours and results in under 48 (again, subject to availability).

Using your own server:

Follow Installing ACPT Extensions on Your Server that was previously mentioned on installing Tableau Extensions on your server.
Upload your model to your ACP server
On the server running ACP and Tableau Server, run your model and generate the folder structure with the initial files as specified in “Model Alterations” (“Within the same module, near the middle you’ll see a button titled ‘Save User Inputs’...”)

After all installation is done, you can sign in to Tableau Server. You’ll be placed into a folder made specifically for the user signed in if using our server (navigate there for private servers; this can be adjusted in Tableau Server’s “Settings”) with the model inside for you to select and then the Dashboard for you to select.

For any problems or support, please contact bfilstrup@lumina.com.