Metrics

Metrics are the numerical side of status updates. Use them when users need precise values in counters, charts, or progress views. For a readable account of what is happening, combine them with messages. You choose which metrics matter when starting the roster job, and each status response returns their latest values. Each metric is an aggregate for the current roster. Its returned scope is identical to the scope you requested, so you can reliably match the value to the right element in your user interface.

A metric value is null until the solver publishes its first metrics update, or when the selected scope has no value.

Choose what each metric measures

A metric scope is defined by its metricKey and, optionally, its ruleLabel:

ruleLabel can only be used for metrics based on labeled rules.

With only a metricKey, the service aggregates that metric across every rule of the relevant type.
With both a metricKey and ruleLabel, it aggregates only rules of that type that have the exact, case-sensitive label.

Rule labels let you turn a broad metric into a number with a clear meaning for your users. For example, label each Period Distribution rule that limits weekend work with maximum-weekend-amount, then request PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS with that label. The result is the total number of excessive weekend periods across all matching rules.

Track excessive weekend periods

{
  "metricKey": "PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS",
  "ruleLabel": "maximum-weekend-amount"
}

Add numerical updates to your interface

Choose the numbers users need

Add each metric scope to statusOptions.metricScopes in your POST /roster/start request. A scope can track a metric across all matching rules, or use ruleLabel to limit it to a labeled group of rules.

Add status options to the roster start request

{
  "statusOptions": {
    "metricScopes": [
      {
        "metricKey": "UTILIZATION.MINUTES_BELOW_IDEAL",
        "ruleLabel": "weekly-hours"
      },
      {
        "metricKey": "PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS"
      }
    ]
  }
}

Start the roster job

Send the roster start request and retain the returned jobId. The service creates one status-metric entry for every requested scope.

Poll for the latest numbers

Call GET /roster/status/{jobId} while the job runs. Each response contains the latest values in the metrics array, using the same scopes you requested.

Metrics returned when checking job status

{
  "jobId": "7a608c99-8d91-4ab7-bd66-5561ad2c0c09",
  "status": "running",
  "hasResult": true,
  "metrics": [
    {
      "scope": {
        "metricKey": "UTILIZATION.MINUTES_BELOW_IDEAL",
        "ruleLabel": "weekly-hours"
      },
      "value": 120
    },
    {
      "scope": {
        "metricKey": "PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS"
      },
      "value": 2
    }
  ]
}

Keep the interface up to date

Match every returned scope to the metric in your interface and update its displayed value on each poll. Values will move as the solver improves the roster.

Available metrics

Metric key	Description
`AVAILABILITY.WORKED_MINUTES`	Total minutes worked in the periods covered by Availability rules.
`AVAILABILITY.ASSIGNMENTS`	Number of assignments relevant to Availability rules.
`DEMAND.MISSING_MINUTES_TO_MIN`	Total minutes missing below minimum demand.
`DEMAND.MISSING_MINUTES_TO_IDEAL`	Total minutes missing below ideal demand.
`DEMAND.MISSING_SHIFTS_TO_MIN`	Total shifts missing below minimum shift demand.
`DEMAND.MISSING_SHIFTS_TO_IDEAL`	Total shifts missing below ideal shift demand.
`COOLDOWN.MISSING_DAYS`	Total number of required cooldown days that are missing.
`COOLDOWN.MISSING_MINUTES`	Total number of required cooldown minutes that are missing.
`COOLDOWN.VIOLATIONS`	Number of cooldowns that are shorter than required.
`CONSECUTIVE.MIN_VIOLATIONS`	Number of consecutive-work groups that are shorter than the configured minimum.
`PATTERN.DESIRED_COMPLETE_MATCHES`	Number of periods that completely match a desired pattern.
`PATTERN.DESIRED_PARTIAL_MATCHES`	Number of periods that partially match a desired pattern.
`PATTERN.DESIRED_INCOMPLETE_PERIODS`	Number of periods that do not completely match a desired pattern.
`PATTERN.UNDESIRED_COMPLETE_PERIODS`	Number of periods that completely match an undesired pattern.
`UTILIZATION.TOTAL_MINUTES`	Total worked minutes counted by Utilization rules.
`UTILIZATION.MINUTES_BELOW_MIN`	Total minutes by which work falls below configured minimum-hour targets.
`UTILIZATION.MINUTES_BELOW_IDEAL`	Total minutes by which work falls below configured ideal-hour targets.
`UTILIZATION.MINUTES_ABOVE_IDEAL`	Total minutes by which work exceeds configured ideal-hour targets.
`UTILIZATION.ASSIGNMENTS_BELOW_MIN`	Total assignments by which work falls below configured minimum-shift targets.
`UTILIZATION.ASSIGNMENTS_BELOW_IDEAL`	Total assignments by which work falls below configured ideal-shift targets.
`UTILIZATION.ASSIGNMENTS_ABOVE_IDEAL`	Total assignments by which work exceeds configured ideal-shift targets.
`PERIOD_DISTRIBUTION.WORKED_PERIODS`	Number of periods with at least one assignment.
`PERIOD_DISTRIBUTION.MISSING_WORKED_PERIODS`	Total number of required worked periods that are missing.
`PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS`	Total number of worked periods above configured maximums.
`PERIOD_DISTRIBUTION.MAX_CONSECUTIVE_VIOLATIONS`	Total amount by which consecutive worked-period groups exceed their maximum.
`PERIOD_DISTRIBUTION.MIN_SURROUNDING_VIOLATIONS`	Total number of required surrounding free periods that are missing.
`PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS`	Number of employee-rule combinations that violate the continuous-rest requirement.

Getting started

Entities

Concepts

Status updates

Choose what each metric measures

Add numerical updates to your interface

Available metrics

​Choose what each metric measures

​Add numerical updates to your interface

​Available metrics

Choose what each metric measures

Add numerical updates to your interface

Available metrics