Hiring Plans

Hiring Plans manage the full lifecycle of resource requisitions, from initial proposal through approval and recruitment to final fulfillment. Plans can be created manually or auto-generated from capacity plan hiring triggers.

Overview

When capacity planning reveals persistent resource gaps, the organization needs a structured process to fill those gaps. ProBeya hiring plans provide a governed requisition pipeline with clear status transitions, approval gates, and traceability back to the capacity plan that triggered the need. Each plan tracks the target role, headcount, salary estimates, justification, and the eventual hired resource.

Getting Started

1. Navigate to PPM > Hiring Plans to see the requisition pipeline.
2. Click + New Hiring Plan or use Auto-Generate from Capacity Plan to create plans for all under-resourced roles.
3. Fill in the role, requested headcount, target start date, and justification.
4. Submit for approval — an authorized approver reviews and approves the requisition.
5. Track the plan through recruitment until the position is filled.

How It Works

Requisition Lifecycle

Hiring plans follow a strict state machine with validated transitions:

proposed --> approved --> in_recruitment --> filled
    \            \               \
     --> cancelled  --> cancelled    --> cancelled

Status	Description
Proposed	Initial request — can be edited before approval
Approved	Management has authorized the hire
In Recruitment	Active recruiting is underway
Filled	Position has been filled and linked to the hired user
Cancelled	Requisition withdrawn at any non-terminal stage

Valid Transitions:

From	Allowed To
proposed	approved, cancelled
approved	in_recruitment, cancelled
in_recruitment	filled, cancelled
filled	(terminal state)
cancelled	(terminal state)

Attempting an invalid transition (e.g., jumping from proposed directly to in_recruitment) returns a BAD_REQUEST error with a descriptive message.

Creating a Hiring Plan

The create mutation requires:

Field	Type	Required	Description
roleId	string	Yes	Reference to an organization role definition (validated)
requestedHeadcount	number	Yes	Number of positions to fill
startDate	string (date)	Yes	Target start date for the hire
justification	string	Yes	Business case for the hire
linkedCapacityPlanId	string	No	Reference to originating capacity plan
salaryEstimateMin	number	No	Lower bound of salary range
salaryEstimateMax	number	No	Upper bound of salary range

The role must exist in the organization's role definitions before it can be referenced.

Auto-Generation from Capacity Plans

The autoGenerate mutation reads a capacity plan and creates one hiring plan per role in the organization's role definitions. Each auto-generated plan includes:

• The target role from the capacity plan
• A default headcount of 1 (adjustable before approval)
• A justification referencing the originating capacity plan by name
• A link back to the capacity plan via linkedCapacityPlanId

This bulk-creation feature saves significant time compared to manually creating individual requisitions for each under-resourced role.

Updating Plans

Plans can only be updated while in proposed status. Once approved, the plan details are locked to maintain governance integrity. The update supports partial modification of:

• Requested headcount
• Start date
• Justification
• Salary estimate range
• Role assignment

Approval Workflow

The approve mutation transitions a plan from proposed to approved. It records:

• The approver's user ID (approvedById)
• The approval timestamp (approvedAt)

Only users with Admin role can approve hiring plans.

Recruitment Tracking

The markInRecruitment mutation moves an approved plan into active recruitment. This signals to the team that the position is being actively sourced.

Fulfillment

When a hire is completed, the markFilled mutation:

• Sets the status to filled
• Links the hired user's profile via linkedUserId
• Records the fulfillment timestamp (filledAt)

This closes the loop from demand identification through capacity gap to staffing resolution.

Cancellation

The cancel mutation withdraws a requisition from any non-terminal status (proposed, approved, or in_recruitment). Cancellation is a terminal state and cannot be reversed.

Salary Estimates

Salary values are stored as text (numeric strings) in the database for precision with large currency amounts. Each plan can optionally include:

• salaryEstimateMin — lower bound of the expected salary range
• salaryEstimateMax — upper bound of the expected salary range

These help budget owners assess the financial impact of approved hires before committing to recruitment.

Listing and Filtering

The list query supports optional filters:

Filter	Type	Description
status	enum	Filter by current status (proposed, approved, in_recruitment, filled, cancelled)
roleId	string	Filter by specific role

Results are ordered by creation date descending and include the role name and code via a left join to the role definitions table.

Configuration

• Roles — must exist in the organization's role definitions before a plan can reference them
• Capacity plan link — optional reference to the capacity plan that triggered the hire
• Salary currency — follows the organization's default currency settings

Permissions

Action	Required Role
View hiring plans	Any member
Create or update proposed plans	Editor or Admin
Approve a plan	Admin
Advance to recruitment or filled	Admin
Cancel a plan	Admin
Auto-generate from capacity plan	Admin

API Reference

Procedure	Type	Description
ppmHiringPlans.create	Mutation	Create a new hiring plan
ppmHiringPlans.autoGenerate	Mutation	Bulk-create plans from a capacity plan
ppmHiringPlans.update	Mutation	Update a proposed plan's details
ppmHiringPlans.approve	Mutation	Transition from proposed to approved
ppmHiringPlans.markInRecruitment	Mutation	Transition from approved to in_recruitment
ppmHiringPlans.markFilled	Mutation	Transition to filled with hired user link
ppmHiringPlans.cancel	Mutation	Cancel from any non-terminal status
ppmHiringPlans.list	Query	List plans with optional status/role filters
ppmHiringPlans.getById	Query	Get a single plan with role details

Tips & Best Practices

تلميح

Use the auto-generate feature after approving a capacity plan. It creates draft requisitions for every under-resourced role in a single action, saving significant time compared to manual creation.

تلميح

Always include a clear justification that references specific project demand. Requisitions with vague justifications are more likely to be questioned during approval and budget review cycles.

تلميح

Monitor the pipeline view regularly. Plans stuck in proposed for more than two weeks may indicate a bottleneck in the approval process that needs management attention.

Related Features

• Capacity Plans — Hiring triggers originate from capacity gap analysis
• Resource Reports — Monitor utilization after hires are onboarded
• Budgets & Costs — Salary estimates feed into labor cost forecasts