> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Employees

> Learn how to define the employees that will be used in the roster.

Employees form the foundation for all schedules produced by the solver. The primary objective for all produced schedules is to assign employees to shifts in such a way that they can optimally cover all demand for labour.

<Card title="Employee schema">
  <ResponseField name="employee" type="object">
    <Expandable title="properties">
      <ResponseField name="id" type="string" required>
        Unique identifier for this employee.
      </ResponseField>

      <ResponseField name="labels" type="array of string">
        List of labels assigned to this employee. Labels can be used in rules to group employees.
      </ResponseField>

      <ResponseField name="attributes" type="array of object">
        List of attributes that this employee has. Shifts, demands and tasks can have requirements on the attributes that an employee has.
      </ResponseField>

      <Expandable title="attributes – item structure">
        <ResponseField name="category" type="string">
          The category of the attribute.
        </ResponseField>

        <ResponseField name="values" type="array of string" required>
          The values that the employee has for this attribute. For example, an employee could have the values "marketing" and "finance" for an attribute with the category "department".
        </ResponseField>

        <ResponseField name="periods" type="object">
          List of periods in the schedule. Periods can be defined explicitly or through a recurrent definition (for example, to generate weeks).
        </ResponseField>

        <Expandable title="periods – properties">
          <ResponseField name="days" type="object">
            List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period.
          </ResponseField>

          <Expandable title="days – properties">
            <ResponseField name="dates" type="array of date (date)">
              List of dates in the schedule. Only allowed in CALENDAR payloads.
            </ResponseField>

            <ResponseField name="dayIndices" type="array of dayIndex">
              List of day indices in the schedule. Only allowed in RECURRING payloads.
            </ResponseField>

            <ResponseField name="daysOfWeek" type="array of dayOfWeek">
              List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
            </ResponseField>

            <ResponseField name="startTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>

            <ResponseField name="endTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>
          </Expandable>

          <ResponseField name="customDefinitions" type="array of object">
            List of custom period definitions. Each custom period definition defines one period in the schedule.
          </ResponseField>

          <Expandable title="customDefinitions – item structure">
            <ResponseField name="startDay" type="object">
              Describes one day in the schedule.
            </ResponseField>

            <Expandable title="startDay – properties">
              <ResponseField name="date" type="string (date)">
                Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
              </ResponseField>

              <ResponseField name="dayIndex" type="integer">
                Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
              </ResponseField>
            </Expandable>

            <ResponseField name="endDay" type="object">
              Describes one day in the schedule.
            </ResponseField>

            <Expandable title="endDay – properties">
              <ResponseField name="date" type="string (date)">
                Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
              </ResponseField>

              <ResponseField name="dayIndex" type="integer">
                Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
              </ResponseField>
            </Expandable>

            <ResponseField name="startTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>

            <ResponseField name="endTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>

            <ResponseField name="applyTimeToAllDays" type="boolean">
              If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
            </ResponseField>
          </Expandable>

          <ResponseField name="recurrentDefinition" type="object">
            A recurrent definition to easily create a set of similar periods.
          </ResponseField>

          <Expandable title="recurrentDefinition – properties">
            <ResponseField name="daysPerPeriod" type="integer" required>
              The number of days in each period.
            </ResponseField>

            <ResponseField name="daysBetweenStarts" type="integer">
              The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods.
            </ResponseField>

            <ResponseField name="startDay" type="object">
              Describes one day in the schedule.
            </ResponseField>

            <Expandable title="startDay – properties">
              <ResponseField name="date" type="string (date)">
                Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
              </ResponseField>

              <ResponseField name="dayIndex" type="integer">
                Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
              </ResponseField>
            </Expandable>

            <ResponseField name="endDay" type="object">
              Describes one day in the schedule.
            </ResponseField>

            <Expandable title="endDay – properties">
              <ResponseField name="date" type="string (date)">
                Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
              </ResponseField>

              <ResponseField name="dayIndex" type="integer">
                Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
              </ResponseField>
            </Expandable>

            <ResponseField name="startTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>

            <ResponseField name="endTime" type="string (time)">
              TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
            </ResponseField>

            <ResponseField name="applyTimeToAllDays" type="boolean">
              If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
            </ResponseField>
          </Expandable>

          <ResponseField name="labels" type="array of string">
            Provide labels to re-use periods that were defined in the configuration.
          </ResponseField>
        </Expandable>
      </Expandable>

      <ResponseField name="roles" type="array of object">
        Optional list of roles that this employee can work. Each role can have additional attributes that the employee has when working that role.
      </ResponseField>

      <Expandable title="roles – item structure">
        <ResponseField name="id" type="string">
          Unique identifier for this role.
        </ResponseField>

        <ResponseField name="attributes" type="array of object">
          List of additional attributes this employee has when they work in this role.
        </ResponseField>

        <Expandable title="attributes – item structure">
          <ResponseField name="category" type="string">
            The category of the attribute.
          </ResponseField>

          <ResponseField name="values" type="array of string" required>
            The values that the employee has for this attribute. For example, an employee could have the values "marketing" and "finance" for an attribute with the category "department".
          </ResponseField>

          <ResponseField name="periods" type="object">
            List of periods in the schedule. Periods can be defined explicitly or through a recurrent definition (for example, to generate weeks).
          </ResponseField>

          <Expandable title="periods – properties">
            <ResponseField name="days" type="object">
              List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period.
            </ResponseField>

            <Expandable title="days – properties">
              <ResponseField name="dates" type="array of date (date)">
                List of dates in the schedule. Only allowed in CALENDAR payloads.
              </ResponseField>

              <ResponseField name="dayIndices" type="array of dayIndex">
                List of day indices in the schedule. Only allowed in RECURRING payloads.
              </ResponseField>

              <ResponseField name="daysOfWeek" type="array of dayOfWeek">
                List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
              </ResponseField>

              <ResponseField name="startTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>

              <ResponseField name="endTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>
            </Expandable>

            <ResponseField name="customDefinitions" type="array of object">
              List of custom period definitions. Each custom period definition defines one period in the schedule.
            </ResponseField>

            <Expandable title="customDefinitions – item structure">
              <ResponseField name="startDay" type="object">
                Describes one day in the schedule.
              </ResponseField>

              <Expandable title="startDay – properties">
                <ResponseField name="date" type="string (date)">
                  Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
                </ResponseField>

                <ResponseField name="dayIndex" type="integer">
                  Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
                </ResponseField>
              </Expandable>

              <ResponseField name="endDay" type="object">
                Describes one day in the schedule.
              </ResponseField>

              <Expandable title="endDay – properties">
                <ResponseField name="date" type="string (date)">
                  Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
                </ResponseField>

                <ResponseField name="dayIndex" type="integer">
                  Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
                </ResponseField>
              </Expandable>

              <ResponseField name="startTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>

              <ResponseField name="endTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>

              <ResponseField name="applyTimeToAllDays" type="boolean">
                If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
              </ResponseField>
            </Expandable>

            <ResponseField name="recurrentDefinition" type="object">
              A recurrent definition to easily create a set of similar periods.
            </ResponseField>

            <Expandable title="recurrentDefinition – properties">
              <ResponseField name="daysPerPeriod" type="integer" required>
                The number of days in each period.
              </ResponseField>

              <ResponseField name="daysBetweenStarts" type="integer">
                The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods.
              </ResponseField>

              <ResponseField name="startDay" type="object">
                Describes one day in the schedule.
              </ResponseField>

              <Expandable title="startDay – properties">
                <ResponseField name="date" type="string (date)">
                  Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
                </ResponseField>

                <ResponseField name="dayIndex" type="integer">
                  Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
                </ResponseField>
              </Expandable>

              <ResponseField name="endDay" type="object">
                Describes one day in the schedule.
              </ResponseField>

              <Expandable title="endDay – properties">
                <ResponseField name="date" type="string (date)">
                  Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules.
                </ResponseField>

                <ResponseField name="dayIndex" type="integer">
                  Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules.
                </ResponseField>
              </Expandable>

              <ResponseField name="startTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>

              <ResponseField name="endTime" type="string (time)">
                TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight.
              </ResponseField>

              <ResponseField name="applyTimeToAllDays" type="boolean">
                If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. Default: false.
              </ResponseField>
            </Expandable>

            <ResponseField name="labels" type="array of string">
              Provide labels to re-use periods that were defined in the configuration.
            </ResponseField>
          </Expandable>
        </Expandable>
      </Expandable>

      <ResponseField name="preassignedShifts" type="array of object">
        List of assignments that are pre-assigned to this employee.
      </ResponseField>

      <Expandable title="preassignedShifts – item structure">
        <ResponseField name="shiftId" type="string" required>
          Unique identifier for the shift.
        </ResponseField>

        <ResponseField name="days" type="object" required>
          List of days in the schedule.
        </ResponseField>

        <Expandable title="days – properties">
          <ResponseField name="dates" type="array of date (date)">
            List of dates in the schedule. Only allowed in CALENDAR payloads.
          </ResponseField>

          <ResponseField name="dayIndices" type="array of dayIndex">
            List of day indices in the schedule. Only allowed in RECURRING payloads.
          </ResponseField>

          <ResponseField name="daysOfWeek" type="array of dayOfWeek">
            List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.
          </ResponseField>
        </Expandable>

        <ResponseField name="isLocked" type="boolean">
          Whether the shift is locked. Locked shifts cannot be changed by us. For read-only employees, all shifts are automatically considered locked. Default: false.
        </ResponseField>

        <ResponseField name="roleId" type="string">
          The role id of the role that the employee has when working this shift. Needs to match a role id from the employee's list of roles.
        </ResponseField>
      </Expandable>

      <ResponseField name="isReadOnly" type="boolean">
        If set to true, the employee will only work their preassigned shifts. These will not be altered, and we will not assign new shifts to this employee. Default: false.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Card>

## Attributes

Employee attributes provide a flexible way to specify custom characteristics for each employee. These attributes can be used to determine eligibility for shifts, demands, or tasks. In addition, some rules can be configured to apply to all employees that meet certain attribute requirements. Some good examples of characteristics where it might make sense to use attributes are `departments`, `competences`, or `personnel-groups`.

Each attribute must have its own unique category indicating what kind of attribute it is. An employee can have multiple values for the same attribute.

Here's an example of how to specify attributes for an employee:

<Tip>
  The following example shows an employee that is part of the departments `finance` and `hr`, and has the competences `manager` and `accountant`. Finally, they are part of the personnel group `group-1`.

  ```json theme={null}
  {
    "id": "employee-1",
    "attributes": [
      {
        "category": "department",
        "values": ["finance", "hr"]
      },
      {
        "category": "competence",
        "values": ["manager", "accountant"]
      },
      {
        "category": "personnel-group",
        "values": ["group-1"]
      }
    ]
  }
  ```
</Tip>

## Preassigned shifts

It is possible to start the solver from a partially filled schedule where employees already have some shifts assigned to them. These are specified in `preassignedShifts`. If these pre-assignments are set to `isLocked`, the solver will never change them. The solver therefore considers unlocked preassigned shifts as suggestions.

<Tip>
  The following example shows an employee that is preassigned to work `shift-1` shifts on each of the first four days of the schedule. These assignments are set as `isLocked` and will not be changed by the solver.

  ```json highlight={6} theme={null}
  {
    "id": "employee-1",
    "preassignedShifts": [
      {
        "shiftId": "shift-1",
        "isLocked": true,
        "days": {
          "dayIndices": [0, 1, 2, 3]
        }
      }
    ]
  }
  ```
</Tip>

## Read-only employees

You can set an employee to `isReadOnly` to indicate that the solver should only use their preassigned shifts and not assign them to any new shifts. This is useful when you want to preserve certain employee assignments while allowing the solver to optimize the rest of the schedule.

When an employee is marked as `isReadOnly`, the solver will:

* Use all their preassigned shifts (regardless of whether they are locked or unlocked)
* Not assign the employee to any additional shifts beyond their preassigned ones

<Tip>
  The following example shows an employee that is set to read-only. The solver will only use their preassigned shifts and will not assign them to any new shifts.

  ```json highlight={3} theme={null}
  {
    "id": "employee-1",
    "isReadOnly": true,
    "preassignedShifts": [
      {
        "shiftId": "shift-1",
        "days": {
          "dayIndices": [0, 1, 2, 3]
        }
      }
    ]
  }
  ```
</Tip>