XPM Reconciliation

Reconciliation compares your StructureGram (SG) data against the live state of Xero Practice Manager (XPM) for a linked group. It shows you every difference — missing entities, field mismatches, membership gaps, and relationship discrepancies — and lets you decide how to resolve each one.

Unlike sync (which pulls XPM data into SG) or push (which sends SG data to XPM), reconciliation gives you full, per-item control over which direction the data flows and how conflicts are resolved.

When to Use Reconciliation

• After data has been edited in both SG and XPM independently
• To verify that an earlier sync or push completed correctly
• To clean up duplicate entities or stale mappings
• To identify entities or relationships that exist on only one side
• To resolve field-level conflicts (e.g. different ABN, different name spelling)

---

How It Works

Reconciliation is a three-step wizard:

Step 1: Select Group & Generate Preview

1. Choose a linked XPM group from the dropdown
2. Optionally enable or disable cross-group endpoint inclusion
3. Click Generate Preview — the system builds normalised snapshots of both sides and compares them

Behind the scenes, the snapshot builder:

• Loads all SG entities in the group, their relationships, and their XPM mappings
• Fetches all XPM clients and relationships from the linked group via the XPM API
• Normalises both sides into a common canonical format for apples-to-apples comparison
• Runs the diff engine to identify every difference

Step 2: Review Differences & Make Decisions

The diff review table shows every difference found, grouped by type. For each item you choose an action — what should happen when you apply. Every item defaults to Skip (do nothing) so you're always in control.

Step 3: Apply & View Results

Click Apply to execute your decisions. The system saves your decisions, then processes them in a safe, phased order. A results panel shows exactly what happened to each item.

---

Difference Types

The diff engine classifies differences into five categories:

Membership Differences

Group membership gaps — an entity is in one group but not the other.

Stale mapping detection: If an entity has an XPM mapping but can't be found in XPM at all (e.g. it was deleted from XPM), the item is shown as informational and non-actionable until the entity is re-established.

Entity Presence Differences

Entities that exist on only one side.

Name-based matching: When an unmapped SG entity has a similar name to an unmatched XPM entity, the system suggests Link Entities as an action. This avoids creating duplicates by linking the two records together instead.

Entity Field Differences

Matched entities where field values differ between SG and XPM.

The diff engine compares entity-type-appropriate fields (name, ABN, ACN, date of birth, etc.) after normalising identifiers — stripping whitespace and dashes from ABN, ACN, and TFN so that "86 002 943 303" and "86002943303" aren't reported as different.

Relationship Presence Differences

Relationships that exist on only one side.

Endpoint readiness: If a relationship's endpoint entities haven't been synced to XPM yet, the item is marked non-actionable with an explanatory note. Sync or link the entities first, then re-run reconciliation.

Relationship Field Differences

Matched relationships where metadata differs (e.g. number of shares, percentage, relationship type).

The fields compared depend on the relationship type:

Available actions are the same as entity field differences: Use SG, Use XPM, Merge Fields, or Skip.

---

Relationship Matching

Relationships are matched between SG and XPM using a multi-pass strategy:

Pass 1: Mapping Match

If the SG relationship has an XPM mapping (external ID), the system looks for the same ID on the XPM side. This is the most reliable match.

Pass 2: Logical Key Fallback

For unmatched relationships, the system builds a logical key from the source entity, target entity, and relationship type. If the same logical key exists on the XPM side, the relationships are matched.

This catches cases where:

• The relationship has no mapping (unmapped)
• A symmetric relationship (e.g. spouse) was imported from the other direction
• A cross-group relationship's XPM UUID changed due to direction filtering

Pass 3: Partial Key Fallback (Cross-Group)

For relationships where one endpoint has no XPM mapping (typically a cross-group entity), the system attempts a partial match using the known endpoint plus the canonical relationship type. This only matches when exactly one XPM candidate exists, to avoid ambiguity.

Relationship Filtering

Before comparison, both sides apply the same filters:

• Reciprocal reverse types are excluded (e.g. "child" is dropped; only "parent" is kept)
• Symmetric relationships are deduplicated (spouse A→B and B→A become one entry)
• Non-XPM-representable types are excluded (e.g. ownership, loan, security)
• Cross-group relationships can optionally be excluded based on the cross-group setting

---

Actions Reference

Entity Actions

Relationship Actions

Membership Actions

---

Safety Guards

Destructive Action Protection

Actions tagged as destructive (delete SG entity, remove from SG group, remove from XPM group) are subject to additional safeguards:

• By default, destructive actions are skipped during apply unless explicitly allowed
• The apply engine checks allowDestructive and requireDecisionForDestructive flags

Out-of-Scope Delete Guard

Before deleting an SG entity, the system checks:

1. The entity must not still be present in the XPM group
2. The entity must not be a member of another mapped SG group
3. The entity must have no active SG relationships referencing it

If any check fails, the delete is blocked with an explanatory reason.

Preview Expiry

Previews have an expiry time. If the preview has expired when you try to apply, you'll need to generate a fresh one. This ensures you're working with current data, not a stale snapshot.

Phased Execution

The apply engine processes items in a specific order to minimise cascaded failures:

1. Membership changes first (group membership)
2. Entity actions second (presence + field changes)
3. Relationship presence third
4. Relationship field changes last

Each item has its own error boundary — a failure on one item does not prevent others from being applied.

---

Cross-Group Endpoints

By default, reconciliation includes cross-group endpoints — entities that appear in relationships but belong to a different group. This gives a complete picture of the relationship graph.

You can disable cross-group inclusion in the group selector if you only want to compare entities that are direct members of the selected group. When disabled:

• Cross-group relationships (one endpoint inside the group, one outside) are excluded from both sides
• This reduces noise but may hide legitimate discrepancies

---

Data Normalisation

During reconciliation, identifier fields are normalised for accurate comparison:

• ABN — whitespace and dashes stripped before comparing (e.g. "86 002 943 303" matches "86002943303")
• ACN — same normalisation
• TFN — same normalisation

Entity names are also normalised for name-based matching:

• Case-insensitive comparison
• Leading "The" removed (e.g. "The Smith Family Trust" matches "Smith Family Trust")
• Abbreviated suffixes normalised ("PTY." → "PTY", "LTD." → "LTD")
• Trustee suffixes stripped (" ATF ..." removed)

---

Tips

• Generate a fresh preview before applying — stale previews don't reflect recent changes
• Start with Skip for everything, then selectively change actions for items you want to resolve. The wizard defaults all items to Skip for safety
• Use Link Entities when you see matching names — this is cleaner than importing a duplicate and deleting the original
• Review field diffs carefully — the Use SG and Use XPM actions overwrite the target system entirely for the affected fields
• Use Merge Fields for fine-grained control — pick the best value per field when both sides have useful data
• Re-run after applying — generate a new preview after applying to verify everything is now in sync
• Enable cross-group endpoints when dealing with directors, trustees, or other entities that span multiple groups

---

Troubleshooting

"Preview has expired"

Generate a new preview. Previews expire after a set period to ensure you're comparing current data.

Relationship items show "Blocked"

The endpoint entities haven't been synced to XPM yet. Link or push the entities first, then re-run reconciliation.

"Delete SG" action was skipped

The out-of-scope delete guard prevented the deletion. Check whether the entity has active relationships or belongs to other groups. You may need to remove those dependencies first.

Name matches show unexpected candidates

Name matching uses normalised comparison (case-insensitive, suffix-stripped). Common entity names like "Smith Family Trust" may produce false matches across unrelated client groups. Always verify the candidate is the correct entity before linking.

Field diffs show identifiers as different even though they look the same

Check for invisible whitespace, leading zeros, or formatting differences. The diff engine strips whitespace and dashes for ABN/ACN/TFN comparison, but other fields use exact string comparison.

Some relationships were not compared

Only XPM-representable relationship types are included. Types like ownership, loan, security, and guarantor have no XPM equivalent and are excluded from reconciliation. Reciprocal reverse types (e.g. "child") are also excluded — only the primary direction (e.g. "parent") is shown.

XPM API Limitations

The same XPM API limitations that apply to sync and push also apply to reconciliation. Not all fields visible in XPM's web interface are available via the API, which means some differences may not be detectable. See the XPM Sync help page for details on API limitations.

---

Related Topics

• Connecting to Xero Practice Manager — set up the XPM integration
• Xero Practice Manager Sync — pull XPM data into StructureGram
• Push to Xero Practice Manager — send StructureGram data to XPM
• Understanding Groups — organize entities into groups
• Relationship Types Reference — supported relationship types