Getting started with employee shift scheduling

This guide introduces Timefold’s Employee Shift Scheduling model and walks you through the steps to use Timefold Platform to create an employee shift schedule.

The steps in this guide can be completed in under 10 minutes.

1. Employee shift scheduling hello world example

This hello world uses an example with one employee and one shift to demonstrate the process of requesting and retrieving a solution from Timefold’s Employee Shift Scheduling model.

In the example, Beth is a security guard who works the night shift at a medical clinic.

1.1. Prerequisites

To follow this guide, you need:

  • An active Timefold Platform account

  • An API client (optional but recommended)

1.2. Start a trial

To register for a trial with Timefold Platform:

  1. Navigate to https://app.timefold.ai.

  2. Click Log in.

  3. Click Sign up.

    Either enter the email address and password you want to register with and click continue or select one of the federated log-in options and follow the prompts.

  4. Verify your email address.

A tenant will be created for you and you can invite other users to your tenant.

Complete an employee shift scheduling test run.

  1. From the Models page, select Employee Scheduling.

  2. Click + New run.

  3. Select Basic and click Run.

When the test run begins you will see the Overview page which shows the constraints score changing over the length of the model run.

basic demo overview

Click Visualizations to view visualizations of the solution.

1.2.1. Shifts

The shifts visualization shows the schedule for the shifts with the employee assigned to each shift:

basic demo shift visualization

1.2.2. Employees

The employee visualization shows the shift schedule per employee:

basic demo employee visualization

1.3. Creating a dataset

A dataset for the Employee Shift Scheduling model must include information about the shifts that need to be covered and the employees who are available to work those shifts. The dataset can include information about the time and location of the shift, the required skills necessary of the person who works the shift, and the employees' preferred shifts.

You create your dataset using our predefined model schema which follows the OpenAPI specification.

See API Spec for more information.

The modelInput object contains the dataset to be scheduled, which, at a minimum, must include employees and shifts.

{
  "modelInput": {
    "employees": [
      {
        "id": "Beth",
        "skills": [
          {
            "id": "Security guard"
          }
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon Night",
        "start": "2027-02-01T00:00:00Z",
        "end": "2027-02-02T08:00:00Z",
        "requiredSkills": [
          "Security guard"
        ]
      }
    ]
  }
}
Copy this example dataset into a file called sample.json to use in this hello world example.

1.3.1. Employees

In this example, there is one employee. employees includes id and skills.

{
  "employees": [
    {
      "id": "Beth",
      "skills": [
        {
          "id": "Security guard"
        }
      ]
    }
  ]
}

id is a unique identifier that identifies the employee. In this case, the id has the value "Beth", but you could use the employee’s full name or an employee ID number.

skills is a unique identifier that represents the employee’s skills that are matched against the skills that are required for individual shifts. In this case, skills has the value "Security guard" and could be any other role that is required for the shift, for instance, "Doctor", "Nurse", or "Receptionist". There is no limit to the number of skills that can be listed. It can be used to include certifications and licenses.

{
  "id": "Beth",
  "skills": [
    {
      "id": "Security guard"
    },
    {
      "id": "CPR cert"
    }
  ]
}

1.3.2. Shifts

In this example, there is one shift.

Shifts includes information about the shift, the start and end times, and the requiredSkills for the shift:

{
  "shifts": [
    {
      "id": "Mon Night",
      "start": "2027-02-01T00:00:00Z",
      "end": "2027-02-02T08:00:00Z",
      "requiredSkills": [
        "Security guard"
      ]
    }
  ]
}

id is a unique identifier that represents the shift to be worked, in this case "2027-02-01-night" represents a night shift on February 1st, 2027.

start is the start time of the shift.

end is the end time of the shift.

Both start and end uses the ISO 8601 date and time format.

requiredSkills contains the skills the employee must have to be assigned this shift. In this instance, the shift requires an employee with the skill Security guard.

1.4. Post the dataset

You have two options to post the dataset.

  1. Post the dataset in the Timefold Platform UI

  2. Post the dataset to the Timefold OpenAPI

1.4.1. Post the dataset in the Timefold Platform UI

Typically, you post the dataset to the API. However, for testing purposes, you can upload your sample.json directly in the Timefold Platform UI.

  1. Log into the Timefold Platform dashboard: https://app.timefold.ai

  2. Select the Employee Scheduling tile.

  3. Click New run.

  4. Select Custom and click Next

  5. Upload the sample.json file you saved earlier.

  6. Click Schedule run.

  7. Navigate to the Output section to see the completed schedule

1.4.2. Post the dataset to the Timefold OpenAPI

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

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

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

Request the solution for your dataset by posting the sample.json file to the API endpoint /v1/schedules/.

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]

1.5. Output from the request

The output to the API request follows:

{
  "id": "ID",
  "name": "NAME",
  "submitDateTime": "2024-07-17T10:26:25.571295Z",
  "startDateTime": null,
  "activeDateTime": null,
  "completeDateTime": null,
  "shutdownDateTime": null,
  "solverStatus": "SOLVING_SCHEDULED",
  "score": null,
  "tags": null,
  "validationResult": null
}

The output includes an id and name that have been assigned to identify the run associated with the dataset. You’ll use this id to retrieve the results. Later, you’ll use name to locate more information in Timefold Platform.

solverStatus confirms the dataset has been scheduled for solving.

1.6. Request the solution

Append the ID from the output you received to the API endpoint /v1/schedules/ and create a GET request to retrieve the solution:

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

1.6.1. Completed schedule

{
  "run": {
    "id": "ID",
    "name": "NAME",
    "submitDateTime": "2024-07-17T10:26:25.571295Z",
    "startDateTime": "2024-07-17T10:26:30.719639034Z",
    "activeDateTime": "2024-07-17T10:26:30.819639034Z",
    "completeDateTime": "2024-07-17T10:26:33.991793212Z",
    "shutdownDateTime": "2024-07-17T10:26:34.091793212Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/0soft",
    "tags": null,
    "validationResult": {
      "summary": "VALIDATION_NOT_SUPPORTED"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon Night",
        "employee": "Beth"
      }
    ]
  },
  "kpis": {
    "unassignedShifts": 0
  }
}

The output shows the solverStatus is SOLVING COMPLETED.

modelOutput contains the solution for the dataset.

{
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon Night",
        "employee": "Beth"
      }
    ]
  }
}

shifts includes the shifts that have been scheduled and the employees assigned to the shifts.

employee scheduling hello world

Beyond hello world

This example walked you through creating a simple dataset to create a schedule for one employee for one shift. Timefold optimizes employee shift schedules for thousands of employees automatically with the goal of minimizing labor costs, ensuring proper coverage of employees with the correct skills, and increasing employee satisfaction through fairness of shift allocation and preferred shifts.

Configure a webhook

In this getting started guide, you learned how to retrieve the solution for your dataset through the API and Timefold Platform. However, you can configure a webhook to receive the solution without the need to poll the Timefold Platform API.

To configure a webhook:

  1. Log in to Timefold Platform app.timefold.ai

  2. From the Dashboard, click the tenant menu drop-down menu and select Tenant settings.

  3. Select Webhook and click New webhook.

  4. Give your webhook a name.

  5. Enter the URL for your webhook and the header values.

  6. Enable the webhook and click Add webhook.

See Configuring webhooks for more information.

Try the demo dataset

Timefold platform includes a demo dataset you can use to explore the functionality of the platform.

Access the demo dataset in the UI

To access the demo dataset in the UI:

  1. Log into Timefold Platform: app.timefold.ai

  2. Select the Employee Shift Scheduling tile.

  3. Click New Run.

  4. Select the demo dataset you would like to run from the drop-down menu, and click Schedule run.

Access the demo dataset with the API

To get the list of available demo datasets and information about each dataset from the API, make the following call:

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

To download the BASIC demo dataset, make the following API call:

curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/demo-data/BASIC -o sample.json

To post the demo dataset, use the following API call:

The output from the POST operation includes a run ID that you need for subsequent commands. 
curl -X POST -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]

To get the current status and score of the dataset, replace <ID> with the identifier from the previous post operation and make 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

To get the complete employee shift schedule, replace <ID> with the identifier from the previous post operation and make the following API call:

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

Next