# Common issues and solutions

Use this page to triage problems on the home screen, principal report, custom, business-analysis,
and sign-in surfaces it can show.

| If you need to… | Go to |
|---|---|
| Identify the surface you reached | [Reach and identify the affected surface](#reach-and-identify-the-affected-surface) |
| Compare what is visible with the expected screen | [Read the settled surface](#read-the-settled-surface) |
| Restore or save changes | [Restore home work](#restore-home-work) |
| Handle a sign-in or principal-report branch | [Handle access and report branches](#handle-access-and-report-branches) |
| Match an error or unexpected control | [When a message or control does not match](#when-a-message-or-control-does-not-match) |
| Continue to the owned help topic | [Continue from the result](#continue-from-the-result) |

## Before you start

The home screen is the starting surface for signed-in work and for the signed-out sign-in branch.
It can take you to the library, principal report, custom, and business-analysis surfaces.

**Prerequisites**

- You know whether you are signed in.
- You have reached the home screen.
- You have the exact labels and message currently visible.
- For a principal-report problem, you know which report setup is selected.

The home screen does not require a field before you compare it. Report columns depend on the report
setup selected for your screen.

| Check | Why it matters |
|---|---|
| Access state | It determines whether the home content or login content is shown. |
| Home screen | It identifies the surface to compare. |
| Exact wording | The message and label determine which troubleshooting row applies. |
| Report setup | The principal-report columns depend on the selected setup. |

## Reach and identify the affected surface

From the home screen, open the surface where the problem appears. The home screen switches between
signed-in content and the login surface according to your access state.

**Prerequisites**

- You know whether you are signed in.
- You can read the labels currently displayed.

**Steps**

1. Open the home screen.
2. Compare each visible label with the entries in the table below.

   | If you need to… | Start with… |
   |---|---|
     | Work with **Dashboard** | **Dashboard** |
   | Work with the principal report | **Principals Report** |
     | Check a time range | **Interval** |
     | Check sorting | **Sort by Booking**, **Sort by Target**, or **Sort by Achievement** |
    | Resolve an access problem | **Email**, **Password**, or `Enter code` |

3. Record the route and the exact label or message that led you to the affected surface.

**Result:** You have matched the problem to a home, principal-report, custom, business-analysis, or
login branch.

## Read the settled surface

The settled surface is the screen after loading finishes. Compare its labels, controls, required
markers, buttons, columns, and visible loading state before changing anything.

**Prerequisites**

- You have reached the affected home surface.
- The screen has finished loading.

**Steps**

1. Look for the three sorting controls **Sort by Booking**, **Sort by Target**, and **Sort by Achievement**.
2. Check whether any of those controls carries a required marker.
3. Check whether buttons or report columns are visible.
4. Check whether a password field or spinner is visible.
5. Record the five visible controls without text labels.
6. Compare the visible result with the branch table.

   | What you see | Follow |
   |---|---|
    | The three sorting controls | Investigate the sorting surface. |
    | No buttons or report columns | Continue with the home or report page that owns the problem. |
   | A password field | Follow the sign-in branch. |
   | A spinner | Wait for the screen to settle before comparing it. |

The settled screen has shown three sorting controls with no required markers, zero buttons, zero
report columns, and five visible controls without text labels. It has shown no visible password
field and no spinner.

The custom surface also provides the optional **Over**, **Highlight**, and **Interval**
fields. The **Over** choices are `Clients`, `Sales Responsibles`, `Projects`, and `Market Segments`.
The **Interval** choices are `Last 12 Months` and `All Years`.

**Result:** You have recorded the controls and screen elements that are visible before applying a
fix.

![Compare the settled labels, sorting controls, and empty button and column areas.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/7938e002abe71479df3f6fdb7c154f95.png)

## Restore home work

Work on the home screen changes the tabs and widgets available there. Edit mode provides the
available actions.

**Prerequisites**

- You are signed in and on the home screen.
- The home screen is in edit mode for **Add New Widget**, **Save**, and **Restore Standard Tabs**.

**Steps**

1. Select **Add New Widget** to open the widget-selection action.
2. Enter the tab name in the required **New Tab** field when the new-tab popup opens.

**Result:** The required **New Tab** value is entered in the new-tab popup.

### Save changes

**Prerequisites**

- You are signed in and on the home screen.
- The home screen is in edit mode.

**Steps**

1. Select **Save** to save the tabs.

After a successful save, the tabs are saved and edit mode closes. Undo replaces the current tabs with
the original copy and exits edit mode.

**Result:** The tabs are saved and edit mode closes.

### Remove an extra tab

Use this procedure when an edit-tab popup offers the conditional deletion action.

**Prerequisites**

- You are signed in and on the home screen.
- The home screen is in edit mode.
- The edit-tab popup is open.

**Steps**

1. Select **Delete** in the edit-tab popup when the deletion action is available.

**Result:** The tab deletion action is applied.

### Restore standard tabs

**Prerequisites**

- You are signed in and on the home screen.
- The home screen is in edit mode.

**Steps**

1. Select **Restore Standard Tabs** to open the restore menu.
2. Choose one restore-menu action.

   | If you need to… | Select |
   |---|---|
   | Close the restore menu | **Cancel** |
   | Restore the standard tabs | **Restore** |

**Result:** The restore menu closes or the standard tabs are restored according to your selection.

![Identify the settled home surface before making changes.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/420ccaabe5b7987c5c6d91a5113df44f.png)

## Handle access and report branches

The login branch checks access, while the principal-report branch gathers report information. Use
the branch that matches the fields and surface currently shown.

**Prerequisites**

- You know whether the login flow asks for credentials or a verification code.
- For the principal report, you have reached the report surface.

**Steps**

1. Use the access-state table to choose the login fields.

   | If the sign-in flow… | Use |
   |---|---|
   | Does not require verification | **Email** and **Password** |
    | Requires verification | `Enter code` |

2. In the principal report, enter the required **Report** value when the report surface asks for it.
3. Follow the report setup fields when the introduction-and-outlines popup is open.
4. If the principal-report validation message appears, choose one or more principals before trying the report action again.

The principal-report surface also carries **Introduction :**, **Sales Analysis :**, **Lost
Opportunities and Competition :**, **Client Complaints and Difficulties :**, **Suggestions for
Business Improvement :**, **Booking Forecast :**, and **Conclusion :** fields in its introduction-
and-outlines popup.

**Result:** You are working in the login or principal-report branch that matches the fields shown.

## When a message or control does not match

Use the exact wording on screen to separate a validation message, a general request failure, a
login failure, a control that does not appear, and a surface whose values depend on the saved setup.

| What you see | Meaning | What to do |
|---|---|---|
| `This Field Is Required` | A required field is empty. | Return to the required field on the active surface and enter its value. |
| `An error occurred while processing your request` | The request returned a general error. | Check the active surface and retry the action when its prerequisites are satisfied. |
| `Please choose one or more principals` | The principal report needs one or more principals selected. | Select one or more principals before retrying the report action. |
| `Incorrect username or password` | The sign-in credentials were rejected. | Re-enter **Email** and **Password**. |

The available **Highlight** choices depend on the selected **Over** choice.

### Out of scope messages and choices

The following entries belong to other surfaces or depend on runtime records rather than a fixed
choice list.

| Entry | Owned by |
|---|---|
| **Vendors** as an **Over** option | Custom surface; it is not an active **Over** option. |
| **This Year**, **Definite Year**, `last 12 months`, and **From / To** | Principal report time-frame choices, not the custom **Interval** field. |
| `Your request was completed successfully` | Pipeline, status, sales, backlog, and management-report widgets. |
| `An error occurred while processing your request` | Pipeline, status, sales, backlog, and management-report widgets. |

**Result:** You have matched the exact message or control discrepancy to the action or surface that
owns it.

## Continue from the result

After the immediate triage, continue in the page that owns the next task rather than repeating the
same comparison on the home screen.

| If you need to… | Continue with… |
|---|---|
| Understand home content | [Home overview](dashboard-overview.md) |
| Choose or understand widgets | [Widget catalog](dashboard-widget-catalog.md) |
| Personalize the workspace | [Personalizing your workspace](personalizing-your-workspace.md) |
| Work with the principal report | [Principal report](principal-report.md) |
| Match a broader error message | [General error messages](general-error-messages.md) |
| Review recurring questions | [FAQ](faq.md) |
| Get further assistance | [Getting help](getting-help.md) |

**Result:** You have moved from the immediate home-surface problem to the page that owns the next
piece of work.