This article is a work in progress, don't trust it's contents, yet.

Migrate to ETH ID's Matrix service

Except for the Computer Vision Lab (CVL) all D-ITET institutes and groups have to migrate away from D-ITET ISG's Matrix service to ETH ID's Matrix service. This article explains how to do this.
Read this manual completely before starting. You might want to do a simple migration or a more complex one, depending on your needs. So make sure you understand the necessary preparation and decide which steps of the migration you will do and which steps you'll leave out.
When you start, follow to the order of the migration steps outlined here.

Terms and abbreviations

The homeserver is the Matrix service on which an account or room was initially created. The following four homeservers are distinguished:

• The D-ITET homeserver will be referred to as the old homeserver, the ETH ID homeserver as the new homeserver.
  Make sure you know which is your old and new homeserver now.
  

• The credentials you use to login on both old and new homeservers is always your ETH login and ETH password

• Rooms on the old homeserver you have the role Admin in are referred to as Your rooms

Optional preparation

For the following migration steps it's convenient to open a browser window logged into your old and new account each, to be able to switch back and forth between them.

Visual distinction

• To be able to visually distinguish your old and new accounts, you might want to upload different profile pictures for the time of the migration

• It might also be helpful to change the display name of your accounts for the same purpose

Add other homeserver

Adding the new homeserver to the old account and vice versa enables searching for public rooms on the added homeserver:

1. In the column listing your rooms, klick on the plus symbol [+] to the right of the title Rooms:
   

2. From the popup menu select Explore public rooms:
   

3. Klick on the arrowhead pointing downwards [⋁] next to Matrix rooms [<homeserver>]:
   

4. In the popup menu select Add a new server:
   

5. Enter the homeserver of your account you're not working with right now:
   

6. Klick on Add

Replace your old with your new account in rooms you joined

Accept invites with your new account

1. Check if your new account already received invites to rooms your old account has joined:
   

2. Accept the invites for those rooms you want to join:
   

Check uninvited rooms' settings

With your old account, repeat the following steps for each room your new account hasn't been invited to, yet:

1. Hover your mouse over a room's name in the room list

2. Klick on the triple dots [···] when they appear

3. Select Settings in the popup menu:
   

4. Check the room's access settings under Security & Privacy → Who can access this room?
   

5. Note the room's address or ID from the last part of the room's URL, beginning with either a hash [#] or an exclamation mark [!]:

   • #<room address>:<rooms homeserver>

   • !<room id>:<rooms homeserver>

   Alternatively you can find a room's address in its settings under General → Room Addresses → Published Addresses → Main Address:
   
   And it's ID under Advanced → Room information:
   

Depending on the setting you can then join a room or ask for an invite.

Join rooms with your new account

This is possible if a room's access setting is Anyone who knows the room's link, apart from guests or Anyone who knows the room's link, including guests:
→ try to join these rooms with your new account by entering each room's URL in your browser's URL field:

• https://<new homeserver>/_matrix/client/#/room/#<room address>:<rooms homeserver>

• https://<new homeserver>/_matrix/client/#/room/!<room id>:<rooms homeserver>

Ask for an invite for your new account

This can be done if the room's access setting is Only people who have been invited:
→ use your old account to ask the room admins to invite your new account:
Please invite my account @<ETH username>:<new homeserver> due to the Matrix migration from D-ITET to ETH ID.

Leave rooms with your old account

After successfully joining a room with your new account, leave the room with your old account. This step is important, as deletion of a room from the old homeserver is only possible when there are no more members with local accounts:

1. Open the popup menu containing the room's settings again

2. Select Leave Room

Decrypt chat history with your new account

In case you're not interested in a room's chat history, skip ahead to the next step.
For your new account to be able to read the chat history of the freshly joined rooms, the end to end (E2E) room keys have to be exported from your old account and imported with your new account.
The E2E keys of a room are rotated every 7 days or after 100 messages so this step needs to be done quickly after joining a room.

Export E2E keys from your old account

In your old account:

1. Klick on your display name in the top left area to open a popup menu containing the account settings:
   

2. Select Security & Privacy:
   

3. Under Encryption → Cryptography klick on Export E2E room keys to save the room keys to a file:
   

Import E2E keys to your new account

In your new account:

1. As with the export step before, go to Settings → Security & Privacy → Encryption → Cryptography

2. Klick on Import E2E room keys to load the room keys from the file you previously saved

Bring your rooms to the new homeserver

You have the choice of recreating your rooms from scratch on the new homeserver and invite room members again with their new accounts. This is an easy way to clean up the chat history and memberships.
If you want to keep the chat history of a room, follow the steps below to synchronize your rooms to the new homeserver.

Exception: Local rooms

The exception are local rooms set up to be accessible only on their homeserver. They cannot be synchronized to another homeserver. Such rooms will have to be re-created on the new homeserver, the chat history will be lost.
Rooms with such a setup show This room is not accessible by remote Matrix servers under Room Settings → Advanced → Room information:

If you invite an account on the new homeserver to a local room on the old homeserver, the invite will fail.

Set up your new account as room admin

With your old account, repeat the following steps for each of your rooms:

1. Invite your new account with your old account

2. Have your new account accept the invite. Verify this happened in the chat history:
   

3. With your old account, grant your new account the role Admin by klicking on its profile picture appearing in the chat stating its joining.

4. Grant your new account the role Admin:
   

5. On the appearing warning dialogue, klick Continue

6. Verify the role change is visible in the room's chat history:
   

Replace room members with their new accounts

With your new account, repeat the following steps for each of your rooms:

1. If your room is only accessible by invite, invite members again with their new accounts.
   The Computer Vision Lab (CVL) won't migrate to the new homeserver and its members don't need to be invited with their new accounts.

2. Kick the corresponding old account out of your room to enable deletion of a room from the old homeserver

Leave your rooms with your old account

With your old account, repeat the following steps for each of your rooms:

1. Verify your new account has the role Admin

2. Leave the room

How to invite an account to one of your rooms

1. Right click on the room in the column listing all rooms

2. If the room has no members, yet, klick on the button Invite to this room:
   

3. Otherwise open the popup menu of a room containing Settings and select Invite People

4. Type the account you want to invite into the field left to the green button labelled Invite:
   

5. While you're typing, account suggestions appear in the lower part of the window. Select the account from the suggestions:
   

6. Klick on Invite

7. Verify the invite appeared in the room's chat history: