---
alias: user-guide-automation-controller-versions
tags:
- automation
- connect iot
description: "Put an Automation Controller change into production with versions: what reaches running instances, moving one instance at a time, rolling back, and the Update Controller Versions wizard"
---

# Change a Controller in Production

The **Automation Controller** is a versioned entity. Each **Automation Controller Instance** runs one version of it: the version it was connected with, until you update the instance. Instances of one controller can run different versions at the same time.

Use this page to decide where to make a change, to move instances to a new version one at a time, to roll back, and to review what the **Update Controller Versions** wizard changes in your workflows.

## What Reaches a Running Instance

A running controller follows changes to the workflows of the version it runs, and only of that version.

| Change | What the running instances do |
|---|---|
| A workflow of a version in the `Created` state is added, changed, or removed. | Every instance that runs this version applies the change at once. A changed Setup workflow still needs a restart, and an added driver needs a replacement of the instance. See [[operation-guide-connect-iot-runbook#what-a-change-reaches]]. |
| A new version of the controller is created. | No instance moves. Each instance keeps the version it runs. |
| A version is approved or set `Effective`. | No instance moves. Update each instance that must run it. |

Table: What a controller change reaches

!!! warning
    You can edit only a version in the `Created` state, and every edit reaches every instance that runs that version. Run production instances on a version that is no longer edited, and make each change in a new version.

## Version States

A new version starts in the `Created` state, where you can [[user-guide-edit-automation-controller|edit]] it. To release it, add it to a **Change Set**, request approval, and approve it: the version becomes `Active`. Set it `Effective` with [[user-guide-set-version-effective]], or enable **Make Change Set Items Effective on Approval** on the **Change Set**. For the full state model, see [[user-guide-universal-state-model]] and [[user-guide-change-set-index]].

**Update** on the **Connect IoT** page offers every version of the instance's controller, in any revision, that is in the `Created`, `Active`, or `Effective` state. A version waiting for approval (`Frozen`) or terminated is not offered. A revision marked obsolete cannot be assigned to an instance again; see [[user-guide-mark-as-obsolete-and-reactivate]].

## Put a New Version into Production

1. On the **Automation Controller** page, open the version that runs in production and select **New** followed by **Version**. Select the **Change Set**. See [[user-guide-create-automation-controller]].
2. Change the workflows of the new version in the designer. No running instance receives these changes.
3. Try the new version on one instance:
    1. On the **Connect IoT** page, select the instance and select **Stop**. **Update** is available only for an instance that is not running.
    2. Select **Update**. In the **Controller** step, select the new version and select **Next**. The wizard does not accept the version that the instance already runs.
    3. In the **Automation Driver Instances** step, check the driver instances. For a driver that the new version adds, select its entity and **Automation Manager**. Select **Update**. The instance must end with one driver instance for each driver of the new version and its parent controllers. Otherwise, the update fails.
    4. Select **Start**. The new controller logs one `Adding workflow` line for each workflow of the new version.
4. While the version is `Created`, every further edit reaches this instance at once. When it behaves as expected, request approval of the **Change Set** and approve it.
5. Move the remaining instances to the new version, either one at a time as in step 3, or with an **Automation Scheduled Action** (ASA) that waits until each entity is idle. See [Move Many Instances with an ASA](#move-many-instances-with-an-asa).

For the procedure on the **Connect IoT** page, see [[user-guide-automation-connect-iot]].

### What an Update Costs

Stopping and starting the instance costs what a restart costs: every workflow of the controller starts again, each Setup chain runs again from `OnInitialize`, values stored as `Temporary` are lost, and a file driver with `ignoreInitial` set to `false` reports every file still in its folder as new. See [[operation-guide-connect-iot-runbook#restart-an-instance]].

The instance keeps its name and ID. The data store of an instance belongs to its instance ID and is kept in the persistency location of its **Automation Manager**, so values stored as `Persistent` stay with the instance and the new version reads them.

A value that the new version stores under an identifier that the old version already used starts from the old value. Rename the identifier when its meaning changes. See [[user-guide-automation-task-core-store]].

### Move Many Instances with an ASA

The **Update Controller Version** action of an **Automation Scheduled Action** stops each instance, moves it to the revision and version you specify, and starts it again, when its Detector and Acceptance Gates report that the entity is ready. It does not require you to stop the instance first. See [[user-guide-automation-scheduled-action-action]] and the controller update scenarios [[tutorials-automation-scheduled-action-scenario-02-fixed-validity-window]], [[tutorials-automation-scheduled-action-scenario-03-no-materials-on-resource]], and [[tutorials-automation-scheduled-action-scenario-04-workflow-ready-signal]].

The action matches the drivers of the instance to the drivers of the target version by name. It fails when the target version has a different number of drivers, or when a driver cannot be matched. For a version that adds a driver, update each instance on the **Connect IoT** page, or replace it as described in [[operation-guide-connect-iot-runbook#replace-an-instance]].

## Roll Back

- Move the instance back to the earlier version: **Stop**, **Update** with the earlier version, and **Start**. The earlier version stays selectable while it is `Active` or `Effective` and its revision is not obsolete.
- For many instances, use an **Update Controller Version** action with the earlier revision and version.
- A rollback costs what an update costs. Values stored as `Persistent` by the newer version stay in the data store of the instance.

## Update Controller Versions Wizard

The wizard moves the tasks and converters of a controller's workflows to newer package versions, runs their migrations, and saves the result as a new version of the controller. Run it after you synchronize an **Automation Tasks Library** ([[user-guide-automation-tasks-library-index]]) and as part of the 12.0 upgrade.

Open the version to update from on the **Automation Controller** page and select **Update** in the **Connect** group of the top ribbon. The button is available while the revision of the controller is in the Active revision state. The wizard has the following steps:

| Step | What it shows or changes |
|---|---|
| **Change Set** | The **Change Set** of the new version. |
| **Controller Version** | The version of the controller package. It lists the versions available in the repository and selects the highest. Shown for the Connect IoT scope only. |
| **Drivers** | Each driver of the controller with its **Automation Driver Definition**, **Automation Protocol**, and package version. This step changes nothing: the driver package comes from the **Automation Protocol**. Shown for the Connect IoT scope only. |
| **Tasks and Converters** | The tasks and converters, grouped by package, whose version in the workflows differs from the version that the controller's packages offer. **Update All Tasks And Converters** is selected and cannot be cleared. |

Table: Steps of the Update Controller Versions wizard

When you select **Update**, the wizard does the following for each workflow:

- Sets the new package version on every listed task and converter.
- Runs the migrations that the task or converter declares up to its new version. A migration can change settings, replace a task, or rename its ports and links. For example, the 12.0.0 migrations replace the file tasks with **Execute Equipment Command** and **On Equipment Event**.
- Skips the tasks that show the `FALLBACK` label, from the task packages that 12.0 no longer bundles, and leaves them as they are.
- Skips the workflows inherited from a parent controller. Update those on the parent. See [[user-guide-extend-automation-controller]].

The result is a new version in the `Created` state. Running instances keep their version until you update them.

### Migration Log

When the update completes, the wizard shows the messages of every migration it ran as feedback messages. Each message starts with the task it concerns: the task ID and name in Data Flow, the task name in Control Flow. A warning usually names a task that the migration could not convert and that you must change by hand. Keep the messages for the review.

### Review the New Version

1. Open each task that a migration message names, and complete the change it asks for.
2. Open every workflow of the new version. Check that no task shows the `FALLBACK` label, and that the links of migrated tasks still connect the ports you expect.
3. Try the new version on one instance, as described in [Put a New Version into Production](#put-a-new-version-into-production), before you approve it.

!!! info
    The bundled task packages must be moved to Automation Tasks Library packages on 11.x, before the upgrade. After the upgrade, the wizard skips them. See the [bundled task packages migration guide](https://developer.criticalmanufacturing.com/explore/guides/migration/version-specific/1200/connect_iot_bundled_tasks_1200/), the [Connect IoT 12.0 upgrade checklist](https://developer.criticalmanufacturing.com/explore/guides/migration/version-specific/1200/connect_iot_upgrade_checklist_1200/), and the [Automation Controller version management walkthrough](https://developer.criticalmanufacturing.com/explore/guides/customizations/automation/how-tos/controller_upgrade/).