Import and Maintain Organization Structures - Article
Summary
Use import and export to establish or maintain organization structures at scale. The important task is not only getting rows into the platform: it is preserving the identity, parent path, and settings of the business relationships those rows represent.
This article explains how to:
- Choose between manual maintenance, spreadsheet import, and a connected process.
- Prepare the current organization import template.
- Distinguish creating a record from updating an existing one.
- Validate a controlled batch before applying a wider change.
Choose the maintenance method
| Method | Appropriate use | Responsibility to establish |
|---|---|---|
| Manual creation and editing | A small number of organizations or occasional changes. | Who approves names, parent relationships, and settings. |
| Organization import | Initial setup, branch rollouts, and controlled batches of updates. | Who prepares the file, validates identifiers, and reviews the resulting records. |
| Export | Review, reconciliation, or preparation for approved maintenance. | Who may receive the file and how its business information is protected. |
| API or integrated provisioning | A connected business or identity system maintains the structure repeatedly. | Which system is authoritative and how creation, renaming, moving, and removal are handled. |
Importing the organization structure is different from importing users and assigning their memberships. Plan both when bringing a new customer population onto the platform.
Start with the current template
Open Organizations → Import and select Download example. The organization import interface accepts an XLSX file.
Use a new example from the platform where you will perform the import. Available identifiers, fields, and hierarchy columns can depend on its configuration and existing structure. A file prepared for another customer implementation or an earlier setup may not be suitable.
Keep the template's column structure and follow its instructions. Treat names, identifiers, and hierarchy paths as controlled data rather than presentation text.
| Information | How to prepare it | Why it matters |
|---|---|---|
| Title | Use the approved, consistent organization name. | In a title-based configuration, Title is the matching identifier for an existing organization. |
| Suborganization levels | Complete the hierarchy columns in the downloaded example, preserving every required parent level. | A branch name alone may not identify its intended place in the structure. |
| Email mask | Use approved domains in the format shown by the example. | Domain rules can affect subsequent membership assignment. |
| URL | Use the supported organization URL value according to the downloaded example and your approved entry-route design. | Do not treat this field as proof of membership assignment or as a way to configure a separate internet domain. |
| Organization ID and other optional fields, only if included | Use additional columns only when they appear in the current template for your platform. Preserve the agreed identifiers and follow the matching rules shown. | An option available elsewhere in the interface is not necessarily supported by organization import. |
Do not invent columns for a field that is not supported by the downloaded example. If you need another hierarchy level or identifier, confirm the supported configuration before preparing a large file.
Manage discounts separately. Organization import does not maintain the current Discounts rules. See Discount campaigns and Coupons for the complete workflow. Configure organization-targeted discounts and their expiration under Course administration → Discount campaigns → Discounts, using Organizations as an audience criterion. Do not add legacy organization-discount or discount-expiry columns to the import file.
Understand update versus creation
Title-based matching
In the standard title-based setup, the import page identifies Title as the unique organization identifier. A row matching an existing title can update that record; a new title is treated as a different organization.
This means changing the title in a maintenance spreadsheet is not necessarily a rename. If the title is the key, that change can create another organization instead of updating the original one.
For example, if Northstar Services is the matching title, changing that spreadsheet value to Northstar Academy can create another organization rather than rename the existing one. In a title-based setup, make the approved rename on the existing record and use its current title for later imports. Where supported Organization ID matching is enabled, preserve that ID when updating the name.
Organization ID matching
Where the Organization ID feature is enabled, the ID forms part of the import/export structure. An existing organization's name can be updated by specifying its ID.
Changing the identifier itself is a different operation. The documented special case allows an automatically generated ID to be updated through name matching; it does not provide the same import route for an ID already entered manually. Treat identifier changes as controlled maintenance and confirm the supported method before proceeding.
Some implementations use other configured business identifiers. Follow the active configuration and current template rather than combining matching assumptions from several implementations.
| Intended change | Safe approach | Risk to avoid |
|---|---|---|
| Add a new organization | Use a genuinely new approved identity and complete its required settings. | Accidentally duplicating an existing customer under another spelling. |
| Update settings on an existing organization | Preserve its matching title or supported identifier. | Creating a new record because the matching value changed. |
| Rename an organization | Use the supported ID-based update where enabled, or an approved manual edit in a title-based setup. | Assuming that a changed title will be recognized as the same record. |
| Add a nested branch | Include the complete required parent path. | Creating the branch under the wrong parent or omitting levels. |
| Reorganize an existing branch | Use the documented Move process unless a specific integration/import method has been confirmed for the case. | Treating a changed spreadsheet path as a guaranteed move operation. |
Import a controlled batch
- Export or otherwise record the existing structure and the settings relevant to the proposed change.
- Download the current import example.
- Prepare a small, representative batch covering the creation or update cases you need.
- Review the identifiers, titles, parent paths, email masks, URLs, and any supported optional fields with the responsible owner.
- On Import organizations, choose the XLSX file, use Upload, then complete Import as presented by the interface.
- Read the resulting messages and inspect the actual organization records.
- Apply the wider approved batch only after the representative result is correct.
An export provides useful evidence and a comparison point. It is not a promise of automatic rollback. Do not assume an import is all-or-nothing or that rerunning a file will reverse a previous result.
Keep the approved source file, date, purpose, and result together so another administrator can understand what changed.
Import and export at suborganization level
The suborganization management interface supports import and export at the relevant hierarchy level. A scoped administrator may see the higher-level path in a template or export because it is needed to locate the branch.
That visible path does not grant permission to update the parent levels. Administrators without access to a higher level can maintain only the permitted level and below.
If the template includes a column for a new lower-level organization, use it according to the downloaded example. Preserve the existing parent path when creating the new branch.
Coordinate with connected systems
For an integrated academy, agree where the authoritative organization data lives. A CRM may maintain customer identity, an HR system may maintain departments, and an identity service may assign users to the resulting structure.
The administrator needs to understand the outcome and ownership of that process even when the integration itself is maintained by a technical team.
| Decision | What to agree |
|---|---|
| Record identity | Which stable identifier links the organization between systems. |
| Authoritative fields | Which system owns titles, parent relationships, and relevant settings. |
| Update timing | When changes arrive and how administrators recognize a pending update. |
| Manual exceptions | Which changes may be made locally without being overwritten. |
| Departures and restructuring | Whether the process removes membership, moves a branch, blocks an account, or performs another approved action. |
| Failure ownership | Who investigates unmatched identifiers, rejected records, or incomplete synchronization. |
Do not assume a connected login automatically maintains every organization field. Authentication, account creation, membership assignment, and organization synchronization are distinct capabilities.
Practical maintenance patterns
| Requirement | Recommended approach | Outcome |
|---|---|---|
| Launch a customer with many branches | Import the approved structure first, validate it, then add or provision users. | Membership can be assigned to stable, verified branches. |
| Review the organization structure annually | Compare an export with the approved structure. Use import for supported field updates and the Move action for approved branch moves. | Business relationships stay current without confusing structural maintenance with discount management. |
| Reconcile a partner network | Export the permitted structure and compare it with the authoritative business register. | Missing, duplicate, or obsolete relationships are identified before changes are applied. |
| Maintain a frequently changing enterprise | Use an approved connected process with clear field ownership. | Repeated manual imports do not compete with the authoritative system. |
Verify the result
| Scenario or check | Expected result or evidence |
|---|---|
| Record matching Inspect a new record and an updated existing record. | Creation and update occurred as intended, without duplicates. |
| Hierarchy Open representative full parent paths. | Branches are under the approved parents. |
| Operational settings Inspect email masks, URLs, and any optional fields actually included in the import. | The batch changed only the approved settings. |
| Downstream behavior Check representative membership, automatic enrollment, or connected-system results. | The structural change produces the intended operational outcome. |
Troubleshooting
| What you observe | What to check |
|---|---|
| A duplicate was created | Compare the matching title or identifier with the existing record. Do not delete either record until relationships and the intended survivor have been reviewed. |
| A name change did not update the existing record | Check whether the platform uses title-based matching or supports an Organization ID update. |
| A branch appears in the wrong place | Review all parent columns and the level from which the import was performed. |
| The file is rejected or fields are missing | Download the current example, check XLSX format, required fields, active identifiers, and supported hierarchy depth. |
| An administrator sees parent names but cannot update them | The path supplies context; it does not extend the administrator's scope. |
| Users were enrolled after the import | Review the configured organization Activities or onboarding rules and the membership changes associated with the import. Do not assume the import file contains an Activities column. |
| A manual correction is later reversed | Check whether a connected system owns that field and update the authoritative source through its approved process. |
FAQ
-
Can I import organization discounts and their expiration dates with the organization structure?
No. Maintain current organization-targeted discount rules under Course administration → Discount campaigns → Discounts, using Organizations as an audience criterion. Do not add legacy organization-discount or discount-expiry columns to the organization import file.
-
Does importing organization structures also create users and assign their memberships?
Organization structure import and user creation or membership assignment are separate tasks. Import and verify the organization hierarchy first, then use the approved user import, invitation, or provisioning process to place people in the correct organizations.
-
Will changing a title in the organization import file rename the existing organization?
Not necessarily. When Title is the matching identifier, a different title can create another organization. Use an approved manual rename, or the supported Organization ID matching route where enabled. Download the current example and check the matching rules before importing.
-
Can I move an existing organization branch by changing its path in an import file?
Do not assume so. Use the documented Move action unless a specific import or integration method has been confirmed for that case. Preserve parent paths in ordinary updates and verify the resulting hierarchy after a controlled test batch.