Document & Image Field Migration

This appendix describes an ExtraView command-line utility named DocumentImageMigration that moves fields with the display types of document and image from internal storage within the database, to the file system. The utility will typically be run with the support of doDocumentMigration.bat (Windows) or doDocumentMigration.sh (Linux).

By default, the contents of document and image fields uploaded to ExtraView are stored as binary objects in the database. The ExtraView Administrator has the choice to configure the system to store the uploaded field contents on the file system, where they will be accessible by the application server.

The program must be run stand-alone, and the ExtraView application server(s) should be stopped while the documents and images are being migrated.

Configuring External Storage

Note: It is strongly recommend that you back up your database prior to performing any of the procedures described below.

To configure the storage options, log in to ExtraView with the Administrator role. These settings are shared with storing file attachments on the file system. Click on the Admin navigation button, then the System Controls tab, then select All Behavior Settings, and edit the following settings:

  • ATTACHMENT_REPOSITORY_OPT - This setting controls whether attachments, documents and images are stored internally within the database, externally on the file system, or in some combination of the two methods.

    If the value of this setting is INTERNAL (the default value), then all attachments, documents and images are stored internally within the database. If the value is set to EXTERNAL, then all the attachments, documents and images are stored on the external file system.

    Alternatively, you may provide a comma separated list of file extensions and then all files with these extensions are stored in the database while all others are stored externally in the file repository.

    For example, if you set the value of this setting to txt, doc, docx, htm, html then files of these types will be stored within the database. This strategy leaves the files stored internally in the database as searchable by keywords, while image and video files with extensions such as jpg and mp4 are stored externally

  • ATTACHMENT_REPOSITORY_ROOT – This setting defines the location outside the database where attachments, documents and images will be stored. You must ensure that the path is valid from the application server(s) that are running ExtraView and that you have all the permissions to read and write to the storage. In a clustered or load-balanced environment, you must ensure that all instances of ExtraView can read and write to the same file system using this path.

    Please note – if you change this setting, new attachments will be saved to the new location, and existing attachments will still reference the old location. You will need to ensure that the previous file path is still accessible by the ExtraView instance, or these existing attachments will not be available to end users.

    Set up a separate backup method for this external storage as backing up your database will no longer backup the file attachments

  • ATTACHMENT_REPOSITORY_DMAX - This setting defines the maximum number of files or directories that will be created under one node of the external directory structure. The default for this value is 999. It is not likely that this value needs to be altered.

Running the Migration Utility

The DocumentImageMigration utility is a Java program. This is run from Windows with the doDocumentMigration.bat file, and from Linux with the doDocumentMigration.sh file.

The migration command line utility is included in the ExtraView application package. It requires Java be installed on the application server to run. We provide shell and batch file scripts that you can use to run the utility.

If you have deployed ExtraView in a WAR/EAR file, you will need to set up an exploded directory to run this script. The scripts are located in the evj/WEB-INF/data folder on your application server. Syntax:

doDocumentMigration [-instanceName] [-testOnly] [-migrate] [-updateSize]

You must provide one of the optional parameters. The meaning of the parameters is:

  • -instanceOnly - the name of your ExtraView instance, e.g. evj. This parameter is required
  • -testOnly - perform a dry run of the migration, but without making any changes to the database or to the file system
  • -migrate - perform the migration
  • -updateSize - update the size of the external attachments in the database (not normally used)

Microsoft Windows with Apache Tomcat

Edit the doDocumentMigration.bat file.

Locate the lines

set JAVA_HOME=%1
set TOMCAT_HOME=%2
set EV_BASE=%3

replace %1 with your path to Java, e.g. D:ExtraView\java\jdk-1.4.2
replace %2 with your path to Tomcat, e.g. D:ExtraView\jakarta-tomcat-5.0.28
replace %3 with your path to ExtraView, e.g. D:ExtraView\jakarta-tomcat-5.0.28\webapps\evj

Save and exit the edit session.

Open a Command window in the evj\WEB-INF\data folder and type the following command:

doDocumentMigration instanceName "parameter"

where

instanceName and "parameter" are defined by the options listed above.

Linux / Unix with Tomcat

Edit the doDocumentMigration.sh file.

Locate the lines

TOMCAT_HOME=/usr/local/extraview/tomcat
JAVA_HOME=/usr/local/extraview/java

Set TOMCAT_HOME and JAVA_HOME to the correct paths for your installation.

Save and exit the edit session.

At the command prompt, type the following command:

sh doDocumentMigration.sh instanceName "parameter"

where

instanceName and "parameter" are defined by the options listed above.

Completing the Migration

You must use the Java utility named runPatches when you have completed the above steps. The setup for this is identical to the setup for doDocumentMigration, except you edit the file named either runPatches.bat or runPatches.sh. Once you have set up the file, simply run the runPatches from the command line.

 

Again: We strongly recommend that you back up your database prior to performing any of the procedures described above. Please contact support@extraview.com if you would like assistance with this step.