Manifest.txt

Submitted by ckelley on Mon, 11/15/2010 - 16:43

You may use a manifest.txt in both automatic and manual updates. It is advised to run the checkVersion and checkSite commands when using the manifest.txt for an automatic update; otherwise, it may abort the automatic update.

There is one command per line in manifest.txt. Each line is processed according to its colon--delimited format: 

  • command
  • description
  • options. The options are comma-separated.

Here is an example command:

batchSql:Upgrade 5 of 14 - Runs the SQL statements to upgrade the schema - 1 of 6 batch files:tempBackupDatabase,update1.sql

That line specified the batchSql command, which runs a bunch of sql statements in the specified file (update1.sql) using the specified database connection (tempBackupDatabase, which is a special variable indicating that you are using a backup of a database made during the upgrade by another command). The desciption part ("Upgrade 5 of 14...") is displayed to the user in a summary at the beginning of the upgrade and during each step of the upgrade.

If you are doing a task that requires database access, you must use shutdownNetworkServer target to shut it down and then start the db with startNetworkServerInsecureMode. See the Updates page, Database Operations for a sample script.

Here are the different tasks available. Some may be applicable only to manual updates.

  • backupDatabase - backs up a database to the backup dir. Since there are other facilities for backing up the database, this command is designed for backing up a database so that the backup can be used for further processing in the upgrade. (See backupCurrentDatabase command for backing up the current database.) This command stores a tempBackupDatabase variable that may be used by other commands.
    • databaseConnectionUrl- db connection string
    • backupFileName - name of backup file, exclusing extension. If there is already a file using the same name, it will increment the filename, e.g. tempBackupDatabaseFileName = backupFileName + "-" + j;
  • backupCurrentDatabase - backs up the current system database to the backup directory. Gets the path from catalinaHome. Uses the cloneDatabase() method, which is faster than the usual backup method.
    • Note: You must have database.path=\\databases in application.properties for this target to work.
  • checkVersion - checks if the current version should be upgraded by checking a value in the registry. e.g.: checkVersion:Upgrade 1 of 3 - Checks the version.:SOFTWARE\RTI - TIMS\zCore TIMS,1.0.1h,1.0.1k
    • prefKey - registry key to check - e.g. SOFTWARE\RTI - TIMS\zCore TIMS
    • version to check: each supported version, comma-separated i.e. TIMS 1.0.1h,TIMS 1.0.1k
  • checkSite - Loops through a list of intended sites. e.g.: checkSite:Upgrade 2 of 3 - Checks the site.:MAM
    • intendedSites - list of intended sites using the site abbreviation: e.g.: MAM, SOW,
  • encryptDatabase - encrypts the database
    • databaseConnectionUrl
    • bootPasswordFileName
  • unzipTempDatabase - unzips a database created by the backupDatabase command. It is important that this command follow backupDatabase command. There are no options for this command - it gets the filename from a variable stored when backupDatabase was run.
  • addJar - adds a jar file and function to the database
    • databaseConnectionUrl - db connection string. If it is tempBackupDatabase, it will use the tempBackupDatabase created by the backupDatabase command.
    • jarName - name of jar
    • method - method name
    • sqlFileName - file name of sql that has the function. One line per sql statement. No semi-colon at end of sql statements.
  • updateDatabaseVersion - updates the db to the version currently in the classpath.
    • databaseConnectionUrl- db connection string. If it is tempBackupDatabase, it will use the tempBackupDatabase created by the backupDatabase command.
  • updateAdminSchema - upgrades the data in the Admin schema, and then runs DynasiteUtils.verifySchema to add any missing tables or columns to the database. Shutdown the database.
    • Expects sql to update the following tables: DISTRICT, FORM_TYPE, FLOW, FORM, FORM_FIELD, FIELD_ENUMERATION, PAGE_ITEM, RULE_DEFINITION. SQL is generated by clicking "Dump Admin schema table data to .csv files" link.
    • See UpdateDatabaseDAO.updateAdminDatabase() for details on this update.
    • databaseConnectionUrl - db connection string. If it is tempBackupDatabase, it will use the tempBackupDatabase created by the backupDatabase command. To update the current database, enter currentDb.
    • updatefilePathVar - path to the directory that contains the Admin schema sql. If equal to Constants.UPDATES_CURRENT_PATH, uses that; otherwise, uses the directory specified in the updatefilePathVarvariable in the upgrade directory. Leave blank if using currentDb. 
    • Example: updateAdminSchema:Updates the admin schema.:currentDb,,adminSql-derby2010-11-12-083036817.zip
  • replaceDatabase - replaces the currently running database by performing the following tasks: shutdown the embedded database, shutdown the Network server (used by the Zcore runtime database), rename the current Zcore runtime database from zeprs to zeprs-empty, then move the embedded database to the former location of the Zcore runtime database.
    • databaseConnectionUrl - db connection string. If it is tempBackupDatabase, it will use the tempBackupDatabase created by the backupDatabase command.
    • pathToReplacementDatabase - path to the repacement database.
    • copyOfOriginalDbName - name for the original database copies. If there is already a copy, the name will be incremented.
  • refreshSites - Refreshes the sites xml files using data from the sites table in the database. These are used by the site setup dropdown. Shuts down the database after it has completed the command.
  • startNetworkServer - starts the network server. 
  • startNetworkServerInsecureMode - starts network server in insecure mode, setting derby.connection.requireAuthentication = false and derby.database.sqlAuthorization - false.
  • shutdownNetworkServer - shuts down the network server.
  • disableDerbyProperties - renames derby.propertiies file to derby.properties.bak
  • restoreDerbyProperties - renames derby.properties.bak to derby.properties
  • batchSql - Run sql statements from a file. This runs each line separately and saves the results of the operation. Shuts down the database once it has completed all of the statements.
    • sqlFileName - sql file name
    • databaseConnectionUrl - db connection string.
      • If it is tempBackupDatabase, it will use the tempBackupDatabase created by the backupDatabase command.
      • If it is currentDb, it will create the string to connect to the current database using the bootpassword and credentials.
  • importCsvData - unzips files to UPDATES_CURRENT_PATH, deletes any data already in the table, and imports the new data. e.g.: importCsvData :Upgrade 3 of 3 - Updates the COURT table in admin schema.:importCsvData_03112011_125150.zip,ADMIN,COURT,0,
    • The .cvs filename should be the table name in upper case, e.g.FORM.csv
    • Properties:
      • fileName - importCsvData_Timestamp.zip (can be any name, but it is handy to have the timestamp.
      • zipDirName - name of update archive, minus .zip
      • schema - ADMIN or APP
      • table - name of table
      • keepIdentityStr - 1 if mssql, null otherwise.
  • updateFiles - unzips files into the INSTALL_DIR.
    • fileName
  • deleteFile - Deletes a file. e.g.: deleteFile:Upgrade 1 of 1 - Delete file.:updates\archive\fileToDelete.zip
    • fileName - file to delete e.g. updates\archive\update_10192010_165142.zip
  • cleanDirectoryRecursive - Deletes contents of a directory, but preserves the directory.
    • fileName - directory to delete
  • deleteDirectoryRecursive - Deletes a directory and any files or disectories within it.
    • fileName - directory to delete
  • mkdir - Creates a directory
    • dirPath - path to create
  • renameFile - Renames a file.
    • source - File to rename
    • dest - Destination filename
  • list - List the contents of a directory. Output is included with the updateLog_manifest_update_*.json file
    • dirPath - Directory to list.
  • listFileItems - Outputs a list of FileItems, List of files, including lastModified and size. Creates a file and places in the pending directory, to be uploaded during the next sync process.
  • sendFile: Zips file and places in pending directory.:logs\\zeprs.log,zeprsLog_
    • pathToFile - Path to the file that is being transported.
    • outputFileName - used for the output filename. Should have an underscore at the end - i.e.: "syncEvent_"
  • object_list - Outputs a list of all Objects in the system, storing each Object as a SyncLog inside a SyncEvent list. Creates a file and places in the pending directory, to be uploaded during the next sync process.
  • end - Displays a message that the update is complete. e.g.: end:Upgrade complete. Close and re-open the DAR.:

A sample manifest.txt is available. The sample uses tempBackupDatabase for the databaseConnectionUr. If you do not need to use tempBackupDatabase, the url will probably be in the format jdbc:derby:C:\\pathTo\\databases\\dbname.

Sample updates: