Updates

Overview

Zcore has support for two different types of updates: Automatic and Manual. Manual updates are covered on the Manual updates page.

Automatic Updates

The Zcore application checks for updates when it is launched using the Eclipse RCP application executable. It first launches a separate process that downloads any updates, enabling the application to continue its startup. This may be particularly useful when users are on a slow network connection. Downloaded updates will be processed the next time the application is started. If there were already updates in the updates/new directory, the application will process them. Since the updater runs before Tomcat is started, there is no need to restart the application after it runs an update.

In summary, updates are applied in two steps:

1. The update is downloaded.
2. After the appplication is restarted, the update is processed.

The update site url is in resources/forms/ApplicationDefinition.js.

Preparing Updates

Use the build.xml ant target "update_1_prepare-update" to create a new update directory in your source code's "update" directory. This target creates several directory heirarchies in which you may place your updated files:

• ${updates.dir}/update_${buildDate}/webapps/${project}/
• ${updates.dir}/update_${buildDate}/webapps/${project}/WEB-INF/pages
• ${updates.dir}/update_${buildDate}/webapps/${project}/WEB-INF/classes/org/rti/zcore/irs/utils

This target also runs the "versionInfo" target which replaces buid date and nnumber placeholders with the current date and number. It copies this file to ${updates.dir}/update_${buildDate}/webapps/${project}/WEB-INF/pages/version.html

Once you have copied all of your files into the update directories, run update_2_make-updatedfiles-zip and update_3_make-update-zip to make the required zip files for the update. Move the final ${updates.dir}/update_${buildDate}/updatedFiles_${buildDate}.zip to the server. There is also an alternate target named update_3_make-update-sql-admin-zip that can be used instead of update_3_make-update-zip. This target adds adminSql-derby_${buildDate}.zip and additionalSql_${buildDate}.sql to the final update_${buildDate}.zip.

Screencast of Update Preparation, Adobe flash presentation, mp4 format, size: 8 MB

The automatic updates now can use a manifest.txt file to provide finer-grained control of the updates process. Follow the instructions in the Manifest.txt page to create the manifest.txt file. The command listed in the manifest.txt command are run before the automatic updates listed below. Some of the commands available for automatic updates manifest.txt follow - the comprehensive listing is on the Manifest.txt page.

• checkVersion:Checks app version:SOFTWARE\RTI - TIMS\zCore TIMS,1.0.1d,1.0.1e,
• checkSite:Checks if this upgrade is for this site:SOW,MAM
• backupCurrentDatabase:Backs up the current database. Please be patient; this will take a minute or two.:
• updateAdminSchema:Updates the admin schema.:currentDb,,adminSql-derby_10132010_090323.zip,
• updateFiles:Updates files in the installation.:updatedFiles_10192010_172449.zip,
• deleteFile:Deletes a file in the installation.:updates\archive\update_10192010_165142.zip
• deleteDirectoryRecursive:Deletes a directory in the installation.:updates\testo
• mkdir:Creates a directory in the installation.:updates\testoto
• renameFile:Renames a file in the installation.:updates\test1.txt,updates\test2.txt
• list:List the contents of a directory in the installation.:updates\archive
• object_listing: Outputs a list of all Objects in the system, storing each Object as a SyncLog inside a SyncEvent list.:

After manifest.txt commands are run, the updater checks if isSupportedVersion or isIntendedSite are false before running the automatic updates. Those values will be true unless checkVersion or checkSite is in the manifest.txt file and if the update site failed those commands (i.e. wrong site or version).

Example of Updates

Note: You can have more than one update in the updates-date.zip file.

Updating files

Any file beneath the Constants.INSTALL_DIR can be updated. Start off your update archive creation by creating a base directory hierarchy - webapps\APP_NAME\WEB-INF\. This is the most commonly updated path. Of course you may update any file under your install directory.

• To update the main zcore-base jars, add a lib dir to the base hierarchy to create the following directory hierarchy - webapps\APP_NAME\WEB-INF\lib and place the jars in the lib directory. Zip this webapps directory, and rename it to updatedFiles-date.zip. Then place this zip in a zip called updates-date.zip and upload to the server.
• To update the form definitions and SQL, add a classes directory to the base heirarchy to create \webapps\APP_NAME\WEB-INF\classes. Then copy the resources directory and its content to the classes dir. Zip this webapps directory, and rename it to updatedFiles-date.zip. Then place this zip in a zip called updates-date.zip and upload to the server.
• If you need to update a form, please refer to Files required to Update a form.

Database Operations

All of the database-oriented targets use an embedded connection, which means that the network database should be shut down before a connection can be made in the target. Use shutdownNetworkServer to shut it down and then use  startNetworkServerInsecureMode to start it. Example of a script that updates a table using a csv file:

shutdownNetworkServer:Upgrade 1 of 5 - Shut down the network server.: 
startNetworkServerInsecureMode:Upgrade 2 of 5 - Re-starts the DAR database in non-secure mode for upgrade.: 
backupCurrentDatabase :Upgrade 3 of 5 - Backs up the database. Please be patient; this will take a minute or two.: 
importCsvData :Upgrade 4 of 5 - Updates the ITEM table in app schema.:importCsvData_02082012_110400.zip,APP,ITEM,0, 
startNetworkServer:Upgrade 5 of 5 - Re-starts the DAR database.: 
end:Upgrade complete. Close and re-open the DAR.:

Updating the Admin schema

In the web application, click the Admin left nav link and click "Data Center." In the Application Updates section, click "Dump Admin schema table data to .csv files." These files will be saved to the APP_NAME\backups directory, named adminSql-dbname_date.zip. Admin schema updates must be listed in a manifest.txt file - e.g.: updateAdminSchema:Updates the admin schema.:currentDb,,adminSql-derby_10132010_090323.zip,

Executing additional SQL

Sometimes you may need to perform additional SQL updates - such as adding a column to a table in the admin schema. Create a sql file named additionalSql-date.sql. Enter the SQL update statements in this file, one statement per line. Do not end each line with a semi-colon. Place this zip in a zip called updates-date.zip and upload to the server. The update_3_make-update-sql-admin-zip build.xml will add this file to the zip.

Example batch sql update

Processing Updates

When the appplication starts, the system checks if there are any updates. It unzips the archive into updates/new then loops through the file in that folder, checking for new files that start with the following:

• dynaSiteForms - copies dynaSiteForms.jar to the lib dir. This is unused.
• adminSql - unzip to updates/current and runs the sql to update the admin schema.
• importTableSql - unzip to updates/current, delete data from the table, and imports the data from the file to the table. The file must be named importTableSql-databaseschema.table.keepIdentity.zip. 
  • Each zip file has only one csv import file.
  • Filename breakdown:
    • database - derby or mssql
    • schema - schema of the table
    • table - table into which the import will happen.
    • keepIdentity - 1 if you want to use the import files id's, or 0 if you want to use the autogenerated id's. See Populating SQL Server database ADMIN schema and Populating SQL Server database APP schema for more information on which tables need to keepIdentity.
• additionalSql - executes a sql batch update file.
• updatedFiles - unzips the file at Constants.INSTALL_DIR.

Once it has completed processing these new files, it performs the following cleanup:

• archives the updated files to updates/archive and deletes all files in update directory. 
• removes sql files from updates/current
• Saves a log in the following location: Constants.ARCHIVE_PATH + siteAbbrev + File.separator + "log" + File.separator + "pending" + File.separator + "updateLog_" + updatefilename + "." + timestamp + "." + Constants.SYNC_FORMAT. This file is uploaded to the server at the next file sync
• If there are errors, they are saved in Constants.ARCHIVE_PATH + siteAbbrev + File.separator + "log" + File.separator + "pending" + File.separator + "errorSyncLogAppUpdates_" + updatefilename + "." + timestamp + "." + Constants.SYNC_FORMAT and uploaded to the server upon the next sync.