As with any production system, executing an upgrade for vCommander® works best when you employ careful planning and processes. Doing so ensures you have adequately notified users of expected outages, includes working with a staging or development system, understanding how to best interact with Embotics® Technical Support to overcome an obstacle, and have a known good configuration to which you can roll back in the event of unexpected issues.


Notifying Users

Whenever upgrading any system, it’s best to let your users know in advance so they aren’t surprised by the service not being available when they need it. Typical vCommander upgrades take about an hour from start to finish if you are following the best practices outlined here, and keeping up to date.

Embotics recommends updating the Service Portal message of the day 36 hours to a week in advance of performing the upgrade to advise users.

  1. Under the Configuration menu, choose System Configuration.
  2. Switch to the Service Portal tab.
  3. Enter your message in the Service Portal Message of the Day field and click Save Settings.


Here’s a sample message:


To serve you better, a software upgrade has been scheduled for 17:00 – 18:00 Thursday, September 11, 2014. If you have any questions or concerns, or notice anything unusual once service has been restored, please let the system administrator know at admin@yourcompany.com.


Additionally, send an email notifying users who may not login to the Service Portal during the period the message of the day is active.


Staging Upgrade Process

Users rarely encounter vCommander upgrade failures, but in the few cases where failures occur, more often than not, the problem lies with information in the database being in an unexpected format, or similar issues. As such, Embotics recommends maintaining a staging environment so you can perform a test run on upgrades prior to upgrading your production environment. Your vCommander license does permit the upkeep of a staging environment, but you should let your account manager and/or the support team know that you have one running. A permanent staging environment is also useful for trying out new workflows or policies, and becoming familiar with new vCommander features before implementing them as solutions in your production environment.


If you do not wish to maintain a persistent staging environment, you can also clone your app server and do a test run, if you are installed using the default postgres SQL database. Installations against SQL databases will require a bit more work, but can be similarly handled following the procedure below.

  1. Backup the SQL database.
  2. Create a new “dummy” database on your SQL Server.
  3. Install the version of vCommander you are currently running against the dummy database. This install will be upgraded as your test. Once you’ve completed the testing you can destroy the database.
  4. Stop the vCommander Windows service.
  5. Restore the backup of your SQL database, overwriting the dummy database.
  6. Restart the vCommander Windows service.
  7. Perform the upgrade.

Embotics technical support can also run through the upgrade scenario for you, if you can upload a copy of your database backup to our FTP server. The lead time for this activity is variable, depending on availability of support resources, so please try and contact support with more than 72 hours business hours notice. Whenever you send us a database, you can choose to remove private information yourself, or we will do so once we’ve received it.

Production Upgrade Process

1. Notify Embotics support of your planned upgrade date and time.  If needed a support resource can be on standby for your upgrade.

2. Notify users of the outage timeframe for the production system by setting the "message of the day" in the service portal and by emailing users who do not log in frequently.

3. Backup the vCommander database.  

4. Take a snapshot of your vCommander application server

5. Download the latest vCommander release from the Embotics webpage: https://www.embotics.com/embotics-support-downloads. For legacy versions please contact Support.

6. Copy "vCommander <version> Installer with Documents.zip" to the vCommander server and unblock the file

7. Run "vcommander_<version>_install.exe"  as administrator


Note: During the upgrade, the Installer will retain the SQL connection, service account settings and port configuration from the previous installation.  If the service account password has changed it will need to be updated during the install process and credentials in vCommander will also need to be updated after the upgrade.  Please follow this article if credentials have changed.


8. Introduction, close all other programs and click next

9. Licence Agreement, review, accept and click next

10. Customer Experience, review and click next

11. Check Existing Versions, Select "upgrade to the new version" and click "next"

12. Upgrade, review, select "continue upgrade" and select "next"

Verify the retained username is correct then select "next"

13. The upgrade process will begin

14.  Pre-Installation Summary, validate there is enough free disk space for the upgrade then select "install"



15. Installing, the upgrade will take approximately 15-30 minutes, however, this time can fluctuate depending on the environment.


16. Account Configuration, verify the retained credentials from the previous installation are correct, then select "next"

17. Port Configuration, verify the ports are correct for your implementation then select "next"

18. Database Configuration, verify the database connection information is correct then select "next"

19. Shortcuts, select "next", pre-existing shortcuts are not affected by this selection menu

the installer will now continue and complete the vCommander upgrade, this process will take some time to complete

20. Install Complete,  select "done", The installation is now complete.  The vCommander windows services will start and you will be able to log in after a few minutes. 



Resolving Failures

In the event a vCommander upgrade fails, follow the procedure below to provide Embotics support with the files required to investigate the issue.  


1. Logon to the vCommander server and upload the files below to our secure file drop


C:\install.log

C:\Program Files\Embotics\install_failure.log


The directories below should be zipped and uploaded to our secure file drop


C:\Program Files\Embotics\vCommander\tomcat\logs

C:\Program Files\Embotics\vCommander\identityservice\logs


2. Upload the database backup taken prior to upgrading to our secure file drop  This will give Embotics support and engineers immediate access to investigate, develop and release a resolution to you.


3. Restore the vCommander database from the backup taken prior to upgrading


4. Restore the vCommander server from backup taken prior to upgrading 


5. Restart the vCommander windows service


6. Log an incident with Embotics support 


Post-Upgrade Activity

Once you have successfully upgraded your vCommander, remember to complete the following activities:

  • Turn off or update the Service Portal Message of the Day.
  • Test the most common actions that your users employ when working with vCommander. If you experience any failures or unusual behavior, contact Embotics Support, providing as much detail as possible. This may include diagnostics packages, screenshots, or a backup of the upgraded database itself.
  • Take database backups and/or snapshots of the vCommander application server.

 

See Also