Driven Administrator Guide

version 1.2-eap-11

Migrating Your Data for a Driven Upgrade

Tip	It is highly recommended that you contact Technical Support before starting migration.

Data migration from Driven Server version 1.1 to an upgraded Driven Server 1.2 requires that you perform the following tasks in sequential order:

Back up your Driven Server 1.1 data
Upgrade the Driven Server by replacing the WAR file
Install the latest version of the CLI Client
Check the status of your data
Perform the migration process

Back Up Your Driven Server 1.1

Refer to Backing Up and Restoring Driven Repositories for detailed information about backing up your data.

Upgrade the Driven Server and CLI Client

To upgrade the Driven Server, you need to replace the WAR file contents of your deployment with the contents of the version 1.2 WAR file while the server is stopped. After you restart the server, install the version 1.2 Driven CLI Client.

Note	After you replace the WAR file, you cannot log in to Driven until you complete the migration process.

Step 1: Download the Driven Server installation ZIP archive, which includes Apache Tomcat and embedded Elasticsearch libraries, by one of the following methods:

Download the ZIP archive directly with this hyperlink: driven-tomcat-1.2-eap-11.zip
Alternatively, on UNIX, Linux, and Mac, run the following command:

$ wget -i http://eap.concurrentinc.com/driven/1.2/driven-server/latest-tomcat.txt

Step 2: Extract the ZIP archive to the default driven-tomcat-1.2/ directory, which is later referred to as ${UPGRADE_DIR}.

Step 3: Run the shutdown.sh script in the Driven installation directory:

$ cd ${DIR}
$ bin/shutdown.sh

Step 4: Remove the contents of the ${DIR}/webapps/ directory by running the following command:

$ rm -rf ${DIR}/webapps/*

Step 5: Copy the WAR file from the newly extracted webapps directory to the webapps directory in the Driven installation path:

$ cp ${UPGRADE_DIR}/webapps/ROOT.war ${DIR}/webapps/ROOT.war

Step 6: Verify that the ownership and file permissions are correct on the copied file.

Step 7: Run the startup.sh script in the Driven installation directory:

$ cd ${DIR}
$ bin/startup.sh

Step 8: For sites running with an external Elasticsearch cluster:

Upgrade to Elasticsearch version 1.4.3.
If necessary, upgrade Elasticsearch plugins to be compatible with version 1.4.3.

Step 9: Follow the steps in Installing the Driven CLI Client. The CLI Client must be at the same version as the Driven Server installation to complete the upgrade.

Determine Whether Migration Tasks Are Required

Prerequisite: The version of your Driven CLI Client must be the same version as the Driven Server.

Check the status of your data by entering the following command in your Client CLI home directory:

driven reindex --status

If the response statement states the following:

server reindex status: RUNNING_CURRENT

then you do not need to perform the migration process.

However, if the response statement says:

server reindex status: CREATE_NEW_INDEX

then proceed with the migration process.

Note	If the response statement is not one of the two documented above, then either your Driven Server is partially upgraded or there is a mismatch of your Driven Server and the CLI Client. In this case, contact Concurrent Technical Support before continuing with the migration process.

Perform the Migration Process

If you determine that your data needs to be migrated, perform the following tasks:

Step 1: Establish a terminal session with the Driven Server

Depending on data size, the migration can take from seconds to several hours or more. Therefore, use a tool like GNU Screen on a machine that runs all day, preferably on a machine hosting a Driven Server, to persist the console session.

Note	Contact Concurrent Technical Support if you have questions about establishing a persistent session with a tool like GNU Screen.

Step 2: Start the data migration process

If you are using the CLI Client on the same machine that hosts the Driven Server, enter the following command:
```
driven reindex --start --stay-connected
```
If you are working in a CLI Client that is on a machine that is different from the one that hosts the Driven Server installation, enter the following command. (Substitute "8080" with your Driven Server port number if the server was configured to run with a non-default port number.)
```
driven reindex --hosts _driven.server.URL_ --port 8080  --start --stay-connected
```

Step 3: Monitor the migration process

The CLI Client manages the migration process by communicating with the server and kicks off subsequent processing steps in the following order:

CREATE_NEW_INDEX
ENTITY
CASCADING
SLICE
BINDING

For migrations with remote CLI Client only: Periodically check the output of the CLI reindex to view the status reporting of each migration process, which includes long steps of the Cascading data reindex, genealogy updates, and progress reports on how many records have been processed.

Example of CLI reindex output

******************
starting: CREATE_NEW_INDEX
status: indexes created for for CREATE_NEW_INDEX
finished CREATE_NEW_INDEX
******************
starting: ENTITY
status: 0 changes from 326 initial records done for ENTITY
status: 326 changes from 326 initial records done for ENTITY
finished ENTITY
******************
starting: CASCADING
status: 0 changes from 1256596 initial records done for CASCADING
status: 0 changes from 1256596 initial records done for CASCADING
status: 11000 changes from 1256596 initial records done for CASCADING
status: 27500 changes from 1256596 initial records done for CASCADING
status: 44000 changes from 1256596 initial records done for CASCADING
status: 60500 changes from 1256596 initial records done for CASCADING
status: 77000 changes from 1256596 initial records done for CASCADING
status: 99000 changes from 1256596 initial records done for CASCADING
...
status: 1215450 changes from 1256596 initial records done for CASCADING
status: 1220950 changes from 1256596 initial records done for CASCADING
status: 1231950 changes from 1256596 initial records done for CASCADING
status: 1242950 changes from 1256596 initial records done for CASCADING
status: 1253421 changes from 1256596 initial records done for CASCADING
status: 1256546 changes from 1256596 initial records done for CASCADING
finished CASCADING
******************
starting: SLICE
status: 0 changes from 1155445 initial records done for SLICE
status: 5500 changes from 1155445 initial records done for SLICE
status: 33000 changes from 1155445 initial records done for SLICE
status: 60500 changes from 1155445 initial records done for SLICE
status: 82500 changes from 1155445 initial records done for SLICE
status: 110000 changes from 1155445 initial records done for SLICE
...
status: 1078000 changes from 1155445 initial records done for SLICE
status: 1100000 changes from 1155445 initial records done for SLICE
status: 1122000 changes from 1155445 initial records done for SLICE
status: 1144000 changes from 1155445 initial records done for SLICE
status: 1155445 changes from 1155445 initial records done for SLICE
finished SLICE
******************
starting: BINDING
status: 0 changes from 11856 initial records done for BINDING
status: 11856 changes from 11856 initial records done for BINDING
finished BINDING

Step 4: Restart the Driven Server when migration is complete

When the migration process is complete, the CLI displays the following output:

********************************************************
reindex done ( took _duration_ ). webapp restart needed.
********************************************************

Step 5: The best practice is to ensure old indexes of the Elasticsearch datastore are removed

Run the following command in the Client CLI home directory:

driven reindex --status

If the output from the command is server reindex status: DELETE_OLD_INDEXES, you have completed the migration but the old indexes remain. You can delete the old indexes at this point. The old indexes are cascading_1 and entity_1. See the Elasticsearch Delete an Index documentation for more information.
If the output from the command displays RUNNING_CURRENT, then the old indexes are removed. The indexes from the migration to Driven 1.2 are cascading_4, entity_4, and slice_4.

Next Topic

Troubleshooting Driven