# Principals Report

Use the Principals Report to prepare a report for selected accounts, choose its reporting
period and content, generate it, and download it as a PDF.

## Principals Report overview

The Principals Report is a Dashboard report tab for reviewing account-related sales information
in one report. Select one or more accounts, choose the period and report sections, and prepare
charts or detail lists for those accounts.

The report settings group the available output into report sections and list variants. Report
sections include narrative content, charts, an overall analysis, and lists. List variants are the
inquiry, offer, order, delivered, lost, and cancelled job lists.

| If you need to… | Go to |
|---|---|
| Understand the Dashboard area that contains the report | [Dashboard overview](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/dashboard-overview) |
| Prepare the account selection and report name | [Before you start](#before-you-start) |
| Recognize the controls on the report page | [Open the report and identify its controls](#open-the-report-and-identify-its-controls) |
| Choose a period and report content | [Set the reporting period and report options](#set-the-reporting-period-and-report-options) |
| Add narrative content | [Add introduction and outline content](#add-introduction-and-outline-content) |
| Generate and review the report | [Generate and read the report](#generate-and-read-the-report) |
| Narrow a detail list | [Filter an available detail list](#filter-an-available-detail-list) |
| Diagnose a stopped generation attempt | [When report generation fails](#when-report-generation-fails) |
| Download the report or continue to broader report navigation | [Continue from the report](#continue-from-the-report) |

## Before you start

The report is prepared from selected accounts and a report name, rather than from a business
record that you save. Have the account records you want to include available for selection.

| Have or know | Why it matters |
|---|---|
| One or more account records | **Accounts** is required and accepts multiple selections. |
| A report name | **Report** is required. |
| Access to the qualifying Dashboard tab and subscription condition | The report page appears only when the Dashboard tab and subscription condition allow it. |

Open it from the Dashboard reporting flow. The Principals Report appears when the Dashboard is on
the qualifying report tab and the subscription condition allows it.

## Open the report and identify its controls

The Principals Report page is the report setup surface. Its main controls identify the accounts,
report name, period, settings, narrative content, generation action, and PDF action.

**Prerequisites**

- Have access to the Dashboard report tab.
- Have the accounts and report name ready.

**Steps**

1. Open the Principals Report from the Dashboard reporting flow.
2. Locate **Accounts** for the account selection.
3. Locate **Report** for the report name.
4. Locate **Time Frame** for the reporting period.
5. Select one of the report actions in this table.

   | Action | Purpose |
   |---|---|
   | **Settings** | Configure report sections, charts, and lists. |
   | **Introduction & Outline** | Prepare the narrative sections. |
   | **Generate Report** | Start report generation. |
   | **Download as PDF** | Download the report as a PDF when it is ready. |

![The Principals Report controls for accounts, report name, time frame, settings, narrative content, generation, and PDF output](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3ec7419c5ea2bb5a616cf926fdbf193f.png)

**Result:** The Principals Report setup controls are on screen, including **Accounts**, **Report**,
**Time Frame**, **Settings**, **Introduction & Outline**, **Generate Report**, and **Download as
PDF**.

## Set the reporting period and report options

The reporting period limits the dates used by the report. The settings determine which report
sections, charts, and lists are included before generation.

**Prerequisites**

- Open the Principals Report.
- Select the accounts and enter the report name.

**Steps**

1. In **Time Frame**, follow the applicable row.

   | If you need to report on… | Select or enter |
   |---|---|
   | The current year | **This Year** |
   | A named calendar year | **Definite Year**, then a year from `1990` through the current year |
   | The previous twelve-month period | **last 12 months** |
   | A custom date range | **From / To**, then the first date in **From** and the last date in **To**; check that **From** is not later than **To** |

2. Select **OK** in the time-frame popup.
3. Select **Settings**.
4. Select the report content options from the table.

   | If you need to include… | Select |
   |---|---|
   | All available report settings | **All** |
   | Running-job content | **Running jobs** |
   | Running firm-offer status | **Status of running firm offers** |
   | Running-order status | **Status of running orders** |
   | Lost-job reasons | **Reasons for lost jobs** |
   | Booking trends | **Bookings over time** |
   | Detail lists | **Show Lists** |
   | Account-based filtering | **Client** |
   | Product-based filtering | **Product Type** |

5. When a chart is enabled, choose its chart type from **Bar** or **Pie**.
6. When **Bookings over time** is enabled, choose **Monthly** where that period is required.
7. Select **OK** in the settings popup.

The chart choices appear only when the related chart is enabled. **Running jobs** is a settings
option that is disabled in **Settings**. Valid changes to saved settings can require the
report to be generated again.

![The Principals Report page with its report setup controls and available actions](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/be7d28e636dbe3611625fb89c37a4044.png)

> **Note:** The choices in **Accounts** depend on the accounts available to you.

**Result:** The report has a selected time frame and saved report options for its sections, charts,
lists, account filter, and product filter.

### Add introduction and outline content

The Introduction & Outline popup holds the narrative sections that accompany the report's figures
and lists.

**Prerequisites**

- Open the Principals Report.
- Set the reporting period and report options.

**Steps**

1. Select **Introduction & Outline**.
2. Enter the report introduction under **Introduction :**.
3. Enter the sales discussion under **Sales Analysis :**.
4. Enter the lost-opportunity discussion under **Lost Opportunities and Competition :**.
5. Enter the complaints and difficulties under **Client Complaints and Difficulties :**.
6. Enter the improvement proposals under **Suggestions for Business Improvement :**.
7. Enter the booking expectations under **Booking Forecast :**.
8. Enter the closing text under **Conclusion :**.
9. Confirm the entries in the report introduction and outline popup.

**Result:** The report introduction and outline content is prepared for the report.

## Generate and read the report

The generated report brings together the enabled charts, summaries, section navigation, and
available detail lists. The report sections are conditional: a section appears when its report
setting and report data allow it.

**Prerequisites**

- Select the accounts and enter **Report**.
- Set **Time Frame** and **Settings**.
- Complete **Introduction & Outline** when narrative content is required.

**Steps**

1. Select **Generate Report**.
2. Use the report navigation entries to move to **Running Jobs**, **Status of running firm offers**,
   **Status of running orders**, **Sales Overview**, **Reasons for lost jobs**, **Status of
   submitted offers**, **Bookings over time**, **Deliveries over time**, or **Overall Analysis**.
3. In the job summaries, read **Jobs (Count)** and **Jobs (Value)**.
4. In the submitted-offer summary, read `Hit Rate (count)` and `Hit Rate (value)` when submitted-offer data is available.
5. In **Overall Analysis**, use the time view and client view to compare submitted offers and received orders by count and value.
6. Select a report section to read its charts and summaries.

**Result:** The report view contains the enabled report sections and their available charts,
summaries, and analysis views. **Generate Report** is disabled while the report is ready or while
generation is in progress. The chart and setup controls are shown before a report is generated.

### Filter an available detail list

Detail lists show job information grouped by the report list selected in settings. Each available
list provides a filter row and a filter at the column heading.

**Prerequisites**

- Generate a report with **Show Lists** selected.
- Open a list that is available in the generated report.

**Steps**

1. Select the detail list that matches the work you need to review.

   | If you need to review… | Select |
   |---|---|
   | Current inquiries | `Current inquiries` |
   | Current offers | `Current offers` |
   | Current orders | `Current orders` |
   | Completed deliveries | `Delivered jobs` |
   | Lost work | `Lost jobs` |
   | Cancelled work | `Cancelled jobs` |

2. Enter a value in the filter row to narrow the list.
3. Use the filter at the column heading for a column-specific filter.
4. Read the columns available in the selected list, such as **Job no.**, **Client**, **Offer price**,
   **Order price**, **Backlog**, **Expected delivery date**, **Lost reason**, and **Cancellation reason**.

**Result:** The selected detail list is narrowed by its filters, and its visible headers identify
the job information available in that list.

## When report generation fails

Report generation checks the required inputs before it processes the report. A missing account
selection has a report-specific validation message; a processing failure uses a general error
message.

| What appears | What to do |
|---|---|
| `Required` | Complete the required field marked on the report setup form. |
| `Please choose one or more principals` | Select one or more records in **Accounts**, then generate the report again. |
| `An error occurred while processing your request` | Review the report inputs and submit the report again. |

The report-specific account-selection check applies when no principal or client is selected. The
general processing message identifies a processing failure rather than a particular field.

## Continue from the report

After the report settings are valid, the report provides a PDF action for continuing from the
report view. The PDF action follows the report's generated state and calls the download path.

**Prerequisites**

- Have valid report settings.
- Have generated report content available for download.

**Steps**

| If | Consequence |
|---|---|
| The generated report is available | The PDF is available for download. |
| Valid saved settings require another generation | The PDF is unavailable until the report is generated again. |

1. If valid saved settings require another generation, select **Generate Report**.
2. After the generated report is available, select **Download as PDF**.
3. Open the broader **Reports** area when you need the application's other report navigation.

**Result:** The report's PDF download action is available from the generated-report state, and the
broader **Reports** area remains available for other report navigation.
