# Principals Report

## Principals Report overview

The Principals Report is a reporting view for reviewing principal-related sales activity over a
chosen period. Use it when you need a consolidated view of jobs, offers, orders, deliveries, lost
 jobs, and cancellations for selected accounts. It sits on the reporting path and opens
at `/principalReport`.

| If you need to… | Go to |
|---|---|
| Check the fields and actions available when the report opens | [Open the report and identify its controls](#open-the-report-and-identify-its-controls) |
| Choose the period, charts, lists, clients, or product types | [Set the reporting period and report options](#set-the-reporting-period-and-report-options) |
| Generate and read the report sections | [Generate and read the report](#generate-and-read-the-report) |
| Resolve a missing selection or invalid period | [When report generation fails](#when-report-generation-fails) |
| Continue with reporting | [Reporting overview](doc:dashboard-overview) |
| Use the general Reports area | [Reports hub](doc:reports-hub) |
| Maintain report availability and sections | [Reports settings](doc:configuration-reports-settings) |

The report supports the sales path from inquiry and pricing through offer, sales order, delivery,
and the related principal-side financial flow. Use the report to review that activity rather than
to change a sales job's stage.

## Before you start

The Principals Report is ready to configure when the required account and report information is
entered.

**Prerequisites**

| Before you begin | Why it matters |
|---|---|
| Choose at least one entry in **Accounts** | Report generation requires a selected principal or client entry. |
| Have a report name ready for **Report** | **Report** has a required validation rule. |
| Have the reporting period ready | **From** and **To** are required when you use a date range. |
| Use a role and subscription that expose the report on the active Sales Report reporting tab | The report surface appears only when the subscription and active tab conditions are met. |

**Steps**

1. Select an entry in **Accounts**.
2. Enter the report name in **Report**.

**Result:** The required account and report name are entered, and the report is ready to open.

## Open the report and identify its controls

The report screen brings together account selection, report naming, period selection, report
settings, report introduction text, generation, and PDF download.

**Prerequisites**

- You have access to the reporting tab.

**Steps**

1. Open the Principals Report screen.
2. Locate **Accounts**, **Report**, and **Time Frame** on the screen.
3. Locate **Settings** and **Introduction & Outline** for report configuration and explanatory text.
4. Locate **Generate Report** to create the report.
5. Locate **Download as PDF** to create a PDF download.
6. Read the current time-frame text shown beneath **Time Frame**.

![Identify Accounts, Report, Time Frame, and the report actions on arrival.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9e36b0a64aa0666d8feeaa7062ddcb65.png)

The screen also displays **Tickets**. The visible time-frame text is `last 12 months`.

**Result:** You can distinguish the account and report fields from the controls that configure,
generate, and download the report, so you are ready to set the reporting period.

## Set the reporting period and report options

The reporting period determines which activity the report evaluates. The report offers preset
periods, a definite year, or a date range, and its settings determine which analyses and lists are
included.

**Prerequisites**

- You have opened the Principals Report screen.
- You know the period and the report areas you need to review.

**Steps**

1. Select **Time Frame**.
2. Choose and complete one period according to the question you need to answer.

   | If you need to… | Choose |
   |---|---|
   | Review the current calendar year | **This Year** |
   | Review one named year | **Definite Year**, then enter a year from 1990 through the current year |
   | Review the most recent rolling period | **last 12 months** |
   | Set your own start and end dates | **From / To**, then enter both required dates and keep **From** on or before **To** |

3. Select **Settings**.
4. Choose **All** or select the report sections you want to include.
5. Set **Show Lists** according to whether the report must include its detail lists.
6. Select the clients in **Client** when the report must be limited to particular clients.
7. Select the product types in **Product Type** when the report must be limited to particular
   product types.
8. Choose the chart type and period options for the enabled report sections.

**All** enables or disables the seven selectable chart settings: **Status of running firm offers**,
**Status of running orders**, **Reasons for lost jobs**, **Bookings over time**, **Deliveries over
time**, **Status of submitted offers**, and **Sales Overview + Overall Analysis**. **Running jobs**
is displayed in the settings but its checkbox cannot be changed.

When you select **Show Lists**, the settings expose the multi-choice selectors **Inquiries list
columns**, **Offers list columns**, **Orders list columns**, the delivery list columns, **Lost offers
list columns**, and **Cancelled jobs list columns**. **Client** and **Product Type** are searchable
multi-select filters. The **Status** filter is not available.

![Set the reporting period from the Time Frame choices.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/9e36b0a64aa0666d8feeaa7062ddcb65.png)

Changing valid values in **Time Frame** or **Settings** can require you to generate the report
again before the displayed analysis reflects the changes.

**Result:** The report has a selected period and the chart, section, list, client, and product
options needed for the analysis, so you are ready to generate it.

### Add introduction and outline content

Use this optional procedure when the report needs explanatory text.

**Prerequisites**

- You have opened the Principals Report screen.

**Steps**

1. Select **Introduction & Outline**.
2. Edit the available temporary report content.
3. Select **OK**.

Saving copies the temporary introduction, sales analysis, lost opportunities, client complaints,
suggested requirements, booking forecast, and conclusion values to the report fields.

**Result:** The available introduction and outline content is saved with the report.

## Generate and read the report

The generated report presents principal sales activity as charts and conditional detail lists.
Each section appears when its report setting is enabled and report data is available.

**Prerequisites**

- You have selected at least one principal or client entry.
- You have entered the required report name and period values.
- You have selected the report sections and options you need.

**Steps**

1. Select **Generate Report**.
2. Select a report-section entry to move to the corresponding analysis.

   | If you need to review… | Go to |
   |---|---|
   | Jobs currently in progress | **Running Jobs** |
   | Running firm offers | **Status of running firm offers** |
   | Running orders | **Status of running orders** |
   | The sales overview | **Sales Overview** |
   | Lost-job reasons | **Reasons for lost jobs** |
   | Submitted-offer performance | **Status of submitted offers** |
   | Bookings over time | **Bookings over time** |
   | Deliveries over time | **Deliveries over time** |
   | The combined analysis | **Overall Analysis** |

3. Review the generated content according to the analysis you need.

   | If you need to… | Review or choose |
   |---|---|
   | Compare chart presentations | **Bar** or **Pie** |
   | Compare booking or delivery periods | **Monthly**, **Quarterly**, or **Yearly** |
   | Compare job totals | **Jobs (Count)** and **Jobs (Value)** |
   | Review submitted-offer performance | **Hit Rate (count)** and **Hit Rate (value)** in **Status of submitted offers** |
   | Review submitted offers and received orders by perspective | The time and client views in **Overall Analysis** |
   | Review detail records | **Current inquiries**, **Current offers**, **Current orders**, **Delivered jobs**, **Lost jobs**, and **Cancelled jobs** |

4. Read the visible list headers, including **Job no.**, **Client**, and
   **Cancellation reason**.
5. Select **Download as PDF** when you need a PDF copy of the report.

The report charts use **Jobs (Count)** and **Jobs (Value)**. Running Jobs, Status of running firm
offers, Status of running orders, Sales Overview, and Reasons for lost jobs offer Bar and Pie views.
Status of submitted offers also shows Hit Rate (count) and Hit Rate (value) when submitted-offer data
exists. Bookings over time and Deliveries over time offer Monthly, Quarterly, and Yearly choices.
Overall Analysis compares submitted offers with received orders in time and client views; its time view
offers the same three period choices, while the client view has count and value displays.

Each available detail list has a filter row and header filter. The lists use virtual scrolling, do
not provide enabled paging in this report surface, and do not allow editing. Lists appear only when
their data is available.

The lists and columns shown depend on the report setup and the data available for the selected
period. Work from the headers and sections that appear on your screen.

**Result:** The report displays the enabled analyses and available detail lists, or a PDF download
is requested from **Download as PDF**. If the request stops, use the troubleshooting table below.

## When report generation fails

Report generation stops when a required selection or value is missing. Use the message on screen
to correct the input before selecting **Generate Report** again.

| What you see | Correct alternative |
|---|---|---|
| `Please choose one or more principals` | Select an entry in **Accounts**. |
| `An error occurred while processing your request` | Check the required report fields and selections. |
| **From** or **To** requires a value | Enter both required dates. |
| The **From** date is later than the **To** date | Change the dates so **From** is on or before **To**. |

**Steps**

1. Select an entry in **Accounts** when the message requires a principal selection.
2. Apply the correction in the table to **Accounts**, **From**, **To**, or **Report**, according
   to the message.

   | If you see… | Take this action |
   |---|---|
   | **From** or **To** requires a value | Enter both required dates in **From** and **To**. |
   | The required report field is empty | Enter the report name in **Report**. |
   | `An error occurred while processing your request` remains after checking the required fields | Review **Accounts**, **Report**, **From**, and **To**. |

3. Select **Generate Report** to retry the report request.

**Result:** The required selection or value is corrected and the report request is submitted again;
return to [Generate and read the report](#generate-and-read-the-report) when it opens.

## Continue from the report

The Principals Report is one of the reporting destinations in the reporting area. After reviewing the
analysis, continue with the area that matches your next task.

| If you need to… | Continue with |
|---|---|
| Return to the reporting view | [Reporting overview](doc:dashboard-overview) |
| Work with the general reporting area | [Reports hub](doc:reports-hub) |
| Change which report sections are available | [Reports settings](doc:configuration-reports-settings) |
| Continue the sales process behind the analysis | [Sales jobs lifecycle](doc:sales-jobs-lifecycle) |

**Result:** You have a route from the Principals Report to the reporting view, the general Reports area,
report configuration, or the sales process documentation.