How to Upgrade Planning Analytics Workspace (PAW)

Updated for PAW 2.0.68. Planning Analytics Workspace (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 through step by step 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

  1. If PAW runs on a Virtual Machine, have a snapshot taken before you do anything.
  2. 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).
  3. Check that your version of Docker is up to date via IBM’s Software Product Capability report.
  4. Download the installation files from Passport Advantage or IBM’s Fix Central.
  5. Unpack the zip file.
  6. Rename the unzipped folder PAW_nnnn, where “nnnn” stands for the version number (say, “PAW_2063” for version 2.0.63). Removing the dots makes it easier to refer to!
  7. Move the folder to your “PAW” folder, or whatever you have called the master folder where PAW is installed.
  8. In the new version, go to the config folder and rename the “certs” folder to “certs_old” and the “ssl” folder to “ssl_old”. I know you don’t need to, but it can’t hurt!
  9. 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.
  10. Create a Backup of your existing PAW environment.

Update Planning Analytics Workspace

About one and a half hours. 1 hour and 30 minutes.

Upgrading PAW:

  1. Preparation

    You must have followed the preparation steps above before going any further. Please do them before you go any further!

  2. 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.

  3. PowerShell as Admin

    Open Windows PowerShell as an Administrator.

  4. Navigate

    Navigate to the new installation location, for example, E:/PAW_Install_Kits/PAW_2068/

  5. 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.

  6. Backed Up?

    The first thing you will be asked is 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.

  7. Preflight Check

    Then the script will initiate a series of preflight checks of your environment, making sure that all the correct settings are in place.

  8. Install Docker Images

    Reply “Y” when you are 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.

  9. PAW Admin

    Reply “Y” when you are prompted to open the Planning Analytics Workspace Administration tool.

  10. Accept Licences

    That will open PAW Admin in a browser. Here you need to accept the two licence agreements.

  11. Check Paths

    Then, in PAW Admin, check that the paths and URI’s are all correct.

  12. 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.

  13. Update

    Hit the Update button.

  14. Restart on Status Tab

    Flip to the Status tab, and if necessary, Restart Planning Analytics Workspace there as well.

  15. Test

    Test that PAW and PAX are working as expected.

  16. Advise Users

    Advise users that the Planning Analytics Workspace update is now complete and that PAW and PAX are available again.

  17. 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 is three steps to this:

  1. You need to clean out the image files from the old installation of PAW. To do this run the ./scripts/clean.ps1 or ./scripts/ 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!
  2. Delete the folder from the previous version of PAW. So if you have upgraded from version 2.0.53 to 2.0.63, delete the folder from 2.0.53.
  3. 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.

You might also like