Metrics

Metrics let you show users how a roster is developing while the solver runs. Each metric is an aggregate for the current roster. The returned scope matches the scope you requested, which makes it straightforward to associate a value with the metric shown 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.

Scope metrics with rule labels

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.

This lets you track a meaningful business measure rather than every instance of a rule type. 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"
}

Track and show metrics

Choose the metrics to track

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 the job status

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
    }
  ]
}

Show progress to users

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 between minimum and ideal demand.
`DEMAND.MISSING_SHIFTS_TO_MIN`	Total shifts missing below minimum shift demand.
`DEMAND.MISSING_SHIFTS_TO_IDEAL`	Total shifts missing between minimum and 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

Scope metrics with rule labels

Track and show metrics

Available metrics

​Scope metrics with rule labels

​Track and show metrics

​Available metrics

Scope metrics with rule labels

Track and show metrics

Available metrics