Create a New Group in XPM

Create in XPM takes a StructureGram group that isn't linked to XPM yet, creates a new group in Xero Practice Manager (XPM), and sends every entity and relationship in it to XPM. You get it on the group's XPM page for an unlinked group, or through Create + Export in the Import Hub.

Before anything is written to XPM, StructureGram checks what the push would run into and asks you about anything that needs a decision. This page explains that check, what each thing it finds means, and what the push then does.

Linking to a group that already exists in XPM is different. If the group is already in XPM, link to it instead. You then pull from XPM or run a two-way sync, and this page doesn't apply. See Connecting to Xero Practice Manager.

Creating a group in XPM needs Group Admin access, like any push. See XPM Permissions by Member Role.

Key Terms

Linked client: an entity StructureGram has already connected to a client in XPM, for example because it was pushed or pulled before, perhaps with another group.
Archived client: a client someone archived in XPM. XPM keeps it, but hides it from its client lists.
Deleted client: a client someone deleted in XPM. In XPM, deleting a client also archives it, so a deleted client is also archived.
Re-create: StructureGram creates a brand-new client in XPM for the entity and links the entity to it. The old archived or deleted client stays as it is in XPM.

Step 1: The Check

When you click Create in XPM, StructureGram first reads from XPM. It writes nothing. It looks at every entity the push would send, both the group's own and any entity in another group that one of its relationships connects to. It checks for four things:

What it looks for	Why it matters
Linked clients that are archived or deleted in XPM	XPM refuses to update an archived or deleted client, so the push re-creates them.
Entities with no link that look like an existing XPM client	Creating them would make a duplicate in XPM. Companies are matched on name, ACN or ABN. People are matched on first and last name.
An XPM group with the same name	Creating would give XPM two groups with that name.
Linked clients whose status XPM didn't report	StructureGram can't tell you whether they're active.

If it finds nothing, the push goes ahead straight away. You won't see a dialog.
If it finds anything, the Before you create in XPM dialog opens.

Step 2: The Dialog

The dialog lists what the check found, in sections. Nothing has been written to XPM at this point.

Cancel closes the dialog and writes nothing.
Create in XPM goes ahead with the push, applying what the dialog says and the choices you made.

Previously deleted in XPM

These entities were previously deleted in XPM. They will be re-created as new clients in XPM.

These entities are linked to XPM clients that have since been deleted. You'll often see this when:

the group was pushed to XPM before, and
then deleted in XPM with its clients (for example with Delete in XPM and delete members).

The push creates a new XPM client for each one and links the entity to it. There's nothing to choose, unless an active XPM client looks like it. See When a client to be re-created is already in XPM.

Archived in XPM

These entities are archived in XPM. They will be re-created as new clients in XPM.

These entities are linked to XPM clients that are archived, not deleted. If you continue, each one is re-created as a new client, the same as a deleted one. The archived client stays in XPM, so XPM then has the old archived client and a new active one.

If you'd rather keep an archived client, see Restoring an archived client instead below. StructureGram can't do this for you: XPM doesn't let other software bring an archived client back.

When a client to be re-created is already in XPM

Sometimes a client was deleted or archived in XPM, then entered again by hand. Re-creating it would make a duplicate. If an active XPM client looks like it (same name, or for a company the same ACN or ABN), the list notes "an active XPM client looks like it; choose below". You then choose, under Already in XPM? Choose for each:

Link to [client] in XPM and update it. The entity is linked to that existing client, and no new client is created. Its old relationships in XPM went with the old client, so StructureGram creates them again for the linked client.
Re-create as a new client anyway. Choose this when it's a different client that happens to look alike.

If a push reaches such a client without a choice, for example because it was re-entered in XPM after the check, the push doesn't re-create it. It leaves the entity on its old client and skips its relationships, and the summary says so. Click Create in XPM (or push) again to see the choice.

Some deleted and some archived

A group can have both. They're shown in their own sections, and the push re-creates each one in the right way. The push summary tells you, for each client, whether it was archived or deleted.

Cancel applies to the whole push, not to one client. To keep one archived client, you cancel everything, restore that client in XPM, and create again.

Linked clients in other groups that are archived or deleted

Some relationships connect this group's entities to entities in other groups, and those entities may be linked to archived or deleted clients. This push does not re-create them, because they belong to another group. The relationships to them will fail. To fix that:

Push their group first, which re-creates them.
Then push this one.

Already in XPM? Choose for each

These entities have no link to XPM, but an active XPM client looks like them. You must choose for each one before Create in XPM becomes available:

Link to [client] in XPM and update it. The entity is linked to that existing client instead of creating a new one, and StructureGram sends its details to that client. Choose this when it's the same person or company.
Create a new client anyway. Choose this when it's a different client that happens to look alike.

For each possible match, the dialog shows why it matched, for example "Same ACN" or "Exact name match", and which XPM groups that client is in.

A client already linked to another StructureGram entity can't be chosen. The dialog names that entity. Linking would take the client away from it. If they really are the same, merge the two entities in StructureGram first.

XPM already has a group with this name

Continuing creates a second group with the same name. If you meant the existing group, cancel and link to it instead. See Connecting to Xero Practice Manager.

XPM didn't report the status of these clients

StructureGram couldn't confirm these linked clients are active. The push still tries them. If XPM turns out to have any of them archived or deleted, the push re-creates them as new clients.

Step 3: The Push

The push then runs as described in Push to Xero Practice Manager: clients, then the XPM group and its members, then relationships.

For each re-created client:

a new XPM client is created and the entity is linked to it;
the old client's relationships in XPM went with it, so StructureGram forgets them and creates them again for the new client.

Your choices on possible duplicates are applied as the push runs:

linked entities update the client you chose;
the others are created.

The push summary shows how many clients were re-created, and whether the old ones were archived or deleted.

If relationships weren't written, the summary shows Next step: run a two-way sync. It says why, for example because XPM limited requests or the push stopped, and has an Open two-way sync button.

Shareholdings need a two-way sync afterwards

Most relationships, such as directors, secretaries and trustees, are re-created in the same push.

Shareholdings are not. A shareholding in XPM is tied to the old client, so when that client was archived or deleted, the shareholding went with it. StructureGram only re-creates a shareholding through a two-way sync, where you review it first. In the push summary, these show as:

Shareholding not written: one of its clients was deleted or archived in XPM and recreated, so its XPM holding went with it. Run a two-way sync to recreate the holding in XPM.

So when a push re-creates clients that have shareholdings, it takes two steps:

Create in XPM (this push): re-creates the clients and most relationships.
Two-way sync on the group's XPM page: review and apply the shareholdings it offers.

Pushing a second time won't re-create them. A push deliberately leaves these shareholdings alone until the two-way sync has replaced them. See XPM Reconciliation.

Restoring an Archived Client Instead

If you want to keep an archived XPM client rather than re-create it:

Click Cancel in the dialog. Nothing has been written.
In XPM, restore the archived client (make it active again). The exact steps are in XPM's own help.
Back in StructureGram, click Create in XPM again.

The check now finds the restored client active. The push updates it, and doesn't create a new one. Any other archived or deleted clients are still listed, and are re-created when you continue.

Pushing One Entity

Push [entity] to XPM, in an entity's ⋯ menu, runs the same check for that one entity:

an archived or deleted linked client;
a possible duplicate.

It shows the same dialog, titled Before you push to XPM, and the same choices apply.

Limits

An archived look-alike can't be found. XPM doesn't list archived clients, so the check only finds possible duplicates among active ones. If an entity with no link matches only an archived client, the push creates a new client without asking.
StructureGram can't restore archived clients. XPM only allows that in its own interface.
The check reflects XPM when you clicked. If a client is archived in XPM between the check and the push, the push still re-creates it, and the summary says so.

Troubleshooting

The Create in XPM button in the dialog is greyed out

Choose Link or Create a new client anyway for every entity under Already in XPM? Choose for each. The button becomes available once each one has a choice.

The same name appears twice in the list

The group has two StructureGram entities with that name, each linked to its own XPM client. Check whether one is a duplicate in StructureGram, and merge them if so, before you push. Otherwise both are re-created as separate XPM clients.

"Push decisions refused"

Something changed after the check. For example, another push linked the XPM client you chose to a different entity. Nothing was written. Click Create in XPM again to run a fresh check.

"Relationships not attempted (XPM limited requests)"

XPM allows only so many requests in a short time. A push that re-creates many clients can reach that limit. The push then stops before it writes the relationships, so nothing is written for them and nothing is left half-done. Your clients and the XPM group are already in XPM.

Wait a minute, then click Open two-way sync in the summary's Next step panel. The two-way sync compares the group with XPM and lets you review and apply the missing relationships, including any shareholdings, in one pass.

Shareholdings show "not written" after the push

This is expected after clients are re-created. Run a two-way sync on the group's XPM page. See Shareholdings need a two-way sync afterwards.

Help & Documentation