# Common issues and solutions

Identify the dashboard or report surface affected by a problem, apply the available correction,
and continue from the result.

| If you need to… | Go to |
|---|---|
| Identify whether the issue is in Home, a custom dashboard, Business Analysis, or Principal Report | [Reach and identify the affected surface](#reach-and-identify-the-affected-surface) |
| Read the controls and report values currently on screen | [Read the settled surface](#read-the-settled-surface) |
| Restore a widget or change a dashboard tab | [Restore home work](#restore-home-work) and [Dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview) |
| Personalize and save the wider workspace | [Personalizing your workspace](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/personalizing-your-workspace) |
| Find recurring dashboard questions | FAQ (sibling page) |
| Match a message to its exact wording | [When a message or control does not match](#when-a-message-or-control-does-not-match) and [General error messages](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/general-error-messages) |
| Continue when the problem remains | [Continue from the result](#continue-from-the-result) and [Getting help](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/getting-help) |

## Before you start

Home is the signed-in starting surface for dashboard work. The covered surfaces are **Home**, the
dashboard library, custom-dashboard, **Business Analysis**, and principal-report surfaces reached
from the signed-in dashboard.

The Home shell is available after you sign in. Start troubleshooting only after the signed-in
session is in place.

**Prerequisites**

- You are signed in so the Home shell can be available.
- You know which dashboard or report surface contains the problem, or you can reach **Home**.

## Reach and identify the affected surface

Use the visible navigation and controls to decide which dashboard or report surface owns the problem.
The same dashboard can show different controls when you edit it, view a prepared dashboard, open a
report popup, or use a feature-controlled widget.

| What you see | Surface to identify |
|---|---|
| The main **Home** surface | Home |
| Dashboard editing actions | Dashboard editing |
| A role dashboard choice while the dashboard is not being edited | Role dashboard prepared by an administrator |
| A dashboard library with available tabs | Dashboard library |
| A custom dashboard surface | Custom dashboard |
| **Business Analysis** | Business Analysis |
| A popup titled **Settings** | Principal Report settings |
| A control titled **Introduction & Outline** | Principal Report introduction and outline |
| Options attached to a widget | That widget's available options |

**Prerequisites**

- You are signed in.
- You can reach **Home** or the dashboard or report surface that contains the problem.

**Steps**

1. Open **Home**.
2. Use the table to match the visible surface to the dashboard or report area that owns the problem.
3. Select **Settings** when the problem concerns Principal Report choices or readouts.
4. Select **Introduction & Outline** when the problem concerns the report introduction.
5. Read the options shown with the affected widget when the problem concerns a widget choice. In
   **Highlight**, choose from the account choices displayed by the control.
   The **Highlight** control presents those account choices as its selectable values.
6. Continue with [Restore standard tabs](#restore-standard-tabs) for a missing standard tab.
7. Continue with [Save changes](#save-changes) for a dashboard change that needs committing.

**Result:** You have identified the visible dashboard or report surface that needs attention.
Continue with [Read the settled surface](#read-the-settled-surface) when the problem concerns a
report or its settings.

## Read the settled surface

The settled surface is the report or settings view that remains on screen after it opens. Use the
labels, buttons, and table headings shown on that page.

**Prerequisites**

- You have reached the Principal Report surface.

**Steps**

1. Open the Principal Report surface from the dashboard.
2. Check whether **Report** has a required marker.
3. Check for **Generate Report** and **Download as PDF**.
4. Read the visible report text, including **Accounts**, **Time Frame**, `last 12 months`,
   **Settings**, **Introduction & Outline**, and **Tickets**.
5. If **Settings** is available, select it and read the controls and readouts on that surface.
6. Compare the settings surface with the following visible labels and buttons: **All**,
   **Running jobs**, **Bar**, **Pie**, **Status of running firm offers**, **Status of running
   orders**, **Reasons for lost jobs**, **Bookings over time**, **Monthly**, **Quarterly**,
   **Yearly**, **Deliveries over time**, **Status of submitted offers**, **Sales Overview +
   Overall Analysis**, **Show Lists**, **Generate Report**, **Download as PDF**, and **OK**.
7. Read the settings readouts **Accounts**, **Time Frame**, **Client**, and **Product Type**.

![Read the visible Principal Report controls, required marker, and report actions](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/2f267c2b884aa3e174f4e36cdf24706e.png)

**Result:** You have the Principal Report labels, buttons, and readouts needed to continue the task.
Continue with [Handle access and report branches](#handle-access-and-report-branches) when a choice
is unavailable.

## Restore home work

A widget is a dashboard area that you can restore while the Home surface is signed in and in edit
mode. Use the available dashboard editing controls when a widget is missing or the dashboard tab
needs correction.

**Prerequisites**

- You are signed in.
- The Home dashboard is in edit mode.

**Steps**

1. Open the dashboard editing surface.
2. Select **Widget** while the dashboard is in edit mode.
3. Choose the correction that matches the problem:

   | If you need to… | Select or open… |
   |---|---|
   | Remove the selected widget from the active tab | **Remove widget from tab** |
   | Add a dashboard tab | The add-new-tab or edit-tab popup, then **New Tab** |
   | Apply another correction to the active tab | The dashboard-tab action available for that tab |

**Result:** The available widget or tab correction is applied to the editable Home surface and is
ready for [Save changes](#save-changes).

### Save changes

Save commits an eligible dashboard edit while the signed-in Home surface is in edit mode.

**Prerequisites**

- You are signed in.
- You have changed an editable dashboard surface.
- The dashboard is in edit mode.

**Steps**

1. Select **Save**.
2. Read the message returned by the product.

| Message | What to do |
|---|---|
| `Your request was completed successfully` | Continue from the saved dashboard result. |
| `An error occurred while processing your request` | Treat the dashboard change as a processing error and use [When a message or control does not match](#when-a-message-or-control-does-not-match). |

**Result:** The product returns either `Your request was completed successfully` or
`An error occurred while processing your request` after the dashboard save request.

### Remove an extra tab

An extra tab is an active dashboard tab that the product permits you to edit or remove. The tab
actions depend on the active tab and its availability conditions.

**Prerequisites**

- You are signed in and viewing the dashboard library.
- The active tab is editable when you remove it.

**Steps**

1. Check that the active tab is the tab you intend to remove.
2. If **Delete tab** is visible, select **Delete tab**.
3. If you need to change the active user or MRM tab name instead, select **Rename tab**.
4. Open the dashboard library and check the active tab.

**Result:** The active editable tab is removed or renamed when its corresponding tab action is
available; otherwise, you have identified that the active tab is not editable under its current
conditions.

### Restore standard tabs

Standard tabs are dashboard library entries controlled by tab availability and subscription
conditions. **Principals Report** appears for an enabled sales-report tab, and **Eagle View** appears
for an enabled Eagle View tab.

**Prerequisites**

- You are signed in and viewing the dashboard library.

**Steps**

1. Check whether **Principals Report** is available in the dashboard library.
2. Check whether **Eagle View** is available in the dashboard library.
3. Check that the dashboard library contains an active tab and available tabs.
4. If a widget option is absent, check whether that feature is available for the widget.

**Result:** You have matched the missing standard tab or widget option to its availability or
subscription condition.

## Handle access and report branches

Access and report branches determine which choices are available on the current surface. A control
can remain unavailable when your role, subscription, feature access, popup, or editing state does
not provide it.

**Prerequisites**

- You have identified the current dashboard or Principal Report branch.
- You can see the current report or settings surface.

**Steps**

1. Check whether the role dashboard choice is visible while the dashboard is not being edited.
2. Check whether the dashboard library shows an active tab and available tabs.
3. In Principal Report, select **Settings**.
4. In the settings surface, use the available choices **All**, **Running jobs**, **Bar**, **Pie**,
   **Status of running firm offers**, **Status of running orders**, **Reasons for lost jobs**,
   **Bookings over time**, **Monthly**, **Quarterly**, **Yearly**, **Deliveries over time**,
   **Status of submitted offers**, **Sales Overview + Overall Analysis**, and **Show Lists**.
5. Select **OK** to confirm the settings surface when that button is available.
6. If the report requires principals, select one or more principals before generating it.

![Read Principal Report Settings choices, readouts, and OK](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/d343d7b54cfac3295024324742368393.png)

**Result:** You have identified whether the unavailable item follows a role, subscription, feature,
tab, popup, or required-principal branch.
Continue with [When a message or control does not match](#when-a-message-or-control-does-not-match)
when the visible result still does not match the expected choice or message.

## When a message or control does not match

Use the exact message on screen to separate a processing error from a missing report choice. When a
control is hidden, use the visible surface and its available choices rather than treating the hidden
control as a failed action.

| What you see | Meaning | What to do |
|---|---|---|
| `An error occurred while processing your request` after Home work | Home processing error | Return to the editable dashboard branch and review the change before selecting **Save** again. |
| `An error occurred while processing your request` in Principal Report | Principal Report processing error | Review the report branch and its settings before generating the report again. |
| `Please choose one or more principals` | A required principal choice is missing | Choose one or more principals, then return to the report action. |
| **Introduction & Outline** is available in the Principal Report action area | This action belongs to the report introduction and outline | Select **Introduction & Outline** from the Principal Report action area. |

### Out of scope messages and choices

Login and verification choices belong to signed-out branches, not Home troubleshooting. Route the
login message to [Getting help](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/getting-help) or the Login page rather than applying a dashboard
fix.

| Message, control, or value | Route |
|---|---|
| `Incorrect username or password` | Login-specific handling |
| **Email** | Signed-out login branch |
| **Password** | Signed-out login branch |
| **Enter code** | Verification branch |
| **Over** options | **Clients**, **Projects**, and **Market Segments** |
| **Highlight** account choices | In **Highlight**, choose from the account choices displayed by the control. |
| Table headings | Use the headings shown on the current page. |

## Continue from the result

Continue from the dashboard or report surface you can see.

**Prerequisites**

- You have applied the available dashboard or report correction, or matched the exact message.

**Steps**

1. Choose the next task from this table:

   | If the next task concerns… | Open… |
   |---|---|
   | Dashboard orientation or widgets | [Dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview) |
   | Workspace editing | [Personalizing your workspace](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/personalizing-your-workspace) |
   | Exact error wording | [General error messages](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/general-error-messages) |
   | An issue that remains | [Getting help](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/getting-help) |

**Result:** You continue from the Principal Report result or the corrected dashboard branch to the
page that owns the next task or help request.
