Manage reference data

Workspace Reference Data maps Xero records from selected Organisations for consistent reporting. Accounts map directly to Account nodes in a hierarchy. Contacts and tracking records use common Group records.

Reference Data requires the MCP subscription. Open Connections, Xero, then Reference Data. The tabs are Accounts, Group Tracking Dimensions, and Group Contacts, in that order. The page opens on Accounts.

Run a Xero sync first if the page has no source records. See Connect Xero.

Automatic mappings

The default Account hierarchy has three sections: P&L, Balance Sheet and Non-financial. The initial Organisation supplies one Account node for each of its Xero Accounts. Account class determines the section, with type used when class is missing. Unclassified Accounts go under Non-financial.

For subsequent Organisations, Xero sync maps an Account only when both its code and name match one existing Account in the same section. Comparisons ignore case and surrounding spaces. Ambiguous or unmatched Accounts stay under Unmapped for review.

Other source records follow these rules:

• Xero Contacts match by exact business code, then exact name.
• Xero Tracking Categories match Group Tracking Dimensions by exact name.
• Xero Tracking Category Options match Group Tracking Options by exact name within the mapped dimension.
• When there is no match, xpnAI creates a Group item and maps the source record to it.

Existing mapping decisions stay unchanged. Correct a destination in the relevant mapping tab when needed.

Map Xero Accounts

Open Accounts. Choose an Account hierarchy when more than one exists. Expand or collapse sections and Groups to show their Account nodes. Each Account contains its mapped Xero Accounts as compact chips. Chips wrap across the available space, and each Organisation has its own colour and name. Expand or collapse an Account to show or hide its chips. The mapped count appears only while the Account is collapsed.

Account nodes aggregate Xero Accounts directly. Groups contain other nodes. A Xero Account can map to one Account node in each hierarchy, so changing one hierarchy does not change mappings in another.

Expand P&L or Balance Sheet to find its Unmapped group at the top. Unmapped P&L shows Revenue and Expense accounts, while Unmapped Balance Sheet shows Asset, Liability and Equity accounts. Accounts without a recognised class appear under Other unmapped accounts for manual mapping. Each row counts the unmapped accounts for the Organisations currently shown.

Mapped Xero Accounts start collapsed, and the Unmapped groups start expanded. Open an individual Account to see its mapped chips, or select Show Xero Accounts to expand them all. Hide Xero Accounts collapses the mapped chips again and keeps the Unmapped groups available. Select Totals below detail to show children above each parent, or Normal tree to restore parents above their children.

Use these controls to narrow the tree:

• Organisations chooses which Organisations’ chips are visible. This does not change the Workspace’s imported Organisation selection.
• Name differs
• Code differs
• Reset

Enabled filters are combined. Name differs and Code differs exclude unmapped Xero Accounts.

Archived Xero Accounts appear with strikethrough. A red box around a code or name means that value differs from its Account node. Hover over a chip to see any exceptions in its tooltip: Archived, Name differs, or Code differs. Hover over the information icon on its right to see the Xero Account’s Type, reporting code and reporting name.

Xero sync groups archived Accounts in the default hierarchy under Archived P&L accounts or Archived Balance Sheet accounts. Expand either Account node to see its individual Xero Accounts. If xpnAI cannot determine the financial statement from the account class or type, review the mapping manually. Explicitly unmapped Accounts stay unmapped.

To map an Account:

1. Double-click the Xero Account’s chip in the tree, or right-click it and choose Edit mapping.
2. Choose Remap, then open Existing Account and search by code or name to choose its destination.
3. Select Save mapping.

You can also choose Unmapped and save it. This is a deliberate decision that survives later reconciliation.

If no destination exists, use + Account beneath a Group or statement section. Enter an optional Code and required Name, then choose Create account or press Enter. Map the Xero Account to the new node.

Use + Account or + Group beneath a Group or statement section to add a node. Select Edit to change a node’s name, code or parent. Moving an Account keeps its mappings. Account nodes cannot contain other nodes, and mappings cannot target Groups or statement sections.

Use the drag handle beside an Account or Group to move it inside a Group or section, or above or below another node. Dragging keeps nodes within their current statement section. Sections themselves cannot be dragged, and a Group cannot be dropped inside its own children.

Accounts with no set position sort by code within their Group or statement section. Accounts without a code appear after coded Accounts. Drag above or below a row to set the order. To restore code order, right-click the parent Group or statement section and choose Use default order. Select Save hierarchy to keep the change.

To remap an organisation account chip, drag it onto another Account row or drop it anywhere in that Account’s expanded chip area. To unmap it, drop it onto its matching Unmapped row or chip area. A recognised source class prevents a P&L account from being dropped into Balance Sheet, or the reverse. The destination highlights while it accepts a drop and expands after a move. You can also use Edit and Remap without dragging.

Click an Account row or Xero Account chip to select it. Ctrl-click toggles individual selections, and Shift-click selects a visible range. Account nodes and Xero Account chips use separate selections. Right-click a destination and choose Drop here as children to move the selection together. Xero Accounts can be placed only under an Account; Account nodes can be placed only under a Group or statement section. Incompatible statement sections are disabled. You can also drag selected items together. Use Clear selection in the context menu to start again.

To group Accounts, select one or more Account rows in the same statement section. Right-click a selected row and choose Add to new group. Name the group, choose where it belongs, and select Create group. The selected Accounts move into the group with their Xero mappings. Select Save hierarchy to keep the change.

Nodes with no mappings or child nodes can be deleted. Remap their Xero Accounts or move their children first. The three statement sections cannot be deleted or moved.

Mapping and tree edits remain local until you select Save hierarchy. Changed nodes and their parents are highlighted. Discard changes restores the saved tree. A failed save keeps your changes available for correction.

If an import or another user changes the hierarchy while you edit, saving asks you to load the latest tree. Your edits remain visible. Note them, select Discard changes, then reapply them to the latest tree.

Suggest mappings with AI

Select Automap on Unmapped P&L or Unmapped Balance Sheet. Each button reviews unmapped accounts for that statement across all Organisations in the hierarchy, even when the display is filtered by Organisation.

Automap considers code, name, type, class, reporting code and reporting name, along with the existing tree and mappings. It can map to an existing Account or create an Account under a suitable Group or statement section. It leaves uncertain Accounts unmapped. A spinner appears on the active button and a toast reports the mapped and created counts when it finishes.

Review the highlighted nodes and mappings, then select Save hierarchy or Discard changes. Automap does not update Xero or change existing mappings. If a request fails, earlier draft mappings remain available for review. Automap requires an available AI model and supports up to 500 unmapped Accounts per statement. If the hierarchy exceeds the AI review size limit, map Accounts manually.

Update a Xero Account

Double-click a Xero Account in Accounts, then choose Update source. Code and Name start with the currently mapped Account node’s values. An unmapped Account starts with its current source values. Type starts with the source Account’s current type. The type choices use Xero’s friendly names .

Edit Code, Name, or Type, then select Commit to Xero. This saves and commits only the selected Xero Account. Other pending Account drafts stay pending. It does not change the Account node or its mapping.

Codes may contain at most 10 characters and names at most 150. If an Account node’s value exceeds those limits, shorten it before committing. Xero can reject edits to protected Accounts. The form retains your values after a rejection so you can correct them and retry. If another user changes the draft, reload Accounts and review the latest values before retrying. Account settings write access is required.

Map Xero Contacts

Open Group Contacts. Each Contact is a node with its mapped Xero Contacts shown as coloured chips. New Xero Contacts match by business code, then name. If neither matches, the next sync creates a Contact and maps the source to it.

Search by Organisation, code or name. Use Create Contact or a node’s Edit action to manage Contact names and codes. Double-click a Xero chip, or right-click it and choose Edit mapping, to choose an existing Contact and Save mapping. Choose Unmapped to leave it without a destination.

Click selects a chip, Ctrl-click toggles it, and Shift-click selects a range. Drag selected chips onto a Contact, or right-click the destination and choose Drop here as children. Mapping changes save immediately.

Hide Xero Contacts collapses the source chips. Individual disclosures still open them, and Show Xero Contacts expands them all again. Unmapped sources stay visible.

The optional Group Contact code corresponds to Xero ContactNumber. Xero ContactID is not a business or display code.

Map Tracking Categories

Open Group Tracking Dimensions, then Tracking Category Mappings. Each Tracking Dimension is a node with its mapped Xero Categories shown as coloured chips.

Double-click a Xero Tracking Category chip, or right-click it and choose Edit mapping, then choose Remap or Update source. Under Remap, choose an Existing Group Tracking Dimension and select Save mapping.

Different source names can map into one Group Tracking Dimension when they represent the same reporting concept.

Use Create Group Tracking Dimension to add an empty destination node. Edit renames a dimension without changing its category mappings.

An unmapped Group Tracking Dimension has a delete icon beside Edit when none of its Options has source mappings. Confirming deletion removes the dimension, its unmapped Options, its Option hierarchy and their Reporting Hierarchy assignments.

Map Tracking Category Options

Within Group Tracking Dimensions, open Tracking Category Option Mappings.

Choose a Group Tracking Dimension. Its hierarchy shows Groups, Options and the Xero Option chips mapped to each Option. Other dimensions’ Options and Xero sources stay out of this view.

Drag an Option by its handle to reorder it. An insertion line shows where it will go before or after an Option or Group. Dropping in the centre of a Group, when its border is highlighted, moves the Option inside it. Select several Options to move them together. With an Option or its handle focused, Alt+Up and Alt+Down move it among its siblings.

Options with no set position sort by name within their Group. To restore name order, right-click the parent Group or dimension root and choose Use default order, then select Save hierarchy.

Use + Option on the dimension root or a Group to create an Option there. Enter its Name and Parent group, then choose Create option or press Enter. Use + Group to add another level. Edit changes an Option or Group’s name or parent. Option edits retain their Xero mappings. Empty Groups can be removed. Click, Ctrl-click or Shift-click Options, then drag them onto a Group or right-click a Group and choose Drop here as children. New Options, Groups, placement and order are highlighted until you choose Save hierarchy or Discard changes. Saving creates new Options and their placements together. These Options are Workspace destinations and do not create records in Xero. Save or discard before choosing another dimension.

Select Xero Option chips and drop them onto an Option row or anywhere in its expanded chip area. Xero Categories can be dropped onto a Tracking Dimension row. These source mapping changes save immediately. Mapping to a newly created Option also saves the current Option hierarchy, including new Groups and Options, in the same operation. You do not need to save the hierarchy first. If saving fails, the existing mappings stay unchanged and your hierarchy edits remain available to retry or discard. Discard changes reloads the current tree and Option names, including changes saved by another user. Double-click a chip or use Edit mapping to open the Remap and Update source tasks.

Both Tracking views support search and a show/hide control for Xero chips. You can still expand a destination individually after hiding the chips. Unmapped sources stay visible.

Moving a Xero Tracking Category to another Group Tracking Dimension clears its existing Option mappings. Open Tracking Category Option Mappings for the destination dimension and remap the Options shown under Unmapped.

An unmapped Group Tracking Option has a delete icon beside its name. Confirming deletion also removes its Reporting Hierarchy assignments. Records with source mappings must be remapped before they can be deleted.

Rename a Tracking Category or Option in Xero

Open Edit mapping for the source Category or Option, then choose Update source. Name starts with the mapped Group item’s name, or the source name when it is unmapped. Edit the name and choose Commit to Xero. Xero Tracking names have a 100-character limit. This renames only the selected source record and leaves its Group mapping unchanged. Imported names update after the next Xero sync.

If Xero rejects the rename, the dialog retains the name and displays its message. Correct it before retrying. If the outcome is unknown, inspect the live record in Xero before retrying, as the message instructs. Account settings write access is required for these renames.

What Unmapped means

For Accounts and Contacts, Unmapped can mean either:

• no decision exists yet, or
• a user deliberately saved an Unmapped mapping

A deliberate Unmapped decision is stable. A later Xero sync does not automatically map it.

Tracking Category and Option mapping dialogs currently require a Group destination. Their Unmapped nodes identify work that still needs a mapping decision.

Troubleshoot validation

The page displays the server message under one of these alert titles:

• Unable to manage reference data
• Unable to manage Group Contacts
• Unable to manage Group Tracking Dimensions

Common causes are a duplicate Group code, a name outside the permitted length, a source record that is no longer available in the Workspace, or a destination that is no longer available.

For Xero Account drafts, validation can also reject a code over 10 characters, a name over 150 characters, or an unsupported Account Type. Xero may reject changes to protected or system Accounts. The draft remains dirty when that happens.

For the distinction between source and Workspace-owned data, see Workspaces and finance data.