# Realms
{% hint style="info" %}
**Realms** are only available on ClearXP Enterprise plans. Contact your customer support representative if you require access to this feature.
{% endhint %}
### Overview
A **realm** is a sandboxed sub-instance of the ClearXP platform. All data and content is self-contained, creating a logical separation between realm instances with the ability to move data and content between realms using *cross-realm publishing*.
Realms are great use case for the following:
* **Separating business units, brands, or client groups**\
For example, one realm per franchise, region, subsidiary or external customer, so each group only sees the content and learners that belong to them.
* **“Staging” or “sandbox” realms for content development** \
Build and test programs in a private realm, then publish the finished content into your main learner-facing realm when ready.
{% hint style="warning" %}
**When to use Realms**
Many aspects of realms can be replicated with tight *Role-Based Access Controls* (RBAC). It's entirely possible to restrict visibility over users, content and data based on a rigorous permissioning scheme. However, a misconfiguration or human error can result in people gaining access to the wrong data.
Because realms data is logically separated, we recommend using **Realms** when you want an extra layer of assurance. Typically best when used with external third-parties, completley distinct business units, etc.
{% endhint %}
#### The Live Realm
Every organisation has a realm called *Live*. This is the default realm: when someone logs in without picking a specific realm, they land here. The Live realm is where most organisations keep the content their real learners interact with day-to-day.
It can't be deleted and can be considered the "master realm" for all other realms.
#### What's shared between Realms
Most data and content is completely isolated between realms but there are a few caveats. Review the below table to see what's shared and what isn't.
| Resource | Shared / Separate |
| ---------------------------------- | ----------------- |
| **Authentication** (login details) | Shared |
| **Users** | Separate |
| **Activities** | Separate |
| **Activity Content** | Shared |
| **Enrolments** | Separate |
| **Workflows** | Separate |
| **Notifications** | Separate |
| **Data and Reports** | Separate |
| **Roles / Permissions** | Separate |
| **Configuration** | Inherited\* |
The below highlights the behaviour for resources that are shared:
* **Authentication**: For ease of access, users that can access multiple realms will only have a single username and password for all of them. If they reset the password in one realm, it resets everywhere.
* **Activity Content**: While activities are sandboxed between realms, the actual raw static assets they represent (i.e. SCORM packages, PDFs, media, etc.) are stored in a single shared Content Delivery Network (CDN). This means when an activity is published across realms, we don't need to make a copy of all its assets in both locations.
* **Configuration:** Most notably, realm configuration is *inherited* from the **Live** realm. This eases management because things like branding and attribute configuration will automatically flow through to all other realms. Each realm can completely override configuration if required.
### Switching Realms
Use the **Realm Switcher** in the top bar of the Admin Portal to move between realms. The accent colour next to each realm name in the switcher is set when the realm is created and is the simplest way to tell, at a glance, which realm you’re working in.
When you switch realms, the entire Admin Portal will reload to reflect the resources and permissions you have in the destination realm.
### Publishing across Realms
For an admin to be able to publish to another realm, the following must be true:
* Their user profile must exist in both realms.
* They must have the **Publish** permission for the given resource in the *destination realm*.
{% hint style="info" %}
To grant access to Publish permissions, switch to the destination realm and then create a role with the desired Publish Access Level.
{% endhint %}
In the above example, the **Training Administrator** has access to:
* View but not edit **Activities** in Sandbox.
* Edit **User Groups** in Sandbox.
* Publish **Enrolments** from another realm into Sandbox.
#### Users / Groups / Enrolments
Most resources are atomic and publishing to a realm simply copies their data across directly. To publish any resource, simply look for the green, rocket icon at the bottom-right of the resource screen.
Clicking this **Publish** button will popup a realm selection allowing you to specify which realm to publish to:
Publishing is triggered immediately but may take a couple of minutes to run (depending on existing platform workloads). Wait a minute or two then check the destination realm to confirm publishing has completed.
#### Activities
Unlike other resources, activities can have many associated resources that also need to be transferred to the destination realm, which can result in a *cascading publish*. The below table outlines what will and won't be included when an activity is published.
| Resource | Included in Publish |
| ---------------------- | ------------------- |
| **Activity Metadata** | Yes |
| **CMS Content** | Yes |
| **CMS Template** | No |
| **Activity Resources** | Yes |
| **Activity Workflows** | Yes |
| **Activity Hierarchy** | Opt-In |
| **Linked Activities** | No |
#### Cascading Publish
When publishing an activity, ClearXP will also transfer data and content we consider "safe" to publish without risking unintentional overwrites. Internally this is referred to as a *cascading publish*.
Most things attached directly to the activity (i.e. metadata, CMS content and workflows) are safe to publish because they're self-contained. However, the content itself may include references or links to activities that don't directly belong to the activity being published - in this case we can't guarantee those activities are intended to be published (they may have been updated in the destination realm already).
When it comes to activity references inside content, we have a clear distinction for what's included and what isn't:
* Activities included under the **Resources** tab of the activity being published, will also be published (including their metadata, CMS content and resources which can cause further cascading).
* Activities linked or referenced in CMS content but **do not** exist under the **Resources** tab **will not** be published.
{% hint style="info" %}
We recommend ensuring activities are fully self-contained by listing them under the **Resources** tab. Only link to activities at a platform-wide level if they are truly distinct from the content you're building.
{% endhint %}
#### Hierarchies
Similar to linked activities, it's difficult for ClearXP to determine if the children in a hierarchy are intended for publish. Often hierarchies are used to build pathways of existing modules and these modules are managed distinct to the hierarchy itself.
However, in many cases it does make sense to publish the children of a hierarchy at the same time so the publish dialog lists the full hierarchy tree and requests the publisher to confirm which they would also like to publish.
We recommend reviewing this list carefully and only selecting activities you know are safe to publish. Alternatively, if the children are already listed under the **Resources** tab (as described in [Cascading Publish](#cascading-publish)) then they will be published automatically anyway.
### Content Development: Best Practices
When using realms to build content, there are two important risks to be aware of:
1. **Diverging Versions** - when content is changed in two different realms resulting in irreconcilable differences.
2. **Decentralisation** - when content links to many different activities or assets at a platform-wide level meaning the activity isn't self-contained.
#### Diverging Versions
Because realms keep copies of activities, editing the same activity in different realms can cause them to *diverge*. In some cases this is desirable (i.e. when using realms for different business units) but it can also result in irreconcilable differences.
Unfortunately ClearXP doesn't have a "merge" function so when publishing, any changes from the source realm will always fully overwrite changes in the destination realm.
We recommend managing this risk via a strict process:
1. When starting development, publish any existing content from *Live* to your development realm.
2. Treat your development realm as the **source of truth** for all future changes. You can lock editing in the *Live* realm through [Label Permissions](/activities/organising-activities.md#controlling-label-permissions).
3. When ready, publish from your development realm to *Live*.
If in doubt about the possibility of divergence, you can always check the content's **Version History** to see if changes have been made prior to publish.
{% hint style="success" %}
To keep your content in sync, we recommend using one realm as the **source of truth** for a given piece of content.
{% endhint %}
#### Decentralisation
A CMS page may include many different media assets (such as videos/images) as well as links to other activities and resources. Publishing this activity to another realm may require publishing all media and activity links to the destination realm as well. If the activity isn't self contained, this can result in broken links.
This is best prevented by including related assets and activities within the **Resources** tab of the overarching activity. Follow the below rules to ensure activities are automatically included as **Resources** and will therefore be published automatically.
***
**1. Add/Upload activities from the Resource tab**
Instead of loading assets or activities from the primary **Manage Content** > **Activities** screen, first navigate to your primary activity and upload from the **Resources** tab instead.
**Resources** supports all the same functionality as platform-wide activities (you can filter or organise activities through labels) but ensures everything is fully self-contained.
***
**2. Upload assets from the CMS editor**
When you upload assets inside the CMS editor, these will automatically be added to the **Resources** tab for that activity. Note that embedding or linking to an existing activity **does not** include it as a resource by default.
You'll then be able to find these assets under the **Resources** tab for the activity.
***
{% hint style="info" %}
Our recommendation is to keep activities as self-contained as possible through liberal use of **Resources**. Only truly platform-wide activities should be managed from the **Activities** screen.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.clearxp.com/activities/realms.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.