Updated for PAW 2.0.90. This guide covers in detail how to upgrade Planning Analytics Workspace (PAW). PAW is on a release cadence of about every month from IBM. So each month, IBM will release a new version of the PAW server components, usually alongside a new version of Planning Analytics for Excel (PAX) and Planning Analytics Spreadsheet Services (PASS). When a new version of TM1/Planning Analytics core is released, there will usually be a new version of PAW, PASS and PAX. This post takes you step by step through how to upgrade the PAW server on Windows Server 2016.
Planning Analytics Versions
Please note that PAW, PAX and PASS should be kept roughly in sync as PAX uses PAW to communicate with the PA/TM1 server and PASS uses PAX to generate the TM1Web views. So please update PAW, PAX and PASS together and keep your PA server up to date as well. Please check this post for more information on Planning Analytics version management.
Preparation for PAW Upgrade
- If PAW runs on a Virtual Machine, make sure you have a have a snapshot taken of the VM before you do anything. This is the most important step of all. We have seen upgrades of PAW fail and be unrecoverable. Having a VM snapshot saves the day.
- Check that there is enough space on the drive used by Docker. You will need at least as much as is consumed by ProgramData/Docker (or your customized docker data folder) before you upgrade (we have a client with over 100Gb of data here). If you need to move your docker data, please see this post. Also, check that old versions of PAW have been both cleaned and deleted from the server as they can take significant space (there is more info on this below in the Clean Up section).
- Check that your version of Docker is up to date.
- Firstly, check the minimum version of Docker via IBM’s Software Product Compatability report. Just go to this IBM checking site and select “Related Software” on the left and choose the first column “Select a product. Get its list of related software”. Then hit Create a Report enter “Planning Analytics” and the magnifying glass. Then choose your type of installation (probably “Local”), version of PA and Windows or Linux. In Product Components, uncheck All Components and check Planning Analytics Workspace. That will then deliver a Compatibility Report that looks like this.
- To find out what version of Docker you have, just open Windows PowerShell as an admin and enter “docker –version”. You will then be able to compare your Docker version to the minimum required.
- Note that for Windows Server 2016, IBM now packages Docker with the PAW install, so if you are upgrading from a recent installation, it should update Docker as well.
- Note as well that if you are using Windows 2016 and want to upgrade to Mirantis Docker, you will need to ensure you download the Windows 2016 version of it as the default will download the Windows 2019 version of Mirantis Docker and that will not work on 2016.
- Finally, for Windows Server 2019, you will need to download and install the Mirantis version of Docker.
- Firstly, check the minimum version of Docker via IBM’s Software Product Compatability report. Just go to this IBM checking site and select “Related Software” on the left and choose the first column “Select a product. Get its list of related software”. Then hit Create a Report enter “Planning Analytics” and the magnifying glass. Then choose your type of installation (probably “Local”), version of PA and Windows or Linux. In Product Components, uncheck All Components and check Planning Analytics Workspace. That will then deliver a Compatibility Report that looks like this.
- Download the installation files from Passport Advantage or IBM’s Fix Central.
- Unpack the zip file.
- Rename the unzipped folder PAW_nnnn, where “nnnn” stands for the version number (say, “PAW_2090” for version 2.0.90). Removing the dots makes it easier to refer to!
- Move the folder to your “PAW” folder, or whatever you have called the master folder where PAW is installed.
- In the new version, go to the config folder and rename the “certs” folder to “certs_original” and the “ssl” folder to “ssl_original”. I know you don’t need to, but it can’t hurt!
- Go to the installation files for the old version and copy the /config/paw.ps1 environment file, the config/certs folder and the config/ssl folder (so three objects from the config folder on the old location) to the config folder of the new installation location. Note that because you have changed the original names in the new location, no files should be overwritten.
- Create a backup of the current environment using ./scripts/backup.ps1 from the old folder. More details here: Backup of your existing PAW environment.
Update Planning Analytics Workspace
To upgrade Planning Analytics Workspace takes about one and a half hours. 1 hour and 30 minutes.
Upgrading PAW:
- PAUSE HERE: Preparation
You must have followed the preparation steps above before going any further. Please do them before you do anything else!
- Advise Users
Advise users that Planning Analytics Workspace (PAW) will not be available because of an upgrade. Also, let them know that PAX will also not work because they use PAW to connect PAX to TM1 and that PAX will also be updated.
- Upgrade Virtual Machine
PAW really likes computing power! Even if you normally run PAW on a quad core server, for the upgrade to be efficient, we suggest that you upgrade the server to at least an 8 core server while you do the update and then scale it back after completion.
- PowerShell as Admin
Open Windows PowerShell as an Administrator.
- Navigate
Navigate to the new installation location, for example, E:/PAW_Install_Kits/PAW_2090/
- Start Installation Process
Type ./start.ps1 and press enter. This will start the installation process for Planning Analytics Workspace, making reference to your existing environment.
- Preflight Check
The first thing that will happen is that the installer will do a preflight check of your server to determine if it can have Docker and PAW installed and all the settings are correct.
- Backed Up?
In Version 2.0.90 there was no Backup prompt (previously you would be asked if you have taken a backup of PAW before you upgrade). If you haven’t, we very strongly suggest you do. Please see this link for the steps. It will take only a few minutes.
- Install Docker Images
Reply “Y” when prompted to install the Docker images. Note that this may take quite a while as these images are HUGE! I have seen this process take well over an hour.
- PAW Admin
When prompted to open the Planning Analytics Workspace Administration tool reply with a “Y”.
- Accept Licences
That will open PAW Admin in a browser. Here you need to accept the two licence agreements.
- Check Paths
Then, in PAW Admin, check that the paths and URI’s are all correct.
- Validate
Validate and Update Planning Analytics Workspace. That will start or restart PAW services. Note that after PAW version 2.0.57 and the installation of Planning Analytics Spreadsheet Services, you will get a TM1 Applications Server Gateway URI error like this. You can ignore it because there is no longer an application server gateway.
- Update
Hit the Update button.
- Restart on Status Tab
Flip to the Status tab, and if necessary, Restart Planning Analytics Workspace there as well, noting it may take some minutes for all the services to start.
- Test
Test that PAW and PAX are working as expected (tip: you can launch PAW by using the command ./scripts/launch.ps1).
- If Things Don’t Work as Expected
If the test doesn’t quite go as expected, i.e. you can’t log into PAW, then try the following:
- ./scripts/paw.ps1 – this will start any failed processes.
- ./scripts/paw.ps1 stop and then ./scripts/paw.ps1 start – this will stop PAW and then start it again.
- Restart the entire server.
- Call IBM for help!
- Advise Users
Advise users that the Planning Analytics Workspace update is now complete and that PAW and PAX are available again.
- Cleanup
Now that the upgrade of PAW is complete, you need to clean up any redundant Docker images and remove the old folder. Please see the instructions below.
Cleanup from your Planning Analytics Workspace Upgrade
Finally, we need to clean up after the PAW upgrade. There are three steps to this:
- You need to clean out the image files from the old installation of PAW. To do this run the ./scripts/clean.ps1 or ./scripts/clean.sh script from the OLD installation location. This will remove images for the release in which it is run, so make sure it is run for the old installation, not the one you have just upgraded to! This might take 10 minutes or so.
- Delete the folder from the previous version of PAW. So if you have upgraded from version 2.0.68 to 2.0.76, delete the folder from 2.0.68.
- Empty the Recycle bin to reclaim space.
Disk Space Warning: Change Docker Drive
Remember that if you need to change the drive that the Docker images are stored on, you can do so by following the instructions in this post.
TM1 Server Upgrade
Also, you should be keeping the TM1/Planning Analytics core server components up to date as well. If you are looking for instructions to upgrade the core of TM1/Planning Analytics, please see this post.
Need Help?
If you have any questions or need some help with this upgrade, please let us at ExploringTM1 know. We’d love to help you with your update.
