Data Required to Import from XPM

Before pulling data from Xero Practice Manager (XPM), it helps to know which details StructureGram needs to create usable Entities and Relationships.

Some details are essential because they identify the XPM client or Relationship. Other details can be selected during the StructureGram review. StructureGram can also apply limited defaults, but those defaults should be checked before you rely on the imported structure.

This article covers inbound pulls from XPM. For the pull steps, see How to Pull Data from XPM.

The Three Levels of Data Readiness

Required means StructureGram cannot identify or import the item without the detail.
Required to resolve means the detail must be known before import, but you can select it during the StructureGram review if XPM does not provide enough information.
Recommended means the item can import without it, but the resulting Entity or Relationship may be incomplete or use a default value.

XPM supplies its internal client and Relationship identifiers automatically. You do not normally enter those identifiers yourself.

Requirements for Every Entity

XPM detail	Requirement	What happens if it is missing or unsuitable
Client ID	Required	The client is skipped because StructureGram cannot identify it.
Business Structure	Required to resolve	StructureGram tries to match it automatically. If the label is missing, custom, or ambiguous, you must select an SG entity type during review.
Name	Recommended	The Entity can import with a visible placeholder, but you should correct it before using the Group.
Current client	Required	Clients marked archived or deleted in XPM are not imported.

The Business Structure determines whether the client becomes an Individual, Company, Trust, Partnership, or SMSF. See Automatic Type Matching for XPM Structures for recognised labels and keyword matching.

Entity Requirements by Type

SG Entity type	Required to resolve	Recommended XPM details	Optional imported details
Individual	Business Structure resolves to Individual	First Name and Last Name	Middle Name, date of birth, sex, email, phone, address, ABN and TFN
Company	Business Structure resolves to Company	Company Name	ABN, ACN and country
Trust	Business Structure resolves to Trust and a concrete Trust subtype is known	Trust Name	ABN, country and TFN
Partnership	Business Structure resolves to Partnership	Partnership Name	ABN and TFN
SMSF	Business Structure resolves to SMSF	Fund Name	ABN and TFN

Missing names

Names are strongly recommended, but they are not a technical import blocker:

An Individual without a usable person name receives [FirstName] and [LastName] placeholders.
Another Entity without a name receives a placeholder based on its XPM client ID.

Replace these placeholders with the correct names before relying on the Entity in diagrams or reports.

Sensitive identifiers

TFNs are not required for import. Whether StructureGram imports a TFN depends on your organisation's sensitive-data import settings. Do not add a TFN to XPM solely to make an Entity import.

Trust Type Requirements

A Trust cannot complete import until StructureGram knows its Trust subtype. The subtype also determines which Relationships are valid.

XPM Business Structure or description	SG Trust subtype
Unit Trust	Unit Trust
Family Trust	Usually Discretionary Trust
Testamentary Trust	Testamentary Trust
Estate or Deceased Estate	Deceased Estate
Generic Trust	You must choose Discretionary Trust, Testamentary Trust, or Bare Trust/Nominee
Not-for-profit or Charity	You must choose Private Ancillary Fund or Charitable Fund

Custom labels may resolve through keyword matching or an organisation-wide saved mapping. If StructureGram cannot determine a single result, it holds the Trust for your decision instead of guessing.

Requirements for Every Relationship

XPM detail	Requirement
Relationship ID	Required
Supported Relationship Type	Required
Source client	Required
Related client	Required
Importable endpoints	Both clients must exist, be current, and resolve to compatible SG Entity types.
Valid direction	StructureGram must be able to identify the role-holder and the Entity it relates to.

The source and related client cannot be the same Entity. A Relationship is also held or skipped when either endpoint still needs an Entity type or Trust type decision.

Use directional XPM labels such as Director Of, Shareholder Of, and Trustee Of where available. They make the intended direction clear.

Relationship Requirements by Type

In the combinations below, the Entity on the left holds the role and the Entity on the right is the target.

XPM Relationship	Valid Entity combination	Additional data needed
Shareholder Of or company Owner Of	Individual, Company, Trust, or SMSF -> Company	The share class must be resolved in StructureGram. The number of shares is recommended but not required.
Unitholder Of or Unit Trust Owner Of	Individual, Company, Trust, or SMSF -> Unit Trust	The unit class must be resolved in StructureGram. The number of units is recommended but not required.
Director Of	Individual -> Company	No additional fields are required.
Secretary Of	Individual -> Company	No additional fields are required.
Public Officer Of	Individual -> Company	No additional fields are required.
Receiver Manager Of	Individual -> Company	No additional fields are required.
Administrator Of	Individual -> Company	No additional fields are required.
Liquidator Of	Individual -> Company	No additional fields are required.
Trustee Of a Trust	Individual or Company -> Trust	The Trust subtype must be resolved.
Trustee Of an SMSF	Individual or Company -> SMSF	The trustee arrangement must contain either individual trustees only or one corporate trustee.
Beneficiary Of	Individual, Company, or Trust -> Trust; SMSF -> Bare Trust/Nominee	The Trust subtype must be resolved.
Appointer Of or Appointor Of	Individual or Company -> Trust	The target cannot be a Bare Trust/Nominee.
Partner Of	Individual, Company, Trust, or SMSF -> Partnership	A partnership percentage is recommended. The current XPM import does not block a missing percentage.
Member Of	Individual -> SMSF	No additional fields are required.
Spouse	Individual <-> Individual	No additional fields are required.
Parent Of	Individual -> Individual	No additional fields are required.
Child Of	Individual -> Individual	No additional fields are required.

Shareholdings and Unitholdings

Does XPM need a number of shares?

No. A company shareholder can import without a number of shares. For a new shareholding, StructureGram uses 1 when no positive number is supplied.

The same rule applies to a new unitholding: StructureGram uses 1 unit when no positive number is supplied.

This default allows the Relationship to be created, but it does not confirm the real holding. Record the actual quantity in XPM where possible, or correct it during review.

Does XPM need a share or unit class?

The class must be resolved before StructureGram creates a class-aware holding, but it does not have to be populated in XPM.

For a straightforward new holding, the review can recommend Ordinary Shares or Ordinary Units.
You can replace the recommendation with the correct class.
When SG already contains a holding between the same Entities, you must select the existing holding or create a separate class-aware holding.

This review prevents two economically different holdings from being merged just because they have the same owner and target.

Optional Relationship Details

The following details improve accuracy but are not general import blockers:

Number of shares or units
Ownership percentage
Partnership percentage
Start or effective date
End date
Member balance
Notes or other descriptive metadata

Populate quantities, percentages, classes, and dates in XPM whenever they are known. Defaults are useful for completing the workflow, but they are not a substitute for the source documents or the actual ownership register.

Preparing XPM Before a Pull

Confirm every client has the correct Business Structure.
Give every client a meaningful name. For Individuals, record both first and last names.
Make Trust labels specific enough to identify the Trust subtype where possible.
Confirm each Relationship uses the correct clients and direction.
For shareholdings and unitholdings, record the real quantity and class where XPM supports them.
Add useful effective dates and percentages when known.
Remove or correct duplicate and obsolete Relationships before pulling.
Run the pull and review every item that StructureGram flags for a decision.

Edge Cases and Expected Behaviour

An unknown Business Structure does not become a generic Entity. StructureGram asks you to choose the SG entity type.
A generic Trust is held for a subtype decision unless its name or saved mapping resolves the subtype.
A Relationship waits for its Entities. It cannot import while either endpoint is unresolved or unavailable.
Owner is contextual. It becomes a shareholder for a Company and a unitholder for a Unit Trust.
Beneficiary is contextual. StructureGram may convert it to a named beneficiary for an appropriate Trust subtype or to a unitholder when the data clearly represents a Unit Trust holding.
Archived or deleted XPM clients are skipped. Relationships involving those clients are also skipped.
Cross-Group Relationships may need dependency import. StructureGram must be allowed to bring in the client outside the selected XPM Group, or the Relationship is skipped.

Troubleshooting

An Entity did not import

Most likely causes:

The XPM client has no usable client ID.
The client is archived or deleted.
Its Business Structure or Trust subtype still needs your selection.
StructureGram found a possible duplicate that needs review.

Fix:

Check the client in XPM.
Correct its status, name, or Business Structure where necessary.
Return to the StructureGram review and resolve any type or duplicate decision.
Run the pull again.

A Relationship did not import