Identical Environments

All IJC items such as entities, their fields, relationships, datatrees are described by simple records in one of the IJC_* database tables. Each item has its own record, which is uniquely identified by ITEM_ID value (a string of hexadecimal digits). The ITEM_ID value is generated when an IJC item is created and the value never changes.

All IJC items comprise a hierarchical structure that starts with an IJC schema item. The IJC schema item is a common ancestor of all the other items within that particular IJC schema.

Test to Production Metadata Migrator tool is designed to match IJC items in two different database schemas by their IDs, find differences such as new or missing items, changed parameters of an item and update IJC items in the target database schema to be the same as IJC items in the source database schema. In order to do that the tool is given a connection string to both the source and target databases and the IJC schema ID.

The tool expects that the source and target database environments are virtually identical. More specifically this means that the databases are expected to be of the same type and version, for example both databases are Oracle 11g or both databases are MySQL 5.1 or both databases are Derby 10.2. If JChem Cartridge is installed it is expected to be installed in both databases, configured the same way and both installations be of the same version. The IJC schemas that are being synchronized are expected to be of the same version. Both databases are expected to contain the same set of your custom tables and have the same data in those tables.

Database Connections

Test to Production Metadata Migrator tool synchronises IJC schema items between two different database schemas. Those two database schemas are specified in the form of *.ijs files, which are the same files that Instant JChem uses for connecting to database schemas and opening IJC schemas. All that you need to do when preparing these *.ijs files before you can synchronize the IJC schemas is to open both the source and target IJC schema in Instant JChem. Instant JChem application will store the connection information to *.ijs files in your project. The same *.ijs files can then be passed on to the tool.

An *.ijs file is a simple XML file with a set of properties needed for connecting to a database schema and opening a particular IJC schema. The IJC schema to open is specified by the IJC schema item ID value. Since the tool is designed to synchronize the same IJC schema between two environments both the *.ijs files have to contain the same IJC Schema item ID.

Additionally, the tool will not follow any security rules defined in any of the IJC schemas that are being synchronised. Instead it will prompt for a database username and password for both the source and target databases. The username that you use for connecting to the source database will need to have a readonly access to all IJC_* tables within that database. Similarly, the username specified for connecting to the target database will need read-write access to all IJC_* tables in the target database.

Synchronisation Details

When synchronising IJC items between the source and target database schemas the tool first determines differences between the schemas. There can be the following three types of differences.

• Addition - There is an IJC item in the source database schema that does not exist in the target database schema. This type of difference is determined by comparing IJC item IDs between the source and target schemas. If rephrased, 'Addition' means that for an IJC item in the source schema there is no IJC item in the target schema with the same ID.

  Please note that this type of difference could either be caused by a real new IJC item created in the source schema or by an existing IJC item deleted from the target schema. This is an ambiguity that cannot automatically be resolved.

• Removal - There is an IJC item in the target database schema that does not exist in the source database schema. Again, this is determined by comparing IJC item IDs and so more precisely this type of difference means that for an IJC item in the target schema there is no IJC item in the source schema with the same ID.

  As explained previously even this type of difference can either be caused by truly deleting an existing IJC item from the source schema or by adding a new IJC item in the target schema.

• Modification - Both the source and target IJC schemas contain the same IJC item (determined by IDs), but the item definition is different in both schemas. This means that either the source version or the target version or both version of the IJC item have had some of their parameters changed. A very basic example of a modification is renaming an IJC item.

The following table lists all IJC item types that are currently supported and shows what types of differences are recognized and synchronized by the tool.

Performing addition, removal or modification can be disabled using --no-adds, --no-deletes and --no-updates command line flags. See Command-line Syntax for further details.

User Specific Items

The tool will by default synchronize only IJC items that are available/visible for all IJC users. However, it is also possible to synchronize IJC items that are available to a specific user only. The tool will then consider only IJC items belonging to the specified user and will ignore the others.

Please note that Fields, Entities, Relationships and Datatrees are always available to all IJC users and particular users cannot take the ownership of these IJC items. Contrary to these IJC items Views/Forms, Lists, Queries and Scripts can be owned by a user. These IJC items will not be synchronized unless you explicitly tell the tool to do so.

Using on Derby

Although, it is not considered a typical usecase it is possible to synchronize IJC schemas between two Derby databases. The procedure is exactly the same as in case of synchronizing between Oracle or MySQL databases. There is, however, one important difference. A Derby database is not designed to be used in a multi-user environment. This means that a single Derby database can only be used by a single user, process or application at any given time.
Before you use Test to Production Metadata Migrator tool to synchronise IJC schema items between two Derby databases make sure that both these database are not used by any other application. In particular make sure that these databases are not used by Instant JChem.

Command-line Syntax

This is the general command-line syntax when launching Test to Production Metadata Migrator tool.
java -jar test2production.jar [options] [source.ijs target.ijs]
The following table lists all the available options with their parameters and description. The same information can be obtained by running the tool without any command-line parameters.

Examples

The typical usecase will involve running the tool several times without the --apply parameter, checking the changes detected by the tool and confirming that they can really be migrated to the target database schema. When the changes are checked and confirmed the tool can be run again with the --apply parameter, which will apply the changes and update the target database schema.

    java -jar test2production.jar ~/IJCProjects/ijc_project/.config/test.ijs ~/IJCProjects/ijc_project/.config/production.ijs
    # review detected changes printed to stdout

    java -jar test2production.jar --apply ~/IJCProjects/ijc_project/.config/test.ijs ~/IJCProjects/ijc_project/.config/production.ijs
    # double check changes performed in the target database schema printed to stdout

Importing into empty schema

1. Create new empty schema in your database without IJC tables.

2. Use Instant JChem to create new empty IJC schema in your target DB schema.

3. Connect directly to target DB and change schema ID in IJC_SCHEMA table - it must be the same like schema id in the source (can be found in source .ijs file).
   It has to be changed in SCHEMA_ID and ITEM_ID columns where GENERIC_TYPE is equal to "SCHEMA".

4. Change the schema ID in target (newly created) .ijs file - again it should be the same like the source schema id. Then just check that IJC can still connect to target schema after these changes. If so you can use test2production tool.

Limitations

The tool can not use an empty database as target schema. First IJC_* tables have to be present. And if they are, the IDs of source and target IJC schemas have to be identical. This problem may be overcome by few manual steps described in the examples .

The current version of the tool does not synchronize all IJC_* tables. In fact, it does not make much sense to synchronize some of the IJC_*

tables at all. The following list describes all IJC_* database tables and their synchronization specifics.