Article last updated on the 30th of September, 2022.
In this article we will demonstrate how to migrate WorkPoint solutions from version 3.X to version 4.X.
To migrate a WorkPoint solution from version 3.X to version 4.X, the following prerequisites must be met:
- The user granting the necessary permissions (delegated and application) in step 4-8 must be a tenant administrator.
- The user performing the steps after granting the necessary permissions must be a SharePoint administrator.
- The license used for the solution must include the "Migrate to V4" feature. If this feature is not enabled on your license, please contact your WorkPoint partner or WorkPoint Sales at email@example.com.
Note that adding the feature to migrate to WorkPoint version 4 requires moving to a new license model. For more information on the changes that will occur to your license model, please contact your WorkPoint partner. If you are a partner, please contact WorkPoint Sales at firstname.lastname@example.org.
3. Migrating a solution
The migration from version 3 to version 4 of WorkPoint 365 is performed inside the WorkPoint administration:
- In your WorkPoint solution, click the "Home" button.
- In the side panel, click the gear-icon to access the WorkPoint administration.
- In the global settings menu in the WorkPoint administration, click "Update".
This opens the "Update" page for the solution:
The first thing you need to do is to make sure you grant or have signed up with Delegated and Application permissions.
To do this, follow these steps:
- To sign up with Delegated and Application permissions, click the "here" link.
- In the "Tenant" field, type in the name of your tenant. In this demonstration, our tenant is named "m365b711351".
- For "Sign-up with delegated and application permissions", click the "Sign-up" button.
- Sign in with your tenant administrator account.
- Please take a moment to read which permissions WorkPoint requests. WorkPoint requires the mentioned permissions in order to run the migration. If you consent to grant WorkPoint the mentioned permissions, click the "Accept" button.
WorkPoint requests the mentioned permissions in order to provide as smooth and automatic a migration process as possible. As WorkPoint does not know which features and functionalities are used in your WorkPoint solution, the Delegated and Application permissions requested covers all scenarios.
Note that if you cannot successfully grant the consents above, you can try granting the "Delegated permissions" first, using the first button in the list of permissions in pt. 6, and then try and grant the "Delegated and Application permissions".
After successfully consenting to the permissions mentioned, the following page is displayed:
We can now proceed with the migration inside the "Update" page in the WorkPoint administration:
- To proceed to the next steps in the migration process, click the "Start migration to version 4" button.
This process will add the "WorkPoint 365 App" to the tenant app catalog (not the site of the WorkPoint solution).
After the app has been added, the "Update" page changes to the following:
- A message is displayed saying that the app was successfully added to the tenant app catalog.
- The next step in the migration process is so request approval for the WorkPoint 365 App. To do this, click the "Request approval for Add-in." link.
- To request approval for the app, click "Request Approval".
- Optionally type in a reason for the app request and click the "Request" button.
After requesting approval, you will be redirected to your current app requests page in SharePoint.
To continue, we go back go the "Update" page in the WorkPoint administration:
- To approve the app request, click the "Go to Pending App Request" link.
- In the "App Requests" page, click "Approve" for the WorkPoint 365 app.
- Optionally type in a comment for the request response and click the "Approve" button.
After successfully approving the app request, you are redirected to the App Requests page, from where the app request should have disappeared.
We can now continue the migration process in the "Update" page in the WorkPoint administration:
- The next step in the migration process is to install the WorkPoint 365 App on the WorkPoint site. To do this, click the "Install version 4 App on your solution" link.
To add the WorkPoint 365 App to the WorkPoint site, click the "ADD IT" button.
- In the pop up window, click the "Trust it" button.
The WorkPoint 365 App will now be added to the WorkPoint site:
Once the app has been successfully added, it will no longer be grayed out:
Once the app has been successfully added, a new link appears in the "Update" page in the WorkPoint administration:
You may need to refresh your "Update" page for it to display the following information.
- In the "Update" page, click "Click here to continue the migration." link.
- The new WorkPoint 365 App requires a couple more permissions. Please take a moment to read what you will consent to, and please make sure to consent on behalf of your organization.
- To proceed and grant the mentioned permissions, click the "Accept" button.
After successfully granting the mentioned permissions, you will be redirected to the WorkPoint administration dashboard:
- At this point, we can return to the Update page by clicking the "Click here"-link in the WorkPoint administration (or by accessing it from the left side menu), on which a new button should now appear in the bottom of the page:
- To proceed with the migration process, click the "Migrate solution to version 4" button.
- To start the migration job for the WorkPoint solution, click the "Start Migration Job" button. Please note that time taken to complete the migration job depends on the number of sites in your WorkPoint solution. Very large solution with around 2000 sites may take up to 12 hours to complete. Most of the time during the migration, you should not notice any downtime, and you can keep working with your solution while the job is running.
When the job is started, it appears in the Migrate to version 4 page:
- You can click the "Open" link to open the WorkPoint 365 Event Log and view the events happening related to the job.
- You can click the "Cancel" link to cancel the migration job. If the job fails, this link will instead be called "Retry", and you can click it to retry the migration job.
The job can also be inspected in the Job Queue Manager in the WorkPoint administration:
Furthermore, you can follow the events happening related to the migration job in the WorkPoint Event Log:
- In the WorkPoint Event Logging page, turn on "Trace" to see what is currently happening related to the migration process. In this screenshot, we can see that event receivers for each site are being replaced.
When the migration is complete, the job should be cleared from the Job Queue Manager, and the bottom of the "Home" menu of the solution should display "Version: 188.8.131.52" or later: