Sunday, May 27, 2012

Doc Upgrade - TS v7.0 Admin: "How to Use tabcmd"

Available online here, the original doc is very confusing; its problems are discussed here.
The improved doc is here.

The original doc


How to Use tabcmd

tabcmd takes a command, an argument, and options as shown in the format below:

tabcmd command command-argument [options option-arguments]

Using that format and the commands in this document you can run the tool. For example, you could use the following command to create a session on a server called sales-server logged in as Administrator and delete a workbook on the Sales site called Sales_Analysis:

tabcmd delete "Sales_Analysis" -s sales-server -t Sales -u administrator -p p@ssw0rd!

Here’s the same command for a workbook on the Default site, or for a server that is not running multiple sites:

tabcmd delete "Sales_Analysis" -s sales-server -u administrator -p p@ssw0rd!

When the command is successful, tabcmd will return a status code of zero. A full error message for non-zero status codes is printed to stderr. In addition, informative or progress messages may be printed to stdout. A full log named tabcmd.log that includes debugging, progress, and error messages is written to:

  • Windows 7, Windows Vista, and Windows Server 2008 R2: C:\Users\\AppData\Roaming\Tableau
  • Windows Server 2003: C:\Documents and Settings\\Application Data\Tableau


...

Improved doc


How to Use tabcmd

Sessions

tabcmd runs inside an authorized environment called a session.

Sessions are used to identify the Tableau Server the tabcmd will run on. They also need to be run on behalf of an authorized User. because of these, the server name, user name and password need to be provided. See the online doc for further information.

tabcmd details

tabcmd has this format:

tabcmd command command-argument [options option-arguments]

The commands are listed online here with their arguments and options.

Using this format and the commands in this document you can run the tool.

For example, you could use the following command to delete the "Sales_Analysis" workbook* or data source* from the 'Sales' site on the 'sales-server' Tableau Server, where the command is executed as the 'administrator' user:

tabcmd delete "Sales_Analysis" -t Sales -s sales-server -u administrator -p p@ssw0rd!

Here’s the same command for a workbook on the Default site, or for a single-site server (note the missing "-t Sales" option):

tabcmd delete "Sales_Analysis"          -s sales-server -u administrator -p p@ssw0rd!

Notes:

* The delete command's argument is by default the name of a workbook or data source.
See tabcmd Commands – delete workbook-name or datasource-name for more information

When the command is successful, tabcmd will return a status code of zero. A full error message for non-zero status codes is printed to stderr. In addition, informative or progress messages may be printed to stdout. A full log named tabcmd.log that includes debugging, progress, and error messages is written to:

  • Windows 7, Windows Vista, and Windows Server 2008 R2: C:\Users\\AppData\Roaming\Tableau
  • Windows Server 2003: C:\Documents and Settings\\Application Data\Tableau


...

The original doc's problems


The explanation is mangled, hard to follow, and actually impedes comprehension.

All by itself the explanation is unclear.
"For example, you could use the following command to create a session on a server called sales-server logged in as Administrator and delete a workbook on the Sales site called Sales_Analysis:"

Worse, when one is reading the actual command, relating it back to the explanation is very difficult: the command being read doesn't map back well to the explanation just read.

Problems include:

  • The lead is buried

    The most important thing to know about this command is that something is getting deleted.

    But the communication that something will be deleted doesn't occur until the 14th word following "For example, you could use the following command to", which makes it buried as the 23rd word in the sentence.

  • What's a session?

    "session" is the first noun in the explanation, implying that it's a significant thing, so the reader is primed to anchor it in whatever follows. But it's never seen again, and since the User is expecting it—it is important, after all—the further on the reader goes, the greater the confusion becomes trying to resolve the dangling reference.

    Sessions don't matter

    in this context, so there's no reason to mention them, much less promote them to the first position, which needs to be where the most important thing needs to be.

  • The order of explanation elements is different from the order of command elements, i.e.:

    The explanation's elements, in order: The command's elements, in order:
    1. "session", never seen again
    2. "server"
    3. server name: sales-server
    4. login ID: Administrator
      n.b. case doesn't match command
    5. function: "delete"
    6. function object: type
    7. Tableau Server object: type/name, i.e. site/Sales
    8. function object: "Sales_Analysis"
      n.b. needs to back-reference 3 steps
    1. function: "delete"
    2. function object name: "Sales_Analysis"
    3. option - identify server: "-s sales-server"
    4. option - identify site on server: "-t Sales"
    5. option - identify User by name: "-u administrator"
    6. option - identify User's password: "-p p@ssw0rd!"

    Try to relate these two lists of elements. Even when laid out clearly it's difficult to make sense of their relationships.

  • Inconsistent naming structure

    Compare these two clauses:
    • create a session on a server called sales-server
    • delete a workbook on the Sales site called Sales_Analysis

    In the first clause, the final label—"sales-server"—applies to the second noun—"server".
    In the second clause, the final label—"Sales_Analysis"—applies to the first noun—"workbook".

    It's extremely difficult to parse these two clauses to arrive at an internally consistent meaning that corresponds to the actual tabcmd command.

    In order to understand the explanation the reader must realize that it's inconsistent internally and with the actual command, and then puzzle out the truth for him- or herself.

    This is bad.

  • Other internal explanation inconsistencies:

    create a session on a server called sales-server Is "sales-server" the name of the session or server? Maybe both?
    logged in as Administrator nothing wrong here
    delete a workbook on the Sales site called Sales_Analysis
    • Why is a workbook deleted, not something else?
      Even after looking at the command doc it's not clear, but that's another friction point.
    • Is "Sales_Analysis" the workbook name, or the name of a site on something named "Sales"?
    • In reality, "Sales_Analysis" is the workbook name, but it takes a two-step back-reference, and recognizing the fact from the confusing and unreliable explanation for this to be clear.
      Or it takes understanding the tabcmd command structure to know this, highlighting the danger of documentation being written by someone who knows the material but not how to think like someone who doesn't.
  • I could go on, but the horse is well beaten.

Sunday, May 20, 2012

Vanishing Table Borders

Getting the borders you want on Tableau tables can be a very tricky business. When you're building your views and trying to get the borders in place it can feel like you're in a Wonderland, where nothing is what it seems, and nothing stays the same.

The fundamental source of perplexity is that Tableau's borders model is not intuitive, and it's operational model of configuring the borders further muddies the water. In combination, these make for a situation where getting what you want is very much a trial and error process, made worse because it's an unstable condition, and almost not repeatable.

By unstable we mean that the borders configuration you specify can be changed by Tableau in response to actions that are not, from our perspective, connected to the borders' configuration. The Tableau Public workbook embedded below illustrates the basics of this—as dimensions and measures are added to a worksheet Tableau changes the table's borders on its own. This is at best confusing, and is a signal that Tableau considers border decorating an implicit property of the visualization process. In this concept, Tableau reserves the right to change the borders at will, with the user's border specification a subordinate consideration.

Applying lubricant.

In order to get the borders you want, follow these steps:

  1. content first: fully construct your table with the rows, columns, and contents you want
  2. style second: configure the borders to your satisfaction
  3. accept that if you change the rows, columns or contents Tableau may well reconfigure the borders

Thursday, May 17, 2012

Garbled Data from HTML Tables

I was putting together my tides dashboards -here- and found a source of tidal data on a web page.

Lucky day, thought I: with Tableau's copy-and-paste data-grabbing ability it promised to be a simple matter of highlighting the table, ctrl-c, switch the Tableau, ctrl-v, and away we go.

Sadly, my hopes were dashed. Upon pasting the data into Tableau it wasn't at all the same as the web page presented it. In fact, it was pretty much unusable. I was a wee bit miffed, my plans to get back to the beach, nice new tides tables showing up on my iPad were dashed.

The trouble turned out to be the way Tableau recognizes data copied from HTML tables. In this specific instance, the presence of a <br> tag in one of the table headers to make it easier to read was interpreted by Tableau as an end-of-line signal, which scrambled the record processing in the middle of reading the field name first record.

The workbook below, published to Tableau Public, details the situation.

Interestingly, when I contacted Tableau about this situation they told me that it's behaving precisely as intended, that <br> tags are explicitly interpreted as end of record characters because "those are the rules".

Sunday, May 13, 2012

Unexpected Number Reformatting

Tableau sometimes decides that it will format numbers in ways that don't seem to make much sense. In some cases it even contradicts itself, changing a measure's number format in mid-visualization.

The Tableau Published Workbook below demonstrates one such scenario. To see it, cycle through the dashboards in sequence:

  1. The Data – simple data for the Seven Dwarfs.
  2. Connected to Dwarves.csv – Tableau connected to the data.
  3. Correct Number Displays – with one Measure in a table, Tableau uses the right format.
  4. Unwanted Format Changes – adding a second Measure causes Tableau to change the format.
Additional content follows the Workbook.

The Video

This video shows the reformatting in action. The Dwarves data is in the Tableau Public workbook, which can be downloaded.

The primary problem

When someone loads some data there's usually an expectation about the data's nature. In the Dwarves data, the number of Gems mined is a whole number-an integer, and the number of years working in the mine is known to be the number of whole years-another integer.

When Tableau places the Gems and Years in Mine values into an empty table it uses an integer format - no decimal digits. However, upon placing a second value into the same table Tableau decides that it's now appropriate to use a decimal format with two decimal digits.

This is bad.

Consequences

User confusion — changing a visible attribute on a significant element causes the user cognitive problems.

Unrecoverability — once this happens it's unclear how to correct the situation, or prevent it from happening in the future.