Performance reviews, goals and improvement plans · AI skills

Run a performance review in Business Made › HR › Performance from draft to acknowledged. Covers asking for the person's self review, the manager review and rating, finalizing, and the person's acknowledgement. Also goals with progress updates, and performance improvement plans with check-ins, extensions and an outcome, with the email each step sends.

Performance lives in the Business Made app, on HR › Performance (/hr/performance). The screen has three tabs: Reviews, Goals and Improvement plans. Everything on it uses business-made/performance/… (appengine business-made/services/performance.service.ts, controller performance.controller.ts). Call those routes with call_appengine.

Only two steps send anything, and both are emails about the self review:

Step	Email	Who gets it	Template
Asking for a self review	"Your self review", with a link to My reviews in the staff portal	the person being reviewed	`performance.self_review_requested`
The person submitting their own self review in the portal	"Self review submitted", with a link to the review	the reviewer	`performance.self_review_submitted`

Nothing else here sends anything: not goals, not improvement plans, and not finalizing a review.

The Business Made docs cover the same screen for people: Benefits, compensation, performance and learning. For the API, see the Business Made module reference.

Ask first

Who, and what kind of review. The kind is annual, semi-annual, quarterly, probation, 30-day, 60-day, 90-day, promotion or ad-hoc. Ask for the period it covers.
Who reviews. If nobody is named, the reviewer is the person's supervisor on their employee record. If they have none, it is you.
Self review. Should the person write their own in the staff portal (this emails them)? Or is HR recording one they gave on paper or in a meeting? Or is there no self review?
The ratings and words. These come from the manager. Never write a rating, strengths or concerns that the person didn't give you.
For a goal: the title, the due date, and how it is measured.
For an improvement plan: the reason, what must improve, how long it runs (60 days unless they say otherwise), and who runs it.

Steps

1. HR › Performance: create the review

POST business-made/performance/reviews. On screen, New review → Create review.

Field	On screen	Notes
`employeeId`	Person being reviewed	Required. Use the `bm_employee` sk or the `EMP-…` code.
`reviewType`	Kind of review	Required (`reviewType-required`).
`reviewPeriod`	Period start / Period end	`{ startDate, endDate }`. The end can't come before the start (`dates-invalid`).
`reviewerId`	Reviewer	Defaults to the person's supervisor, else the author.
`title`	(automatic)	For example "Annual review — Maria Lopez".
`nextReviewDate`	Next review date	Optional.

The review starts as a draft. Look for an open review first: GET business-made/performance/reviews/employee/<employeeId>.

Hands on: the review's sk. Check: the review shows on Reviews as Draft. You can open it at /hr/performance?openId=<sk>.

2. HR › Performance: the self review

Choose one of the two ways.

The person writes it. POST business-made/performance/reviews/<sk>/start-self-review (a draft only). On screen, Ask for self review. The review moves to self-review.

Stop: this emails the person ("Your self review"). Confirm who and which review, and wait for a yes.

The person answers under My reviews in their staff portal (/staff-portal/reviews). When they submit, the review moves to manager-review and the reviewer is emailed.
HR records it for them. POST business-made/performance/reviews/<sk>/self-assessment, from draft or self-review. On screen, Record the self review. Send any of these answers:
- accomplishments
- challenges
- developmentAreas
- careerAspirations
- additionalComments
- selfRating, from 1 to 5, rounded
At least one answer is required (self-assessment-empty). The answers are saved as via: "recorded", with who recorded them. The review moves to manager-review. No one is emailed.

Hands on: the review's status. Check: the review reads Waiting on self review, or shows the Self review answers.

3. HR › Performance: the manager review

POST business-made/performance/reviews/<sk>/manager-review with:

{ "managerFeedback": { "strengths": "…", "areasForImprovement": "…", "developmentRecommendations": "…", "overallComments": "…" },
  "overallRating": { "managerRating": 4 } }

On screen, use Manager review → Submit manager review. This works from draft through calibration, so the manager can skip the self review or change their review later (Change the manager review). A managerRating from 1 to 5 is required (rating-required). The review moves to calibration.

Until the review is finalized, the person can't see the manager's notes or rating in their portal.

Hands on: the rating and the feedback, exactly as the manager gave them. Check: the Manager review section shows them.

4. HR › Performance: finalize

POST business-made/performance/reviews/<sk>/complete with { finalRating, ratingLabel }. This works from manager-review or calibration. On screen, use Finalize → Finalize review.

finalRating defaults to the manager's rating.
ratingLabel defaults from the rating: 1 unsatisfactory, 2 needs-improvement, 3 developing, 4 meets-expectations, 5 exceeds-expectations.

The review moves to completed. The person can now see it in full under My reviews and acknowledge it there.

Tested: a finalized 4 read "4 of 5 · Meets expectations".

Stop before finalizing, unless the manager asked for it. A finalized review shows the manager's notes to the person. Nothing is emailed.

Hands on: the final rating. Check: the review reads Awaiting acknowledgement.

5. HR › Performance: the acknowledgement

The person acknowledges in their staff portal. If they signed on paper, record it with POST business-made/performance/reviews/<sk>/acknowledge and { comments } (completed only). On screen, Record acknowledgement. The review moves to acknowledged.

A step from the wrong stage is refused with 400 wrong-state (tested), and the message names the stage the review is at.

Hands on: the status acknowledged. Check: the review reads Acknowledged, with Their comment.

6. HR › Performance: goals

Do	Route	Notes
Create	`POST business-made/performance/goals` (New goal → Create goal)	`employeeId`, `title` and `dueDate` are required (`dueDate-required`). The other fields: `type` (`individual` by default, or `team`, `department`, `company`), `category`, `priority`, `startDate` (today by default), `weight` and `description`. The goal starts as a `draft`.
Start	`POST …/goals/<sk>/activate` (Start goal)	Moves it to `active`.
Progress	`POST …/goals/<sk>/progress` with `{ progress, note, status }` (Record progress → Save progress)	`progress` is 0–100. `status` is `on-track`, `at-risk` or `behind`. 100 completes the goal (tested). Each update is kept under Updates.
Finish	`POST …/goals/<sk>/complete` (Mark completed) or `…/cancel` with `{ reason }` (Cancel goal)	Only a started goal can be marked complete. A completed goal can't be cancelled (tested: `wrong-state`).

Hands on: the goal's sk and its progress. Check: the Goals tab shows the goal's status and progress. An overdue goal reads Overdue.

7. HR › Performance: an improvement plan

Stop before creating a plan. An improvement plan is a serious step for the person. Confirm the person, the reason and the length, and wait for a yes. Nothing is sent to them. Plans are confidential by default and don't appear in the staff portal.

Do	Route	Notes
Create	`POST business-made/performance/pips` (New improvement plan → Create plan)	`employeeId` and `reason` are required. The reason is `performance`, `attendance`, `behavior`, `policy-violation`, `skills-gap` or `multiple`. `startDate` is today by default. Set the end with `endDate` or `durationDays`; without either, it is 60 days. `managerId` defaults to the supervisor, else you. Also `reasonDetails`, `improvementGoals[]` and `consequences`. The plan starts as a `draft`.
Start	`POST …/pips/<sk>/activate` (Start plan)	`draft` only.
Check-in	`POST …/pips/<sk>/check-in` with `{ progressSummary, notes }` (Record a check-in → Save check-in)	One of the two is required (`summary-required`). This works on an `active` or `extended` plan only. Tested: a check-in on a draft was refused.
Extend	`POST …/pips/<sk>/extend` with `{ newEndDate, reason }` (Extend)	The status becomes `extended` and `extensionCount` goes up by 1. `originalEndDate` is kept (tested).
Close	`POST …/pips/<sk>/complete` with `{ result, summary, nextAction }` (Close plan)	`result` is `successful` or `unsuccessful` (tested: `extended` is refused with `result-required`; use Extend instead). `nextAction` is `none`, `extend-pip`, `demotion`, `termination` or `reassignment`. The status becomes `completed-successful` or `completed-unsuccessful`.
Cancel	`POST …/pips/<sk>/cancel` with `{ reason }` (Cancel plan)

Closing a plan with nextAction: termination records the decision only. It doesn't end the person's employment. That is HR › People's offboarding: see Hire, onboard and offboard.

Hands on: the plan's sk, status and end date. Check: the Improvement plans tab lists the plan with its Check-ins and end date.

When it's done

Tell the person each review's stage and rating, each goal's progress, and each plan's status and end date. Open /hr/performance?openId=<sk>.

GET business-made/performance/metrics gives the numbers on the screen's tiles. These include Reviews in progress, Waiting on self review, Running late, Average final rating, Open goals and Improvement plans running. It answers "whose reviews are late". GET …/reviews, …/goals and …/pips list them.

What it can't do yet

No review cycles. Each review is created one person at a time. Nothing starts reviews on a schedule, and nextReviewDate doesn't create the next one.
No reminders. A self review that is waiting, or a review that is late, isn't chased by email.
Finalizing tells no one. The person sees the review only when they open their portal.
Goals and improvement plans aren't in the staff portal, and nothing emails anyone about them.
Calibration is a stage only. The review waits in calibration until someone finalizes it. There is no calibration screen.
An improvement plan's nextAction does nothing. It is recorded only.

Don'ts

Don't write, change or invent ratings, strengths, concerns or self-review answers. Record only what the manager or the person gave you.
Don't ask for a self review, finalize a review, or start an improvement plan without a yes.
Don't record an acknowledgement the person didn't give.
Don't treat a closed plan's termination as ending their job.
Don't share one person's review or plan with anyone else.