> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Forecast

> View financial forecast reports, view and manage rolling forecast records with period lines, version history, and actual vs. forecast comparison.

Forecast displays a financial forecast report that projects year-end financial results based on current budget and actuals, with optional filtering by fiscal year, budget, and fund. Route: `/fa/reports/forecast`.

## Overview

The Forecast page is accessible at `/fa/reports/forecast`. No explicit `RequirePermission` wrapper is on this route. The component (`ForecastPage`) uses filters — `fiscalYearId`, `budgetId`, `fundId` — to call `useForecast` and `useForecastSummary`, both scoped to `currentOrganization.id`. Results are rendered via `ForecastChart`, `ForecastReport`, and `ForecastSummary` components. A **Download CSV** button calls `exportForecastToCsv(forecastData)` when data is available.

Rolling forecast records are managed at `/fa/rolling-forecasts`. The Budgeting Hub (`/fa/budgeting?tab=forecasts`) lists rolling forecasts; individual records are accessible at `/fa/rolling-forecasts/:id`.

## Who it's for

Access follows your organization's role and module configuration. Rolling forecast operations require:

* `fa.rolling_forecasts.view` — view forecasts and detail
* `fa.rolling_forecasts.create` — create new rolling forecasts
* `fa.rolling_forecasts.edit` — edit existing rolling forecasts

## Before you start

* A fiscal year must exist in the system for filtering to work.
* The general ledger must have posted transactions for meaningful projections.
* Know the forecast name, start date, horizon in months, update frequency, and sharing level when creating.

## Steps

1. Navigate to **Finance → Reports → Forecast** (`/fa/reports/forecast`).
2. Select a **Fiscal Year** from the dropdown.
3. Optionally filter by **Budget** and **Fund**.
4. Review the `ForecastChart` visualization and `ForecastReport` table.
5. Review summary figures in `ForecastSummary`.
6. Click **Download CSV** to export forecast data.

## Key concepts

| Concept               | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `useForecast`         | Hook computing forecast projections for the selected filters |
| `useForecastSummary`  | Hook returning high-level forecast summary metrics           |
| `ForecastChart`       | Chart component visualizing projected year-end results       |
| `ForecastReport`      | Tabular report of forecast data                              |
| `exportForecastToCsv` | Utility exporting forecast data to CSV                       |

## Viewing a forecast

The Forecast Details page at `/fa/rolling-forecasts/:id` is the tabbed detail view for a single rolling forecast record, showing forecast lines, actual vs. forecast comparisons, and version history. Requires permission `fa.rolling_forecasts.view`.

The component (`RollingForecastDetailPage`) fetches the forecast via `useRollingForecast(id, organizationId)` and lines via `useRollingForecastLines`. It renders a tabbed interface (tab state via `?tab=` search param, default `lines`):

* **Lines tab**: `ForecastLineEditor` for period-level forecast entries
* **vs. Actual tab**: `ForecastVsActualTable` comparing forecast to actual
* **History tab**: `ForecastVersionHistory` showing version audit trail

Action buttons for **Activate** (sets status to `active`) and **Archive** (sets status to `archived`) via `useUpdateForecastStatus`. A `ForecastStatusBadge` shows the current status. The breadcrumb displays `forecast_name`.

Key concepts:

| Concept                   | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `ForecastLineEditor`      | Component for managing period-level forecast line entries |
| `ForecastVsActualTable`   | Comparison table of forecast vs. actual figures           |
| `ForecastVersionHistory`  | Audit trail of forecast version changes                   |
| `ForecastStatusBadge`     | Visual indicator of the forecast status                   |
| `useUpdateForecastStatus` | Mutation for activating or archiving a forecast           |

1. Navigate to the Budgeting Hub (`/fa/budgeting?tab=forecasts`) and open a rolling forecast.
2. On the **Lines** tab, review or edit period-level forecast entries in `ForecastLineEditor`.
3. On the **vs. Actual** tab, compare forecast to actual figures in `ForecastVsActualTable`.
4. On the **History** tab, review version history in `ForecastVersionHistory`.
5. Use **Activate** or **Archive** buttons to change the forecast status.
6. Click **Edit** to navigate to `/fa/rolling-forecasts/:id/edit`.

## Creating a forecast

The New Forecast page (`/fa/rolling-forecasts/new`) creates a rolling forecast record. Requires permission `fa.rolling_forecasts.create`. The page renders `RollingForecastForm` with a `PageHeader`.

On submit: a `fa_rolling_forecasts` record is created via `useCreateRollingForecast` with fields `forecast_name`, optional `forecast_description`, `forecast_start_date`, optional `source_budget_id`, `forecast_horizon_months`, `update_frequency`, `sharing_level`, `status: "draft"`. Forecast lines (if present) are created in parallel via `useCreateForecastLine`. Navigates to `/fa/rolling-forecasts/:id` on success.

Key concepts:

* **Forecast horizon:** `forecast_horizon_months` — defines how many months the forecast covers.
* **Status:** Created with `status: "draft"`.
* **Source budget:** Optional link to an existing budget for variance tracking.

Have account, fund, department, program, and site assignments ready for forecast lines.

1. Navigate to `/fa/rolling-forecasts/new`.
2. Complete the `RollingForecastForm` header fields (name, start date, horizon months, frequency, sharing level, optional source budget).
3. Add forecast lines if desired.
4. Submit. On success, you are redirected to the new forecast detail page.

## Editing a forecast

The Edit Forecast page (`/fa/rolling-forecasts/:id/edit`) allows updates to the forecast header and individual period line entries. Requires permission `fa.rolling_forecasts.edit`. The component (`RollingForecastEditPage`) fetches the existing forecast via `useRollingForecast` and its lines via `useRollingForecastLines`, both scoped by `organizationId`. It renders `RollingForecastForm` pre-populated with current values.

On submit: (1) calls `useUpdateRollingForecast` for the forecast header, (2) creates new lines via `useCreateForecastLine`, (3) updates changed lines via `useUpdateForecastLine`, (4) deletes removed lines via `useDeleteForecastLine`. The breadcrumb displays `Edit: <forecast_name>`.

Before you start: the rolling forecast must be in a status that allows editing.

Key concepts:

| Concept                                           | Description                                             |
| ------------------------------------------------- | ------------------------------------------------------- |
| `RollingForecastForm`                             | Shared form component for forecast header and lines     |
| `useRollingForecast`                              | Hook fetching the existing forecast header              |
| `useRollingForecastLines`                         | Hook fetching period-level lines for the forecast       |
| `useCreateForecastLine` / `useDeleteForecastLine` | Mutations for managing line item additions and removals |

1. Navigate to the Budgeting Hub (`/fa/budgeting?tab=forecasts`) and open the rolling forecast.
2. Click **Edit** to go to `/fa/rolling-forecasts/:id/edit`.
3. Update the forecast header fields in `RollingForecastForm`.
4. Add, update, or remove period lines in the line editor.
5. Click **Save** to submit.
6. On success, the page navigates back to the forecast detail.

## Related

<Columns cols={2}>
  <Card title="Finance & Revenue" icon="building-columns" href="/fa/overview">
    Finance & Revenue core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/fa.tsx
  * src/cores/fa/pages/ForecastPage.tsx
  * src/cores/fa/pages/RollingForecastDetailPage.tsx
  * src/cores/fa/pages/RollingForecastNewPage.tsx
  * src/cores/fa/pages/RollingForecastEditPage.tsx
  * src/cores/fa/hooks/useRollingForecastMutation.ts
  * src/cores/fa/components/RollingForecastForm.tsx
</Accordion>