Migrate your V2 IoT Central application to V3

Currently, when you create a new IoT Central application, it's a V3 application. If you previously created an application, then depending on when you created it, it may be V2. This article describes how to migrate a V2 to a V3 application to be sure you're using the latest IoT Central features.

To learn more, see the Retirement announcement.

To learn how to identify the version of an IoT Central application, see How do I get information about my application?.

The steps to migrate an application from V2 to V3 are:

  1. Create a new V3 application from the V2 application.
  2. Configure the V3 application.
  3. Delete to V2 application.

Create a new V3 application

IoT Central doesn't let you migrate to an existing V3 application. To move existing devices from a V2 to V3 application, use the migration wizard to create your V3 application.

The migration wizard:

  • Creates a new V3 application.
  • Checks your device templates for compatibility with V3.
  • Copies all your device templates to the new V3 application.
  • Copies all users and role assignments to the new V3 application.

Note

To ensure device compatibility with V3, primitive types in the device template become object properties. You don't need to make any changes to your device code.

You must be an administrator to migrate an application to V3.

  1. On the Administration menu, select Migrate to a V3 application:

    Screenshot that shows the application migration wizard

  2. Enter a new Application name and optionally change the autogenerated URL. The URL can't be the same as your current V2 application's URL. However, you can change the URL later after you delete your V2 application.

  3. Select Create a new V3 app.

    Screenshot that shows the options in the application migration wizard

    Depending on the number and complexity of your device templates, this process may take several minutes to complete.

    Warning

    The creation of your V3 application will fail if any device template has fields that start with a number or contain any of the following characters (+, *, ?, ^, $, (, ), [, ], {, }, |, \). The DTDL device template schema that V3 applications use doesn't allow these characters. Update your device template to resolve this issue before you migrate to V3.

  4. When your new V3 app is ready, select Open your new app to open it.

    Screenshot that shows the application migration wizard after the application migration

Configure the V3 application

After your new V3 application is created, make any configuration changes before you move your devices from the V2 application to the V3 application.

Tip

Take a moment to familiarize yourself with V3 as it has some differences from V2.

Here are some recommended configuration steps to consider:

When your V3 application is configured to meet your needs, you're ready to move your devices from your V2 application to your V3 application.

Move your devices to the V3 application

When this step is complete, all your devices communicate only with your new V3 application.

Important

Before you move your devices to your V3 application, delete any devices that you've created in the V3 application.

This step moves all your existing devices to your new V3 application. Your device data isn't copied.

Select Move all devices to start moving your devices. This step could take several minutes to complete.

Screenshot that shows the application migration wizard with the move devices option

After the move is complete, restart all your devices to ensure they connect to the new V3 application.

Warning

Don't delete your V3 application as your V2 application is now inoperable.

Delete your old V2 application

After you've validated that everything works as expected in your new V3 application, delete your old V2 application. This step ensures you don't get billed for an application you no longer use.

Note

To delete an application, you must have permissions to delete resources in the Azure subscription you chose when you created the application. To learn more, see Use role-based access control to manage access to your Azure subscription resources.

  1. In your V2 application, select the Administration tab in the menu
  2. Select Delete to permanently delete your IoT Central application. This option permanently deletes all data associated with that application.

Next steps

Now that you've learned how to migrate your application, the suggested next step is to review the Azure IoT Central UI to see what's changed in V3.