### Install and run the hello-world example Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/README.md Install the cwtwb package and run the canonical end-to-end workflow script. This is the quickest way to see the SDK in action. ```bash pip install cwtwb python examples/scripts/demo_e2e_mcp_workflow.py ``` -------------------------------- ### Development commands Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Commands for installing the package in editable mode, running the test suite, executing example scripts, and starting the MCP server. ```bash # Install in editable mode pip install -e . # Run test suite pytest --basetemp=output/pytest_tmp # Run the mixed showcase example python examples/scripts/demo_all_supported_charts.py # Run the advanced Hyper-backed example python examples/scripts/demo_hyper_and_new_charts.py # Run the guided migration example python examples/migrate_workflow/test_migration_workflow.py # Start MCP server cwtwb ``` -------------------------------- ### Install cwtwb with pip Source: https://github.com/aidatacooper/cwtwb/blob/main/README.md Install cwtwb. Use the base command for the core package, add the [examples] extra to include the Hyper-backed example, or add the [validate] extra for cloud validation uploads to Tableau Cloud/Server. ```bash pip install cwtwb ``` ```bash pip install "cwtwb[examples]" ``` ```bash pip install "cwtwb[validate]" ``` -------------------------------- ### Python example: migrate_twb_guided_json Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Shows how to run a guided migration in one call. If the result status is 'warning_review_required', you can inspect the warning_review_bundle and re-run with mapping_overrides to confirm or override low-confidence matches. ```python from cwtwb.migration import migrate_twb_guided_json import json # One-call guided migration result = migrate_twb_guided_json( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx", output_path="output/SalesDashboard_migrated.twb", ) bundle = json.loads(result) if bundle["status"] == "warning_review_required": # Inspect low-confidence matches and confirm or override them print(bundle["warning_review_bundle"]) # Re-run with confirmed mappings result = migrate_twb_guided_json( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx", output_path="output/SalesDashboard_migrated.twb", mapping_overrides={"Old Field Name": "New Column Name"}, ) ``` -------------------------------- ### Run any example script from the project root Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/README.md Shows how to run the end-to-end workflow and the all-supported-charts scripts from the project root. These are the two primary examples. ```bash python examples/scripts/demo_e2e_mcp_workflow.py python examples/scripts/demo_all_supported_charts.py ``` -------------------------------- ### Clone and set up cwtwb for development Source: https://github.com/aidatacooper/cwtwb/blob/main/CONTRIBUTING.md Clones the repository, installs it in editable mode with the dev extra, and runs the test suite. The [dev] extra includes local contributor tooling for test, lint, and type-check; runtime-only usage can use `pip install -e .` instead. ```bash git clone https://github.com//cwtwb cd cwtwb pip install -e ".[dev]" pytest ``` -------------------------------- ### Setup for Cloud Validation with cwtwb[validate] Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Installs the validation extra and copies the environment template. Fill in Tableau Cloud PAT credentials in the .env file. Credentials can also be selected at runtime with env_path, TABLEAU_ENV_FILE, or a .env file next to the workbook; explicit env_path has the highest priority. ```bash pip install "cwtwb[validate]" cp .env.example .env # Fill in your Tableau Cloud PAT credentials ``` -------------------------------- ### Run migration workflow script Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/migrate_workflow/README.md Executes the migration example script from the repo root. The script runs migrate_twb_guided() to collect warning_review_bundle, then confirms warning mappings via mapping_overrides. It writes the migrated .twb, migration_report.json, and field_mapping.json back to the example folder. ```bash python examples/migrate_workflow/test_migration_workflow.py ``` -------------------------------- ### Tooltip examples for map and multiple tooltips Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/formatting.md Shows how to add tooltips to a chart. The first example adds absolute profit values to a map colored by Profit Ratio. The second shows multiple tooltips with profit, sales, and quantity. ```python # Map showing Profit Ratio as color → add absolute values as tooltip configure_chart("SaleMap", ..., color="Profit Ratio", tooltip="SUM(Profit)") # Shows actual dollar profit on hover # Multiple tooltips configure_chart("SaleMap", ..., tooltip=["SUM(Profit)", "SUM(Sales)", "SUM(Quantity)"]) ``` -------------------------------- ### TWBEditor Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Constructor for TWBEditor to start from a template. ```APIDOC ## TWBEditor ### Description Creates a TWBEditor instance starting from a template and rebuilds workbook content. ### Method TWBEditor ### Parameters - **template** (string) - Required - Template path; empty string uses built-in Superstore template ### Example ```python from cwtwb.twb_editor import TWBEditor editor = TWBEditor("") # "" uses the built-in Superstore template ``` ``` -------------------------------- ### MCP tool example: explicit migration workflow Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Shows how an AI agent can run the explicit migration steps via MCP tools, from inspecting the target schema to applying the migration. Each tool call is shown with its parameters and the expected return value. ```text inspect_target_schema(target_source="data/new_data_source.xlsx") → returns column list and data types profile_twb_for_migration( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx" ) → inventories source fields and workbook scope propose_field_mapping( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx" ) → proposes source-to-target field mappings preview_twb_migration( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx" ) → returns blockers, warnings, and planned rewrites apply_twb_migration( file_path="workbooks/SalesDashboard.twb", target_source="data/new_data_source.xlsx", output_path="output/SalesDashboard_migrated.twb" ) → writes the migrated workbook and reports ``` -------------------------------- ### Create workbook from template with TWBEditor Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Starts from the built-in Superstore template, clears worksheets, adds a calculated field, configures two charts, adds a dashboard, and saves the workbook. Use TWBEditor.open_existing() to keep existing worksheets and dashboards. ```python from cwtwb.twb_editor import TWBEditor editor = TWBEditor("") # "" uses the built-in Superstore template editor.clear_worksheets() editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])") editor.add_worksheet("Sales by Category") editor.configure_chart( worksheet_name="Sales by Category", mark_type="Bar", rows=["Category"], columns=["SUM(Sales)"], ) editor.add_worksheet("Segment Pie") editor.configure_chart( worksheet_name="Segment Pie", mark_type="Pie", color="Segment", wedge_size="SUM(Sales)", ) editor.add_dashboard( dashboard_name="Overview", worksheet_names=["Sales by Category", "Segment Pie"], layout="horizontal", ) editor.save("output/my_workbook.twb") ``` -------------------------------- ### cURL example for validateWorkbookAndUpload Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/tableau-validation-api.md Example cURL command to call the endpoint. Uses X-Tableau-Auth header and multipart form data with the tableau_workbook parameter. ```bash curl --location \ 'https://example.com/api/3.29/sites/{site-id}/workbooks/validateWorkbookAndUpload' \ --header 'X-Tableau-Auth: {auth-token}' \ --header 'Accept: application/json' \ --form 'tableau_workbook=@"path/to/file.twb"' ``` -------------------------------- ### Add a range parameter with add_parameter Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/calculation_builder.md Example of adding a currency target parameter with a range domain, including min, max, granularity, and format. ```python add_parameter( name="Target Profit", datatype="real", default_value="10000", domain_type="range", min_value="-30000", max_value="100000", granularity="10000", default_format="$#,##0" ) ``` -------------------------------- ### cURL example for validateUploadedWorkbook Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/tableau-validation-api.md Example cURL command to call the validateUploadedWorkbook endpoint. Uses X-Tableau-Auth header and Accept: application/json. ```bash curl --location --request POST \ 'https://example.com/api/3.29/sites/{site-id}/workbooks/validateUploadedWorkbook?uploadSessionId=12345:12ab34cd56ef78ab90cd12ef34ab56cd-0:0' \ --header 'X-Tableau-Auth: {auth-token}' \ --header 'Accept: application/json' ``` -------------------------------- ### Run cwtwb as an MCP server Source: https://github.com/aidatacooper/cwtwb/blob/main/README.md Run cwtwb as an MCP server. In an interactive terminal it prints CLI help; when launched by an MCP client over stdio it starts the server. ```bash uvx cwtwb ``` -------------------------------- ### Complex Dashboard Layout Example Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md A detailed JSON structure demonstrating the use of containers, worksheets, filters, and color legends. ```json { "type": "container", "direction": "vertical", "children": [ { "type": "container", "direction": "horizontal", "fixed_size": 56, "children": [ {"type": "worksheet", "name": "KPI Sales"}, {"type": "worksheet", "name": "KPI Profit"} ] }, { "type": "container", "direction": "horizontal", "children": [ {"type": "worksheet", "name": "Sales Map", "weight": 55}, { "type": "container", "direction": "vertical", "fixed_size": 132, "children": [ {"type": "filter", "worksheet": "Sales Map", "field": "Order Date", "mode": "dropdown"}, {"type": "filter", "worksheet": "Sales Map", "field": "Region", "mode": "dropdown"}, {"type": "color", "worksheet": "Sales Map", "field": "Profit Ratio"} ] } ] }, { "type": "container", "direction": "horizontal", "children": [ {"type": "worksheet", "name": "Sales Trend"}, {"type": "worksheet", "name": "Sub-Category Breakdown"} ] } ] } ``` -------------------------------- ### Project structure tree Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Shows the repository layout for the cwtwb project, including source modules, tests, examples, docs, and configuration files. ```text cwtwb/ |-- src/cwtwb/ | |-- __init__.py | |-- capability_registry.py | |-- config.py | |-- charts/ | |-- connections.py | |-- dashboard_actions.py | |-- dashboard_dependencies.py | |-- dashboard_layouts.py | |-- dashboards.py | |-- field_registry.py | |-- layout.py | |-- layout_model.py | |-- layout_rendering.py | |-- mcp/ | |-- parameters.py | |-- skills/ | |-- twb_analyzer.py | |-- twb_editor.py | |-- validate/ # Cloud validation (upload + screenshot) | |-- validator.py | `-- server.py |-- tests/ |-- examples/ |-- docs/ |-- pyproject.toml `-- README.md ``` -------------------------------- ### Label example for bar chart Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/formatting.md Adds labels to a bar chart to show exact values on bars, with descending sort by sales. ```python configure_chart("Sales by Region", mark_type="Bar", rows=["Region"], columns=["SUM(Sales)"], label="SUM(Sales)", # Show values on bars sort_descending="SUM(Sales)") ``` -------------------------------- ### URL Action: add_dashboard_action with action_type='url' Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md Use URL actions when analysis should open an external workflow or reference. The example opens 'https://example.com/product-detail' from 'Sub-Category Breakdown' with caption 'Open Product Detail'. Best practices: keep URL stable and task-oriented, use for handoff/documentation/downstream workflows, avoid too many competing URLs. ```python add_dashboard_action( dashboard_name="Executive Overview", action_type="url", source_sheet="Sub-Category Breakdown", url="https://example.com/product-detail", caption="Open Product Detail", ) ``` -------------------------------- ### Go-To-Sheet Action: add_dashboard_action with action_type='go-to-sheet' Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md Use go-to-sheet actions for a clear overview-to-detail flow. The example navigates from 'Sales Map' to 'State Detail' with caption 'Open State Detail'. Best practices: use only on strong drill-down entry points, keep target sheet focused, pair with caption. ```python add_dashboard_action( dashboard_name="Executive Overview", action_type="go-to-sheet", source_sheet="Sales Map", target_sheet="State Detail", caption="Open State Detail", ) ``` -------------------------------- ### Filter Type Examples: Categorical and Quantitative Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Two filter type examples from the Filter Types table: a categorical filter for a dimension with few values and a quantitative filter for date or numeric ranges. The categorical example uses only the column name, while the quantitative example adds the type property. ```json {"column": "Region"} ``` ```json {"column": "Order Date", "type": "quantitative"} ``` -------------------------------- ### Configure chart with independent measure domains Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/case-driven-enhancements.md Configures a chart with independent color domains for multiple measures. The virtual field is not added as a physical datasource column. Native color and text bindings share separate-domains=true, while existing detail, tooltip, and color bindings survive Measure Values setup. ```python editor.configure_chart("Metrics", mark_type="Square", rows=["Group"], measure_values=["COUNT(ID)", "SUM(Sales)", "SUM(Profit)"], color="Multiple Values", separate_measure_domains=True) ``` -------------------------------- ### Pass env_path to validate_workbook_api Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/validation.md Example of passing env_path to validate_workbook_api when credentials live outside the MCP server's launch environment. env_path takes priority over process environment variables. ```text validate_workbook_api(twb_path, validation_level="semantic", env_path="project/.env") ``` -------------------------------- ### Highlight Action: add_dashboard_action with action_type='highlight' Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md Use highlight actions for softer cross-chart coordination. The example highlights from 'Sales Trend' to 'Sub-Category Breakdown' on field 'Order Date'. Best practices: prefer highlight for comparison without filtering away context, use for shared time periods or dimensions. ```python add_dashboard_action( dashboard_name="Executive Overview", action_type="highlight", source_sheet="Sales Trend", target_sheet="Sub-Category Breakdown", fields=["Order Date"], ) ``` -------------------------------- ### Configure layered chart with pane path/color_extra and worksheet style Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/case-driven-enhancements.md Configures a paired TC/LOD chart with two Multiple Values panes, one using path binding and explicit measure_values, the other with color_extra and detail. Overrides table calculations for Metric A and hides Measure Names labels via worksheet style. This example corresponds to the WW09 parallel coordinates and WW07 paired bar enhancements. ```python editor.configure_layered_chart( "Comparison", columns=["Measure Names"], rows=["Multiple Values", "Multiple Values"], panes=[ {"axis": "Multiple Values", "mark_type": "Line", "detail": "Item", "color": "Selected", "color_extra": ["ATTR(Venue)"], "measure_values": ["Metric A", "Metric B"]}, {"axis": "Multiple Values", "mark_type": "Line", "path": "Item", "label": "Measure Names"}, ], table_calc_overrides={"Metric A": [{"ordering_type": "Field", "order": ["Item", "Selected"]}]}, synchronized=True, hide_axes=True, ) editor.configure_worksheet_style("Comparison", label_formats=[ {"field": "Measure Names", "display": "false"}]) ``` -------------------------------- ### Parameter Action: add_dashboard_action with action_type='parameter' Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md Use parameter actions when selecting a mark should update a workbook parameter. The example sets parameter 'Selected Minimum Date' from 'Apply Button' source field 'Minimum Date' with aggregation 'attr', clear_behavior 'keep-current', clear_value 'd:2026-02-12', and caption 'Set Minimum Date'. Note: clear_value uses Tableau's serialized value format; common examples are 'd:2026-02-12' for date, 'i:0' for integer, 's:LROOT:All' for string. Use clear_behavior='set-value' to assign fixed value on clear, otherwise keep-current. ```python add_dashboard_action( dashboard_name="Analysis", action_type="parameter", source_sheet="Apply Button", source_field="Minimum Date", target_parameter="Selected Minimum Date", aggregation="attr", clear_behavior="keep-current", clear_value="d:2026-02-12", caption="Set Minimum Date", ) ``` -------------------------------- ### Set date options and configure worksheet style with color_style Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/case-driven-enhancements.md Sets the start of week to Sunday and configures a worksheet style with a diverging color palette, center, and totals inclusion. The cell_formats preserve data_class and scope as selectors, enabling decimal average totals with integer detail values. ```python editor.set_date_options(start_of_week="sunday") editor.configure_worksheet_style("Average", color_style={ "field": "SUM(Sales)", "palette": "red_blue_white_diverging_10_0", "center": 0, "include_totals": True}, cell_formats=[{ "field": "SUM(Sales)", "text-format": "n0.00", "data_class": "subtotal", "scope": "rows"}]) ``` -------------------------------- ### Filter Action: add_dashboard_action with action_type='filter' Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md Use filter actions when the primary chart should drive supporting detail views. The example sets a filter action from 'Sales Map' to 'Sub-Category Breakdown' on field 'State/Province' with event type 'on-select'. Best practices: use from main chart to secondary detail charts, choose field matching drill path, keep action easy to explain. ```python add_dashboard_action( dashboard_name="Executive Overview", action_type="filter", source_sheet="Sales Map", target_sheet="Sub-Category Breakdown", fields=["State/Province"], event_type="on-select", ) ``` -------------------------------- ### Ad-hoc terminal commands to avoid for cwtwb Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md These commands are not part of cwtwb and most user machines do not have an mcp CLI installed. They are shown as examples of what agents should not try to invoke. ```bash mcp list-tools cwtwb mcp call cwtwb create_workbook '{"name": "Example"}' gh api /orgs/.../mcp/servers/cwtwb/tools ``` -------------------------------- ### Workflow for defining parameters and calculated fields Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/calculation_builder.md Outlines the sequential steps: define parameters first, then basic calculated fields, then advanced fields, and finally verify with list_fields. ```text 1. Define parameters first (they're referenced by calculated fields) 2. Create basic calculated fields (ratios, differences, flags) 3. Create advanced fields (LOD expressions, table calculations) 4. Verify: call list_fields to confirm all fields are registered ``` -------------------------------- ### cURL Example for validateWorkbook Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/tableau-validation-api.md cURL example for validating a TWB file. The file must be .twb (not .twbx) and the filename must end with .twb. The tableau_workbook form parameter is required. ```bash curl --location \ 'https://example.com/api/3.29/sites/{site-id}/workbooks/validateWorkbook' \ --header 'X-Tableau-Auth: {auth-token}' \ --header 'Accept: application/json' \ --form 'tableau_workbook=@"path/to/file.twb"' ``` -------------------------------- ### TWBEditor.open_existing Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Opens an existing workbook for in-place reconfiguration. ```APIDOC ## TWBEditor.open_existing ### Description Opens an existing workbook to keep existing worksheets and dashboards and reconfigure a sheet in place. ### Method open_existing ### Parameters - **path** (string) - Required - Path to existing workbook ### Example ```python editor = TWBEditor.open_existing("existing.twb") ``` ``` -------------------------------- ### Migration workflow steps (text) Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Lists the five explicit migration steps available as MCP tools and Python functions: inspect_target_schema, profile_twb_for_migration, propose_field_mapping, preview_twb_migration, and apply_twb_migration. ```text 1. inspect_target_schema → Scan the target Excel and list its columns 2. profile_twb_for_migration → Inventory which fields the workbook uses 3. propose_field_mapping → Match source fields to target columns (fuzzy) 4. preview_twb_migration → Dry-run: show what would change, blockers/warnings 5. apply_twb_migration → Write the migrated .twb + JSON reports ``` -------------------------------- ### KPI card ordering with measure_values Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/formatting.md Shows the recommended order for KPI card metrics, leading with primary revenue, then profitability, efficiency, and volume. ```python # Good ordering: primary KPI → profitability → efficiency → volume measure_values=[ "SUM(Sales)", # 1. Primary revenue metric "SUM(Profit)", # 2. Profitability "Profit Ratio", # 3. Efficiency ratio "Profit per Order", # 4. Per-unit metric "Profit per Customer",# 5. Per-customer metric "AVG(Discount)", # 6. Cost indicator "SUM(Quantity)" # 7. Volume ] ``` -------------------------------- ### add_calculated_field Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/calculation_builder.md Documentation for the add_calculated_field SDK function, including parameters and usage examples for table calculations. ```APIDOC ## add_calculated_field ### Description Adds a calculated field to a Tableau workbook, supporting table calculations such as rank, running sum, and window sum. The `table_calc` parameter controls the `` XML element emitted by the SDK. ### Method SDK function call ### Parameters - **field_name** (string) - Required - Name of the calculated field. - **formula** (string) - Required - Tableau formula, e.g., `RANK_DENSE(sum([Current Year Sales]),'desc')`. - **datatype** (string) - Required - Data type of the field, e.g., `integer` or `real`. - **field_type** (string) - Optional - `ordinal` for rank labels, `quantitative` (default) for running totals/window aggregates. - **table_calc** (string or mapping) - Required - Either `"Rows"` or `"Columns"` for directional cases, or a mapping like `{"ordering_type": "Field", "ordering_field": "[Datasource].[Date]"}` for richer metadata. ### Request Example ```python add_calculated_field( field_name="Rank CY", formula="RANK_DENSE(sum([Current Year Sales]),'desc')", datatype="integer", field_type="ordinal", table_calc="Rows" ) ``` ### Response No explicit response documented. The SDK emits the appropriate `` XML element and propagates metadata into referenced `` elements. ``` -------------------------------- ### Explicit MCP server launch commands Source: https://github.com/aidatacooper/cwtwb/blob/main/README.md Equivalent explicit launch styles for the MCP server: using 'uvx cwtwb mcp', 'uvx --from cwtwb cwtwb-mcp', or 'python -m cwtwb.mcp_server'. ```bash uvx cwtwb mcp uvx --from cwtwb cwtwb-mcp python -m cwtwb.mcp_server ``` -------------------------------- ### Pie Chart with configure_chart Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Creates a pie chart for composition or parts-of-whole data. Use at most 5-6 slices; beyond that, prefer a bar chart. Leave columns and rows empty and always add a label to show values. ```python configure_chart("Market Share", mark_type="Pie", color="Segment", # Slices wedge_size="SUM(Sales)", # Slice size label="SUM(Sales)") # Values on slices ``` -------------------------------- ### Auto Layout Generation Prompt for MCP-Enabled LLM Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/prompts/demo_auto_layout_prompt.md Use this natural-language prompt with an MCP-enabled LLM to automatically generate a complete dashboard. It instructs the LLM to call `create_workbook` with no template path (using the built-in Superstore dataset), create three bar charts, arrange them in a 1200x800 dashboard named "Auto Layout Demo" with a specific layout, and save the result to `output/demo_auto_layout.twb`. ```text Build a sales dashboard for me. Call `create_workbook` with no template path to use the built-in Superstore dataset. 1. Create 3 Bar charts: "Sales By Category", "Profit Map", and "Daily Highlights". 2. Arrange them in a new dashboard (1200x800) called "Auto Layout Demo". 3. Layout: Top half is split horizontally between "Sales By Category" and "Profit Map". Bottom half is "Daily Highlights" taking up the full width. 4. Save to `output/demo_auto_layout.twb`. ``` -------------------------------- ### KPI Card with measure_values Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Creates a KPI card with multiple metrics. Use 5-8 metrics maximum, lead with the most important, and mix absolute values with ratios. ```python configure_chart("Total Sales", mark_type="Text", measure_values=["SUM(Sales)", "SUM(Profit)", "Profit Ratio", "AVG(Discount)", "SUM(Quantity)"]) ``` -------------------------------- ### 200 Response for validateWorkbook Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/tableau-validation-api.md Example 200 response when the workbook is valid but may have warnings. The warnings array contains severity, message, line, column, and elementName. ```json { "timestamp": "2026-06-10T14:32:18.456Z", "warnings": [ { "severity": "WARNING", "message": "Unknown map source is used", "line": 245, "column": 18, "elementName": "map" } ] } ``` -------------------------------- ### Natural Language Prompt for Building Executive Dashboard Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/prompts/demo_declarative_layout_prompt.md Use this prompt with an LLM connected to the cwtwb MCP server to create a workbook with 8 worksheets and 2 dashboards. It specifies 4 bar charts, 4 KPI text summaries, and reads layout JSON files from examples/layouts/layout_executive.json and examples/layouts/layout_c2.json. ```text Hi! I want to build an Executive Dashboard related to sales using the cwtwb tool. First, I need 8 worksheets in total. Four of them are detail charts: - "Sales By Category", "Profit Map", "Discount Trend", "Daily Highlights" Please configure all 4 as Bar charts. Put "Ship Mode" on rows and "SUM(Sales)" on columns. The other four are KPI text summaries (they should use the Text mark_type). Please name them by adding " - KPI" to the end of the previous names. Set their label values to SUM(Discount), SUM(Profit), SUM(Quantity), and SUM(Sales) respectively. Once the sheets are ready, create two dashboards: 1. "Executive Summary" (1400x900) For the layout parameter, please read the file `examples/layouts/layout_executive.json` and pass its content directly as the dictionary. Make sure to include all 8 worksheets in the `worksheet_names` list! 2. "C.2 Layout Replica" (1200x800) For this one's layout, please read `examples/layouts/layout_c2.json` and pass it. Include the 8 worksheets here too. Finally, save this workbook to `output`. Thanks! ``` -------------------------------- ### 422 Response for validateWorkbook Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/tableau-validation-api.md Example 422 response when validation errors are found. The errors array contains severity, message, line, column, and elementName. The warnings array is also present. ```json { "timestamp": "2026-06-10T14:32:18.456Z", "errors": [ { "severity": "ERROR", "message": "Missing required closing tag for element", "line": 127, "column": 5, "elementName": "preferences" } ], "warnings": [...] } ``` -------------------------------- ### list_capabilities Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Lists capabilities supported by the MCP server. ```APIDOC ## list_capabilities ### Description Lists the capabilities supported by the MCP server. ### Method list_capabilities ### Parameters None ### Example ```python capabilities = editor.list_capabilities() ``` ``` -------------------------------- ### Run tests Source: https://github.com/aidatacooper/cwtwb/blob/main/CONTRIBUTING.md Commands to run the full test suite, a single test file, and keep temporary workbooks for inspection. Tests are integration tests that build real .twb XML and assert structure with XPath. ```bash # Full suite pytest # Single file pytest tests/test_chart_routing.py -v # Keep temp workbooks for inspection pytest --basetemp=output/pytest_tmp ``` -------------------------------- ### KPI Difference Badge with configure_chart Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Creates a KPI difference badge for 'vs PY' comparison cards. Uses MIN(1) dummy axis, fixed range 0-1 on cols, mark_sizing_off=True, and customized_label with placeholders. color_map keys must exactly match the string values returned by the color field. ```python configure_chart( "Sales KPI Difference", mark_type="Circle", # or "Square" columns=["MIN(1)"], # dummy axis so there is no real x-axis color="Sales Color Filter", # a string field returning "BAD"/"GOOD" label="Sales Difference", # AGG calc returning a % value axis_fixed_range={"min": 0, "max": 1, "scope": "cols"}, mark_sizing_off=True, customized_label=" vs PY", color_map={"BAD": "#e15759", "GOOD": "#03a44e"}, text_format={"Sales Difference": "p0.00%"}, ) ``` -------------------------------- ### Use cwtwb as a CLI Source: https://github.com/aidatacooper/cwtwb/blob/main/README.md CLI commands for help, doctor, status, inspect, validate, analyze, and run. Read-only commands output JSON when requested. ```bash cwtwb --help cwtwb doctor cwtwb status --json cwtwb inspect workbook.twb --json cwtwb validate workbook.twb cwtwb analyze workbook.twb --json cwtwb run examples/specs/basic_cli.yaml ``` -------------------------------- ### Upload and screenshot workflow Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/validation.md Workflow for uploading a workbook and capturing a screenshot. Use only when the user explicitly asks for upload/publish evidence, a visual screenshot, a workbook_id, or .twbx package validation. Do not use as the default substitute for validate_workbook_api. ```text 1. save_workbook(path) 2. upload_workbook(twb_path, env_path="project/.env") - publish to Tableau Cloud 3. screenshot_workbook(workbook_id, env_path="project/.env") - capture view image 4. Report result to human ``` -------------------------------- ### configure_chart (Pie Chart) Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Configures a pie chart for composition/parts-of-whole visualization. Supports color for slices, wedge_size for slice size, and label for values on slices. ```APIDOC ## configure_chart (Pie Chart) ### Description Configures a pie chart for showing composition or parts of a whole. Use color for slices, wedge_size for slice size, and label for values on slices. ### Method configure_chart ### Parameters #### Named Parameters - **mark_type** (string) - Required - Set to ``` -------------------------------- ### Configure Donut chart recipe Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Use for the all_supported_charts workbook or when the user explicitly asks for a Donut chart. Use min 0 on both dual-axis positions, put the categorical split on the first pie, and the sales label on the second pie. The second pie should be white to cut out the middle; the recipe auto-creates min 0 = MIN(0) when the default field is missing. ```python configure_chart_recipe( worksheet_name="Donut Chart", recipe_name="donut", recipe_args={"category": "Category", "measure": "SUM(Sales)"}, ) ``` -------------------------------- ### Prompt for cwtwb MCP to build a sales dashboard Source: https://github.com/aidatacooper/cwtwb/blob/main/examples/prompts/demo_auto_layout4_prompt.md A prompt to send to an AI with cwtwb MCP tool access (like Cline, Cursor, or Gemini) to build a sales dashboard using the built-in Superstore dataset. It instructs creating 2 KPIs and 2 bar charts, then laying them out in a dashboard with a JSON layout tree, and saving to output/demo_auto_layout4.twb. ```text Use cwtwb MCP to build a sales dashboard for me. Call `create_workbook` with no template path to use the built-in Superstore dataset. 1. Create 2 KPIs: the measures are sales and profit, aggregate with sum, mark type is text. Then create 2 Bar charts: "Sales By Ship Mode", "Sales By Category". Sales is the measure. 2. Layout: Put all charts into a new dashboard named "Layout dashboard" (size: 1200x800). Please use JSON layout: The root is a vertical container containing 3 rows: - Row 1 (Horizontal, fixed size 100): Contains a Text area for "Logo Area", and a large Text header for the dashboard title. - Row 2 (Horizontal, distribute evenly, fixed size 150): Contains the 2 KPI worksheets. - Row 3 (Horizontal, distribute evenly): Contains the 2 Bar chart worksheets side by side. 3. Save the final workbook to `output/demo_auto_layout4.twb`. ``` -------------------------------- ### Common Layout Pattern Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md A text-based representation of the recommended dashboard layout structure. ```text Top: KPI summary row Middle left: primary chart Middle right: filters and legends Bottom: one or two detail charts ``` -------------------------------- ### Package a Plain .twb into .twbx Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Packages a plain .twb into a .twbx file. The save produces a single-entry ZIP containing the .twb inside. ```python editor = TWBEditor("src/cwtwb/references/empty_template.twb") # ... editor.save("output/superstore.twbx") # produces a single-entry ZIP with the .twb inside ``` -------------------------------- ### Open and Edit a Packaged Workbook (.twbx) Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Opens a .twbx packaged workbook, preserves extracts and images automatically, and allows normal edits. Saving as .twbx re-bundles the updated .twb with the original extracts/images; saving as .twb extracts just the XML. ```python from cwtwb.twb_editor import TWBEditor # Open a packaged workbook — extracts and images are preserved automatically editor = TWBEditor.open_existing("workbooks/MyDashboard.twbx") # Make changes as usual editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])") # Save as .twbx — re-bundles the updated .twb with the original extracts/images editor.save("output/MyDashboard_v2.twbx") # Or extract just the XML when the packaged format isn't needed editor.save("output/MyDashboard_v2.twb") ``` -------------------------------- ### Generate dashboard layout files Source: https://github.com/aidatacooper/cwtwb/blob/main/README.md Utility functions to generate dashboard layout files in JSON or YAML. Both use the same declarative DSL and accept a layout tree and ASCII preview. ```text generate_layout_json("output/layout.json", layout_tree, ascii_preview) generate_layout_yaml("output/layout.yaml", layout_tree, ascii_preview) ``` -------------------------------- ### Minimal Stable Layout Template Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/dashboard_designer.md A basic JSON template for defining a dashboard container with a KPI row and primary/secondary views. ```json { "type": "container", "direction": "vertical", "children": [ { "type": "container", "direction": "horizontal", "fixed_size": 56, "children": [ {"type": "worksheet", "name": "KPI 1"}, {"type": "worksheet", "name": "KPI 2"} ] }, { "type": "container", "direction": "horizontal", "children": [ {"type": "worksheet", "name": "Primary View", "weight": 2}, {"type": "worksheet", "name": "Secondary View", "weight": 1} ] } ] } ``` -------------------------------- ### Configure Lollipop chart recipe Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Use for the all_supported_charts workbook or when the user explicitly asks for a Lollipop chart. Place the dimension in rows and repeat the same measure on both dual-axis positions; the first axis is the bar, the second is the circle. Keep axes synchronized, hide labels by default, and keep the bar size smaller than the circle size. ```python configure_chart_recipe( worksheet_name="Lollipop Chart", recipe_name="lollipop", recipe_args={"dimension": "State/Province", "measure": "SUM(Sales)"}, ) ``` -------------------------------- ### Configure Butterfly chart recipe Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Use for the all_supported_charts workbook or when the user explicitly asks for a Butterfly chart. Use one bar axis for the left measure and one for the right measure, reverse the first axis so the chart mirrors around the center, and do not synchronize the axes. ```python configure_chart_recipe( worksheet_name="Butterfly Chart", recipe_name="butterfly", recipe_args={ "dimension": "Region", "left_measure": "SUM(Sales)", "right_measure": "SUM(Quantity)", }, ) ``` -------------------------------- ### configure_chart Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Documentation for the configure_chart function, covering KPI cards, bar charts, line/area charts, and map charts. ```APIDOC ## configure_chart ### Description Configures a chart in Tableau with user-facing field names and expressions. Supports multiple mark types including Text, Bar, Area, and Map. ### Method Function call ### Endpoint `configure_chart(title, mark_type, ...)` ### Parameters - **title** (string) - Required - Chart title - **mark_type** (string) - Required - Type of mark: Text, Bar, Area, Map, etc. - **measure_values** (list of strings) - Optional - Metrics for KPI cards (Text mark) - **rows** (list of strings) - Optional - Rows encoding - **columns** (list of strings) - Optional - Columns encoding - **color** (string) - Optional - Color encoding - **label** (string) - Optional - Label encoding - **sort_descending** (string) - Optional - Measure to sort by descending - **tooltip** (string or list) - Optional - Tooltip encoding - **geographic_field** (string) - Optional - Geographic field for maps - **size** (string) - Optional - Size encoding - **map_fields** (list of strings) - Optional - Additional geographic fields - **map_layers** (list of objects) - Optional - Map layer configurations - **map_layer_mode** (string) - Optional - "overlay" (default) or "native" - **map_partition** - Optional - Supported by overlay mode only ### Request Example ```python configure_chart("Total Sales", mark_type="Text", measure_values=["SUM(Sales)", "SUM(Profit)", "Profit Ratio", "AVG(Discount)", "SUM(Quantity)"]) ``` ### Response Returns a configured chart object. ### Notes - Use user-facing field names and Tableau expressions (e.g., `Sales`, `SUM(Sales)`, `MONTH(Order Date)`). - Do not use internal Tableau column-instance names (e.g., `[sum:Sales:qk]`). - For spatial calculations, bind each spatial field explicitly on its map layer. - For native map layers, set `map_layer_mode="native"`; use `geometry="Geometry (generated)"` for country polygons. - `measure_values` selects the worksheet-wide ordered Measure Names domain. - `color_map` keys are public expressions. ``` -------------------------------- ### Multi-Pane Chart with configure_layered_chart Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Builds a multi-pane chart with three or more mark panes or a synchronized 'Multiple Values' axis. Declare every pane independently; do not copy pane XML from a reference TWB. Use synchronized=True and hide_axes=True as shown. ```python configure_layered_chart( "Step Area", columns=["Category", "DAYTRUNC(Month Position)"], rows=["SUM(Month Sales)", "Multiple Values"], panes=[ {"mark_type": "Area"}, { "mark_type": "Area", "axis": "SUM(Month Sales)", "color": "Category", }, { "mark_type": "Line", "axis": "Multiple Values", "color": "Change Type", "size": "Change Size", "measure_values": ["Current Endpoint", "Next Endpoint"], "color_map": { "rise": "#305d8a", "drop": "#da020e", "other": "#b3b3b3", }, }, ], synchronized=True, hide_axes=True, ) ``` -------------------------------- ### Run cwtwb tests with pytest Source: https://github.com/aidatacooper/cwtwb/blob/main/tests/README.md Commands to run the full test suite, with verbose output, a single file, a single test class, and coverage reporting. Requires pytest-cov for the coverage command. ```bash # Run everything pytest tests/ # Run with verbose output pytest tests/ -v # Run a single file pytest tests/test_connections.py -v # Run a single test class pytest tests/test_worksheet_style.py::TestHideBasicOptions -v # Run with coverage (requires pytest-cov) pytest tests/ --cov=src/cwtwb --cov-report=term-missing ``` -------------------------------- ### configure_chart_recipe Source: https://github.com/aidatacooper/cwtwb/blob/main/src/cwtwb/skills/chart_builder.md Documentation for the configure_chart_recipe function, which is used to create specialized chart types (Lollipop, Donut, Butterfly, Calendar) in the workbook. ```APIDOC ## configure_chart_recipe ### Description Configures a chart using a predefined recipe for specialized chart types (Lollipop, Donut, Butterfly, Calendar). This function is used instead of `configure_chart(...)` for these recipe-specific charts. ### Method Function call ### Endpoint `configure_chart_recipe(worksheet_name, recipe_name, recipe_args)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **worksheet_name** (string) - Required - The name of the worksheet where the chart will be created. - **recipe_name** (string) - Required - The recipe identifier. Supported values: `lollipop`, `donut`, `butterfly`, `calendar`. - **recipe_args** (object) - Optional - A dictionary of recipe-specific arguments. The required keys vary by recipe. ### Request Example ```python configure_chart_recipe( worksheet_name="Lollipop Chart", recipe_name="lollipop", recipe_args={"dimension": "State/Province", "measure": "SUM(Sales)"}, ) ``` ### Response #### Success Response (200) No explicit response body is documented. #### Response Example No response example is provided. ### Recipe-Specific Details #### Lollipop - **recipe_args**: `dimension` (string), `measure` (string) - Rules: - Put the dimension in `rows` and repeat the same measure on both dual-axis positions. - The first axis is the bar, the second axis is the circle. - Keep the axes synchronized. - Hide labels by default. - Keep the bar size smaller than the circle size so the lollipop head is visible. #### Donut - **recipe_args**: `category` (string), `measure` (string) - Rules: - Use `min 0` on both dual-axis positions. - Put the categorical split on the first pie. - Put the sales label on the second pie. - Make the second pie white so it cuts out the middle of the donut. - The recipe auto-creates `min 0 = MIN(0)` when the default field is missing. #### Butterfly - **recipe_args**: `dimension` (string), `left_measure` (string), `right_measure` (string) - Rules: - Use one bar axis for the left measure and one for the right measure. - Reverse the first axis so the chart mirrors around the center. - Do not synchronize the axes. #### Calendar - **recipe_args**: None (no arguments required) - Rules: - Because the default color formula uses `SUM([Sales])`, treat it as an aggregated nominal measure, not a plain dimension. - Use `WEEK(Order Date)` on rows and `WEEKDAY(Order Date)` on columns. - Use `DAYTRUNC(Order Date)` for the day labels. - Apply a single `MY(Order Date)` filter member such as `202208`. - The recipe auto-creates `Sales Over 400` when the default field is missing. ``` -------------------------------- ### Compatibility aliases for cwtwb resources Source: https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md Compatibility aliases for common guessed resource names. They exist to keep less disciplined clients from stopping on an Unknown resource error. ```text cwtwb://docs/manual-editing cwtwb://docs/tool-surface ```