> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/administration-and-settings/app-categories.md).

# App Categories

Manage the app categories of a tenant in RealmJoin Portal and use them to group packages in the RealmJoin Tray and in the Intune Company Portal.

App categories determine under which heading end users see a package. RealmJoin Portal keeps one category list per tenant and uses it for both deployment methods:

* **RealmJoin deployment:** the category is the package's **Group name**. The [RealmJoin Tray](https://docs.realmjoin.com/realmjoin-agent/client-menu/realmjoin-tray.md) menu lists the package under this group, and the **Category** filter of the [App Catalog](https://docs.realmjoin.com/realmjoin-agent/client-menu/self-service-portal.md#app-catalog-tab) filters by it. Each package has exactly one group name; in the tray menu, packages without one appear under **Other**.
* **Intune deployment:** the categories are Intune app categories (`mobileAppCategory` in Microsoft Graph) assigned to the app. The Company Portal uses them to filter apps. An Intune app can have several categories.

You manage the list under **Settings** > **App Categories**.

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-e58b4e4a5a59b096b7a3015b5ff742c91ce3332a%2Fsettings-app-categories.png?alt=media" alt="App Categories tab in the RealmJoin Portal settings with New Category, Rename and Delete buttons"><figcaption><p>App Categories tab</p></figcaption></figure>

## Where the list comes from

The list is the union of the categories stored for the tenant in RealmJoin and all app categories in the tenant's Intune, compared case-insensitively. A category created directly in Intune therefore appears here as well.

If no categories are stored for the tenant yet, RealmJoin Portal fills the list the first time it is loaded, from:

* the group names of the tenant's RealmJoin packages,
* the Package Store categories (only if the tenant already has RealmJoin packages),
* the app categories in Intune.

{% hint style="info" %}
Intune app categories are read and written with the Graph permission `DeviceManagementApps.ReadWrite.All`. Without it, the list contains only the categories stored in RealmJoin and deleting a category fails. Renaming needs the permission when Intune deployment is enabled for the tenant.
{% endhint %}

## Add a category

{% stepper %}
{% step %}

### Open the list

Go to **Settings** > **App Categories**.
{% endstep %}

{% step %}

### Create the category

Select **New Category**, enter a name (up to 127 characters) and select **Submit**.
{% endstep %}
{% endstepper %}

Names are compared case-insensitively: you cannot add a category that differs from an existing one only in upper and lower case.

A new category is stored in RealmJoin only. The matching Intune app category is created the first time the category is assigned to an Intune app.

## Rename a category

Select **Rename** next to the category, enter the new name and select **Submit**. RealmJoin Portal changes the name in this order:

1. The matching Intune app category, if Intune deployment is enabled for the tenant. Intune apps reference the category by ID, so their category assignments stay intact.
2. The group name of every RealmJoin package that uses the category.
3. The category list stored in RealmJoin.

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-1d7190cd18b3673653566fb6f0b17ee23a84df42%2Fapp-categories-rename.png?alt=media" alt="Rename Category dialog"><figcaption><p>Rename Category dialog</p></figcaption></figure>

The three stores are not updated in one transaction. If a step fails, the old name stays in the list; renaming it again completes the remaining steps.

The rename is refused if a category with the new name already exists, or if the category is a built-in Intune category (one of the defaults Intune creates, which cannot be changed). Every rename is written to the [Audit Log](https://docs.realmjoin.com/monitoring-and-logs/audit-log.md) together with the number of RealmJoin packages changed.

## Delete a category

Select **Delete** next to the category and confirm with **Confirm Delete**. The category is removed from the list stored in RealmJoin and, if it exists there, from Intune.

A category can only be deleted while no package uses it. The deletion is refused if

* a RealmJoin package uses the category as its group name, or
* an Intune app has the category assigned, or
* the category is a built-in Intune category.

If a package still uses the category, the message names the first package found. Assign a different category to all packages that use it before deleting it, or [rename](#rename-a-category) the category instead.

## Assign categories to packages

### When subscribing to a package

When you subscribe to a package from the [Package Store](https://docs.realmjoin.com/application-management/packages/package-store/package-store-details.md#app-categories), the subscription dialog lets you pick from the category list:

* **RealmJoin deployment:** select one **Group name**.
* **Intune deployment:** select one or more **Categories**.

### For an existing package

Open the [package details](https://docs.realmjoin.com/application-management/packages/package-details.md) and select **Expert settings**:

* **RealmJoin package:** choose the **Group name**. See [Expert Settings](https://docs.realmjoin.com/application-management/packages/package-settings.md#expert-settings) for the other settings in this dialog.
* **Intune app:** add or remove **Categories**. A selected category that does not exist in Intune yet is created there when you save.

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-784d96e77fd5f8be8ae0e2928147eb5fadbd2389%2Fapp-categories-group-name.png?alt=media" alt="Group name field in the expert settings of a RealmJoin package"><figcaption><p>Group name of a RealmJoin package</p></figcaption></figure>

<figure><img src="https://2868468309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-61a60d58944df5bda46022e077cd3a1b9f0bbfff%2Fapp-categories-intune-expert-settings.png?alt=media" alt="Categories field in the expert settings of an Intune app"><figcaption><p>Categories of an Intune app</p></figcaption></figure>

## Permissions

| Action                                    | Permission                                                                                                                                       | Pre-defined roles     |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| View the category list                    | [`CanReadAppCategories`](https://docs.realmjoin.com/administration-and-settings/permission/custom-roles/available-permissions.md#app-categories) | Admin, Auditor        |
| Add, rename and delete categories         | [`CanEditAppCategories`](https://docs.realmjoin.com/administration-and-settings/permission/custom-roles/available-permissions.md#app-categories) | Admin                 |
| Change the categories of a single package | [`CanEditAppExpertSettings`](https://docs.realmjoin.com/administration-and-settings/permission/custom-roles/available-permissions.md)            | Admin, Software Agent |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/administration-and-settings/app-categories.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
