Upgrade Procedure

The upgrade procedure consists of the following steps:

Prepare the necessary information for upgrading the Microsoft 365 application endpoint (collect Microsoft 365 gateway site parameters).
Turn off Microsoft 365 synchronization.
Upgrade the Microsoft 365 application endpoint.
Upgrade the Microsoft 365 application.
Turn on Microsoft 365 synchronization.
Update the Billing control panel and online store customizations.

Important: Skip this step if CloudBlue Commerce 21.0 or later is installed.
Perform post-upgrade validation.

Important:

1. The upgrade procedure is not reversible.

2. All upgrade steps are mandatory.

3. Make sure that the current version of the Microsoft 365 application is higher than 20.3. Upgrading from earlier versions is not supported.

4. Before upgrading the Microsoft 365 application from one version to another, make sure that you are going to follow the allowed upgrade paths. See this KB article for details.

5. If you have Microsoft 365 application instances running in syndication mode (Reseller Mode is set to Indirect CSP Reseller (through Ingram Micro)), make sure that the version of the Federated Credentials Provider application belongs to the Microsoft 365 application version to which you are going to upgrade. See this KB article for details.

6. If a non-LocalDB edition of SQL Server is used by your Microsoft 365 application endpoint, make sure all SQL Server logins of Microsoft 365 gateway application databases have the sysadmin server role. See the Microsoft 365 Integration Provider's Guide >> Cloud Solution Provider Scenario > Deployment Architecture > Preparing SQL Server Databases for details.

7. The names of the Microsoft 365 gateway sites must not be changed after the installation of the Microsoft 365 application endpoint. If you have changed them, reinstate the original names before upgrading the Microsoft 365 application endpoint.

8. Before upgrading the application, we recommend that you check that there are no unprocessed Microsoft 365 tasks in Task Manager. Unprocessed Microsoft 365 tasks may cause issues during and after upgrade.

To upgrade an existing installation of the Microsoft 365 application, perform the following steps:

Prepare the necessary information for upgrading the Microsoft 365 application endpoint. You must prepare the name of the Microsoft 365 gateway site and the name of the Microsoft 365 gateway application. This can be done in the following way:
1. Log in to the Provider Control Panel.
2. Go to Services > Applications, select the APS Connectors tab, and click the Microsoft 365 application.
3. Select the Instances tab and click the target application instance.
4. Select the General tab.
5. Obtain the value of the Application API end-point URI setting. This is a URL that is structured in the following way: https://<Hostname_of_Microsoft_365_Gateway_Site>/<Name_of_Microsoft_365_Gateway_Application>/aps/.
6. Write down the name of the directory from the URL. This is the name of the Microsoft 365 gateway application.
7. Resolve the hostname from the URL into the IP address.
8. Log on to the Microsoft 365 Application Endpoint Host as Administrator via RDP.
9. Open Internet Information Services (IIS) Manager.
10. Go to the list of sites.
11. From the list, select the site with the IP address obtained above.
12. Write down the name of the site. This is the name of the Microsoft 365 gateway site.
Turn off Microsoft 365 synchronization by canceling all periodic tasks Synchronization with Office 365 Portal in Task Manager.
Upgrade the Microsoft 365 application endpoint:
1. Upload the Microsoft 365 application package to the Microsoft 365 Application Endpoint Host.
2. Unpack the application package.
3. Unblock the contents of the O365-Web.zip file. To do this, right-click the file in Windows Explorer, click Properties, click Unblock, and click OK.
4. Unpack the O365-Web.zip file.
5. Start Windows PowerShell Console and go to the directory where the contents of the O365-Web.zip file are located.
6. Run the .\setup.cmd -GatewaySiteName <The name of the Microsoft 365 gateway site> -GatewayAppName <The name of the Microsoft 365 gateway application> -Force command.
7. Check that the application endpoint upgrade is successful:
  1. On the Microsoft 365 Application Endpoint Host, open a browser.
  2. In the browser, open the https://<IP_Address_of_Microsoft_365_Gateway_Site>/<Name_of_Microsoft_365_Gateway_Application>/aps/healthcheck URL.
  3. In the response that you receive, you should see the Congratulations, your Office 365 Application Endpoint is now up and running message and the new version of the application. If the response is different from the response above, this means that the application endpoint upgrade is not successful and that you must resolve this issue before proceeding to the next upgrade step.
    
    Important: If you cannot resolve this issue on your own, contact the Ingram Micro support team and provide all necessary information, including the command that you used to start the application endpoint upgrade and the console output.
Note: If you have several Microsoft 365 gateway sites on the Microsoft 365 Application Endpoint Host, use the procedure provided above to upgrade each Microsoft 365 gateway site.
Upgrade the Microsoft 365 application:
1. Import the Microsoft 365 application package to CloudBlue Commerce. See the APS Application Hosting Guide for details.
2. Upgrade your Microsoft 365 application instances. See the APS Application Hosting Guide for details.
Turn on Microsoft 365 synchronization by running all the periodic tasks Synchronization with Office 365 Portal that you canceled previously.
Update the installed Billing control panel and online store customizations:

Important: Skip this step if CloudBlue Commerce 21.0 or later is installed.
1. Prepare the new Billing customization files:
  1. Upload Microsoft365-x.xx.app.zip to your workstation.
  2. Extract the contents of the application package.
  3. Go to the Microsoft365-x.xx.app directory.
  4. Extract the contents of Customization.zip and go to the Customization directory, which contains two sub-directories: ControlPanelCustomization and OnlineStoreCustomization. Use the contents of these sub-directories to upgrade the Billing control panel customizations and the Billing online store customizations, as described below.
2. Upgrade the Billing control panel customizations:
  1. Log on to the Billing Application Server (OABLINFE) as root.
  2. Go to the /usr/local/bm/customization.o365 directory and replace the old files with the new files:
    - BM_ProvisioningParams.xml
    - SubscrParam_CDB_UpgradeResourceList.xml
    - SubscrParam_UpgradeList.xml
  3. Go to the /usr/local/bm/conf/html/o365 directory and replace the old files with the new files:
    - script.js
    - cowi_script.js
  4. Go to the /usr/local/bm/conf/locale directory and replace the old files with the new files:
    - locale.en.o365 (English)
    - locale.de.o365 (German)
    - locale.es.o365 (Spanish)
    - locale.fr.o365 (French)
    - locale.it.o365 (Italian)
    - locale.ja.o365 (Japanese)
    - locale.nl.o365 (Dutch)
    - locale.pt.o365 (Portuguese)
    - locale.ru.o365 (Russian)
  5. Restart the pba service by using the service pba restart command.
3. Upgrade the Billing online store customizations:
  1. Go to Products > Online Store and select your online store for editing.
  2. Update the o365_provision custom layout template:
    1. Go to Products > Online Store and select the Layout Templates tab.
    2. In the list of layout templates, click the o365_provision layout template.
    3. Click Edit.
    4. In the Template field, replace the old contents with the contents from the o365_provision.tpl.txt file.
    5. Click Save.
  3. Update the resourcegate standard layout template:
    1. Go to Products > Online Store and select the Layout Templates tab.
    2. In the list of layout templates, click the resourcegate layout template.
    3. Click Edit.
    4. In the Template field, replace the old contents with the contents from the o365_resourcegate.tpl.txt file.
    5. Click Save.
  4. Update the custom Microsoft 365 styles of your online store:
    1. Go to Products > Online Store and select the Design tab.
    2. Click Edit.
    3. In the Customized CSS field, replace the old Microsoft 365 styles with the new Microsoft 365 styles from the o365.css.txt file.
      
      Important: Do not remove or change styles that are not related to the Microsoft 365 application.
    4. Click Save.
  5. Update the English translations and the translations of any other languages you need:
    1. Go to Products > Online Store and select the More tab.
    2. Click Languages.
    3. Select the required language by clicking the respective link in the Language ID or Language Name column.
    4. Click Import Dictionary and select the required dictionary file:
      - locale-bmstore.en (English)
      - locale-bmstore.de (German)
      - locale-bmstore.es (Spanish)
      - locale-bmstore.fr (French)
      - locale-bmstore.it (Italian)
      - locale-bmstore.ja (Japanese)
      - locale-bmstore.nl (Dutch)
      - locale-bmstore.pt (Portuguese)
      - locale-bmstore.ru (Russian)
    5. Select the Overwrite Translations checkbox.
    6. Click Save.
  6. Go to Products > Online Store and click Synchronize Now.
Important: If there are resellers selling Microsoft 365 services on your CloudBlue Commerce installation, you must also update the online stores of these resellers.
Perform the following post-upgrade validation steps:
1. In Task Manager, make sure that there are no unprocessed Microsoft 365 tasks scheduled during the upgrade.
2. For each Microsoft 365 application instance, make sure that all settings are correctly specified and all necessary Microsoft APIs are accessible. To do this, select the application instance you need to check and click Test Connection.