Introduction
It's possible to migrate a workspace environment from one instance to another. In this article, we explain how this process works and what is required to get things started.
Migration process
The first step is to submit the request for the migration via a support ticket. This ticket has to be submitted by either the old or the new partner. The following information has to be included in the ticket:
The name of the environment that has to be migrated
Written approval for the migration from all parties involved:
The customer
The new partner
The old partner
Written approval for the costs of the migration (see the pricing page on the Partner Portal)
These costs are invoiced to the partner submitting the migration request
Once the migration request is submitted, a support agent will get in touch with you to plan the migration further. In the meantime, please see the technical changes required before and after the migration listed below.
Technical changes
To ensure a smooth migration, some changes are required both before and after the migration. These changes must be performed for each environment involved in the migration.
The steps slightly differ depending if the environment uses a custom URL for that specific environment. Ensure that you follow the correct steps to prevent issues.
No custom environment URL
If the environment does not have a custom environment URL, follow these steps:
Before the migration:
Go to the SSO app registration in Azure and click Authentication
Add an additional Redirect URI according to the format:
https://newpartner.url/environment/OAuth2/HandleAuthorityResponse
Replace "newpartner.url" with the instance URL of the new partner
Replace "environment" with the name of the workspace environment
Do not delete the existing Redirect URI, as users will still use this to log in until the migration
After the migration:
Go to the SSO app registration in Azure and click Authentication
Delete the old Redirect URI (the one containing the instance URL of the old partner)
Change the Front-channel logout URL according to the format:
https://newpartner.url/environment/SignOut
Replace "newpartner.url" with the instance URL of the new partner
Replace "environment" with the name of the workspace environment
(OPTIONAL) Update the URL as displayed in the welcome email, see this article for steps how to do this
With custom environment URL
If the environment does have a custom environment URL, follow these steps:
Before the migration:
Go to the SSO app registration in Azure and click Authentication.
Add an additional Redirect URI according to the format:
https://newpartner.url/environment/OAuth2/HandleAuthorityResponse
Replace "newpartner.url" with the instance URL of the new partner
Replace "environment" with the name of the workspace environment
Do not delete the existing Redirect URI, as users will still use this to log in until the migration
Change the Front-channel logout URL according to the format:
https://custom.url/environment/SignOut
Replace "custom.url" with the custom URL of the environment
Replace "environment" with the name of the workspace environment
As an example:
If your custom URL is workspace.domain.com;
And your environment name is companyname;
Then the logout URL becomes https://workspace.domain.com/companyname/SignOut
After the migration:
Go to the SSO app registration in Azure and click Authentication
Delete the old Redirect URI (the one containing the instance URL of the old partner)
(OPTIONAL) Update the URL as displayed in the welcome email, see this article for steps how to do this