> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up a shared extension model

> Create a shared extension model, route users to it with user attributes, and set access.

Use this guide to create a shared extension model, route users to it with user attributes, and configure model permissions.

## Requirements

To follow the steps in this guide, you'll need:

* A shared model to use as the parent
* **Organization Admin** permissions, or **Connection Admin** permissions for the connection

To test user access with [user impersonation](https://docs.omni.co/administration/users/impersonate.md), you need **Organization Admin** permissions.

## Setting up the extension

### 1. Set the parent connection's base access to No Access

The base access role is the minimum role every user has on every model in the connection, including the parent model and each extension.

Set the base access role to **No Access** so that no one can access the parent model or its extensions until you grant access.

1. Click **Settings > Connections**.
2. Click the parent connection.
3. Click the **Permissions** tab.
4. Set **Base access role** to **No Access**.
5. Click **Save changes**.

### 2. Create the extension model

1. Click **Develop** in the [sidebar](https://docs.omni.co/administration/settings/sidebar.md).
2. Select the parent model.
3. In the model IDE, click **Model > Advanced > New shared extension**.
4. Enter a name for the extension. For example `customer_1_model`.
5. Set **Allow exploration** and **Branch workflow**:

   > **Allow exploration**
   >
   > Controls how users access the extension
   >
   > * **On** - Users can build their own workbooks or Omni Agent chats on the extension.
   > * **Off** - Users reach the extension only through routing.
   >
   > See [Allow exploration](https://docs.omni.co/modeling/develop/shared-extensions/settings.md#allow-exploration) for more information.

   > **Branch workflow**
   >
   > Controls how you develop and release the extension
   >
   > * **Develop with the parent model** (default) - The extension shares branches and Git with the parent model.
   > * **Develop independently** - The extension has its own branches. Omni doesn't include the extension in Git.
   >
   > See the [Branch workflow reference](https://docs.omni.co/modeling/develop/shared-extensions/settings.md#branch-workflow) for a detailed comparison of these workflows.
6. Click **Create**. Omni opens the new extension in the model IDE.

### 3. Create a user attribute

Create the [user attribute](https://docs.omni.co/administration/users/attributes) Omni uses to select the extension for each user.

1. Click **Settings > Attributes**.
2. Click **New Attribute**.
3. Enter a name and a reference, for example `customer_name`.
4. Assign a value to each [user](https://docs.omni.co/administration/users.md).

> [!TIP]
>
> If you provision allowed values for this attribute, users can switch their own value from the **File** menu instead of waiting for you to reassign it.
>
> Provision only values a user should see, because a switched value routes them to that extension's data. See [User-selected attribute values](https://docs.omni.co/administration/users/attributes/user-selected.md) for more information.

### 4. Map the user attribute in the parent model

1. Click **Develop** in the [sidebar](https://docs.omni.co/administration/settings/sidebar.md).

2. Open the parent model. If the parent model is linked to Git, open a [branch](https://docs.omni.co/content/develop/branch-mode.md).

3. In the model file, use [`dynamic_shared_extensions`](https://docs.omni.co/modeling/models/dynamic-shared-extensions) to map the extension to the user attribute you created in the previous step:

   **Manual mapping**

   Use [`mappings`](https://docs.omni.co/modeling/models/dynamic-shared-extensions#param-mappings) to map each attribute value to an extension:

   ```yaml title="Manual mapping" theme={null}
   dynamic_shared_extensions:
     - user_attribute: customer_name         # User attribute reference
       mappings:
         customer_1_model:                   # Extension model name
           values_for_model: [customer_1]    # User attribute values
         customer_2_model:
           values_for_model: [customer_2]
   ```

   **Programmatic mapping**

   If your extension names follow a pattern, use [`map_pattern`](https://docs.omni.co/modeling/models/dynamic-shared-extensions#param-map-pattern) to build the name from the attribute value:

   ```yaml title="Programmatic mapping" theme={null}
   dynamic_shared_extensions:
     - map_pattern: "{{omni_attributes.customer_name}}_model"
   ```

   > [!NOTE]
   >
   > Use `mappings` or `map_pattern` per extension model, not both.

4. Save the changes. If you made the changes in a branch, merge the branch.

### 5. Grant model access

A user's **Model role** controls their permission to run queries. Users also need access to the dashboard or workbook through its document or folder permissions.

Users can explore and build content using an extension through user attribute routing or by selecting it directly:

| How users use the extension | Allow exploration | Required query permissions |
| - | - | - |
| **Through user attribute routing** — Users start from the parent model. Omni layers in the mapped extension, making its topics, fields, and customizations available for exploration and content creation. The parent remains the content's base shared model. | Can be **Off** | Permission to query the **parent model**. No role is required on the mapped extension. |
| **By selecting it directly** — Users select the extension when creating a workbook or Omni Agent chat. The extension becomes the content's base model. | Must be **On** | Permission to query the **extension model**. A role on the parent alone is not sufficient. |

Model permissions can come from roles assigned to the user, their groups, or the connection. **Allow exploration** does not itself grant query permissions.

Use the connection's [**Permissions tab**](https://docs.omni.co/administration/users/permissions.md#defining-permissions-for-a-connection) to assign permissions to users and user groups.

> [!TIP]
>
> Manage user permissions at scale with the [Omni API](https://docs.omni.co/api.md) or [user groups](https://docs.omni.co/administration/users/groups.md).

### 6. Test access with user impersonation

[Impersonate a test user](https://docs.omni.co/administration/users/impersonate.md) to confirm the setup:

1. Click **Settings > Users** and select a test user. This user can't be an Organization Admin.
2. Set the user's attribute to the value for the extension you want to test.
3. At the bottom of the user's page, click **Impersonate user**.
4. Open a dashboard or workbook built on the parent model that has been shared with the test user, or create a workbook on the parent model if their role allows it.
5. Confirm that the available topics and fields reflect the mapped extension, then run a query to verify the expected results.

## Troubleshooting

> **Users see the parent model instead of their extension**
>
> Omni routes a user to an extension only when the user's attribute value matches a mapping in the parent model. If nothing matches, Omni routes the user to the parent model. Check the following:
>
> * **Attribute reference** - The `user_attribute` value in the model file must match the attribute's **Reference** in **Settings > Attributes**, for example `customer_name`. The reference is case-sensitive.
> * **Attribute value** - The user's value must appear in a `values_for_model` list, or must build an existing extension name through `map_pattern`.
> * **Extension name** - The mapping key, or the name that `map_pattern` builds, must match the extension's name exactly.

> **Users see a 'No Access' error**
>
> For content built on the parent model, confirm that the user has a role on the parent model that permits running queries. A role on the mapped extension alone does not grant permission to run queries in parent-built content.
>
> For content built directly on an extension, check the user's role on that extension.
>
> Confirm that the user, or a group they belong to, has a role on the correct model under **Model access** on the connection's **Permissions** tab.
>
> Also confirm that the dashboard or workbook has been shared with the user through document or folder permissions.

## Next steps

* [Extension settings](https://docs.omni.co/modeling/develop/shared-extensions/settings.md)
* [Branches and Git for extension models](https://docs.omni.co/modeling/develop/shared-extensions/extension-branches.md)
* [dynamic\_shared\_extensions](https://docs.omni.co/modeling/models/dynamic-shared-extensions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.