# Migration Guide

This guide walks you through upgrading from UPV Webservices to the new UDiTH Portal. Alternatively, you can set up a fresh instance.

## Breaking changes

> ⚠️ **Important**: Review these changes before proceeding with your migration.

### URL structure

- **Model URLs have changed** - BBV includes basic compatibility, but you should update to the new URLs as soon as possible.
- **Portal default path** has changed from `/UpvWebservices` to `/Portal`.
  - On Linux, `/` is used by default.
  - This is configurable and can be customised during installation.

### Model Management

- **Import requirement**: All models must go through the new import procedure in order to be compatible with BBV and Streaming.
- **Read-only imports**: Imported models cannot be modified after import.
  - If you need frequent file updates, wait for a future release that supports individual file updates.
- **New format required**: Models must be packaged as ZIP files with the required folder structure.

### Permissions & Database

- **Unified permissions**: There are currently no separate permissions for BBV and Streaming. This is planned to change in a future version.
- **Database requirements**: The Tag Register functionality requires SQL Server. The storage limits in SQL Express may not be sufficient.

### Model Format Requirements

When preparing models for import:

- **Create ZIP archives** from your model folders.
- **Ensure the correct structure**: The `Data` folder must be at the top level of the ZIP file.
- **Validate the structure** before importing to avoid errors.

### MSSQL

- When using the new Tag Register functionality, SQL Express is no longer sufficient because of the storage limitations in Express.

### Installer

- The installer no longer validates prerequisites. Ensure that all prerequisites are met before installation.

## Backups

Ensure that backups of the database and models are created before performing any migration.

## Migration

1. **Verify model accessibility** on the Portal server.
2. **Document all secrets** and save `sharedsettings.json`.
3. **Create comprehensive backups** of the database and models.
4. **Uninstall the web server** and restart the server.
5. **Stop and uninstall the render server**.
6. **Install Portal** in the new installation path and enter the required secrets during setup.
7. **Restart IIS** and verify that Portal is accessible.
8. **Install the new UDiTH render server** and configure it against the **new** Portal instance.
   - Note: models no longer need to be stored on the render server.
9. **Copy the model folders** to the `Models` directory of the new installation.
10. **Use the Migration tab** in the Portal web interface:
    - Navigate to **Central Model Repository → Migration**.
    - Convert the models to the new format and copy them to the import folder.

    ![Model Migration](media/Portal_Migration.png)

11. **Import the models** via the **Model import** section. Create new models and assign model IDs and version IDs.
12. **Configure permissions** for the newly imported models.
13. **Import future models** directly in the new format by using the import folder.