# New dashboard setting

Use this page to create a role dashboard from tabs, widgets, and optional report views.

## What a new dashboard setting is

A new dashboard setting is the configuration work used to assemble a role dashboard from
tabs, widgets, and optional report views. You build it from the **Configuration Dashboard**
page.

Use the sections below according to what you need to do:

| If you need to… | Go to |
|---|---|
| Check what must be available before you configure the setting | [Before you start](#before-you-start) |
| Open the new-record editor | [Open a new dashboard setting](#open-a-new-dashboard-setting) |
| Learn what the editor controls do | [Understand the editor](#understand-the-editor) |
| Add a blank tab and choose its widgets | [Add a tab and its widgets](#add-a-tab-and-its-widgets) |
| Add an imported or report tab | [Choose the tab variation](#choose-the-tab-variation) |
| Save the setting | [Save the dashboard setting](#save-the-dashboard-setting) |
| Resolve a duplicate tab or request error | [When the task does not complete](#when-the-task-does-not-complete) |
| Review the dashboard after saving | [After saving](#after-saving) |
| Open the dashboard list | [Dashboard settings](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings) |
| Maintain an existing setting | [Edit dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-edit-record) |

![The new dashboard-setting editor with its toolbar visible](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/5a75fb7ee5bd054762a3a41535636f02.png)

## Before you start

The dashboard library and its editing actions depend on your subscription, edit mode, the
tabs available to your role, and whether the setting is saved.

| Check | What it controls |
|---|---|
| Dashboard subscription | The dashboard tabs render when the subscription includes the dashboard library. Otherwise, the dashboard area shows the upgrade surface. |
| Edit mode | **Widget**, **Blank Tab**, **Import From**, **Principals Report**, **Eagle View**, **Save**, and **Save and Close** require edit mode. |
| Dashboard tab and available widgets | **Widget** is available only when a dashboard tab exists, widgets are available, and the active tab is a user dashboard. |
| Active tab | Widget work belongs on a user dashboard. **Principals Report** and **Eagle View** show their own content when active. |
| Saved record | **Last Modifications** is available for a saved dashboard setting. |

On arrival, **Widget** was disabled. The editor does not add a product-enforced approval step
before saving or deleting a dashboard setting.

**Prerequisites**

- Have access to the **Configuration Dashboard** page.
- Open the setting in edit mode when you need to add tabs, choose widgets, or save.
- Have a dashboard subscription when you need the dashboard library rather than its upgrade surface.

After these checks, open the new-setting editor.

## Open a new dashboard setting

Open the new-record route when you want to start assembling a dashboard setting rather than
maintain an existing one.

**Prerequisites**

- Complete the checks in [Before you start](#before-you-start).

**Steps**

1. Open the **Configuration Dashboard** page.
2. Confirm that the page text **Configuration Dashboard** appears.
3. Identify **Widget**, **Tab**, **Save**, and **Save and Close**.

![The Configuration Dashboard toolbar on the new-setting route](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/5a75fb7ee5bd054762a3a41535636f02.png)

**Result:** You are on the new-setting page and can begin configuring the setting.

Next, use the editor controls to choose a tab type or modify the active tab.

## Understand the editor

The editor combines a top toolbar, a menu for adding tab variations, an active-tab menu, and
dashboard content. The active tab determines whether you work with user-dashboard widgets, a
Principals Report, or an Eagle View.

| Control or surface | Use |
|---|---|
| **Widget** | Open the widget chooser when an editable user dashboard has available widgets. |
| **Tab** | Open the tab-variation menu. |
| **Blank Tab** | Open the Add new tab flow. |
| **Import From** | Open dashboard import. |
| **Principals Report** | Add or remove the Principals Report tab. |
| **Eagle View** | Add or remove the Eagle View tab. |
| **Last Modifications** | Open the audit-log area for a saved dashboard setting. |
| **Rename tab** | Open tab-name editing from the active tab menu. |
| **Delete tab** | Open tab deletion from the active tab menu. |
| **Search for widget** | Filter widgets in the active tab menu. |

If the subscription does not include the dashboard library, the dashboard tabs are replaced by
the upgrade surface. On a user dashboard, **Search for widget**, **Select all**, and **Remove
widget from tab** belong to widget selection; report tabs show their own controls.

Choose the tab type that matches the content you need.

## Add a tab and its widgets

Use a blank tab when you want to name a tab yourself and choose its widgets.

**Prerequisites**

- Be in edit mode.
- Have a dashboard tab available for widget work.

**Steps**

1. Open the **Tab** menu.
2. Select **Blank Tab**.

   The **Add new tab** dialog opens with the required **New Tab** field and an **OK** button.

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

   If the field is empty, the dialog shows `This Field Is Required`. If the name already exists,
   it shows `You already have this tab in this dashboard`.

5. Open the active tab menu.
6. Enter a search term in **Search for widget**.
7. Select **Select all** to select all available widgets.
8. Select **Remove widget from tab** for a widget you want to remove.

![The Add new tab dialog with New Tab and OK](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/49fb013e081ed0a6173b89468e97f502.png)

**Result:** The tab has a name, and its widgets are selected or removed in the active-tab menu.

Continue with another tab variation or save the setting.

## Choose the tab variation

The **Tab** menu offers four ways to add dashboard content. Choose the variation that matches
the source or report view you need.

| If you need to… | Select | What opens |
|---|---|---|
| Create and name a tab yourself | **Blank Tab** | The **Add new tab** dialog with **New Tab** and **OK** |
| Copy tabs from another role dashboard | **Import From** | The **Import dashboard** dialog with **Another role dashboards** and **Select tab(s)** |
| Add the principals report view | **Principals Report** | **Report**, **Generate Report**, and **Download as PDF** |
| Add the vendor-analysis view | **Eagle View** | Vendor-analysis controls and report choices |

For **Import From**, select a source in **Another role dashboards**. After a source is selected,
the controls for **Select tab(s)** and all-tab import become available.

For **Principals Report**, use **Report** before selecting a report action. If the operation
requires principals and none are selected, the message is `Please choose one or more principals`.

For **Eagle View**, the visible report choices are **Inquiries (Count)**, **Inquiries (Value)**,
**Offers (Count)**, **Offers (Value)**, **Orders (Count)**, **Orders (Value)**, **Lost Orders
(Count)**, **Lost Orders (Value)**, **Hit rate (%)**, and **visits Count**.

![The Import dashboard dialog with source-dashboard and tab-selection controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/2dfa7175aad2c8ecaeb3eaccd5aa54b7.png)

![The Principals Report tab and its report controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7afb3626023ecaf2ea54899ea5d3fa0d.png)

![The Eagle View tab with vendor-analysis and report choices](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/fa83614c10ba514fdad758c3c440e9e9.png)

**Result:** The selected tab variation is open with its controls ready for the next choice.

Save when the tab configuration is complete.

## Save the dashboard setting

Choose the save action that matches whether you need to continue editing.

**Prerequisites**

- Complete the tab and widget choices you want to keep.
- Be in edit mode.
- Resolve any unsaved-change prompt before leaving.

**Steps**

1. Choose one save action:

   | Select | Outcome |
   |---|---|
   | **Save** | Save the setting and remain in the editor. |
   | **Save and Close** | Save the setting and leave the editor. |

2. If a completion or exit popup opens, choose the outcome you need:

   | Select | Outcome |
   |---|---|
   | **Save** | Save the setting. |
   | **Don't Save** | Leave without saving the changes. |
   | **Cancel** | Close the popup and keep the editor open. |

The success message is `Your request was completed successfully`. A request error is reported
as `An error occurred while processing your request`.

![The Save action on the new dashboard-setting editor](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/dd2c193ea6f22ededd72d8c7daf27db9.png)

![The Save and Close action on the new dashboard-setting editor](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/dd2c193ea6f22ededd72d8c7daf27db9.png)

**Result:** **Save** keeps the editor available; **Save and Close** leaves the editor.

If the task does not complete, use the exact message to return to the relevant field or choice.

## When the task does not complete

| What you see | What it means | What to do |
|---|---|---|
| `This Field Is Required` | **New Tab** has no value. | Enter a tab name in **New Tab**, then select **OK**. |
| `You already have this tab in this dashboard` | The tab name is already used. | Enter a different name in **New Tab**, then select **OK**. |
| `An error occurred while processing your request` | The request did not complete. | Review the tab, widget, or report choice and submit the action again. |
| `Please choose one or more principals` | A Principals Report operation needs principals. | Return to report selection and choose principals before generating the report. |

After correcting the choice, return to [Save the dashboard setting](#save-the-dashboard-setting).

## Out of scope

This page covers the dashboard-setting editor. For widget details, use Dashboard widget
catalog. For dashboard use, use Dashboard overview.

## After saving

After saving, use **Last Modifications** to review the saved record's audit-log area when it is
available.

**Steps**

1. Open **Last Modifications** when it is available.
2. Open [Dashboard settings](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings) when you need the list.
3. Open [Edit dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-edit-record) when you
   need to maintain the saved setting.

**Result:** You can review the saved record or continue maintaining dashboard settings.
