---

In this article

• Classic or advanced: choosing your approach
• Set up classic recommendation logic
• Set up advanced recommendation logic
• Handlebars quick reference
• After you save
• Tips

---

What is recommendation logic?

Recommendation logic calculates suggested compensation values for every eligible employee in your merit cycle. You define the rules once, and the system applies them across your population. Recommendation logic can reference any data column in the cycle: performance ratings, band position, tenure, geography, business unit, custom columns your team uploads, or any combination. The examples in this article cover common patterns, but the system is designed to reflect whatever your organization's compensation philosophy requires.

Without recommendations, managers start from a blank input field for every employee. Recommendations anchor decisions to your compensation philosophy, reduce time per review, and keep outcomes consistent across managers.

How recommendations display

• Shown as floating text above the planner's input column, in local currency, company currency, or as a percentage
• Configured as a single target value or a min/target/max range
• Optionally prefilled into the input field so planners start from the suggested value
• Configured independently per pay type, so you can use different logic for salary raises and equity refreshers in the same cycle

Prefilling recommendations

When configuring recommendation logic for any pay type, you can choose whether to prefill the input column with the recommended value. This controls how recommendations appear to planners:

• Prefill off (default): The recommendation appears as floating guidance text above the input field. Planners start from a blank input and can reference the recommendation as they decide.
• Prefill on: The input field is pre-populated with the recommended value. Planners can still override it, but the recommendation serves as the starting point rather than a reference.

Prefilling is useful when you want planners to start from the company's guidance and adjust only where needed, rather than building each decision from scratch.

Recommendations, Smart Flags, and compensation controls

Recommendations are most powerful when paired with Smart Flags and compensation controls. Together, they form a complete governance loop:

• Recommendations set the target. They tell planners what the organization expects for each employee based on your compensation philosophy.
• Smart Flags surface deviations. Smart Flags are rule-based visual indicators that automatically highlight employee rows when specific conditions are met (for example, proposed salary falls outside the band, or a manager's pay is within 10% of a direct report). Flags can reference any column in the cycle, including recommendation outputs.
• Compensation controls enforce boundaries. Each smart flag can optionally carry a control: a soft stop requires the planner to add a justification comment before proceeding, while a hard stop blocks worksheet submission until the value is corrected or an authorized user overrides it.

Example: You set a 4% recommendation for "Meets expectations," attaches a smart flag that fires when a planner's input deviates from the recommendation by more than 1%, and adds a soft stop requiring the planner to explain why. Managers get clear guidance, the comp team gets visibility into every exception, and documentation happens automatically, with no manual review of hundreds of worksheets.

For more on Smart Flags and compensation controls, see Smart Flags.

Classic or advanced: choosing your approach

Both modes produce a recommended value per employee, but they differ in how you build the rules:

Classic setup

Classic setup walks you through a guided flow: select a philosophy, define groupings, fill out a matrix. No formulas. Best when your rules map to performance ratings, band position, compa ratio, or geography.

Advanced setup

Advanced setup opens a Handlebars code editor with syntax highlighting and a live preview panel. Select employees from the cycle to see calculated values update as you edit. Use this when your logic involves multi-factor calculations, conditional rules by business unit, or attributes not available in classic mode.

{{setVar "raisePercent" (inlineIf (eq columns.performanceRating "Exceeds expectations") 0.07 0.04)}}
{{setVar "rawRaise" (multiply columns.basePay (getVar "raisePercent"))}}
{{setVar "daysTenure" (dayDiff columns.startDate "2025-01-01")}}
{{setVar "prorationFactor" (min (divide (getVar "daysTenure") 365) 1)}}
{{min (multiply (getVar "rawRaise") (getVar "prorationFactor")) 15000}}

You can switch between classic and advanced at any time. Switching deletes the existing configuration for that column. Both modes can coexist across different pay types in the same cycle.

---

Set up classic recommendation logic

Select a pay type

Open the recommendation logic configuration page and select the pay type to configure. Pay types appear only when the corresponding column exists in the cycle. Select Setup to configure logic for a chosen program.

• Salary raise: Performance-based recommendations for non-promoted employees
• Salary raise for promoted employees: Separate logic or inherits from salary raise
• Variable raise: Maintains current pay mix, uses band targets, or a hybrid for promoted employees
• New annual bonus: Maintains the current bonus percentage as salary changes
• Spot bonus: Target bonus multiplied by optional company and individual performance multipliers
• Equity refresher: Target percentage multiplied by target equity on the current band (start date eligibility windows)
• Equity promotion shares: Percentage of promoted band target equity, or delta between promoted and current bands
• Equity performance shares: Target percentage multiplied by target equity for the current band (eligible ratings)
• Market cash raise: Different increases by metro, country, or flat rate
• OTE pay mix: Adjusts OTE-related compensation

Choose a compensation philosophy

The philosophy determines your matrix structure.

Salary raise:

Salary raise for promoted employees:

Market cash raise:

Configure dimensions

Depending on the philosophy, you configure one or more dimensions:

• Performance ratings: The rating values used in the cycle
• Countries or metros: Group locations so employees in the same group receive the same recommendation
• Range penetration: Breakpoints for position in band (for example, 0-25%, 25-50%, 50-75%, 75-100%)
• Compa ratio: Breakpoints for salary relative to market (for example, 0.80-0.90, 0.90-1.00, 1.00-1.10)

Configure proration (optional)

Proration adjusts recommendations based on tenure. Set a proration end date and choose the reference point (start date or last compensation change).

proration factor = (proration end date - reference date, in days) / 365

The factor is always between 0 and 1. A 5% recommendation with a 0.504 factor becomes 2.52%.

Fill out the recommendation matrix

Enter values in the matrix. You can enter a single target (5%) or a min/target/max range (3%-5%-7%).

Save and test

Select Save, then open the worksheet to verify. To delete a configuration, select Delete configuration from the three-dot menu. Recommendation logic carries over when you duplicate a cycle.

---

Set up advanced recommendation logic

Select a pay type and choose advanced mode

Open the recommendation logic configuration, select the pay type, and choose

Choose target only or range

• Target only: A single expression that calculates the recommended value
• Range: Three expressions (minimum, target, maximum). If you choose to prefill a value, the target will be used

Write your expressions

The code editor supports Handlebars expressions with syntax highlighting and inline error descriptions. Reference columns with columns.<columnKey>. Select View column keys for a searchable list of available columns.

See Handlebars quick reference for common patterns, or Handlebars expression reference for the full function list.

Key rules:

• Expressions must evaluate to a number for currency and numeric columns
• Column keys are case-sensitive
• Use coalesce or isNullOrUndefined to handle columns that might be empty
• Circular references are not allowed

Preview results

Select Toggle employee preview to see calculated values for specific employees in real time. Test with varied profiles: new hires, promoted employees, employees with missing data, different countries.

Save and configure prefilling

Select Save. Enable Prefill target recommendations to populate the worksheet automatically. Planners can still override prefilled values.

---

Handlebars quick reference

Common patterns for advanced recommendation logic. Reference columns as columns.<columnKey>.

Flat 5% salary raise:

{{multiply columns.basePay 0.05}}

Performance-based raise:

{{#if (eq columns.performanceRating "Exceeds expectations")}}
  {{multiply columns.basePay 0.07}}
{{else if (eq columns.performanceRating "Meets expectations")}}
  {{multiply columns.basePay 0.04}}
{{else}}
  {{multiply columns.basePay 0.02}}
{{/if}}

Promo bump on top of merit:

{{add (multiply columns.basePay 0.03) (inlineIf (eq columns.isPromotion true) 5000 0)}}

Raise capped at $15,000:

{{min (multiply columns.basePay 0.08) 15000}}

Band floor enforcement:

{{max (multiply columns.basePay 0.03) (subtract columns.bandMin columns.basePay)}}

Breaking complex logic into variables:

{{setVar "merit" (multiply columns.basePay 0.04)}}
{{setVar "promo" (inlineIf (eq columns.isPromotion true) 5000 0)}}
{{add (getVar "merit") (getVar "promo")}}

Null-safe column reference:

{{multiply (coalesce columns.adjustedBase columns.basePay) 0.03}}

Range (enter each in its own field):

• Minimum: {{multiply columns.basePay 0.02}}
• Target: {{multiply columns.basePay 0.05}}
• Maximum: {{multiply columns.basePay 0.08}}

Prorated raise based on start date:

{{setVar "daysTenure" (dayDiff columns.startDate "2025-01-01")}}
{{setVar "prorationFactor" (min (divide (getVar "daysTenure") 365) 1)}}
{{multiply (multiply columns.basePay 0.05) (getVar "prorationFactor")}}

For the full function list, see Handlebars expression reference.

---

After you save

Audit logging: All changes to recommendation logic are logged. View the audit trail from the recommendation configuration screen to see when changes were made and by whom.

"Outside recommendations" filter: The worksheet includes a quick filter that flags employees whose proposed compensation falls outside their recommendation, so you can spot where managers deviated from guidance.

---

Tips

• Start with classic unless your logic needs formulas or conditions beyond what classic philosophies offer
• Build advanced expressions incrementally. Start simple, verify in the preview panel, then add complexity
• Handle missing data. Wrap column references in coalesce when a value might be empty, otherwise affected employees see no recommendation
• Check range consistency. Min should always be less than or equal to target, and target less than or equal to max
• Promoted employee not seeing a recommendation? The planner needs permission to view the promoted band. Check Settings > Permissions