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" }