# New dashboard setting

## What a new dashboard setting is

A dashboard setting is the saved arrangement of dashboard tabs and widgets that you create for a
dashboard. Use this page when you need to create that arrangement rather than change an existing
setting. The editor records the tabs and widgets, then records the changes under **Last Modifications**
after a successful save.

| If you need to… | Go to |
|---|---|
| Open the list of saved dashboard settings | Dashboard settings |
| Create a setting | [Before you start](#before-you-start), then [Open a new dashboard setting](#open-a-new-dashboard-setting) |
| Change a saved setting | Edit dashboard setting |
| Use the finished dashboard | Dashboard overview |

## Before you start

The editor protects unsaved changes when you leave it.

Prerequisites

- You are signed in to PAMS.
- You have the dashboard-setting route available in Configuration.
- You know the tabs and widgets that the dashboard needs.

The editor starts in editing mode. The available editor controls are **Widget**, **Tab**, **Save**,
and **Save and Close**. The saved-record history area appears after the dashboard has been saved.

## Open a new dashboard setting

Use the **Dashboard settings** entry in Configuration when you want to create a new dashboard-setting
record.

Prerequisites

- You are signed in to PAMS.

Steps

1. Open **Dashboard settings** from the Configuration menu.
2. Open the new-setting route at `/configuration/dashboard-settings/new`.

![Look at the editor controls available on the new dashboard-setting screen.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/bec5e08092ff44e073ddd9a2f6236541.png)

**Result:** The dashboard-setting editor opens at `/configuration/dashboard-settings/new` with
**Widget**, **Tab**, **Save**, and **Save and Close** available.

## Understand the editor

The editor combines the dashboard tabs, the active tab, and the controls for saving the setting. It
also provides a **Last Modifications** area for a saved dashboard.

**Widget** is available for the active user-dashboard tab. It is disabled when there are no dashboard
tabs or when the active tab is not a user dashboard. The tab options menu is available for the active
tab when its tab settings allow the menu.

The top controls are:

| If you need to… | Select |
|---|---|
| Add a widget to the active user-dashboard tab | **Widget** |
| Add or choose a dashboard tab | **Tab** |
| Store the setting and remain in the editor | **Save** |
| Store the setting and leave the editor | **Save and Close** |
| Rename the active tab | **Rename tab** |
| Remove the active tab | **Delete tab** |

The active tab area changes with the tab you select. When the active tab contains widgets and is a user
dashboard or MRM report, its tab menu provides a **Content:** area and **Search for widget**. The
**Last Modifications** tab and its history appear after the dashboard has been saved.

## Add a tab and its widgets

A blank tab is a user-dashboard tab that you name before adding its widgets.

Prerequisites

- The new dashboard-setting editor is open.
- The **Tab** menu is available.

Steps

1. Select **Tab**.
2. Select **Blank Tab**.

![Look at the choices in the open tab menu.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/946b27c58c1cca82714bc95a7cabc9c9.png)

3. Enter a name in **New Tab**.
4. Select **OK**.
5. Select **Widget**.

The widget selection applies to the active user-dashboard tab. When the tab contains widgets, use
**Search for widget** in its **Content:** menu to find a widget by title.

If you leave **New Tab** empty, the form displays `This Field Is Required`.

![Look at the required marker on **New Tab** and the **OK** button in the blank-tab dialog.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/5b694392a35487a925caa022a07ace44.png)

**Result:** A named dashboard tab is available for widget selection, or the blank-tab dialog remains
open until **New Tab** contains a value.

## Choose the tab variation

The **Tab** menu offers a blank tab, two special dashboard tabs, and an import path. Choose the path
that matches the dashboard you are building.

Prerequisites

- The new dashboard-setting editor is open.
- The **Tab** menu is available.

Steps

1. Select **Tab**.
2. Choose one option from the table.

| If you need to… | Select |
|---|---|
| Create a user-dashboard tab that you name yourself | **Blank Tab** |
| Add the principals report tab | **Principals Report** |
| Add the Eagle View tab | **Eagle View** |
| Bring tabs from another dashboard role | **Import From** |

3. If you selected **Import From**, choose a dashboard in **Another role dashboards**.
4. Select the tabs to bring across in **Select tab(s)**.
5. Select **All (Replace existing tabs)** when you want the imported tabs to replace the current
   tabs.

After the selected source dashboard has tabs, the tab-selection checkboxes appear.

**Result:** The selected tab variation is added to the dashboard editor when that path completes.

## Save the dashboard setting

Saving stores the dashboard tabs and widgets as one dashboard setting and records the changes in its
modification history.

Prerequisites

- You have added the tabs and widgets that the setting needs.
- The editor is open and **Save** is available.

Steps

1. Select the control shown in the table for the outcome you need.

| If you need to… | Select |
|---|---|
| Remain in the editor | **Save** |
| Leave the editor | **Save and Close** |

The save operation counts the dashboard tabs and widgets, stores the dashboard arrangement, saves the
dashboard, and then saves the modification log. A successful modification-log save displays
`Your request was completed successfully`. **Save and Close** then leaves the page.

**Result:** The dashboard setting is stored; **Save** leaves you in the editor, while **Save and
Close** leaves the page after the modification log is saved.

## When the task does not complete

Use the message on screen to choose the next action.

| Message | What to do |
|---|---|
| `This Field Is Required` | Enter a value in **New Tab**, then select **OK** again. |
| `You already have this tab in this dashboard` | Return to the tab choices and keep one instance of the special tab. |
| `An error occurred while processing your request` | Return to the action you were taking and retry it from the editor. |
| `Are you sure you want to ultimately delete this tab and all it's content ?` | Select **Delete** to remove the tab and its content, or **Cancel** to close the confirmation menu. |

## Out of scope

| Message | Owning page |
|---|---|
| `Please choose one or more principals` | Principals report |

## After saving

Use the Dashboard settings list to review the saved record and open the edit surface when you need to
change it. Use Dashboard overview for the dashboard itself and its widgets.

**Result:** You know where to review or edit the setting and where to continue using its tabs and
widgets.