# Dashboard settings

Use Dashboard settings to review role dashboards, maintain their tabs and widgets, and review
forecast rules.

## Dashboard settings at a glance

Dashboard settings are the configuration records used to organise role dashboards and forecast
rules. A role dashboard is the saved dashboard configuration that you maintain through its tabs,
widgets, imports, reports, and view actions.

The Dashboard settings screen is available with the Dashboard settings configuration subscription.
The list uses **Role**, **Tabs**, **Widgets**, **Users**, and **Last modified**.
A dashboard setting record supports tabs, widgets, imports, saved changes, and forecast rules.

| If you need to… | Go to |
|---|---|
| Check the subscription, access, and record conditions first | [Before you begin](#before-you-begin) |
| Open the list, forecast rules, or a role dashboard | [Find and open a dashboard setting](#find-and-open-a-dashboard-setting) |
| Read the list columns and maintenance actions | [Understand the dashboard settings list](#understand-the-dashboard-settings-list) |
| Review or save forecast calculation choices | [Open the forecast rules](#open-the-forecast-rules) |
| Diagnose a missing action or import choice | [When a dashboard setting is unavailable](#when-a-dashboard-setting-is-unavailable) |
| Work with a new dashboard setting | [New dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-new) |
| Maintain an existing dashboard setting | [Edit dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-edit-record) |
| Understand dashboard display and widgets | [Dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview) or [Dashboard widget catalog](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-widget-catalog) |

## Before you begin

Dashboard settings work depends on the Dashboard settings configuration subscription, your editing
state, and whether the dashboard record has been saved.

| Before you begin | What it changes |
|---|---|
| The Dashboard settings configuration subscription is included | The configuration list and **Forecast settings** are available. |
| The screen is in edit mode | Dashboard editing actions are available. |
| A dashboard record has an ID | **Last Modifications** is available for the saved record. |
| Another role dashboard has been selected | The import tab-selection controls are available. |

The subscription is required for this screen. If it is unavailable, the configuration screen is
replaced by a surface with **Back**. Editing actions require edit mode. The **Last Modifications**
tab requires `RoleDashboard.Id`, so the dashboard record must exist before that tab is available.
Import tab-selection controls appear only after you select another role dashboard.

## Find and open a dashboard setting

The Dashboard settings list is the starting point for reviewing a role dashboard or opening its
configuration record. Forecast settings opens a separate forecast-rules popup.

**Prerequisites**

- The Dashboard settings configuration subscription is available.
- You can access the configuration area.

**Steps**

1. In the configuration area, select **Dashboard settings**.
2. Choose one destination.

   | If you need to… | Select or open |
   |---|---|
   | Review forecast rules | **Forecast settings** |
   | Open an existing role dashboard from its row | The dashboard-setting row |
   | Open an existing role dashboard for editing | **Edit** |
   | Open a new dashboard setting | Open the new dashboard-setting page from the Dashboard settings list |

3. If you selected a dashboard row or **Edit**, open the selected dashboard setting's detail page.

![The Dashboard settings list with its role-dashboard columns and Forecast settings action](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/6af6787bfa032faefd3cfd4f64971f28.png)

**Result:** The list, the forecast-rules popup, the saved dashboard-setting record, or the new
dashboard-setting detail surface is open.

## Understand the dashboard settings list

The Dashboard settings list is the directory of role-dashboard configuration records. Use its
columns to identify a record, then use the opened record's maintenance actions to change its
dashboard structure.

| List columns |
|---|
| **Role** |
| **Tabs** |
| **Widgets** |
| **Users** |
| **Last modified** |

Select a row to open the selected dashboard setting, or select its **Edit** action to open the same
record on its detail page. The detail surface provides these maintenance actions:

| Surface | Available actions |
|---|---|
| Dashboard detail toolbar | **Widget**, **Blank Tab**, **Import From**, **Principals Report**, **Eagle View**, **Save**, and **Save and Close** |
| **Tab** menu | **Blank Tab**, **Import From**, **Principals Report**, and **Eagle View** |
| Import popup | **Another role dashboards**, **Select tab(s)**, and **All (Replace existing tabs)** |
| Saved record | **Last Modifications** |

**Widget** opens widget preparation for an active user-dashboard tab with widgets. **Blank Tab**
opens the blank-tab flow. **Import From** opens the import popup. **Principals Report** and
**Eagle View** add or remove their dashboard tabs. **Save** keeps the page open after saving, and
**Save and Close** leaves the page after saving.

Select **Blank Tab** to open the new-tab dialog. The dialog has the required **New Tab** field and
an **OK** button.

The import popup first provides **Another role dashboards**. After you select another role dashboard,
**Select tab(s)** and the all-tabs choice become available when source tabs are present.

![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)

When the record has an ID, select **Last Modifications** to review its saved modification history.
The detail surface can also provide **Rename tab**, **Delete tab**, and **Remove widget from tab**
for an active editable tab. Widget-specific choices and report columns depend on the active tab
and widget area.

When a dashboard-setting request succeeds, the message is `Your request was completed successfully`.
If an imported special tab is already present, the message is `You already have this tab in this
dashboard`. A request error uses `An error occurred while processing your request`.

## Open the forecast rules

Forecast settings are the booking-rule choices used to configure how the forecast is calculated and
how booking periods are represented.

**Prerequisites**

- The Dashboard settings configuration subscription allows **Forecast settings**.
- The Dashboard settings list is open.

**Steps**

1. Select **Forecast settings**.
2. Complete the forecast choices.

   | Field or choice | Select or enter |
   |---|---|
   | **Forecast calculation type** | **Firm offers only** or **Firm offers and received inquiries** |
   | **Forecast calculation method** | The order-chance multiplication method or the at-or-above percentage method |
   | **Rating** | A required percentage when you use the order-chance method |
   | **Tolerated deviation between forecasted and achieved monthly booking** | A value from `0` through `100` |
   | **Listing of the average monthly booking** | **Of the last 3 years** or **Of the last 5 years** |
   | **Average Period For Goods Delivery Till Receiving The Commission Payment** | A value of at least `0` |
   | **Average Period For Goods Delivery Till Receiving The Clients Payment** | A value of at least `0` |
   | Commission and client payment periods | Select them when your company configures them as required |

3. Select the action that matches your choice.

    | If you need to… | Select |
    |---|---|
    | Save the forecast-rule choices | **Save** |
    | Leave the popup without saving | **Cancel** |
    | Confirm the shared popup action | **OK** |

The popup also supports the shared confirmation actions. A required value can show
`This Field Is Required`. Choose the order-chance method before entering its required percentage in
**Rating**; **Rating** is available for that choice.

![The forecast settings surface with its calculation and booking-period fields](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/dd2c193ea6f22ededd72d8c7daf27db9.png)

**Result:** The forecast settings popup remains available for the selected save or cancel action,
with the entered calculation choices and booking-period values displayed.

## When a dashboard setting is unavailable

Dashboard-setting surfaces change when the subscription, editing state, saved-record state, or
import source does not meet the screen's conditions.

| What you see | What it means | What to do |
|---|---|---|
| The configuration screen is replaced by a surface with **Back** | The Dashboard settings subscription is not included. | Select **Back**. |
| **Widget**, **Blank Tab**, **Import From**, **Principals Report**, **Eagle View**, **Save**, or **Save and Close** is unavailable | The screen is not in edit mode. | Continue in edit mode. |
| **Last Modifications** is unavailable | The dashboard record has no `RoleDashboard.Id` yet. | Save or open the saved dashboard record before reviewing modifications. |
| **Select tab(s)** or **All (Replace existing tabs)** is unavailable | Another role dashboard has not been selected, or the source has no tabs available for import. | Select another role dashboard with tabs to import. |
| A widget-specific area is unavailable | Its own subscription or widget guard does not permit it. | Continue with the dashboard area that is available. |
| `You already have this tab in this dashboard` appears | The imported special tab is already on the dashboard. | Close the message and continue with the existing tab. |
| `This Field Is Required` appears | A required forecast value is empty. | Enter the required value before saving. |
| `An error occurred while processing your request` appears | The request returned the common processing error. | Review the values and request conditions, then retry the action. |

## Continue to dashboard maintenance

After opening a role dashboard, continue with **Widget**, **Blank Tab**, **Import From**,
**Principals Report**, or **Eagle View** according to the maintenance task. On a saved record,
**Last Modifications** is the onward review surface for dashboard changes.

For widget meanings and day-to-day dashboard use, continue to [Dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview)
and [Dashboard widget catalog](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-widget-catalog). The focused pages for creating or
maintaining the configuration record are [New dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-new)
and [Edit dashboard setting](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-dashboard-settings-edit-record).
