> ## 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.

# Availability

> Block employees from working on specific days or shifts, or make it desired/undesired for them to work on specific days or shifts.

export const AvailabilityMetricRows = () => <>
    <tr>
      <td><code className="whitespace-nowrap">AVAILABILITY.WORKED_MINUTES</code></td>
      <td>Total minutes worked in the periods covered by Availability rules.</td>
    </tr>
    <tr>
      <td><code className="whitespace-nowrap">AVAILABILITY.ASSIGNMENTS</code></td>
      <td>Number of assignments relevant to Availability rules.</td>
    </tr>
  </>;

This rule can be used for three purposes, all related to which periods or shifts an employee should be considered available for:

1. Mark an employee as **strictly unavailable** for specific periods or shifts.
2. Mark an employee as **available but undesirable** for specific periods or shifts.
3. Mark an employee as **available and desirable** for specific periods or shifts.

<Card title="Rule schema">
  <ResponseField name="availabilityRule" type="object">
    Used to indicate when employees are strictly or preferably available or unavailable to work.

    <Expandable title="properties">
      <ResponseField name="id" type="string" required>
        Unique identifier for the rule.
      </ResponseField>

      <ResponseField name="labels" type="array of string">
        Labels for the rule. Labels can be used to group rules together. For example, if multiple rules are related to the same shift type, they can all be labeled with the same label.
      </ResponseField>

      <ResponseField name="importance" type="string (enum: NONE | VERY_LOW | LOW | MEDIUM | HIGH | ...)" required>
        The importance of the rule. The higher the importance, the more it will be taking the rule into account. Under strict importance, the rule may never be violated.
      </ResponseField>

      <ResponseField name="isDesired" type="boolean" required>
        If set to true, it will be considered preferable for employees to work the shifts that this rule applies to during the specified periods. If set to false, we will try to avoid assigning applicable shifts to employees during the specified periods. If importance is set to strict, this must be false.
      </ResponseField>

      <ResponseField name="filters" type="object">
        Filters to determine the scope of the rule. Used to decide which employees and which shifts the rule should be applied to. Filters use logical OR filtering - an employee or shift is included as long as it is targeted by any of the filters.
      </ResponseField>

      <Expandable title="filters – properties">
        <ResponseField name="employees" type="object">
          Used to filter which employees the rule should be applied to. If not specified, the rule applies to all employees.
        </ResponseField>

        <Expandable title="employees – properties">
          <ResponseField name="ids" type="array of string">
            List of employee ids that the rule should be applied to.
          </ResponseField>

          <ResponseField name="labels" type="array of string">
            List of employee labels that the rule should be applied to.
          </ResponseField>

          <ResponseField name="matchTypes" type="object" />

          <Expandable title="matchTypes – properties">
            <ResponseField name="ids" type="string (enum: NONE | ANY | ALL)">
              Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: "ANY".
            </ResponseField>

            <ResponseField name="labels" type="string (enum: NONE | ANY | ALL)">
              Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: "ANY".
            </ResponseField>
          </Expandable>
        </Expandable>

        <ResponseField name="shifts" type="object">
          Used to filter which shifts the rule should be applied to. If not specified, the rule applies to all shifts.
        </ResponseField>

        <Expandable title="shifts – properties">
          <ResponseField name="ids" type="array of string">
            List of shift ids that the rule should be applied to.
          </ResponseField>

          <ResponseField name="labels" type="array of string">
            List of shift labels that the rule should be applied to.
          </ResponseField>

          <ResponseField name="matchTypes" type="object" />

          <Expandable title="matchTypes – properties">
            <ResponseField name="ids" type="string (enum: NONE | ANY | ALL)">
              Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: "ANY".
            </ResponseField>

            <ResponseField name="labels" type="string (enum: NONE | ANY | ALL)">
              Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: "ANY".
            </ResponseField>
          </Expandable>
        </Expandable>

        <ResponseField name="work" type="object">
          Defines filtering for specific work that the rule should be applied to. For example, it can be used to apply the rule only to work carried out in specific roles.
        </ResponseField>

        <Expandable title="work – properties">
          <ResponseField name="roles" type="object">
            Used to apply the rule only to work carried out in specific roles.
          </ResponseField>

          <Expandable title="roles – properties">
            <ResponseField name="ids" type="array of string">
              List of relevant role ids.
            </ResponseField>
          </Expandable>

          <ResponseField name="workloads" type="object">
            Used to apply the rule only to work carried out with specific workload categories.
          </ResponseField>

          <Expandable title="workloads – properties">
            <ResponseField name="categories" type="array of string">
              If specified, the shift must have at least one of the workload categories specified in this list.
            </ResponseField>
          </Expandable>
        </Expandable>
      </Expandable>

      <ResponseField name="options" type="object">
        Additional options for how the rule should be applied.
      </ResponseField>

      <Expandable title="options – properties">
        <ResponseField name="periodHandling" type="string (enum: PARTIAL | COMPLETE)">
          Used to indicate whether partial fulfillment per period is acceptable (PARTIAL) or not (COMPLETE). This setting can only be used for undesired rules. Default: "PARTIAL".
        </ResponseField>
      </Expandable>

      <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>
</Card>

## Strict unavailability

To define certain periods as strictly unavailable for an employee, simply specify the periods in the rule. The solver will then never assign shifts to the employee during these periods.

<Tip>
  The rule below makes it strictly impossible for employee with id `employee-1` to work on weekends.

  ```json theme={null}
  {
    "id": "eac-weekends",
    "importance": "STRICT",
    "isDesired": false,
    "filters": {
      "employees": {
        "ids": ["employee-1"]
      }
    },
    "periods": {
      "labels": ["WEEKENDS"]
    }
  }
  ```
</Tip>

## Undesired availability

To mark that an employee would rather not work during certain periods, set the `isDesired` field to `false` and choose an [importance level](/v2/rules/index#rule-importance) different than `STRICT`. The solver will try to avoid assigning shifts to the employee during these periods, but it is not strictly forbidden.

<Tip>
  The rule below makes it undesirable for employee with id `employee-1` to work on Mondays or Thursdays.

  ```json theme={null}
  {
    "id": "eac-undesired-mondays-thursdays",
    "importance": "HIGH",
    "isDesired": false,
    "filters": {
      "employees": {
        "ids": ["employee-1"]
      }
    },
    "periods": {
      "days": {
        "daysOfWeek": ["MON", "THU"]
      }
    }
  }
  ```
</Tip>

## Desired availability

To mark that an employee prefers working on certain periods or shifts, set the `isDesired` field to `true` and choose an [importance level](/v2/rules/index#rule-importance) different than `STRICT` (`STRICT` is currently not supported on desired rules).

<Tip>
  The rule below makes it preferred to assign shifts with shift label `night` to employee with id `employee-1` on Mondays, Tuesdays or Wednesdays.

  ```json theme={null}
  {
    "id": "eac-desired-night-shifts",
    "importance": "MEDIUM",
    "isDesired": true,
    "filters": {
      "employees": {
        "ids": ["employee-1"]
      },
      "shifts": {
        "labels": ["night"]
      }
    },
    "periods": {
      "days": {
        "daysOfWeek": ["MON", "TUE", "WED"]
      }
    }
  }
  ```
</Tip>

## Availability with work filters

You can also use work filters to target specific kinds of work. With role and workload filters, you can make the rule apply only to work carried out in certain roles and with certain workload categories.
It is also possible to apply role or workload filters separately.

<Tip>
  The rule below makes it undesirable for employee with id `employee-1` to work shifts in role `role-1` with workload category `on_call` on weekends. Work in other roles or with other workload categories is not targeted by this rule.

  ```json theme={null}
  {
    "id": "eac-undesired-weekend-role-1-oncall-workload",
    "importance": "HIGH",
    "isDesired": false,
    "filters": {
      "employees": {
        "ids": ["employee-1"]
      },
      "work": {
        "roles": {
          "ids": ["role-1"]
        },
        "workloads": {
          "categories": ["on_call"]
        }
      }
    },
    "periods": {
      "labels": ["WEEKENDS"]
    }
  }
  ```
</Tip>

## Metrics

The following [status metric](/v2/concepts/metrics) is available for tracking on Availability rules:

<table>
  <thead><tr><th>Metric key</th><th>Description</th></tr></thead>

  <tbody>
    <AvailabilityMetricRows />
  </tbody>
</table>