Score analysis

The score analysis feature helps you understand the score structure of your schedule. It provides a detailed breakdown of the score, including the score of each constraint and justifications. Justifications are objects that contribute to violating, or meeting the constraint, for example an employee and two overlapping shifts that are assigned to them. This is especially useful when you want to highlight the violations in your user interface.

The score analysis is automatically calculated and stored at the end of each solver run.

The score analysis endpoint optionally accepts a boolean includeJustifications query parameter to control whether the justifications are included in the response. This can be useful to reduce the response size when you only need a top-level score breakdown.

Example 1. Get score analysis for a schedule without justifications

GET /v1/schedules/{id}/score-analysis

Example 2. Sample score analysis result without justifications

{
  "score": "0hard/-100medium/-600soft",
  "constraints": [
    {
      "name": "Employee is paired with preferred employee",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/0soft",
      "matches": []
    },
    {
      "name": "Employee works during preferred time",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/4320soft",
      "matches": []
    }...

Example 3. Get score analysis for a schedule with justifications

GET /v1/schedules/{id}/score-analysis?includeJustifications=true

Example 4. Sample score analysis result including justifications

{
  "score": "0hard/-100medium/-600soft",
  "constraints": [
    {
      "name": "Employee is paired with preferred employee",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/0soft",
      "matches": []
    },
    {
      "name": "Employee works during preferred time",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/4320soft",
      "matches": [
        {
          "score": "0hard/0medium/360soft",
          "justification": {
            "shift": "11",
            "employee": "Beth Jones",
            "overlappingTimeSpans": [
              {
                "start": "2024-03-12T00:00:00Z",
                "end": "2024-03-13T00:00:00Z",
                "includeShiftTags": [],
                "excludeShiftTags": [],
                "shiftTagMatches": "ALL"
              }
            ]
          }
        }...

Consider other use case where you have solved a schedule and want to fine tune it manually afterward. For example, assign a shift to a different employee. Use the score analysis to understand the impact of the change on the score and to validate that the new schedule is feasible.

Example 5. Calculate score analysis for a schedule including justifications

POST /v1/schedules/score-analysis?includeJustifications=true

The endpoint accepts a schedule object in the request body.

Example 6. Sample score analysis result

{
  "score": "0hard/0medium/-1200soft",
  "constraints": [
    {
      "name": "Employee is paired with preferred employee",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/0soft",
      "matches": []
    },
    {
      "name": "Employee works during unpreferred time",
      "weight": "0hard/0medium/1soft",
      "score": "0hard/0medium/-960soft",
      "matches": [
        {
          "score": "0hard/0medium/-480soft",
          "justification": {
            "shift": "177",
            "employee": "Dan Jones21",
            "overlappingTimeSpans": [
                {
                    "start": "2024-03-19T00:00:00Z",
                    "end": "2024-03-20T00:00:00Z",
                    "includeShiftTags": [],
                    "excludeShiftTags": [],
                    "shiftTagMatches": "ALL"
                }
            ]
          }
        }...