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.

How It Works

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.
• 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, if cross-group sync is enabled, these external entities are synced to XPM as well so that the relationship can be created. Each cross-group entity is pushed individually using 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):

Note: TFN (Tax File Number) export is currently suppressed because XPM rejects TFNs that don't pass its own check-digit validation. This may be re-enabled in a future update.

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.

---

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

If XPM returns a 429 (Too Many Requests) response, the push logs a warning but continues processing remaining items. Some items may fail due to rate limiting — re-running the push will retry those items.

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. When pushing, you can enable cross-group dependency sync:

• Enabled — entities from other groups that are needed for relationships in this group are automatically pushed to XPM. A mapping is created for each cross-group entity so it can be referenced by relationships.
• Disabled — cross-group entities are skipped. Relationships that depend on unmapped entities will fail.

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.
• Enable cross-group sync for groups with external directors or trustees to ensure all relationship endpoints exist in XPM.
• TFN is not pushed — if you need TFN data in XPM, enter it directly in XPM for now.

---

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. If endpoints are in different groups, enable cross-group dependency sync.

Duplicate clients appear in XPM

This can happen if you push before pulling. If an entity already exists in XPM but doesn't have a StructureGram ↔ XPM mapping, the push creates a new client. To fix this:

1. Delete the duplicate in XPM
2. Run a Pull sync to establish mappings for existing XPM clients
3. Re-push — existing mappings will cause updates instead of creates

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