Refresh flow output files from the command line

Note: Running flows from the command line that include connections using either the JDBC or ODBC connectors is supported starting in version 2019.2.3.

Also, flows that include cloud connectors, such as Google BigQuery, can't be run from the command line. Instead run the flow manually or run the flow on a schedule in Tableau Server or Tableau Online.

If you want to refresh output files for your flow you can run the flow from the command line instead of opening it in Tableau Prep Builder and running the flow from there. You can run one flow at a time using this method. This option is available on both Windows and Mac machines where Tableau Prep Builder is installed.

For Windows machines, you can also schedule this process using Windows Task Scheduler. For more information about using Windows Task Scheduler, see Task Scheduler in the Microsoft online help.

When you run flows from the command line, Tableau Prep Builder refreshes all outputs for the flow.

You can also schedule your flow to run automatically in Tableau Server or Tableau Online using Tableau Prep Conductor. For more information about using Tableau Prep Conductor to run flows, see Keep Flow Data Fresh.

Note: The output location for the files is specified in the output step for the flow in Tableau Prep Builder when you run the flow. When you refresh the files from the command line, this process uses that same location and will overwrite any previous output files for the flow with the refreshed version.

For information about how to specify an output location for your flow files, see Refresh flow output files from the command line.

To run the flow from the command line, you'll need the following:

  • Administrator privileges on the machine where you are running the flow.

  • The path where Tableau Prep Builder is installed.

  • If connecting to databases and publishing output files to a server, a credentials .json file that includes all required credentials.

  • The path where the Tableau Flow (.tfl) file is located.

Before running the flow

If you are running a flow that connects to database files, published data sources, or publishes output files to a server, then you'll need to create a .json file that includes the credentials that are required to connect to these locations.

When you run the process, the hostname, port and username provided in the credentials .json file is used to find the matching connection in the Tableau flow file (tfl) and updated before running the process.

If connecting to a published data source, include hostname and contentUrl and port (80 for http and 443 for https) in the input connections. The hostname is required to find the matching connection in the Tableau flow file (tfl), and the contentUrl and port is used to establish the connection to the server.

Note: Skip this step if the flow connects to and outputs to local files, files stored on a network share or input files that use Windows Authentication (SSPI). For more information about Windows Authentication, see SSPI Model in the Microsoft online help.

If you plan to reuse the file, place it in a folder where it won't be overwritten by the Tableau Prep Builder install process.

The following table lists the credentials that you need to include in the .json file. Port ID and Site ID are optional if your connections don't require this information.

Input connections Output location
  • hostname (Server name)
  • contentUrl (published data sources) Site ID. This appears after /site/ in the URL when you sign into Tableau Server or Tableau Online
  • port (Port ID)
  • username
  • Password
  • serverUrl
  • contentUrl (Site ID. This appears after /site/ in the URL when you sign into Tableau Server or Tableau Online)
  • username
  • password

The following example shows the syntax to use for the credentials .json file when connecting to a published data source.

{
"inputConnections":[
  {
    "username": "jsmith",
    "contentUrl": "my-testing-site",
    "hostname":"https://my-server",
    "port":443,
    "password": "passw0rd$"
  }
],
"outputConnections":[
  {
    "serverUrl":"https://my-server",
    "contentUrl":"my-testing-site",
    "username":"jsmith",
    "password":"passw0rd$"
  }
]
}

The following example shows the syntax to use for the credentials .json file when connecting to two databases (MySQL and Oracle) and outputs files to a server that includes a Site ID.

{
"inputConnections":[
  {
    "username": "jsmith",
    "hostname":"mysql.example.lan",
    "port":1234,
    "password": "passw0rd"
  },
  {
    "username": "jsmith",
    "hostname":"Oracle.example.lan",
    "port":5678,
    "password": "passw0rd" 
  }
],
"outputConnections":[
  {
    "serverUrl":"http://MyServer",
    "contentUrl":"FinanceTeam",
    "username":"jsmith",
    "password":"passw0rd$"
  }
]
}

Tips for creating your credentials file

Tableau Prep Builder uses information from the flow file and from the credentials .json file to run the flow when you have remote connections. For example, the database name for your remote connections and the project name for your output files come from the flow, and the server name and the log in credentials come from the .json file.

To avoid errors when running the flow, make sure your credentials file follows these guidelines:

  • If using Tableau Prep Builder version 2018.2.2 through 2018.3.1, always include the "inputConnections" and "outputConnections" arrays even if the flow doesn't have remote connections for inputs or outputs. Just leave those arrays blank. If you are using Tableau Prep Builder version 2018.3.2 and later you don't need to include the blank array.

    • No remote input connection? Include this syntax at the top of the .json file

      {
      "inputConnections":[
        ],
    • No remote output connection? Include this syntax at the bottom of the .json file

    • "outputConnections":[
        ]
      }
  • No port ID for your input connection or the port is specified as part of the server name? If there is no port ID for your connection, don't include the "port":xxxx, reference in the .json file, not even "port": "". If the port ID is included in the server name, include the port ID in the host name. For example "hostname": "mssql.example.lan,1234"

  • When referencing the "serverUrl": don't include a "/" at the end of the address. For example, use this "serverUrl": "http://server" not this "serverUrl": "http://server/".

  • If you have multiple input or output connections include the credentials for each one in the file.

  • If connecting to published data sources, make sure to include the hostname and contentUrl in the input connections.

Run the flow

Important: The examples below include the name change for "Tableau Prep" version 2019.1.2 to "Tableau Prep Builder". If you are using an earlier version of the product use "Tableau Prep" instead.

  1. Open the command prompt or terminal command prompt (Mac) as an Administrator.

  2. Run one of the following commands:

    • The flow connects to local files or files stored on a network share and publishes to local files, files stored on a network share or uses Windows authentication:

      Note: If connecting to or outputting to files stored on a network share, use the UNC format for the path: \\server\path\file name. It can't be password protected.

      Windows

       "\[Tableau Prep Builder install location]\Tableau Prep Builder <version>\scripts"\tableau-prep-cli.bat -t "path\to\[your flow file name].tfl"

      Mac

      /Applications/Tableau\ Prep\ Builder\ [Tableau Prep Builder version].app/Contents/scripts/./tableau-prep-cli -t path/to/[your flow file name].tfl
    • The flow connects to databases or publishes to a server:

      Windows

      "\[Tableau Prep Builder install location]\Tableau Prep Builder <version>\scripts"\tableau-prep-cli.bat -c "path\to\[your credential file name].json" -t "path\to\[your flow file name].tfl"

      Mac

      /Applications/Tableau\ Prep\ Builder\ [Tableau Prep Builder version].app/Contents/scripts/./tableau-prep-cli -c path/to/[your credential file name].json -t path/to/[your flow file name].tfl
    • The flow file or credentials file is stored on a network share (use the UNC format for the path: \\server\path\file name):

      Windows

      "\[Tableau Prep Builder install location]\Tableau Prep Builder <version>\scripts"\tableau-prep-cli.bat -c "\server\path\[your credential file name].json" -t "\server\path\[your flow file name].tfl"

      Mac: Map the network share to /Volumes in Finder so that it is persistent, then use /Volumes/.../[your file] to specify the path:

      /Applications/Tableau\ Prep\ Builder\ [Tableau Prep Builder version].app/Contents/scripts/./tableau-prep-cli -c /Volumes/.../[your credential file name].json -t path/to/[your flow file name].tfl

    For examples of sample commands see Syntax examples. For common errors and resolutions see Common errors when using the command line to run flows.

Command options

If you want to view the help options, include -h in the command line.

Command options Description Notes
-c The connection path to the credentials file. Requires the path to where the credentials file is located.
-d Debug the flow process. Include this option to view more information to help debug a problem with refreshing the flow. Log files are stored in: My Tableau Prep Builder Repository\Command Line Repository\Logs
-dsv Disable SSL validation (MacOS) When running flows using the command line on the MacOS, a dialog may show asking for the keychain user and password. Starting with Tableau Prep Builder version 2019.3.2, you can pass in this additional parameter to disable this keychain dialog. For example: /Applications/Tableau\ Prep\ Builder\ [Tableau Prep Builder version].app/Contents/scripts/./tableau-prep-cli -dsv -c path/to/[your credential file name].json -t path/to/[your flow file name].tfl
-h View the help for syntax options

The help option or a syntax error shows the following information:

usage: tableau-prep-cli [-c <arg>] [-d]  [-h] [-t <arg>]
-c,--connections <arg>        Path to a file with all connection information
-d,--debug                    This option is for debugging
-h,--help                     Print usage message
-t,--tflFile <arg>            The Tableau Prep Builder flow file	
-t The .tfl flow file Requires the path to where the .tfl flow file is located.

Syntax examples

The command lines below show three different examples for running a flow using the following criteria:

  • Tableau Prep Builder version: 2019.3.1

    Important: The examples below include the name change for Tableau Prep version 2019.1.2 to Tableau Prep Builder. If you are using an earlier version of the product use "Tableau Prep" instead.

  • Flow name: Flow1.tfl

  • Flow location: C:\Users\jsmith\Documents\My Tableau Prep Builder Repository\Flows

  • Credentials file name: Flow 1.json

  • Credentials file location: C:\Users\jsmith\Desktop\Flow credentials

  • Credentials file location stored on a network share: \tsi.lan\files\Flow credentials

The flow connects to and publishes to local files

Windows

"\Program Files\Tableau\Tableau Prep Builder 2019.3.1\scripts"\tableau-prep-cli.bat   -t "\C:\Users\jsmith\Documents\My Tableau Prep Builder Repository\Flows\Flow1.tfl"

Mac

/Applications/Tableau\ Prep\ Builder\ 2019.3.1.app/Contents/scripts/./tableau-prep-cli  -t /Users/jsmith/Documents/My\ Tableau\ Prep\ Builder\ Repository/Flows.Flow1.tfl

The flow connects to databases and publishes to a server

Windows

"\Program Files\Tableau\Tableau Prep Builder 2019.3.1\scripts"\tableau-prep-cli.bat -c "\C:\Users\jsmith\Desktop\Flow credentials\Flow1.json" -t "\C:\Users\jsmith\Documents\My Tableau Prep Builder Repository\Flows\Flow1.tfl"

Mac

/Applications/Tableau\ Prep\ Builder\ 2019.3.1.app/Contents/scripts/./tableau-prep-cli -c /Users/jsmith/Desktop/Flow\ credentials/Flow1.json -t /Users/jsmith/Documents/My\ Tableau\ Prep\ Builder\ Repository/Flows.Flow1.tfl

The flow publishes to a server and the credentials file is stored on a network share

Windows

"\Program Files\Tableau\Tableau Prep Builder 2019.3.1\scripts"\tableau-prep-cli.bat -c "\\tsi.lan\files\Flow credentials\Flow1.json" -t "\C:\Users\jsmith\Documents\My Tableau Prep Builder Repository\Flows\Flow1.tfl"
Mac/Applications/Tableau\ Prep\ Builder\ 2019.3.1.app/Contents/scripts/./tableau-prep-cli -c /Volumes/files/Flow\ credentials/Flow1.json -t /Users/jsmith/Documents/My\ Tableau\ Prep\ Builder\ Repository/Flows.Flow1.tfl
Thanks for your feedback! There was an error submitting your feedback. Try again or send us a message.