/ Management  

The AWP upgrade survival guide

Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

This is the correct moment in time to upgrade my old CentOS 21.1 AWP VM to a newer 22.2 version. Why? Well, because I already moved from CentOS to RHEL, and I’m left with a legacy image! Before I remove the VM instance, we just execute the upgrade procedure on this VM…How hard can it be!? Just follow the documentation instructions!? 😅 The 22.2 features are already explained in this post…

I know we’re already on 22.3 with the platform, but that doesn’t break the “party-vibe” for this post!

Let get right into it…

Time to follow the OT AWP 22.2 Upgrade Guide which is also delivered with the software package. From experience, I know preparation is key!


Think, before we act is a requirement during the upgrade of the platform. So, this is the time to validate our current situation and double-check the ‘22.2 Supported Environments’ PDF on any mismatches! Spin up your VM where AWP 22.1 is fully up and running in combination with an OTDS instance for default authentication.

I leave the upgrade of OTDS out of scope for this post! I already made a note in this post about the required tomcat version 10, database back-end to save data, and the missing ‘opendj’ service!

We log in to the VM with the terminal tool ‘MobaXterm’ and execute a list of commands to verify our current installation. When a mismatch is found, you need to produce a plan to fix it:

Part Command Result from 22.1 VM
OS version cat /etc/centos-release CentOS Linux release 7.9.2009 (Core)
Java java --version openjdk 11.0.13 2021-10-19 LTS
PostgreSQL psql --version psql (PostgreSQL) 11.14
TomEE (AWP) java -cp ./catalina.jar org.apache.catalina.util.ServerInfo
AWP AppWorks Platform CE 22.1 (build 19)
Tomcat (OTDS) java -cp ./catalina.jar org.apache.catalina.util.ServerInfo
OTDS cat /opt/opentext/otds/install/version.txt 21.3.0
CARS (OT) /opt/opentext/cars/defaultInst/install_log/CARS2.7_07_debug.log 2.7 (build 07)
CARS (OpenLDAP) /opt/opentext/cars/defaultInst/sbin/slapd -VV slapd 2.4.58

Just for my registration: The ‘slapd’ command required me to update the ‘LD_LIBRARY_PATH’ variable: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentext/cars/defaultInst/lib/

In my case there is no mismatch found, so this should be an easy upgrade! 😉

Time to follow the upgrade manual and highlight the required tasks for my specific VM…Apply the tasks for your own environment; they are straight forward. Make sure to use the sysadmin account; This is a platform account which we can use to log in without any OTDS authentication in the ‘System’ shared space:

Administrator rolled account for all organizations with ‘System’ as default

Well, I log in to the system space with my sysadmin account. From the ‘Organization Manager’ artifact I can clearly see my platform account is administrator for all my organizations (incl. the ‘System’):


Check availability of the account otadmin@otds.admin

All specific organizations (excl. the ‘System’) require this account from a ‘User Manager’ artifact perspective. I always connect OTDS to my organizations, so this account is already consolidated to my organization from an OTDS perspective!


Disable OTDS as default authenticator

I connect OTDS only to my specific organization! From this perspective, I can disable the OTDS default authentication from the ‘Security Administration’ artifact:


Run the tool CWSWorkspaceUpgradeAnalyzer

Just a tool from the CWS-CLI-set-of-tools. Read all about it in the ‘Advanced Development Guide’! I know the struggle, so I follow my own post on the CLI to make it come alive with these calls:

export CORDYS_HOME=/opt/opentext/AppWorksPlatform/defaultInst
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentext/AppWorksPlatform/defaultInst/lib
sh /opt/opentext/AppWorksPlatform/defaultInst/components/cws/scripts/linux/CWSWorkspaceUpgradeAnalyzer.sh -all-organizations

#This is my output:
CWS synchronize folder location: /opt/opentext/AppWorksPlatform/defaultInst/cws/sync
The maximum length supported for the path of the CWS synchronize folder location on the file system is 4096 characters.
Analysis of all workspaces in organization 'appworks_tips' has started.
No issues were found in workspace 'ws_aw_tips'.
Analysis is complete.
0 issues were found. You can safely upgrade your workspaces.

max_locks_per_transaction for PostgreSQL

Interesting, as I already faced its limits during a previous 21.4 installation!

sudo vi /var/lib/pgsql/11/data/postgresql.conf
#Uncomment "max_locks_per_transaction" and set the value to 1024. Can be found in the section LOCK MANAGEMENT at the end of the file!
shutdown -r now #Reboots the machine...Just to finish our preparation!

There is more on the checklist in the documentation but does not apply to my specific image; I don’t have SVN connected; I use the default service containers; I have a simple one-entity project.

Cover Your Ass with a CARS / OpenLDAP backup!

I couldn’t find it in the upgrade manual, but I saw a failure after my first upgrade (as preparation for this post!). So, in quick steps:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentext/cars/defaultInst/lib/
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/opentext/cars/defaultInst/lib/sasl
cd /opt/opentext/cars/defaultInst/sbin/

./slapd -T cat -n 0 -F ../slapd.d -l /home/sysadmin/backup_config.ldif
./slapd -T cat -n 1 -F ../slapd.d -l /home/sysadmin/backup_content.ldif

sudo LD_LIBRARY_PATH=$LD_LIBRARY_PATH ./slapd -T add -n 0 -F ../slapd.d -l /home/sysadmin/backup_config.ldif
sudo LD_LIBRARY_PATH=$LD_LIBRARY_PATH ./slapd -T add -n 1 -F ../slapd.d -l /home/sysadmin/backup_content.ldif

Make sure to do a final check on CARS before running the upgrade:

  1. Check CARS service status on a correct running service: systemctl status cars-slapddefaultInst
  2. Make a connection with ‘JXplorer’ to verify!

Now it’s time for that next step…

Follow the CARS upgrade installation

Make sure the installation packages for the platform are available in the VM like we would normally do for an installation. My starting point is this path: cd ~/opentext-appworks-suite-22.2-linux/OpenTextAppWorksPlatform/. Make sure to have X11 correctly configured, and you should be ready to run the next couple of command:

chmod +x OpenText_CARS_2.7.bin
chmod +x OpenText_AppWorks_Platform_22.2.bin
sudo ./OpenText_CARS_2.7.bin

The CARS installation wizard starts, and we can just follow the steps like we normally would do. We should see some extra screens matching our upgrade procedure. Starting with the first screen like this one:


Continue the wizard with a final summary where we can hit the ‘Install’ button:


In the end, we can hit the ‘Done’ button:


The logging?

cat /tmp/cars_custom_log.log
cat /opt/opentext/cars/defaultInst/install_log/OpenText_CARS_2.7_Install_DATE.log
cat /opt/opentext/cars/defaultInst/install_log/scriptExecution.log
#This last logfile gives me an error: `STDERR : /opt/opentext/cars/defaultInst/temp/carscontent.ldif: No such file or directory`
#A search for the file didn't give any results: `sudo find / -name carscontent.ldif`...Strange...Comment me if I miss a clue!?

So, you see I have an upgraded CARS instance, but there is no content inside it (you can recheck with ‘JXplorer’)! This was not as expected, but that’s why I made a backup. Time to restore our backup into the upgraded CARS instance. After this we can recheck ‘JXplorer’ with a valid response! 😅

Let’s also check our service with a daemon-reload:

systemctl daemon-reload
systemctl status cars-slapddefaultInst

Everything “smells” fine! So, CARS is done; next step…

Follow the AWP upgrade installation

All right, back to cd ~/opentext-appworks-suite-22.2-linux/OpenTextAppWorksPlatform/ and give the magic command (learned in this post): sudo CATALINA_HOME=$CATALINA_HOME CLASSPATH=$CLASSPATH ./OpenText_AppWorks_Platform_22.2.bin

Just follow the wizard like we always do with the upgrade option, and hit ‘Install’:


In the next steps you are required to provide the database credentials and in the end you can hit ‘Install’ again from the summary page:


Time for coffee…☕, and when I’m back it’s done:



cat /tmp/cordys_custom_log.log
cat /opt/opentext/AppWorksPlatform/defaultInst/install_log/changelog_baseline.xml
cat /opt/opentext/AppWorksPlatform/defaultInst/install_log/configureapplicationserver.log

Looks all fine…Next step…

Upgrade packages

The AWP node/instance is upgraded, now it’s time to update the packages on it. We can do this with a familiar URL: Yes, that’s the same URL when we install an image from scratch! Have a look in this post for any reference.

I just follow the flow:

  • Login with sysadmin when asked
  • Deploy the ‘UPGRADE’ operations


From experience, I know it’s now the time for a long lunch-break…

… 🍔

When back…hit the ‘Finish’ button in the wizard, and you are provided with the upgraded login page:


Next step…

First login with a “runtime upgrade” option

Well, where are you waiting for…Login to the ‘System’ space with the sysadmin account and get noticed on our first upgrade detection:


Wait a minute, and finally you can close the ‘Upgrading CWS runtime repositories’ modal panel.

Nice…That’s all! Next…

Upgrade workspace

Move to your own specific organization now. In my case; we can enter this space with the sysadmin account, but we would like the use our OTDS awdev again. So, open the ‘Security Administration’ artifact and restore the default OTDS authenticator:


Sign out from the sysadmin account, and you are (by default) redirected to OTDS again…Time to login with awdev. After login, we can enter the ‘Workspace Documents’ artifact which prompts you with another upgrade message:


Make your choice, and hit next…


Time to open our ‘Workspace’ and continue our lives where we left…

Double-check in the ‘About’ artifact:


Niceeee…Finally, a “DONE” on the AWP upgrade topic of my backlog! Was it hard to do? Not at all! Is this everything? Well, not completely! The upgrade documentation contains a chapter on post-tasks, but I leave those with you for your own environment. My environment is kept simple, so I’m able to show a basic upgrade procedure. I guess you can make your own conclusion on a sufficient knowledgeable upgrade post with a head start on any upgrades in the future.

What else is out of scope for this post, but is as important to keep in mind?

  • Do a “clean build output” on your solution and re-publish the projects
  • Upgrade the Published Source Layer which relates to BPM instances to show information in the PIM. This information can get out of synch because of the large data set. You can upgrade this data per BPM from the ‘Deployed Process Models’ artifact in the ‘System’ space (only!)
  • SVN version upgrade when your solution is attached to it (as recommended)
  • Customizations which depend on the platform dependencies (upgrade the dependencies in your local IDE)
  • Upgrade your OTDS instance (incl. Tomcat)
  • Upgrade your connected CMS (like OTCS or Documentum)
  • This post shows an in-place upgrade, but you can also do a parallel upgrade and do a migration after it…It’s all up to you!

Have a great upgrade weekend, and I CU in the next one…

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?