Org Chart Drag & Drop — technical documentation

Drag & Drop Org Chart — Support & Help

User and admin hub for Org Chart Drag & Drop by WorkforceVision Ltd: try the visual, watch the demo, get support, and jump to field reference and advanced Power Query guides below.

Start here:

• Download and try the visual with our sample Power BI report from Microsoft Marketplace: Org Chart Drag and Drop — Marketplace
• Demo video: Org Chart demo (YouTube)
• Support, technical questions, or licensing: irawatt@workforcevision.co.uk
• How data is handled and secured: Data Security and Flow Overview

Contents

Contents

• Support & Help
• Advanced Org Chart Guides
• Licensing
• Org Chart Visual Documentation (User + Admin Guide)
• 1) Data Inputs (Power BI Fields)
  • Dynamic Styling and Icons
  • Dotted-Line Relationship
  • Card ordering
• 2) Main User Actions (Toolbar)
  • Node editing
  • Layout & view
  • Load & save
  • Export data
  • Print & export
  • Reset
  • Search
  • Overflow menus
  • Context controls
• 3) Dialog Input Fields
• 4) Keyboard Shortcuts & Accessibility
• 5) Formatting Settings (Power BI Format Pane)
• Best Practice Notes

Advanced Org Chart Guides

• Create Reporting Line Slicer/Filter Using Power Query (M)
• Create a Supervisor/Team Slicer/Filter For The Org Chart Visual
• Layer-Based Org Slicer and Dynamic Layer Columns (Power Query)
• Create Org Chart Using Microsoft Graph API Including Images
• Create 64-bit text for image field from a file or folder
• Compress Image Text to Meet Power BI Size Requirements
• Dynamic Styling and Icons — JSON reference guide
• Dotted-Line Reporting — field format and examples

Licensing

A licence is required to use this visual. All users, both viewers and developers, need a valid licence to access any features within the chart in Power BI Desktop or Power BI Service. Please see our overview here: Licensing and pricing.

You can explore the full functionality by downloading the sample report. Trial and purchase terms change over time—always check the current Marketplace listing for the latest options. Trial access, if offered, may require assigning a licence through your Microsoft 365 admin centre; see Microsoft’s terms at purchase.

Once purchased, a licence needs to be assigned to individuals or groups in your organisation in order for them to use the visual. Licences can be moved from one user to another without issue. Full instructions are available here: Microsoft guide to assigning licences .

Org Chart Visual Documentation (User + Admin Guide)

This visual builds an interactive organisation chart from employee-manager relationships. It supports editing, search, layout tools, export/print, and reusable change logs.

1) Data Inputs (Power BI Fields)

Required

• Employee ID (employeeId): Unique ID for each node. The sort order of this column in your Power BI model controls how sibling cards are arranged — see card ordering.
• Manager ID (managerId): Parent employee ID (reporting line).

Optional

• Name (name): Employee display name.
• Job Title (jobtitle): Role on the card.
• Colour (colour): Node/header colour (based on settings).
• Legend (legend): Category used in legend focus/filter.
• Legend Sort Key (legendSortKey): Custom legend sort order.
• Extra Details (Extra): Additional card attributes.
• Picture (Picture): Base64 image data for the card photo.
• Dotted-Line Relationship (dottedline): Secondary reporting lines shown as dashed connectors between employee cards. Does not affect hierarchy or roll-up. See full reference below or the standalone guide.
• Line Style (linestyle): Connection style override.
• Cumulative Field (total): Primary rollup value.
• Secondary Cumulative (Totalalt): Secondary rollup/variance value.
• Employee Id Measure / Manager Id Measure: Measure-based IDs when needed.
• Dynamic Styling and Icons: Per-employee JSON overrides for connector lines, card size, borders, text colours, and status icons. See full reference below or the standalone JSON guide.

Dynamic Styling and Icons

Drag a text column or measure into the visual field Dynamic Styling and Icons. Each row should contain a JSON object (as plain text) describing overrides for that employee's card and its incoming connector line.

• Leave the field blank for a row to use only the format-pane defaults.
• You can combine several features in one JSON object.
• Property names are case-sensitive — use the exact names shown below.

A minimal valid value is an empty object (no overrides):

{}

A typical value with multiple settings:

{
  "Color": "#d97706",
  "Thickness": 2,
  "Type": "Dotted",
  "Width": 220,
  "Icons": [
    {
      "Name": "exclamation-triangle-fill",
      "Color": "#d97706",
      "Legend": "At risk",
      "Size": 16,
      "Placement": "top",
      "LegendOrder": 1
    }
  ]
}

Using this in Power BI

• Prepared data: store the JSON string in your source table or CSV column.
• Calculated column / DAX measure: build the JSON string with concatenation or JSON functions, then bind that field to Dynamic Styling and Icons.
• CSV files: wrap the JSON in double quotes and escape inner quotes by doubling them, e.g. "{""Icons"":[{""Name"":""shield""}]}".

Connector lines

These properties style the line into the employee's node (from their manager):

Property	Type	Description
Color	String	Line colour (hex, rgb, or CSS colour name). Overrides the format-pane line colour for this node.
Thickness	Number	Line width in pixels.
Type	String	Set to "Dotted" for a dashed line. Omit or use any other value for a solid line.

Card layout

Property	Type	Description
Width	Number	Card width in pixels (1–998). Overrides the format-pane node width for this row.
Height	Number	Card height in pixels (1–998). Overrides the format-pane node height for this row.
FillBackground	Boolean	When true or false, overrides the format-pane setting Fill Background With Color Field for this card only.

Card borders

Override the card border independently of the format pane:

Property	Type	Description
BorderColor	String	Border colour for the card.
BorderStyle	String	"Solid" or "Dotted" (also accepts "Dashed").
BorderLegend	String	Label shown in the visual's Border legend section. Requires a border override (BorderColor and/or BorderStyle).

Text colours

Override individual text colours on a card. Values not set fall back to the format pane. Either nest them under TextColors or place them at the top level of the JSON object:

Property	Affects
HeaderTextColor	Card header bar text
NameTextColor	Employee name
JobTextColor	Job title
ExtraDetailsTextColor	Extra details, cumulative fields, layer, etc.
CardMenuTextColor	Card menu trigger

Icons

Add one or more status icons to a card with the Icons array. Icons appear in the top-right or bottom-right corner of the card. Three icon sources are supported (first match wins):

1. Image — Base64 image (PNG, JPEG, GIF, WebP)
2. Svg — Inline SVG markup
3. Name — Built-in icon from the registry

Property	Required	Description
Name	For built-in icons	Registry icon name (see table below). Ignored when Image or Svg is set.
Svg	For custom SVG	Full inline SVG string starting with <svg.
Image, Base64, or ImageBase64	For image icons	Full data URL (data:image/png;base64,...) or raw base64 string.
MimeType	No	MIME type when using raw base64 (default image/png). E.g. image/jpeg, png, jpeg.
Color	No	Icon tint colour for SVG and built-in icons (default #333333). Does not recolour image icons.
Size	No	Icon size in pixels (8–64, default 16).
Placement	No	"top" (top-right) or "bottom" (bottom-right, default).
Legend	No	Label in the visual's Icons legend. Clicking the legend item focuses matching nodes.
LegendOrder	No	Sort order in the icon legend (lower numbers appear higher).

Built-in icon names

Use the exact Name value in your JSON:

Name	Description
triangle-fill	Filled upward triangle
exclamation-triangle-fill	Warning triangle with exclamation mark
slash-circle-fill	Circle with diagonal slash (prohibited)
shield-lock-fill	Shield with lock
shield	Shield (alias of shield-lock-fill artwork)
x-circle-fill	Circle with X
x-circle	Circle with X (alias)
army-private	Single chevron rank insignia
army-private-first-class	Two chevrons
army-corporal	Two chevrons (corporal)
army-sergeant	Three chevrons
army-1-star	One star
army-2-star	Two stars
army-3-star	Three stars
army-4-star	Four stars
army-5-star	Five stars

Custom SVG and base64 image icons

Pass your own SVG markup in the Svg property. Use fill="currentColor" on paths if you want the Color property to tint the icon. Inside JSON strings, escape double quotes with \".

For raster images (logo, badge, photo icon), use a full data URL in Image or raw base64 with MimeType. Supported formats: PNG, JPEG, GIF, WebP. Maximum size per icon: 256 KB of base64 data. Color does not apply to image icons.

Legend integration

The visual legend can show three dynamic sections driven by this field:

Section	How to populate
Icons	Set Legend (and optionally LegendOrder) on icon objects.
Border	Set BorderLegend together with BorderColor and/or BorderStyle.
Colours	Uses the separate Legend and Colour data fields (not part of this JSON).

Clicking an icon or border legend entry focuses the chart on nodes that match that legend value. Icon matching uses the icon type, colour, legend label, and size.

Dynamic styling examples

Manager with warning icon and dashed connector

{
  "Color": "#ca8a04",
  "Thickness": 2,
  "Type": "Dotted",
  "Icons": [
    {
      "Name": "exclamation-triangle-fill",
      "Color": "#ca8a04",
      "Legend": "Acting role",
      "LegendOrder": 1
    }
  ]
}

Executive card with custom border and text colours

{
  "Width": 280,
  "Height": 130,
  "BorderColor": "#7c3aed",
  "BorderStyle": "Solid",
  "BorderLegend": "Executive",
  "TextColors": {
    "HeaderTextColor": "#ffffff",
    "NameTextColor": "#1e1b4b",
    "JobTextColor": "#5b21b6"
  },
  "Icons": [
    {
      "Name": "army-3-star",
      "Color": "#7c3aed",
      "Size": 20,
      "Legend": "3-star",
      "LegendOrder": 3
    }
  ]
}

Line style example

{
  "Type": "Dotted",
  "Thickness": "2",
  "Color": "Red"
}

Dotted-Line Relationship

The Dotted-Line Relationship field (dottedline) lets you show secondary reporting relationships alongside the main hierarchy defined by Manager ID. These appear as dashed connector lines between employee cards — useful for matrix management, project reporting, or dotted-line accountability.

How it differs from Manager ID

• Manager ID defines the primary org structure. Solid lines connect each employee to their direct manager.
• Dotted-Line Relationship adds optional extra links. They do not change hierarchy, headcount roll-up, or parent/child layout.
• Each employee row can define one or more dotted-line connections to other people already in the chart.

Dotted lines run from the employee to the related manager. An optional comment label can appear on the line, and the line colour can be customised.

Assigning the field in Power BI

1. In the visual fields pane, drag your dotted-line data into Dotted-Line Relationship.
2. Ensure Employee ID and Manager ID are already assigned so the main chart renders.
3. Populate the field on each employee row that needs an extra reporting relationship.
4. Leave the field blank for employees with no dotted-line relationships.

Recommended format (JSON array)

Use a JSON array when you need comments, colours, or multiple dotted-line managers for one employee. Each object should include a ManagerID that exactly matches an Employee ID elsewhere in the dataset.

[
  {
    "ManagerID": "MGR-104",
    "Comment": "Project sponsor",
    "Color": "#2E86AB"
  },
  {
    "ManagerID": "MGR-207",
    "Comment": "Functional lead"
  }
]

Property	Required	Description
ManagerID	Yes	The Employee ID of the dotted-line manager. The link is only drawn if this person exists in the chart.
Comment	No	Short text shown on the connector (for example, role or relationship type).
Color	No	Line colour as a hex value (for example, #808080). Defaults to grey when omitted.

Simple format (single manager)

For a single dotted-line manager with no label or colour, store just the manager's Employee ID as plain text:

MGR-104

This creates one dashed line from the employee to that manager.

Power BI modelling tips

• Build the JSON in Power Query, DAX, or your source system if relationships are stored in separate tables.
• Keep ManagerID values consistent with Employee ID formatting (including leading zeros).
• The visual can auto-quote unquoted JSON keys and values, but valid JSON is the most reliable approach.
• Invalid JSON falls back to treating the entire cell value as a single manager ID.

Example dataset rows

Employee ID	Manager ID	Dotted-Line Relationship
EMP-001	MGR-050	[{"ManagerID":"MGR-104","Comment":"Programme lead"}]
EMP-002	MGR-050	MGR-207
EMP-003	MGR-104	(blank)

In this example, EMP-001 reports solid-line to MGR-050 and dotted-line to MGR-104. EMP-002 has one simple dotted-line to MGR-207. EMP-003 has no dotted-line relationships.

Creating links inside the visual

You can also add dotted-line connections manually from the chart toolbar:

1. Open Links → Create Links.
2. Select the employee and the target manager.
3. Optionally enter a comment.

Manual links are session changes. To persist relationships in your data model, use the Dotted-Line Relationship field.

Card ordering

The org chart lays out nodes in a hierarchy from Manager ID. Among employees who share the same manager — siblings at the same level — the visual arranges their cards in a row (or column, depending on chart orientation). That left-to-right (or top-to-bottom) sequence is driven by the sort order of Employee ID in your Power BI data model, not by a separate visual field.

Default behaviour

• Without a custom sort, siblings appear in the default order Power BI applies to Employee ID — typically alphabetical for text IDs, or numeric order for numbers.
• Ordering applies only among peers under the same manager. It does not change reporting lines, hierarchy depth, or roll-up values.
• In Top or Bottom orientation, lower-ranked siblings appear further left; in Left or Right orientation, they appear further up.
• Dragging cards in the visual can reposition them for the current session, but the underlying data order is restored on refresh unless you save a layout scenario.

Set a custom order with a Rank column

To control sibling sequence yourself, add a numeric Rank column to your employee table and tell Power BI to sort Employee ID by that column. Lower rank values appear earlier in the sibling row (further left in a top-oriented chart). The Rank column does not need to be dragged into the visual — this is a data-model setting only.

1. Add a numeric column called Rank (or any name you prefer) to your employee table.
2. Assign a rank to each employee. Use whole numbers; gaps such as 10, 20, 30 make it easier to insert people later without renumbering everyone.
3. In Power BI Desktop, open Data or Model view and select the Employee ID column in your employee table.
4. On the Column tools ribbon, choose Sort by column → Rank.
5. Confirm the Sort by column indicator appears on Employee ID (a small sort icon in the column header or in the Properties pane).
6. Refresh the report. Sibling cards now follow your rank values.

Example dataset rows

Employee ID	Manager ID	Name	Rank	Resulting sibling order under MGR-050
EMP-101	MGR-050	Alice	1	First (leftmost)
EMP-102	MGR-050	Bob	2	Second
EMP-103	MGR-050	Carol	3	Third (rightmost)
EMP-201	MGR-100	Dan	1	Separate team — rank restarts under a different manager

Alice, Bob, and Carol share manager MGR-050, so their ranks (1, 2, 3) control their order in that row. Dan reports to a different manager, so his rank only matters relative to his own siblings under MGR-100.

---

2) Main User Actions (Toolbar)

Quick reference for every toolbar button and control in the visual. Download toolbar reference (PDF)

Node editing

Feature	Purpose
Drag & Drop Nodes	Reorganise reporting lines by dragging employees to a new manager.
Swap with Parent	Exchange an employee with their direct manager.
Add Node	Add a new employee to the organisation.
Edit Node	Modify an employee's details or manager.
Remove Node	Remove a single employee, an entire hierarchy, or replace an employee with another.
Links	Create or remove dotted-line relationships from the chart toolbar (Links → Create Links). Select the employee and target manager, optionally add a comment. Manual links are session-only; use the Dotted-Line Relationship field to persist them in your data model.

Layout & view

Feature	Purpose
Expand	Expand or collapse the organisation to a chosen number of levels or show the full chart.
Horizontal / Compact	Toggle between standard and compact layouts.
Swap Layout	Rotate the chart orientation (Top, Left, Bottom, Right).
Fit to Screen	Automatically fit the visible chart into the available space.

Load & save

Feature	Purpose
Undo / Redo	Reverse or reapply changes.
Manage Saves	Save, load, import or export editing sessions.
Change Log	View, filter and roll back individual changes.

Export data

Feature	Purpose
Export to Excel	Download the current chart and change summary.
Copy to Excel	Copy chart data for pasting into Excel or another application.
Download / Import CSV	Export the chart for offline editing or re-import changes.

Print & export

Feature	Purpose
Print Current View	Print the currently visible chart.
Download PDF	Export the chart as a PDF.
Export SVG	Export the chart as SVG text for use in PowerPoint. Once downloaded, rename the file extension from .txt to .svg. In PowerPoint, select Insert → Pictures, choose the SVG file, then resize it as required. To edit individual elements, right-click the image and select Convert to Shape.

Reset

Feature	Purpose
Reset Changes	Restore the chart to the original Power BI data and clear all edits.

Search

Feature	Purpose
Search Box	Find employees by typing search terms.
Search Field	Choose which field to search (Name, ID, Job Title, custom fields, etc.).
Search Button	Perform a full search and display all matching employees.

Overflow menus

Feature	Purpose
Layout (⋯)	Contains layout controls when the toolbar is too narrow.
Menu (☰)	Contains the remaining toolbar actions on smaller screens.

Context controls

Feature	Purpose
Drag Session Controls	Undo, Redo, Done and Cancel while dragging nodes. See also Keyboard Shortcuts & Accessibility.
Branch View Banner	Return from branch-only view to the full organisation.
Zoom & Pan	Zoom and navigate the chart when enabled.

---

3) Dialog Input Fields (What They Are For)

Add Employee (popupForm)

• Inputs: Employee ID (unique), Manager ID (valid parent), Name, Job, Colour, totals, legend, and extra fields.
• Submit checks ID rules, then creates the node.

Edit Employee (popupForm6)

• Inputs: Employee selector, new Manager ID, Name, Job, Colour, totals, legend/colour, and extra fields.
• Submit updates the node and writes to change log.

Remove Node (popupForm2)

• Input: Employee selector.
• Mode controls either single-node remove (children remapped) or full hierarchy remove.
• Submit applies deletion.

Create Link (popupForm3)

• Inputs: Source Employee ID, Target Employee ID, and Comment label.
• Submit adds connection line/label.

Remove Link (popupForm4)

• Input: Employee selector.
• Submit removes matching connection(s).

Expand N Levels (popupForm10)

• Input: Integer depth value.
• Submit expands to selected depth.

Export Data (popupForm8)

• Output field: textToExport.
• Select delimiter: CSV or tab.
• Run Generate Data, then Copy Data.

Save/Load Changes

• New Save: Enter a save name and store current action log.
• Saved table supports Load, Overwrite, and Delete actions.
• Copy Text Log: Copy serialized action log for sharing/archive.
• Load Text Log: Paste a prior log and submit to reapply edits.

---

4) Keyboard Shortcuts & Accessibility

Chart Shortcuts

• +, =, or numpad Add: zoom in.
• -, _, or numpad Subtract: zoom out.
• 0: Fit/reset view.
• Shift + Arrow keys: pan chart.

Interaction & Accessibility Behavior

• Enter/Space on visual: move focus into controls.
• Enter/Space on legend item: focus chart by legend value.
• Escape: close the top-most dialog.
• Tab / Shift+Tab: keep focus inside open dialogs.

Formal accessibility documentation for this visual is available in the VPAT® 2.5 Rev EU (PDF) (Voluntary Product Accessibility Template, EN 301 549–oriented revision).

---

5) Formatting Settings (Power BI Format Pane)

Settings are grouped under sections defined in capabilities.json.

Data Card

• Typography: Font family, text sizes, and colours.
• Spacing/Layout: Children margin, node margins, neighbour/pair spacing.
• Node Appearance: Background, border, rounding, width/height, card design.
• Value Labels: Cumulative prefix, ID prefix, thousands separator.
• Focus/Accessibility: Keyboard focus border colour and thickness.
• Feature Toggles: Move/add/edit/remove, mini menus, links, save/load, export, layout, print, reset, search, expanded-state cache.
• Orientation & Density: Visual orientation, text alignment, and density mode.
• Expand Behavior: Default expand level and auto-expand threshold.
• Expand Button Style: Width/height, text size/colour, border colour/thickness, and background.
• Navigation Button Color.
• Legend Order: Data order, A-Z, Z-A, colour value, or custom sort key.

Line Settings

• Line colour and thickness.
• Secondary connection style (square or rounded).
• Connection label position and label text colour.
• Special connection routing toggle.

Search Settings

• Default search field (Employee ID, Name, or Job Title).
• Search highlight colour and highlight thickness.

Zoom Settings

• Show or hide zoom +/- buttons.
• Show or hide arrow pan buttons.

Cumulative Settings

• Show zeros.
• Exclude self from cumulative values.
• Display unit: none/auto/K/M/B.
• Decimal places.
• Conditional formatting toggle and separate colour option.
• Show variance and variance prefix.
• Threshold percentage.
• Above/equal/below comparison colours.
• Show values in header and show second value in header.

Save And Export Settings

• Delete empty columns from generated export output.

---