Relocating a friend means changing the base URL of the server that hosts the application. This implies to change also all the existing OSLC links plus any configuration bound to a friend's URL. Given this, it cannot be performed as simply as a regular friend update operation: it starts from the same update dialog but once submitted, a dedicated page to track the progress, failures and completion is displayed.

The process can take from several minutes to some hours to complete, this will depend on how much information needs to be updated and this is why the process is divided in three phases:

1. The Preview phase, which identifies the number of steps (changes) required to complete the process.
2. The Rehosting phase, which takes care of those changes.
3. The Conclusion phase, which commits the changes made in the Friend Update dialog and cleans up any temporary data.

This is a process with no revert action: once started (the Rehosting phase), there's no way to undo what has been done; the Conclusion phase will commit only the data changed in the Friends Update dialog, but even if this third phase is not performed, the changes made on the previous phase are already applied. Be aware also that starting each phase requires an administrator's explicit action; if the process is left alone, it will never conclude.

Regular users should not use the application while the whole process is running, doing so could leave some changes outdated.

This is an almost never required functionality in production environments, it's more required in testing/development environments where migrating data is common. The process below assumes that data is backed up and migration has been completed, changes will be locally-performed-only: this is not a migrating tool.

Finally, be aware that only the OSLC links owned by the OSLC domain of the ${local-app} application will be updated, no remote (not-owned) links will be changed. Bidirectional links must be updated from both ends, in their own application.

Relocating a Friend

Make sure to backup the entire database before applying the following steps and to have the permission to edit all the projects containing the OSLC data to update.

1. In the Friends page, choose the friend you want to update and click on the pencil icon located on the last column of the table.
2. Update friend's information in the opened dialog. To enable the The Root Services URI (and OAuth Key) field, click in the Relocate link.
3. Click on the Update button to start the previewing phase (the Root Services URI must be different and valid).
4. In the opened page, wait for the Preview phase to complete.
5. Once done, make sure no warning/error has being raised (no warning icon is displayed in the page).
6. Click on the Relocate button.
7. Click in the OK button of the confirmation dialog.
8. Once the Relocation phase is completed, make sure no warning/error has being raised (no warning icon is displayed in the page).
9. Click on the Conclude button.
10. Click in the OK button of the confirmation dialog.

If everything went OK, the chosen friend, OSLC links and all other configuration bound to the friend base URI has been updated and the friends page is displayed again.

If, on the other hand, something went wrong during the process, (steps 5 and 8), warning/error details can be viewed by downloading the process log. There's a log for each subtask and a generic log for the whole process. To download a subtask log, click in the corresponding icon of the last column in the subtasks table. To download the generic log, along with all subtasks' logs, click in the Download logs button. Warnings/errors in logs do not prevent the overall process completion, they help to identify something that possibly was missed (like permission) or something that needs to be done manually. If, for example, a link could not be updated by a temporary glitch in the network, that particular link could be updated manually before concluding the process. If something went really wrong, like the server going down at the middle of the process, it can be started over after restoring the backup.

Canceling a Friend Relocation

It was already said that there was no way to revert a concluded relocation. In this context, canceling means to abort a relocation preview which has not started the Rehosting phase. If, by any reason, the administrator changes his/her mind, at the middle of the process (step 5), it is possible to abort the process by clicking in the Cancel button located at the middle of the page. Be aware that this is the only step where the cancellation is possible, the button won't be visible at any other stage of the process.

Be also aware that no changes can be done, to the relocating friend, while the process is running. If any other administrator enters to the friends page, the last column of the corresponding friend will display only the icon to enter the friend relocation page; there won't be a way to start another relocation process nor to update a single field of the relocating friend.

Last but not least: the same administrator (privileges) that started the relocation process must complete it. Any administrator, on the other hand, can unblock the relocating friend by canceling the process.