Push to Xero Practice Manager

StructureGram can push entities and relationships from your workspace to Xero Practice Manager (XPM). This is the reverse of the sync/pull flow — instead of importing XPM data into StructureGram, it sends StructureGram data out to XPM.

Pushing requires Group Admin access. Because a push writes into your practice management system, it sits at a higher access level than pulling. Member - Edit can pull from XPM, link a group, and correct data inside StructureGram, but cannot push any of it back. If you don't see the push option, or a push is refused, check your access level for that group with an organisation admin. See XPM Permissions by Member Role.

How It Works

Creating a new XPM group? Create in XPM checks for archived or deleted clients, possible duplicates and a same-named group before it writes anything, and asks you first. See Create a New Group in XPM.

When you click Push to XPM on a linked group's XPM page, StructureGram sends all entities and relationships in the current group to your XPM account. The push runs in five phases:

Phase 1: Entity Sync

Each entity in the group is sent to XPM as a client record.

• If the entity already has an XPM mapping (e.g. it was previously synced or pushed), the existing XPM client is updated.
• If the entity has no mapping, a new XPM client is created.
• If the entity's XPM client was archived or deleted in XPM, XPM refuses the update. The push creates a new client and links the entity to it. The summary says whether the old client was archived or deleted. Shareholdings with that client then need a two-way sync; see Create a New Group in XPM.
• Entity data (name, identifiers, contact details) is mapped to the appropriate XPM client type and sent as the payload.

Phase 2: Group Sync

After entities are synced, the XPM group itself is updated to ensure its name and metadata match the StructureGram group.

Phase 3: Group Membership

The XPM group's membership list is updated so that all synced entities appear as members of the group in XPM. This ensures the group structure in XPM mirrors StructureGram.

Phase 4: Cross-Group Dependencies

Some relationships reference entities that belong to a different StructureGram group. For example, a director might be a member of a different group but serve as a director of a company in this group.

During push, cross-group dependency entities are synced to XPM automatically so that required relationship endpoints exist. Each dependency entity is pushed with the same create-or-update logic.

Phase 5: Relationship Sync

Finally, relationships between entities are sent to XPM. The system maps each StructureGram relationship type to its XPM equivalent and creates or updates the relationship in XPM.

---

Entity Type Mapping

StructureGram entities are mapped to XPM client types for the push:

The type mapping can be overridden at the group level if the default mapping doesn't suit your XPM configuration.

---

What Data Is Pushed

Entity Fields

The push sends the following data to XPM (when available):

TFN: StructureGram fills a gap in XPM; it never overwrites a TFN already recorded there, and never sends one that fails the check digit — XPM would reject the whole client update. An omitted TFN is reported with a reason naming only its last 3 digits, and the item is not marked as applied.

Director ID: not sent. XPM's client API has no Director ID field, and writes naming one are accepted then silently discarded — so a "successful" push would be misleading.

Both are covered in TFNs and Director IDs with XPM.

Relationship Fields

---

Merge Policy

The push uses a sparse merge policy by default. This means:

• On create, all available fields are sent in the payload.
• On update, only the entity name is sent if it has changed. Other fields are included only if they have values — empty fields are not sent, so they won't overwrite existing data in XPM.

This prevents accidental data loss when StructureGram has less data than XPM for a given client.

---

Relationship Filtering

Not all relationships are sent to XPM. The push applies several filters:

Unsupported Types

Some StructureGram relationship types don't have XPM equivalents. These are silently skipped. The push summary will note how many relationships were skipped.

Reciprocal Reverse Types

Certain relationship types have a natural reverse in StructureGram (e.g. parent ↔ child). Only the primary direction is pushed — the reverse direction is excluded to avoid creating duplicate relationships in XPM. XPM will generally create the reciprocal relationship automatically.

Symmetric Deduplication

For symmetric relationships like spouse, StructureGram stores both directions (A→B and B→A) but XPM only needs one. The push detects symmetric pairs and sends only one direction, preferring the version where both endpoints already have XPM mappings.

---

While It Runs

The progress window shows where the push is, and updates every few seconds:

• Clients — 7 of 19: Hold Co Pty Ltd: the client being sent, with counts of clients re-created (archived or deleted in XPM) and of any that failed so far.
• Creating the XPM group, then Adding members to the XPM group (for Create in XPM).
• Clients in other groups: entities in other groups that the relationships need.
• Relationships — 4 of 12, with any that failed so far.

While a push runs, the page doesn't make any other request that reaches Xero, so the push has XPM's request limit to itself.

Push Results

After the push completes, a summary is displayed showing:

• Overall status — Success, Partial Success, or Failed
• Per-entity results — whether each entity was created, updated, or failed
• Per-relationship results — whether each relationship was created, updated, or failed
• Warnings — non-fatal issues encountered during the push
• Errors — failures that prevented specific items from syncing

Status Meanings

Field Presence Tracking

The summary includes which identifier fields were present in each entity's push payload (ABN, ACN, TFN, DIN, date of birth, sex). This helps you verify that the data reaching XPM is complete.

---

Error Handling

Authentication Failures

If XPM returns a 401 (Unauthorized) or 403 (Forbidden) error during entity sync, the push is aborted immediately. This prevents wasting time on subsequent requests that would also fail. Check your Xero connection and re-authenticate if needed.

Rate Limiting

XPM allows only so many requests in a short time. When it answers 429 (Too Many Requests) and retries don't get through, the push stops rather than fail every remaining item. Its summary then says it stopped because XPM limited requests. Wait a minute, then run a two-way sync to write what was left.

To stay under the limit, the push skips calls it doesn't need. A client the check before Create in XPM already found archived or deleted is re-created straight away, without reading it again or sending an update XPM would refuse.

Missing Entity

If an entity referenced by a relationship hasn't been synced to XPM (and isn't covered by cross-group sync), the relationship push will fail for that item. The summary will report which relationships couldn't be created.

---

Cross-Group Dependencies

Entities can appear in relationships across multiple groups. Push includes these dependencies by default:

• Entities from other groups that are required for relationships are automatically pushed to XPM.
• A mapping is created for each dependency entity so relationships can be created reliably.

Cross-group entities are pushed as standalone clients in XPM (they are not added to this group's membership).

---

Tips

• Sync (pull) before you push — if the group already has data in XPM, pull first so that existing mappings are established. This ensures the push updates existing records rather than creating duplicates.
• Check the summary — review per-entity and per-relationship results to catch any failures or warnings.
• Re-push after fixing issues — the push is idempotent. Items that already have mappings will be updated, not duplicated.
• Cross-group dependencies are synced automatically — external directors/trustees needed for relationships are pushed as dependency entities.
• TFN fills gaps only: it is sent only when it passes the ATO check digit and XPM has no TFN for that client. See TFNs and Director IDs with XPM.

---

Troubleshooting

"Push aborted — authentication failure"

Your Xero connection may have expired. Go to Xero Integration settings and re-authenticate. Then retry the push.

Some entities show as "Failed"

Check the error details in the push summary. Common causes:

• The entity data couldn't be mapped to a valid XPM client type
• A required field was missing or invalid
• XPM rejected the payload (e.g. invalid identifier format)

Relationships weren't created

This usually means one or both endpoints don't have XPM mappings. Ensure all entities were pushed successfully before the relationship sync runs. Cross-group dependencies are auto-synced, but failures can still occur if a dependency entity itself fails validation or API write.

Duplicate clients appear in XPM

Before it creates a client, the push checks for an active XPM client that looks the same: name, and for companies ACN or ABN.

• Create in XPM and single-entity pushes ask you first: link to the existing client, or create anyway. See Create a New Group in XPM.
• Otherwise a possible duplicate fails that entity's row instead of creating it.

A duplicate can still appear when the existing client is archived in XPM, because XPM doesn't list archived clients, so the check can't see them. To clean up:

1. Delete or archive the duplicate in XPM.
2. Run a pull so StructureGram links to the clients you're keeping.
3. Push again. Linked entities are updated, not created.

XPM API Limitations

The same XPM API limitations that apply to the sync/pull flow also apply to pushing. Not all StructureGram fields can be sent to XPM due to gaps in the XPM API. For example, TFN export is currently suppressed. See the XPM Sync help page for more 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
• XPM Reconciliation — compare and resolve differences between SG and XPM
• Understanding Groups — organize entities into groups
• Relationship Types Reference — supported relationship types