Skip to content

Visuals & Projections

Visual tools manage the visual elements on report pages. Projection tools manage the data field bindings (roles) of each visual.


get_visuals

Returns all top-level visuals for a given page. Nested visuals (children of containers) are not included at the top level — retrieve them via get_visual.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
page_id string ✅ Page id from get_pages

Response

{
  "visuals": [
    {
      "id": "visual-001",
      "friendlyName": "Revenue by Region",
      "category": "Chart",
      "type": "barChart",
      "x": 0, "y": 0, "z": 0,
      "width": 400, "height": 300
    }
  ]
}

get_visual

Returns a single visual by ID, including its projections, visual-level filters, and child visuals (for containers).

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
visual_id string ✅ Visual id from get_visuals

Response

Full Visual object with visualProjections, visualLevelFilters, and children arrays.


create_visual

Creates a new visual on a page (or as a child of a container visual). Returns the generated visual id.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
page_id string ✅ Parent page id
friendly_name string ✅ Display name / title
category string ✅ Static, Interaction, Container, or Chart
visual_type string ✅ Platform-native type (e.g. "barChart", "tableEx", "slicer") — from list_bi_platform_visual_types
x decimal ✅ Left position on canvas
y decimal ✅ Top position on canvas
z decimal ✅ Z-order / layer depth
width decimal ✅ Visual width
height decimal ✅ Visual height
description string — Optional description
parent_visual_id string — Parent visual id for nested visuals (Container children)

Response

{
  "status": "Success",
  "visualId": "visual-guid"
}

update_visual

Updates a visual's properties. Null optional fields leave values unchanged; empty string clears the description.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
asset_id string ✅ Asset id (for scoping)
id_visual string ✅ Visual id
friendly_name string — New display name
category string — New category
visual_type string — New platform-native type
x, y, z decimal — New position
width, height decimal — New dimensions
description string — New description (empty to clear)

Response

{ "status": "Success" }

delete_visual

Deletes a visual and all its projections, filters, and child visuals (cascade delete).

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
visual_id string ✅ Visual id from get_visuals

Response

{ "status": "Success" }

get_visual_projections

Returns all data field bindings (projections) for a visual.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
visual_id string ✅ Visual id

Response

{
  "projections": [
    {
      "projectionId": 1,
      "projectionName": "Category",
      "isActive": true,
      "isDimension": true,
      "isMeasure": false,
      "idColumnReference": "Sales.Region",
      "order": 0
    }
  ]
}

get_visual_projection

Returns a single projection by its row ID.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
projection_id int ✅ Projection row ID (integer) from get_visual_projections

create_visual_projection

Creates a new data field binding on a visual. Returns the generated row ID.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
visual_id string ✅ Parent visual id
projection_name string ✅ Projection role name (e.g. "Values", "X", "Legend", "Category")
is_active bool ✅ Whether the projection is active
order int ✅ Position when multiple fields are in the same role
expression string — Inline expression code
expression_language string — Language of the expression (e.g. "DAX", "MDX", "SQL")
expression_type string — Expression type hint
type string — Optional projection type
is_dimension bool — Whether this is a dimension field
is_measure bool — Whether this is a measure field
id_column_reference string — Column reference in TableName.ColumnName format

Response

{
  "status": "Success",
  "projectionId": 42
}

update_visual_projection

Updates a projection. Null optional fields leave values unchanged; empty string clears nullable strings.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
asset_id string ✅ Asset id (for scoping)
id_visual_projection int ✅ Projection row ID
projection_name string — New role name
expression string — New expression code
expression_language string — New expression language
expression_type string — New expression type
is_active bool — Active flag
order int — New position
type string — New type
is_dimension bool — Dimension flag
is_measure bool — Measure flag
id_column_reference string — New column reference

Response

{ "status": "Success" }

delete_visual_projection

Deletes a projection by its row ID.

Parameters

Name Type Required Description
session_id string ✅ Session id from create_session
projection_id int ✅ Projection row ID

Response

{ "status": "Success" }