Skills and risk factors

Making sure the correct employees are assigned to the correct shifts is an important factor in employee shift scheduling.

Different shifts require different skills. For instance, a hospital requires nurses in the ICU to be trained in ICU procedures.

In other cases, skills might just be preferred but not required. An event looking for volunteers might prefer volunteers who have first-aid training over volunteers who don’t, but will also accept volunteers without first-aid training.

Risk factors are also an important consideration in employee shift scheduling. If an employee has a compromised immune system, scheduling them to work in an environment where they might be exposed to COVID-19 would be a risk.

This guide explains skills and risk factors with the following examples.

Assigning employees with required skills
Assigning employees with multiple skills
Assigning employees with preferred skills
Risk factors

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for this model:

Log in to Timefold Platform: app.timefold.ai
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
Create a new API key or use an existing one. Ensure the list of models for the API key contains the current model.

In the examples, replace <API_KEY> with the API Key you just copied.

1. Assigning employees with required skills

Employees can include skills that are used to determine if they should be assigned to shifts.

{
  "id": "Beth",
  "skills": [
    {
      "id": "security"
    }
  ]
}

Shifts also include the skills that are required of the person who will be assigned to the shift.

{
  "shifts": [
    {
      "id": "mon-sec",
      "start": "2027-02-01T00:00:00Z",
      "end": "2027-02-02T08:00:00Z",
      "requiredSkills": [
        "security"
      ]
    }
  ]
}

In the following example, Ann and Beth are both available for the shift, however, only Beth has the required security skill.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Skills: required skill example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Ann",
        "skills": [
          {
            "id": "doctor"
          }
        ]
      },
      {
        "id": "Beth",
        "skills": [
          {
            "id": "security"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "mon-sec",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z",
        "requiredSkills": [
          "security"
        ]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Skills: required skill example",
    "submitDateTime": "2025-02-19T07:59:36.850272829Z",
    "startDateTime": "2025-02-19T07:59:42.88054275Z",
    "activeDateTime": "2025-02-19T07:59:42.93678946Z",
    "completeDateTime": "2025-02-19T08:04:43.16445426Z",
    "shutdownDateTime": "2025-02-19T08:04:43.307088825Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "mon-sec",
        "employee": "Beth"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the schedule with Beth assigned to the security shift.

2. Assigning employees with multiple skills

Shifts and employees can both have multiple shifts that must be matched for an assignment to be made.

In the following example, Beth and Carl are both available for a shift. The shift has two required skills, security and first-aid.

Beth and Carl both have the security skill, but only Carl has the security skill and the first-aid skill.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Skills: multiple skills example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Beth",
        "skills": [
          {
            "id": "security"
          }
        ]
      },
      {
        "id": "Carl",
        "skills": [
          {
            "id": "security"
          },
          {
            "id": "first-aid"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "mon-sec",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z",
        "requiredSkills": [
          "security", "first-aid"
        ]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Skills: multiple skills example",
    "submitDateTime": "2025-02-19T08:30:28.178931158Z",
    "startDateTime": "2025-02-19T08:30:34.190480064Z",
    "activeDateTime": "2025-02-19T08:30:34.318230242Z",
    "completeDateTime": "2025-02-19T08:35:34.533973055Z",
    "shutdownDateTime": "2025-02-19T08:35:34.764465774Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "mon-sec",
        "employee": "Carl"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the schedule with Carl assigned to the shift that requires the skills security and first-aid.

3. Assigning employees with preferred skills

When skills are only preferred and employees without the skill can still be assigned, they are included as preferredSkills:

requiredSkills and preferredSkills can both be included in the same shifts or used separately.

{
  "shifts": [
    {
      "id": "mon-sec",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "preferredSkills": [
        "first-aid"
      ]
    }
  ]
}

In the following example, Beth and Carl both have the required security skill, but only Carl has the preferred first-aid skill.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Skills: preferred skills example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Beth",
        "skills": [
          {
            "id": "security"
          }
        ]
      },
      {
        "id": "Carl",
        "skills": [
          {
            "id": "security"
          },
          {
            "id": "first-aid"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "mon-sec",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z",
        "requiredSkills": [
          "security"
        ],
        "preferredSkills": [
          "first-aid"
        ]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Skills: preferred skills example",
    "submitDateTime": "2025-02-20T06:57:28.217023617Z",
    "startDateTime": "2025-02-20T06:57:38.305320329Z",
    "activeDateTime": "2025-02-20T06:57:38.447753272Z",
    "completeDateTime": "2025-02-20T07:02:38.832848935Z",
    "shutdownDateTime": "2025-02-20T07:02:39.016900039Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "mon-sec",
        "employee": "Carl"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the schedule with Carl assigned to the shift.

4. Risk factors

When employees have risk factors, it’s important not to expose them to those risks.

Employees can define prohibitedRiskFactors:

{
  "id": "Carl",
  "prohibitedRiskFactors": [
    "covid-19"
  ]
}

The risks associated with a shift are defined in riskFactors:

{
  "shifts": [
    {
      "id": "mon-sec",
      "start": "2027-02-01T08:00:00Z",
      "end": "2027-02-01T16:00:00Z",
      "riskFactors": [
        "covid-19"
      ]
    }
  ]
}

risk factors

In the following example, Beth and Carl both have the required skill security, but only Carl has the preferred skill first-aid, however, Carl has a prohibited risk factor for COVID-19.

The shift is assigned to Beth.

Input
Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call:

curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Risk factors example"
    }
  },
  "modelInput": {
    "employees": [
      {
        "id": "Beth",
        "skills": [
          {
            "id": "security"
          }
        ]
      },
      {
        "id": "Carl",
        "skills": [
          {
            "id": "security"
          },
          {
            "id": "first-aid"
          }
        ],
        "prohibitedRiskFactors": [
          "covid-19"
        ]
      }
    ],
    "shifts": [
      {
        "id": "mon-sec",
        "start": "2027-02-01T08:00:00Z",
        "end": "2027-02-01T16:00:00Z",
        "requiredSkills": [
          "security"
        ],
        "preferredSkills": [
          "first-aid"
        ],
        "riskFactors": [
          "covid-19"
        ]
      }
    ]
  }
}

To request the solution, locate the 'ID' from the response to the post operation and append it to the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>

{
  "run": {
    "id": "ID",
    "name": "Risk factors example",
    "submitDateTime": "2025-02-20T07:21:29.749994031Z",
    "startDateTime": "2025-02-20T07:21:39.712315225Z",
    "activeDateTime": "2025-02-20T07:21:39.846012595Z",
    "completeDateTime": "2025-02-20T07:26:40.223992857Z",
    "shutdownDateTime": "2025-02-20T07:26:40.435553658Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "mon-sec",
        "employee": "Beth"
      }
    ]
  },
  "kpis": {
    "assignedShifts": 1,
    "unassignedShifts": 0,
    "workingTimeFairnessPercentage": null,
    "disruptionPercentage": 0.0,
    "averageDurationOfEmployeesPreferencesMet": null,
    "minimumDurationOfPreferencesMetAcrossEmployees": null,
    "averageDurationOfEmployeesUnpreferencesViolated": null,
    "maximumDurationOfUnpreferencesViolatedAcrossEmployees": null
  }
}

modelOutput contains the schedule with Beth assigned to the shift.

See the Employee Shift Scheduling User Guide
Understand the constraints of the Employee Shift Scheduling model.
See the full API spec or try the online API.
Manage schedules with Time zones and Daylight Saving Time (DST) changes.
Manage Employee availability.

Skills and risk factors

Prerequisites

1. Assigning employees with required skills

2. Assigning employees with multiple skills

3. Assigning employees with preferred skills

4. Risk factors

Next