> 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/automation/runbooks/runbook-report-settings.md).

# Runbook Report Settings

Configure centralized email and storage delivery settings for reporting runbooks.

## Overview

Several RealmJoin runbooks include automated reporting capabilities to deliver reports, notifications, and alerts directly to administrators. Depending on configuration, reports can be:

* **sent via email** — using the Microsoft Graph API on behalf of a configured sender address
* **uploaded to an Azure Storage Account** — and made available as a time-limited SAS download link

Supporting both delivery channels is the intended standard for all reporting runbooks going forward. Not all reporting runbooks may support both channels yet, but the set of supported runbooks is continuously growing. Both channels can be enabled independently or in combination.

All shared settings are configured once in the [RealmJoin Runbook Customization](https://portal.realmjoin.com/settings/runbooks-customizations) and automatically apply to all runbooks that use the respective feature. Settings that differ per runbook (such as the target container name) are not part of this central configuration and are set directly in the respective runbook.

The functions that consume these settings — [`Send-RjRbReportEmail`](https://docs.realmjoin.com/dev-reference/report-functions/send-rjrbreportemail.md) and [`Publish-RjRbFilesToStorageContainer`](https://docs.realmjoin.com/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) — are provided by the **RealmJoin.RunbookHelper** PowerShell module. See [Report Functions](https://docs.realmjoin.com/dev-reference/report-functions.md) for detailed usage documentation.

## Email Delivery

### Prerequisites

We recommend using a dedicated shared mailbox, such as `realmjoin-report@contoso.com`. This mailbox will be used as the sender address for all reports. You can use a no-reply address, as recipients are not expected to respond to automated reports.

> **Note:** The sender address must be a user or shared mailbox — a Microsoft 365 group cannot send mail via the Graph API. Group addresses as report **recipients** work technically, but are not recommended: whether members actually receive the email depends on the group's follow/subscription settings, and delivery failures are only visible as non-delivery reports in the sender mailbox.

### Configuration

As described in detail in the [JSON Based Customizing](https://docs.realmjoin.com/automation/runbooks/runbook-customization#json-based-customizing) documentation, navigate to [RealmJoin Runbook Customization](https://portal.realmjoin.com/settings/runbooks-customizations) in the RealmJoin Portal (Settings > Runbook Customizations).

In the `Settings` block, add or modify the `RJReport` section to include the `EmailSender` property with your desired sender email address:

```json
{
    "Settings": {
        "RJReport": {
            "EmailSender": "realmjoin-report@contoso.com"
        }
    }
}
```

Replace `realmjoin-report@contoso.com` with your actual shared mailbox address.

### Service Desk Contact Information (optional)

This central configuration only provides the unified Service Desk values for all runbooks. Whether the contact information is actually included in a notification email is determined by the respective runbook itself — only runbooks that implement the corresponding Service Desk parameters (e.g. `ServiceDeskDisplayName`, `ServiceDeskPortalUrl`) read these values and render them in their emails.

To provide the Service Desk contact information for these runbooks, add the following properties to the `RJReport` section:

```json
{
    "Settings": {
        "RJReport": {
            "EmailSender": "realmjoin-report@contoso.com",
            "ServiceDesk_DisplayName": "IT Service Desk",
            "ServiceDesk_EMail": "servicedesk@domain.com",
            "ServiceDesk_Phone": "+49123456789",
            "ServiceDesk_PortalUrl": "https://servicedesk.domain.com"
        }
    }
}
```

**Parameters:**

* `ServiceDesk_DisplayName` — Display name of your Service Desk (e.g., "IT Support", "Help Desk")
* `ServiceDesk_EMail` — Service Desk email address (shown as a clickable `mailto:` link)
* `ServiceDesk_Phone` — Service Desk phone number in international format (shown as a clickable `tel:` link)
* `ServiceDesk_PortalUrl` — URL of your Service Desk portal or website (shown as a clickable link)

All parameters are optional. If configured, they will appear in the email footer as clickable links.

> **Note:** Some runbooks additionally accept a per-run ticket link (e.g. `ServiceDeskTicketUrl`) to reference the specific ticket that triggered the request. This is a runbook parameter, not part of this central configuration.

### Email Branding (optional)

Report emails can carry tenant-specific branding: the default RealmJoin header and footer graphics can be replaced with your own images, the footer image can link to a custom target — for example your intranet or IT portal — and the template colors can be adjusted to your corporate design.

To configure branding, add a `Branding` sub-section to the `RJReport` block (nested like `StorageAccount`):

```json
{
    "Settings": {
        "RJReport": {
            "Branding": {
                "HeaderImageUrl": "https://cdn.contoso.com/branding/email-header.png",
                "FooterImageUrl": "https://cdn.contoso.com/branding/email-footer.png",
                "FooterLink": "https://intranet.contoso.com",
                "AccentColor": "#0052cc",
                "TextColor": "#1a1a2e"
            }
        }
    }
}
```

**Parameters:**

| Setting          | Required | Default                      | Description                                                                                             |
| ---------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `HeaderImageUrl` | no       | RealmJoin header graphic     | Public HTTPS URL of a custom header image that replaces the default RealmJoin header graphic            |
| `FooterImageUrl` | no       | RealmJoin footer graphic     | Public HTTPS URL of a custom footer image that replaces the default RealmJoin footer graphic            |
| `FooterLink`     | no       | `https://www.realmjoin.com`  | URL the footer image links to                                                                           |
| `AccentColor`    | no       | `#f8842c` (RealmJoin orange) | Accent color of the email template: table header rows, action buttons, accent borders of the info boxes |
| `TextColor`      | no       | `#011e33` (RealmJoin navy)   | Primary text color of the email template: body text, headings, list items, code                         |

**Image requirements:**

* The image must be reachable via a **public HTTPS URL** — for example an Azure Blob Storage container with anonymous read access, a CDN, or the company website. A URL containing a SAS token also works and keeps the container private.
* Supported formats: **PNG, JPEG or GIF**. The format is detected from the file signature, not from the file extension.
* Images are rendered at **750 px width**. Recommended dimensions are **750×200 px** (matching the default banners) or **1500×400 px** for high-DPI displays.
* Maximum **200 KB** per image; **100 KB or less** is recommended. The branding images share the \~4 MB total email size limit with the report attachments (for comparison, the default RealmJoin graphics are 52 KB and 15 KB).

**Color requirements:**

* Values must be 6-digit hexadecimal colors including the leading `#` — for example `#0052cc`. Short forms (`#05c`) and color names (`red`) are not supported.
* Both emails and their attachments are read in light **and** dark mode: pick a text color that stays legible on a white content card, and an accent color with enough contrast against white button text.
* Status colors (green/red/amber for success, error and warning states) and the neutral grays are deliberately not configurable — they carry meaning that should not change per tenant.

The images are downloaded and validated by the runbook on each run. If a setting is left empty, the default RealmJoin graphic, color and footer link are used. If a download fails, an image is invalid, or a color is not a valid hex value, a warning is logged and the corresponding default is used instead — a broken branding configuration never prevents a report email from being sent.

All settings are optional and take effect for all runbooks that send report emails.

> **Note:** The color settings require **RealmJoin.RunbookHelper 0.8.9** or later in the Automation Account. With older module versions the image settings still apply and the colors are ignored.

## Storage Account Delivery

Reporting runbooks that support this delivery channel can upload their output to an Azure Blob Storage container. After a successful upload, the runbook returns a time-limited SAS link that can be used to download the file directly. This channel can be used independently of or in addition to email delivery.

### Prerequisites

An existing Azure Storage Account is required. The Automation Account's managed identity (or the service principal used by the runbooks) needs the built-in Azure RBAC role **Reader and Data Access**, assigned directly on the Storage Account.

The upload retrieves the storage account key via `listKeys` and uses it to create the container, upload the files and sign the SAS download links. **Reader and Data Access** is the smallest built-in role that includes this action. **Storage Account Contributor** works as well, but additionally allows managing and deleting the Storage Account. **Storage Blob Data Contributor** is not sufficient, as it does not include `listKeys`.

> **Note:** The account key grants access to all data in the Storage Account. Use a dedicated Storage Account for reports and assign the role on the Storage Account, not on its resource group. Shared key access must be allowed on the Storage Account (`allowSharedKeyAccess` must not be `false`, for example through the Azure Policy "Storage accounts should prevent shared key access"), otherwise the upload fails.

### Configuration

Navigate to [RealmJoin Runbook Customization](https://portal.realmjoin.com/settings/runbooks-customizations) and add a `StorageAccount` sub-section to the `RJReport` block:

```json
{
    "Settings": {
        "RJReport": {
            "StorageAccount": {
                "ResourceGroup": "rg-reports",
                "StorageAccountName": "stcontosoreports",
                "SubscriptionId": "00000000-0000-0000-0000-000000000000",
                "LinkExpiryDays": 6
            }
        }
    }
}
```

**Parameters:**

| Setting              | Required        | Default                          | Description                                                                                                                                     |
| -------------------- | --------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ResourceGroup`      | yes             | —                                | Resource group that contains the Storage Account                                                                                                |
| `StorageAccountName` | yes             | —                                | Name of the Azure Storage Account                                                                                                               |
| `SubscriptionId`     | no, recommended | subscription selected at sign-in | ID of the Azure subscription that contains the Storage Account, see [Subscription of the Storage Account](#subscription-of-the-storage-account) |
| `LinkExpiryDays`     | no              | `6`                              | Number of days until the generated SAS download link expires                                                                                    |

> **Note:** Settings that are specific to an individual runbook — such as the target container name or a custom blob name — are configured directly on that runbook and are intentionally not part of this central configuration. The same applies to blob-name prefixing: whether a timestamp prefix (`yyyyMMdd-HHmmss`) is prepended to the blob name to prevent overwrites is controlled by the `AddBlobNamePrefix` parameter of [`Publish-RjRbFilesToStorageContainer`](https://docs.realmjoin.com/dev-reference/report-functions/publish-rjrbfilestostoragecontainer.md) (default `$false`), which each runbook passes explicitly.

### Subscription of the Storage Account

Setting `SubscriptionId` is optional, but recommended. The runbooks sign in to Azure with the managed identity without naming a subscription, so Azure selects one of the subscriptions in which the managed identity holds a role assignment. Which one is not documented, and it is not necessarily the subscription of the Automation Account. Without `SubscriptionId`, the upload looks for the Storage Account in this selected subscription.

As long as the managed identity holds role assignments in a single subscription only, this works, even when the Storage Account is in a different subscription than the Automation Account. Once the managed identity also holds a role in another subscription, for example because other runbooks manage resources there, Azure may select that subscription instead. The upload then fails because the Storage Account is not found there. This can start at any time after such a role assignment, although nothing changed on the report runbooks or their settings.

With `SubscriptionId` set, the upload always uses the subscription that contains the Storage Account. You find the ID on the **Overview** page of the Storage Account in the Azure portal. If you use a Storage Account in another subscription for individual runbooks, set its `SubscriptionId` in that override as well, see [Use a different Storage Account for individual runbooks](#use-a-different-storage-account-for-individual-runbooks).

### Use a different Storage Account for individual runbooks

The `RJReport.StorageAccount` settings apply to all reporting runbooks. If one or more runbooks should upload to a different Storage Account or resource group, or use a different link lifetime, add an override for each of these runbooks to the `Runbooks` section of the same customization:

```json
{
    "Settings": {
        "RJReport": {
            "StorageAccount": {
                "ResourceGroup": "rg-reports",
                "StorageAccountName": "stcontosoreports",
                "SubscriptionId": "00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "Runbooks": {
        "rjgit-org_general_report-license-assignment_scheduled": {
            "Settings": {
                "RJReport": {
                    "StorageAccount": {
                        "ResourceGroup": "rg-licensing",
                        "StorageAccountName": "stcontosolicensing",
                        "LinkExpiryDays": 1
                    }
                }
            }
        }
    }
}
```

In this example, Report License Assignment (Scheduled) uploads to `stcontosolicensing` and its download links expire after one day. All other reporting runbooks keep using `stcontosoreports`.

* **Runbook name:** The key below `Runbooks` is the full runbook name, shown on the runbook's reference page under **Location** → **Full Runbook name**. It must match exactly, including upper and lower case. Add one block per runbook.
* **Inheritance:** For each setting, the runbook's own `Settings` are checked first, then the global `Settings`. Only the keys you set are overridden, all others are inherited. To shorten the link lifetime of a single runbook, `LinkExpiryDays` alone is enough. If the Storage Account is in a different resource group, always set `ResourceGroup` and `StorageAccountName` together; if it is in a different subscription, also set `SubscriptionId`.
* **Permissions:** The managed identity also needs **Reader and Data Access** on every Storage Account used in an override, as described in the prerequisites above.
* **Scheduled runs:** Settings are applied when a run is started or scheduled. Existing schedules keep the Storage Account they were created with; re-create them to use the override.
* **Container:** The container is not part of `RJReport.StorageAccount`. To change it for a single runbook, set a default for the runbook's container parameter (usually `ContainerName`) in the same block, for example `"Default": { "ContainerName": "license-reports" }`.

## Combined Example

The following snippet shows a complete `RJReport` configuration with all features enabled:

```json
{
    "Settings": {
        "RJReport": {
            "EmailSender": "realmjoin-report@contoso.com",
            "ServiceDesk_DisplayName": "IT Service Desk",
            "ServiceDesk_EMail": "servicedesk@domain.com",
            "ServiceDesk_Phone": "+49123456789",
            "ServiceDesk_PortalUrl": "https://servicedesk.domain.com",
            "Branding": {
                "HeaderImageUrl": "https://cdn.contoso.com/branding/email-header.png",
                "FooterImageUrl": "https://cdn.contoso.com/branding/email-footer.png",
                "FooterLink": "https://intranet.contoso.com",
                "AccentColor": "#0052cc",
                "TextColor": "#1a1a2e"
            },
            "StorageAccount": {
                "ResourceGroup": "rg-reports",
                "StorageAccountName": "stcontosoreports",
                "SubscriptionId": "00000000-0000-0000-0000-000000000000",
                "LinkExpiryDays": 6
            }
        }
    }
}
```

## Runbook-specific storage settings (deprecated)

Some older reporting runbooks read their Storage Account from a settings block of their own. They now also use `RJReport.StorageAccount`, but keep reading their own block so that existing configurations continue to work:

| Settings block          | Runbooks                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IntuneDevicesReport`   | [Export All Intune Devices](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/export-all-intune-devices.md), [Export All Autopilot Devices](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/export-all-autopilot-devices.md), [Export Non Compliant Devices](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/export-non-compliant-devices.md) |
| `EnrolledDevicesReport` | [Enrolled Devices Report (Scheduled)](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/enrolled-devices-report_scheduled.md)                                                                                                                                                                                                                                                                             |
| `TenantPolicyReport`    | [Export Policy Report](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/export-policy-report.md)                                                                                                                                                                                                                                                                                                         |
| `OfficeLicensingReport` | [Office365 License Report](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/office365-license-report.md)                                                                                                                                                                                                                                                                                                 |
| `CaPoliciesExport`      | [Backup Conditional Access Policies](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/security/backup-conditional-access-policies.md)                                                                                                                                                                                                                                                                            |
| `ListAdminsReport`      | [List Admin Users](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/security/list-admin-users.md)                                                                                                                                                                                                                                                                                                                |
| `InactiveDevices`       | [List Inactive Devices](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/security/list-inactive-devices.md)                                                                                                                                                                                                                                                                                                      |
| `VulnAppRegExport`      | [List Vulnerable App Regs](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/security/list-vulnerable-app-regs.md)                                                                                                                                                                                                                                                                                                |
| `EntAppsReport`         | [Export Enterprise Application Users](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/applications/export-enterprise-application-users.md)                                                                                                                                                                                                                                                                      |

The storage keys of these blocks correspond to `RJReport.StorageAccount` as follows:

| Runbook-specific key                                                      | `RJReport.StorageAccount` key                                                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ResourceGroup`                                                           | `ResourceGroup`                                                                                                                                                         |
| `StorageAccount.Name`                                                     | `StorageAccountName`                                                                                                                                                    |
| `LinkExpiryDays` (only `EntAppsReport`)                                   | `LinkExpiryDays`                                                                                                                                                        |
| `StorageAccount.Location`, `StorageAccount.Sku`                           | none: ignored, because the Storage Account is no longer created automatically                                                                                           |
| `SubscriptionId` (only `IntuneDevicesReport` and `OfficeLicensingReport`) | `SubscriptionId`                                                                                                                                                        |
| `Container`                                                               | none: set the container per runbook as described in [Use a different Storage Account for individual runbooks](#use-a-different-storage-account-for-individual-runbooks) |

Other keys in these blocks, such as `CreateLinks` or the report options of `OfficeLicensingReport`, are not affected and keep working.

### Precedence

These runbooks take the resource group and the Storage Account name from the first of these sources that provides them:

1. Values passed directly to the runbook, for example by a scheduled run, an API call or a parameter default in the runbook customization
2. The runbook-specific settings block
3. The Automation variable `SettingsExports` (only Export All Autopilot Devices, Backup Conditional Access Policies, List Inactive Devices and Export Enterprise Application Users)
4. `RJReport.StorageAccount`, including the overrides for individual runbooks

`RJReport.StorageAccount` is only used when the sources above do not provide both the resource group and the Storage Account name; it then provides both, together with its `SubscriptionId`. `RJReport.StorageAccount.LinkExpiryDays` applies in every case, except that `EntAppsReport.LinkExpiryDays` takes precedence for Export Enterprise Application Users.

### Moving to RJReport.StorageAccount

1. Configure `RJReport.StorageAccount` as described in [Storage Account Delivery](#storage-account-delivery). If a runbook used a different Storage Account than the others, add an override for that runbook, with its `SubscriptionId` if the account is in another subscription, as described in [Use a different Storage Account for individual runbooks](#use-a-different-storage-account-for-individual-runbooks).
2. Assign **Reader and Data Access** on every Storage Account to the managed identity, as described in the prerequisites of [Storage Account Delivery](#storage-account-delivery).
3. Remove the runbook-specific blocks from the customization. If a block sets `Container`, `CreateLinks` or report options you want to keep, keep only these keys, or set them as parameter defaults of the runbook.
4. Re-create the scheduled runs of these runbooks. A scheduled run keeps the values from the time it was created, including the previous Storage Account.

> **Note:** The parameters `StorageAccountLocation` and `StorageAccountSku` are deprecated and ignored. Scheduled runs created with an earlier version still pass them; these runs keep working and log a warning. A later version removes both parameters, so re-create such scheduled runs before then.


---

# 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/automation/runbooks/runbook-report-settings.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.
