# Edit dashboard setting

## What a dashboard setting is

A dashboard setting is the saved role-dashboard configuration that you customize through
tabs, widgets, imports, reports, and views.

The page provides these main actions:

| If you need to… | Go to |
|---|---|
| Find the saved dashboard-setting record | [Dashboard settings](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings) |
| Add, remove, or arrange widgets and tabs | [Customize and save the dashboard](#customize-and-save-the-dashboard) |
| Import tabs from another role dashboard | [Import tabs from another role dashboard](#import-tabs-from-another-role-dashboard) |
| Add or remove the optional report or view | [Choose the dashboard branch](#choose-the-dashboard-branch) |
| Review saved changes | [After saving the dashboard setting](#after-saving-the-dashboard-setting) |
| Learn what individual widgets mean | [Dashboard widget catalog](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-widget-catalog) |
| Use the resulting dashboard | [Dashboard overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview) |
| Read the report content | [Principal report](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/principal-report) |

The page provides **Widget**, **Tab**, **Save**, and **Save and Close** actions. The **Tab**
menu provides **Blank Tab**, **Import From**, **Principals Report**, and **Eagle View**. A
saved record also provides a **Last Modifications** tab for reviewing its history.

## Before you start

The **Dashboard settings** configuration subscription is required for this screen. Editing
actions are available when the page is in edit mode. **Last Modifications** is available
after the setting has been saved and has an ID.

| Check | What must be true | What it affects |
|---|---|---|
| Configuration access | The **Dashboard settings** configuration subscription is included. | The screen and its dashboard-library surfaces are available. |
| Edit state | The page is in edit mode. | **Widget**, **Blank Tab**, **Import From**, **Principals Report**, **Eagle View**, **Save**, and **Save and Close** are editing actions. |
| Saved-record state | The dashboard setting has an ID. | **Last Modifications** is available. |
| Import state | Another role dashboard has been selected in the import popup. | **Select tab(s)** and the source-tab checkboxes appear. |

No product-enforced approver is specified before saving or deleting a dashboard-setting
record.

> **Note:** The dashboard library shows its tabs and widget areas according to the
> subscription, active tab, and widget conditions.

With these conditions in place, open the saved record from the **Dashboard settings** list.

## Find and open a dashboard setting

Prerequisites

- The **Dashboard settings** configuration subscription is included.
- You have a saved dashboard setting to customize.

Steps

1. Open the **Dashboard settings** list from the configuration navigation.
2. Select the row for the dashboard setting you want to customize.
3. Select the row's edit action if the list presents one.

The selected saved dashboard setting opens for editing. Continue by identifying the controls
and dashboard-library areas on the edit screen.

**Result:** The selected saved dashboard setting opens for editing.

## Understand the dashboard-setting screen

The dashboard-setting screen is the library for one saved role-dashboard configuration. Its
tabs and widget areas change according to the available subscription, the active tab, and the
widget conditions.

On this screen, you can select **Widget**, **Tab**, **Save**, or **Save and Close**. You can
also select Sort by Booking, Sort by Target, or Sort by Achievement.

Select **Tab** to reach the tab actions. The menu includes **Blank Tab**, **Import From**,
**Principals Report**, and **Eagle View** when their edit conditions allow them.

![The Tab menu with tab creation, import, report, and view choices](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/36244083d9144359c4a8523b87495dc7.png)

On a saved record, select **Last Modifications** to open the saved-record history surface.

## Customize and save the dashboard

Use this procedure to change the tabs or widgets in an existing dashboard setting and commit
those changes.

Prerequisites

- You opened an existing saved dashboard setting from the **Dashboard settings** list.
- The page is in edit mode.
- The dashboard library has an active tab that meets the action's conditions.

Steps

1. In an active user-dashboard tab with widgets, select **Widget** to open the widget-add
   preparation.
2. In the **Tab** menu, select **Blank Tab** to open the blank-tab preparation.
3. In the tab actions for an editable user-dashboard or MRM report tab, select **Rename tab**.
4. In the tab rename dialog, enter a value in **New Tab**.
5. In the tab actions for an active editable tab, select **Delete tab** when the tab dropdown
   is available.
6. In an active tab with widgets, select **Remove widget from tab** to select or remove a
   widget.
7. In the widget-selection dialog, select **Select all** to select every widget.
8. Select **Save** to save the dashboard setting and keep this page open.
9. Select **Save and Close** to save the dashboard setting and leave the edit page.

After a successful dashboard and modification-log save, the message is
`Your request was completed successfully`.

**Result:** **Save** keeps the edit page open, while **Save and Close** leaves the page after
the save action.

![The widget-selection surface opened from Widget](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/a2c96bca15790eb08cd24e819f09964a.png)

The optional report and view tabs are controlled from the same **Tab** menu.

## Choose the dashboard branch

The dashboard branches are optional tabs for report and view work. They are available while
the page is in edit mode, and selecting each action toggles its corresponding tab.

| If you need to… | Select |
|---|---|
| Add or remove the principals report tab | **Principals Report** |
| Add or remove the Eagle View tab | **Eagle View** |

The report's column sets are built from runtime selections, so the available columns depend on
the selections made for that report.

If no principal or client is selected when the report is generated, the message is
`Please choose one or more principals`.

If you need to reuse tabs from another saved role dashboard, continue with **Import From**.

### Import tabs from another role dashboard

Prerequisites

- The page is in edit mode.
- Another role dashboard has saved dashboard data.
- The source dashboard is different from the current record.

Steps

1. In the **Tab** menu, select **Import From**.
2. In the import popup, open **Another role dashboards**.
3. Select a source dashboard whose saved dashboard data is non-empty and whose ID differs from
   the current record.
4. Review **Select tab(s)** after the source dashboard is selected.
5. Select one checkbox for each source tab to import.
6. If the control is available, select **All (Replace existing tabs)** to select or clear all
   source tabs for replacement.
7. Select the popup's **OK** action to apply the import choice.

![The import popup with the source-dashboard and tab-selection controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/920cd67907c57ec935022ac0d5485d5f.png)

To close the import popup without applying the choice, select **Cancel**.

**Result:** The selected source tabs are prepared for import, or the import popup closes
without applying a choice when you select **Cancel**.

### Choose custom-dashboard options

Use the option that matches the active dashboard surface:

| Option | Available when |
|---|---|
| **Rename tab** | The active tab is an editable user-dashboard or MRM report tab, its dropdown is available, and the page is in edit mode. |
| **Delete tab** | The active tab's dropdown is available and the page is in edit mode. |
| **Remove widget from tab** | The active tab contains widgets; removal additionally requires edit mode. |
| **Widget** | A dashboard tab exists, the dashboard contains at least one tab, the active tab is a user dashboard, and the widget conditions allow the surface. |

Widget-specific surfaces depend on the subscription and widget conditions.

## When saving or loading goes wrong

Use the message on screen to choose the recovery path below.

| What you see or encounter | What to do |
|---|---|
| `An error occurred while processing your request` while saving or loading the dashboard | Review the dashboard changes and repeat the save or reload action from the dashboard screen. |
| `You already have this tab in this dashboard` while importing | Remove the duplicate special tab from the import choice, then continue with the remaining tabs. |
| The exit popup opens after you changed dashboard tabs | In the exit popup, select **Don't Save**, **Save**, or **Cancel**, depending on the outcome you want. |
| A dashboard choice, source-tab choice, saved value, or principal-report column is not available | Continue with the choices visible on your screen; these values depend on the dashboard data and runtime selections. |

The exit popup opens after you change dashboard tabs, when they differ from their original
copy. Choose one outcome:

| Select | Outcome |
|---|---|
| **Don't Save** | Leaves without saving. |
| **Save** | Saves and closes. |
| **Cancel** | Closes the popup without applying the exit choice. |

**Result:** You leave without saving, save and close, or close the popup without applying the
exit choice.

## After saving the dashboard setting

On a saved record, **Last Modifications** is the history area for the record's saved changes.
Use **Save and Close** when you want to leave the edit page.

The edit flow does not establish a stage or status change. Widget-specific meanings and the
work of using the resulting dashboard belong to [Dashboard widget catalog](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-widget-catalog)
and [Dashboard overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview). The report's reader-facing content belongs
to [Principal report](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/principal-report).

**Result:** The saved dashboard setting is available for review through **Last Modifications**,
and the edit page is closed when you use **Save and Close**.
