# Bonus calculation

Use Bonus calculation to review and maintain the year-based sequence of cost, salary,
achievement, and bonus-distribution values.

## Before you start

Bonus calculation is a year-based sequence with four stages: Costs, Salaries, Achievement,
and Bonus distribution. The page loads the year from the route. A later stage becomes
available only when the current calculation stage reaches it.

```mermaid
flowchart LR
    Costs -->|Next step| Salaries
    Salaries -->|Next step| Achievement
    Achievement -->|Next step| Distribution[Bonus distribution]
```

> **Note:** Review the stage bar before looking for a later stage's fields. You can select a
> stage only after the current calculation stage reaches it.

| If you need to… | Go to |
|---|---|
| Open the year-specific calculation | [Open Bonus calculation](#open-bonus-calculation) |
| Identify fields and conditions before editing | [Read the stages and fields](#read-the-stages-and-fields) |
| Review or maintain stage values | [Review and maintain stage values](#review-and-maintain-stage-values) |
| Set the bonus share | [Distribution](#distribution) |
| Review earning controls | [Earning panel](#earning-panel) |
| Follow the cost-to-achievement sequence | [Costs, Salaries, and Achievement progression](#costs-salaries-and-achievement-progression) |
| Handle groups, imports, and popup choices | [Handle stage and popup variations](#handle-stage-and-popup-variations) |
| Investigate an access, save, or load message | [When a calculation action goes wrong](#when-a-calculation-action-goes-wrong) |

![The configuration entry point before opening the year-specific calculation](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/152a466afcf6d227df11248a3d85d3e1.png)

## Open Bonus calculation

Open the configuration entry for the required year, then check that the calculation stage bar
is on screen before using a stage.

**Prerequisites**

- You are signed in with access to the configuration area.
- You know the year whose calculation you need to review.

**Steps**

1. Open the configuration area.
2. Select the Bonus calculation entry.
3. Open the year-specific route in the form `configuration/bonuce/<Year>`.
4. Select **Year**.
5. Confirm that the Bonus calculation stage bar is on screen.

If access is refused, the application displays `You are not allowed to View this page!`. If
the application returns you to Dashboard, stop there because the calculation page has not been
reached.

**Result:** The selected year is open on the Bonus calculation screen, or the access message
identifies why the screen cannot be used from the current account.

## Read the stages and fields

The stage bar is the route through the calculation. Costs covers branch cost inputs, including
expected depreciation and amortization; Salaries covers administration, sales, and
teamless-group salary amounts, plus optional service usage; Achievement covers booking and
performance values; and Bonus distribution covers the net-earning share and distribution values.

| Stage or surface | Reader-facing controls and fields | Condition |
|---|---|---|
| Period | **Year** | The selected year comes from the year-specific route. |
| Costs | **Salary currency**, **Expected SG&A**, expected depreciation and amortization, **C&M collection risk%**, **Income tax**, **Legal reserve**, **First profit distribution %** | A branch is open and its collection is not empty. |
| Salaries | **Salary currency**, salary amounts, service-usage percentages, **Service usage from the main branch (Only for Bonus calculation)**, **Group**, **Group name** | A branch and its salary collection are available. |
| Achievement | **Booking today**, **Booking tendency**, **Expected achievement of objectives**, **Team's minimum booking rate for a bonus payout** | A branch is open. The team-performance value also requires a teamless group. |
| Bonus distribution | If present, **Share of net earning for distribution as a bonus**, **Team**, **Teamless**, **Amount**, **In ratio of salaries** | A populated branch is visible, open, and not displayed as a widget. |
| Earning | If present, **Earning up today**, **Earning till 31 Dec**, **Including Forecast** | An open visible distribution branch has cost data and is not displayed as a widget. |
| Import | File control | The import modal is open. |

The add-group popup requires **Group name**. Use these limits when entering values:

| Value family | Constraint |
|---|---|
| Expected SG&A and expected depreciation and amortization | Minimum `0` |
| Collection risk, income tax, legal reserve, first profit distribution, usage, and bonus shares | `0` to `100` |
| Target ratio | `100` to `200` for the branch ratio; minimum `0` for the other target values |
| Salary amounts | Minimum `0` |
| Achievement performance, minimum booking rate, and teamless adjustment | Minimum `0` |

Select **Costs**, **Salaries**, **Achievement**, or **Bonus distribution** in the stage bar, then
open the branch panel below it. Branch panels, service usage, and distribution branches are
collapsible or conditional, so their contents appear only after their conditions hold.

![The Year field and stage bar on Bonus calculation.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/0204f63edda4fb604281c56ffed4df6d.png)

## Review and maintain stage values

When a stage is available, review its visible branch values before saving. Costs, Salaries, and
Achievement also provide **Next step** to advance the sequence.

**Prerequisites**

- The year-specific Bonus calculation screen is open.
- The stage you need is available in the stage bar.

**Steps**

1. Select the available stage tab: **Costs**, **Salaries**, **Achievement**, or **Bonus distribution**.
2. Open the branch panel whose values you need to review.
3. Review the fields shown for that branch.
4. Change a supported input within the limits in [Read the stages and fields](#read-the-stages-and-fields).
5. Select **Save** on the active stage.
6. Select **Next step** after Costs, Salaries, or Achievement when the next stage is available.

The parent page's **Save** action is inactive. Use the active stage's **Save** instead.

**Result:** The selected stage remains open with its configured values, and the next available
stage can be selected when the sequence permits it.

The documented annual sequence is to choose the applicable year, save the branch cost inputs,
save salaries, review the achieved booking figures, and then save the bonus distribution.

### Distribution

When Bonus distribution is present, use it to set the share of net earning used as a bonus and
review the values shown for teams, teamless groups, and amount-based distribution.

**Prerequisites**

- **Bonus distribution** is available in the stage bar.
- The relevant distribution branch is populated, visible, and open.

**Steps**

1. Select **Bonus distribution**.
2. Open the applicable distribution branch.
3. Enter the share in **Share of net earning for distribution as a bonus** within `0` to `100`.
4. Review the **Team**, **Teamless**, and **Amount** values shown for the open branch.
5. Select the active distribution **Save** when the branch is not displayed as a widget.

The amount-based branch includes **In ratio of salaries** when its branch is open, visible, not
hidden for a widget, not displayed as a widget, and uses the percentage distribution type. The
team-based ratio field additionally requires teams and an Administration team.

**Result:** The open branch shows its net-earning share and available team, teamless, and amount
values. The active distribution **Save** is available only on the non-widget path.

### Earning panel

When present, the Earning panel provides controls for viewing earning periods in an eligible open
distribution branch.

| Control | Appears when |
|---|---|
| **Earning up today** | The branch is populated, visible, open, not a widget, and has cost data. |
| **Earning till 31 Dec** | The branch is populated, visible, open, not a widget, and has cost data. |
| **Including Forecast** | The same earning-panel conditions hold. |

Select an earning control only after the branch and cost conditions are visible.

### Costs, Salaries, and Achievement progression

Costs is the opening stage for branch cost inputs. Salaries follows it for administration, sales,
and teamless-group salary amounts, with optional service usage from the main branch. Achievement
follows Salaries for booking, tendency, teamless performance, and the minimum booking rate for a
bonus payout.

| Progression or variation | What must be available |
|---|---|
| Costs to Salaries | The current calculation stage reaches Salaries; the Salaries stage then becomes selectable. |
| Salaries to Achievement | The current calculation stage reaches Achievement; the Achievement stage then becomes selectable. |
| Branch values | An open branch with a non-empty collection. |
| Salary totals | Administration, Sales, or SalesTeamless branch type. |
| Service usage | The usage table is open and its corresponding team type applies. |
| Teamless performance | A teamless group exists. |
| Later stage availability | The requested stage number is no greater than the current calculation stage. |

Target settings are not a selectable stage-bar item. Use [Targets and budgets](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-booking-target)
for target configuration.

## Handle stage and popup variations

The Salaries stage can open group and import variations. A popup choice or icon-only action is a
separate surface, not an ordinary stage field.

**Prerequisites**

- **Salaries** is available and selected for group work.
- The relevant branch or popup action is visible.

**Steps**

1. Select **Group** to open the group variation.
2. In the add-group popup, enter the required value in **Group name**.
3. If the edit-group popup is shown, review the existing group value before changing it.
4. Choose the applicable popup action:

   | If you need to… | Select |
   |---|---|
   | Confirm or import | **Save**, **Upload**, or **Ok** |
   | Confirm or reject a choice | **Yes** or **No** |
   | Close without confirming | **Cancel** |
   | Leave without saving | **Don't Save** |
   | Return from a subscription-upgrade variation | **Back** |

5. In the import modal, select **Upload** after choosing the file.

To remove a teamless salary, use its icon-only delete action. Confirm the deletion with **Yes**
or leave it unchanged with **No**.

**Result:** The applicable group, import, confirmation, cancellation, or subscription-upgrade
surface remains on its corresponding popup path. Icon-only actions remain available only through
their visible icon; they are not named fields.

## When a calculation action goes wrong

Use the message on screen to choose the next action.

| What you see | What it means | What to do |
|---|---|---|
| `You are not allowed to View this page!` | The current account was refused access to the page. | Return to the configuration entry point and use an account with the required access. |
| `An error occurred while processing your request` | A header load/save or bonus-submission request did not complete. | Check the selected year and stage, then reopen the stage before attempting the supported action again. |
| `Salary portions exceeded the total salary of sales teams` | The salary portions exceed the total salary of sales teams. | Review the sales salary portions before saving the stage again. |
| `Your request was completed successfully` | The bonus submission reports completion. | Remain on the calculation page and review the updated stage values. |
| The parent **Save** is inactive | The parent save path is not active. | Use the active stage **Save** instead. |

When a message appears, review the selected year and stage. If the parent **Save** is inactive,
use the active stage **Save** instead.

### Out of scope

Use this page for the named stage fields and controls above. Do not infer the following
from the calculation surface:

| Do not infer | Boundary |
|---|---|
| Literal-false fields | Min margin, salary portions, commission or margin distribution values, salary totals, amount fields, and group fields under inactive guards are not active fields here. |
| Year options | Available runtime **Year** choices are not defined here. |
| Branch data | Runtime branch, team, teamless, panel-expansion, and default-value data are not defined here. |
| Wrong-screen observations | Dashboard controls such as `Accounts`, `Report`, `Time Frame`, `Generate Report`, `Download as PDF`, `Sort by Booking`, `Sort by Target`, and `Sort by Achievement` are not Bonus calculation controls. |
| Approval actor | No product-enforced person who must approve saving or deleting a calculation value is identified. |

## After reviewing the calculation

After reviewing the available year and stage values, continue with the configuration area that
owns the next decision. Use [Targets and budgets](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-booking-target) for target
work, [Teams](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/teams) for team-related configuration, and [Management report widgets](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/management-report-widgets)
for related reporting.

After selecting a stage or saving a value, review the displayed stage values before continuing.
Use the active stage **Save** for stage changes, then continue with the configuration area that
owns the next decision.
