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

# Migration Guide

> Migrate from Fill API v1 to v2 with breaking changes and new features

This guide covers breaking changes and new features when migrating to Fill API v2.

## Breaking Changes

### Request Level

<Warning>
  The `contracts` list has been deprecated. Use `rules` instead for defining labor constraints.
</Warning>

| Deprecated  | Replacement | Notes                                        |
| ----------- | ----------- | -------------------------------------------- |
| `contracts` | `rules`     | Define constraints using the new Rule system |

### Employee Changes

| Deprecated    | Replacement | Notes                                    |
| ------------- | ----------- | ---------------------------------------- |
| `periodRules` | `rules`     | Use global rules with employee filtering |
| `contract`    | `rules`     | Reference rules instead of contracts     |

### Shift Changes

| Deprecated  | Replacement     | Notes                              |
| ----------- | --------------- | ---------------------------------- |
| `value`     | `min` and `max` | Specify exact staffing range       |
| `critical`  | `min` and `max` | Use `min` for required staffing    |
| `employees` | `assignments`   | Pre-assign with Assignment objects |
| `locked`    | `assignments`   | Set `locked: true` in Assignment   |
| `blacklist` | `blocklist`     | Renamed for inclusive terminology  |

<Info>
  New field `tags` added to shifts for grouping in rules (e.g., `EARLY`, `NIGHT`).
</Info>

## New Features

### Rules

Rules replace period rules and contracts with a more flexible system for counters and sequences.

<CodeGroup>
  ```json Old: Period Rule theme={null}
  {
    "period": {
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-10T17:00:00"
    },
    "maxWorkingDays": 4
  }
  ```

  ```json New: Rule theme={null}
  {
    "period": {
      "from": "2024-03-06T08:00:00",
      "to": "2024-03-10T17:00:00"
    },
    "constraint": "COUNTER",
    "type": "DAYS_WORKED",
    "max": 4
  }
  ```
</CodeGroup>

<Tip>
  Use `tags` in rules to apply constraints to specific shift types only.
</Tip>

See [Rules documentation](/guides/fill/examples/rule) for complete examples.

### Patterns

Define preferred or prohibited sequences of shifts across single or multiple days.

```json Pattern Example theme={null}
{
  "type": "MULTI_DAY",
  "satisfy": "PROHIBITED",
  "elements": [
    { "type": "ON", "tags": ["LATE"] },
    { "type": "ON", "tags": ["EARLY"] }
  ]
}
```

See [Patterns documentation](/guides/fill/examples/pattern) for complete examples.

### Demands

Specify staffing requirements independent of shift structure, allowing flexible coverage optimization.

```json Demand Example theme={null}
{
  "demands": [
    {
      "name": "Peak hours",
      "from": "2022-01-01T14:00:00",
      "to": "2022-01-01T18:00:00",
      "min": 3,
      "max": 5
    }
  ]
}
```

See [Demands documentation](/guides/fill/examples/demand) for complete examples.

### Assignments

Granularly specify pre-defined shift assignments with optional locking.

```json Assignment Example theme={null}
{
  "assignments": [
    {
      "shift": "morning-1",
      "employee": "Alice",
      "locked": true
    }
  ]
}
```

See [Lock Plan documentation](/guides/fill/examples/lock) for complete examples.

## Migration Checklist

<Steps>
  <Step title="Update shift definitions">
    Replace `value` with `min` and `max` properties:

    ```json theme={null}
    // Before
    { "value": 2 }

    // After
    { "min": 2, "max": 2 }
    ```
  </Step>

  <Step title="Convert contracts to rules">
    Migrate contract-based constraints to the new Rule format with `constraint` and `type` fields.
  </Step>

  <Step title="Update employee references">
    Remove `contract` and `periodRules` from employees. Define rules at the request level instead.
  </Step>

  <Step title="Rename blacklist to blocklist">
    Update any `blacklist` fields on shifts to `blocklist`.
  </Step>

  <Step title="Convert locked shifts to assignments">
    Replace `employees` and `locked` on shifts with the `assignments` array.
  </Step>
</Steps>