Powerbi Report CLI

Authoring Workflows & Examples

Read this for concrete PBIR authoring workflows: pages, visuals, layout templates, themes, drillthrough, interactions, and visual-type routing.

Related references:

• formatting.md (see formatting.md) — value encoding, colors, selectors, VCOs, and formatting properties.

• expressions.md (see expressions.md) — field expressions, filters, and sort definitions.

Mandatory completion gate: Every workflow in this file that creates or changes rendered report content must end with validation, loading the latest PBIR into a preview host, screenshot capture of every affected page, and review using screenshot-review.md (see screenshot-review.md). Use --all-pages for report-wide changes such as themes or global formatting. Load/reload and screenshot are separate commands; never combine --reload and --screenshot. A successful powerbi-report-author validate result must be followed by loading the validated PBIR, capturing screenshots of every affected page, and reviewing those screenshots; schema validation alone never completes a workflow. If any of those steps cannot be completed using the latest PBIR, report screenshot validation as blocked and do not claim the authoring task is complete.

Before editing existing reports: inventory the report with powerbi-report-author preview-pages <path-to-.Report-dir> and powerbi-report-author preview-visuals <path-to-.Report-dir>. Add --with-derived when you need counts or cheap computed flags.

Examples are structural patterns. Property names may vary by visual type. Always confirm exact properties with powerbi-report-author formatting describe-object <type> <object> before applying formatting.

Contents

• Names & Format Versions

• Add a New Page

• Add a Visual to a Page

• Common Layout Templates

• Change Theme

• Visual Type References

• Drillthrough Page

• Same-Report Drillthrough Workflow

• Visual Interactions

Names & Format Versions

ID Generation

// Node.js
const crypto = require('crypto');
const visualId = crypto.randomBytes(10).toString('hex');                  // 20 hex chars
const pageId   = 'ReportSection' + crypto.randomBytes(12).toString('hex'); // ReportSection + 24 hex
const filterId = 'Filter'        + crypto.randomBytes(12).toString('hex'); // Filter + 24 hex

Format Versions

These are file-content versions (not $schema URLs) and are constants for the current PBIR format:

• version.json → "version": "2.0.0"

• definition.pbir → "version": "4.0"

For $schema URL versioning rules and the file layout, see SKILL.md § PBIR File Layout (see ../authoring-part-02.md, section pbir-file-layout). When creating a new file of any type, copy the $schema URL from an existing file of the same type in the same report.

Add a New Page

1. Generate a unique page name (e.g. ReportSection + 24 hex chars)

2. Create the directory: definition/pages/<pageName>/

3. Create page.json:

   Copy

   {
     "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/page/2.1.0/schema.json",
     "name": "<pageName>",
     "displayName": "My New Page",
     "displayOption": "FitToPage",
     "height": 720,
     "width": 1280
   }

4. Create visuals/ subdirectory (can be empty initially)

5. Add the page name to pages.json → pageOrder array at the desired position

Note: For the $schema URL, copy from an existing page.json in the same report.

Add a Visual to a Page

1. Generate a unique visual name (20 hex chars)

2. Create definition/pages/<pageName>/visuals/<visualName>/visual.json

3. Populate with the visual definition:

   Copy

   {
     "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.9.0/schema.json",
     "name": "<visualName>",
     "position": {
       "x": 0, "y": 0, "z": 1000,
       "height": 300, "width": 400,
       "tabOrder": 1000
     },
     "visual": {
       "visualType": "<type>",
       "query": {
         "queryState": {
           "<RoleName>": {
             "projections": [
               {
                 "field": { /* expression — see references/authoring/expressions.md */ },
                 "queryRef": "<Entity>.<Property>",
                 "nativeQueryRef": "<Property>"
               }
             ]
           }
         }
       }
     }
   }

⚠️ All role projections (Rows, Columns, Values, etc.) must be inside queryState, not directly under query. Placing them under query causes a schema validation error.

Position guidelines (1280×720 canvas):

• z: Stacking order. Higher = on top. Increment by 1000 for each visual.

• tabOrder: Keyboard navigation order. Usually matches z.

• Keep visuals within canvas bounds: x + width ≤ 1280, y + height ≤ 720.

Common Layout Templates

Full-width KPI row + detail chart (720px canvas example):

KPI Card 1:  x=20,  y=20,  w=290, h=82
KPI Card 2:  x=330, y=20,  w=290, h=82
KPI Card 3:  x=640, y=20,  w=290, h=82
KPI Card 4:  x=950, y=20,  w=290, h=82
Main Chart:  x=20,  y=118, w=1240, h=582

Card heights follow the card sizing formula (see card-part-02.md, section card-sizing-required) — derive per canvas, don't hardcode.

2×2 Grid:

Top-Left:     x=20,  y=20,  w=610, h=340
Top-Right:    x=650, y=20,  w=610, h=340
Bottom-Left:  x=20,  y=380, w=610, h=320
Bottom-Right: x=650, y=380, w=610, h=320

Header + sidebar + main:

Header:   x=0,   y=0,   w=1280, h=80
Sidebar:  x=0,   y=80,  w=280,  h=640
Main:     x=300, y=80,  w=960,  h=640

Change Theme

In report.json, update the themeCollection.customTheme:

{
  "customTheme": {
    "name": "<CustomThemeName>-<guid>.json",
    "reportVersionAtImport": {
      "visual": "2.6.0",
      "report": "3.1.0",
      "page": "2.3.0"
    },
    "type": "RegisteredResources"
  }
}

Also ensure the theme file exists in StaticResources/RegisteredResources/ and is listed in the resourcePackages array with matching name and path.

On every theme edit, follow the GUID cache-busting procedure in theming.md (see theming.md, section theme-name-guid-convention-cache-busting) — rotate the GUID suffix (keep <CustomThemeName> stable), update all report.json references, and rerun the host-specific workflow in preview.md (see preview.md). Only change <CustomThemeName> if the user explicitly requests a rename.

⚠️ type must be "RegisteredResources" — not "SharedResources". Using the wrong type causes the theme to silently fail.

Inside report.json, both customTheme.name and the matching resourcePackages[].items[].name MUST include the .json extension and equal the item's path (e.g., all three are "<ThemeName>.json"). Using the bare theme name causes the published report to incorrectly apply the theme on Power BI service. The name field inside the theme JSON file itself stays as the bare theme name (no .json suffix). See theming.md for details.

Visual Type References

Use these focused references for visual-specific templates, formatting rules, and known rendering pitfalls.

Drillthrough Page

A drillthrough page adds pageBinding and drillthrough filters to page.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/page/2.1.0/schema.json",
  "name": "<pageName>",
  "displayName": "Detail Drillthrough",
  "displayOption": "FitToPage",
  "height": 720,
  "width": 1280,
  "filterConfig": {
    "filters": [
      {
        "name": "Filter<24hex>",
        "field": {
          "Column": {
            "Expression": { "SourceRef": { "Entity": "<Table>" } },
            "Property": "<DrillthroughColumn>"
          }
        },
        "type": "Categorical",
        "howCreated": "Drillthrough"
      }
    ]
  },
  "pageBinding": {
    "name": "Pod",
    "type": "Drillthrough",
    "parameters": [
      {
        "name": "Param_Filter<24hex>",
        "boundFilter": "Filter<24hex>",
        "fieldExpr": {
          "Column": {
            "Expression": { "SourceRef": { "Entity": "<Table>" } },
            "Property": "<DrillthroughColumn>"
          }
        }
      }
    ]
  }
}

Key points:

• Each drillthrough field needs both a filter entry (with "howCreated": "Drillthrough") and a matching pageBinding.parameters entry with boundFilter referencing the filter name.

• The pageBinding.name is typically "Pod".

• pageBinding.type is "Drillthrough" (or "Tooltip" for tooltip pages).

• To trigger a drillthrough (or any page navigation, bookmark, or slicer action) from a button, see the Drillthrough button pattern (see button-part-03.md, section drillthrough-button). The button enables only when a selected data point carries the drillthrough field; a slicer selection alone does not enable it.

• For bookmark files, saved page/visual/filter state, groups, show/hide patterns, and bookmark verification, see bookmark.md (see bookmark.md).

Same-Report Drillthrough Workflow

A same-report drillthrough opens the target page with filter context from a selected data point in a source visual:

1. Choose the drillthrough field and ensure the source visual projects it.

2. Create the target page and add a page filter marked "howCreated": "Drillthrough".

3. Add pageBinding.type: "Drillthrough" with a parameter whose boundFilter references that filter and whose fieldExpr matches it.

4. Add the target visuals and the required Back button (see button-part-03.md, section back-button).

5. Use the source visual's drillthrough menu, or add a Drillthrough button (see button-part-03.md, section drillthrough-button) when the report needs an explicit action.

6. Validate and reload the report, select a source data point carrying the field, navigate to the target, and confirm the filter context and Back action.

Visual Interactions

Control how visuals cross-filter/highlight each other on a page. Add visualInteractions array to page.json:

{
  "visualInteractions": [
    {
      "source": "<sourceVisualName>",
      "target": "<targetVisualName>",
      "type": "NoFilter"
    }
  ]
}

By default (no entry), visuals cross-filter each other. Only add entries to override the default behavior.