Configuring Migration Behaviors

The standard behaviors of the migration toolkit can be modified in several specific ways. These provide a group a method to control the standard behaviors for their migrations consistently independent of content configuration and mapping. Following are the ways in which you can change the behavior of the migration to suit your needs.

INI Options File

The ini options file enables the ability to configure the behavior of the migration. Some of these values are for usability, and some provide specific changes in behaviors.

The base ini looks like the following

	-consoleLog
	-vmargs
	-Dlog4j.configuration=file:log4j.properties
	-Dosgi.requiredJavaVersion=1.8
	-Xms1024m
	-Xmx1024m

This basic configuration provides the minimum to operate the application. The following sections describe other options that can be added in the vmargs section. These are in a format of -Dkey=value.

Working directory

By default, log and work files will be located in {userDirectory}/AppData/Local/SodiusWillert/Doors Migration/. If you want to use another location as working directory, you can add the following parameter to the INI options file: -Ddoors.workingDirectory=C:\location\to\use

Logging values

The logging options in the options file do the following.

The -consoleLog makes sure the application provides a system console for the launch of the application. This will give you real time information about the logging.

The -Dlog4j.configuration points to a log4j options file. The base logging in the application uses log4j. This enables the user to customize the logging options that are visible. The base options are as follows:

	# Root logger option
	log4j.rootLogger= INFO, file, stdout
	
	# Direct log messages to a log file
	log4j.appender.file=org.apache.log4j.RollingFileAppender
	log4j.appender.file.File=${doors.workingDirectory}\\doors2dng.log
	log4j.appender.file.MaxFileSize=10MB
	log4j.appender.file.MaxBackupIndex=10
	log4j.appender.file.layout=org.apache.log4j.PatternLayout
	log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n
	
	# Direct log messages to stdout
	log4j.appender.stdout=org.apache.log4j.ConsoleAppender
	log4j.appender.stdout.Target=System.out
	log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
	log4j.appender.stdout.layout.ConversionPattern=%-8r %-5p [%t] %m (%c)%n

You can customize logging as you find desirable.

Commonly repeated dialog values

The dialogs demand server information and user information. For those running the application they can set default values that populate these dialogs. They include the following.

	-Drm.uri=https://clm-606-nice.sodius.cloud:9443/rm
	-Dclm.userId=patricia
	-Dclm.userPwd=patricia
	-Dclm.consumerKey=MigrationTool
	-Dclm.consumerSecret=MigrationTool
	-Ddoors.path=C:\Program Files\IBM\Rational\DOORS\9.6\bin\doors.exe
	-Ddoors.portserver=36677@DOORSSERVERNAME
	-Ddoors.user=doorsuser
	-Ddoors.password=doorspassword

This provides connection information to the repositories. All options are available in dialogs and can be manually entered. Having these values in the ini is just a convenience and the application uses the dialog values you enter Often times organizations avoid using the password information because this is a plain text file.

DOORS Client Configuration

By default the application uses the DOORS Client in a headless mode to access information from DOORS. The behavior of this headless client is that it will be opened to request information from DOORS, and when not in use it will self-close. In large migrations, and in some networks, the repeated opening and closing of DOORS can manifest a less stable interaction. To eliminate this issue it is possible to interact with a live DOORS client session. Simply launch DOORS Client with your user id connected to your target source repository. And then set the following ini configuration.

	-Ddng.usedoorsactiveclient=true

Creating DOORS Next Components

If using the toolkit to generate components it is valuable to specify a specific template to be used. Since most organizations have a standard template this is just a configuration that can be set. It will do a name lookup of the configurations and apply that template.

	-Ddng.templateName="My Component Template"

Alternative Enumeration Separator

The default separator between enumeration values in DOORS and in the configuration templates is a comma (,). In some configurations in DOORS the comma is used as a label and this does not provide a good separator. To allow flexibility an alternative separator can be used. It will be used in the extraction of information from DOORS as well as in your configuration files. It is set with the following parameter.

	-Ddng.separatorcharacteroverride="^"

Migration Recovery Modes

If a failure occurs, typically a DOORS or ELM Server issue, the migration can be restarted. By default we use a conservative mode of recovery of the migration. This model of recovery is performed by continuing on after the last component that was fully migrated. In components only partially migrated all migrated objects (in changesets) will be deleted and the entire component is restarted.

In situations where you may have lots of modules in a component it might not be desirable to restart the entire component. In these cases we will attempt a more aggressive solution that simply deletes the last changeset created and continues from that point on.

	-Ddng.aggressiverecovery=true

It is recommended to use the default mode.

RTF Table Support

Some users have used complex usage of RTF in their DOORS Object Text. Our standard RTF to HTML addresses most cases, however RTF table information is not exchanged.

Most users do not use these RTF tables as they can cause other challenges in maintaining in DOORS. However, support to migrate these tables is necessary. The support for RTF tables does a second read of the DOORS module to identify RTF tables. When an RTF table is found the Primary Text in DOORS Next is update with an RTF file that preserves the contents from DOORS. Within DOORS Next, the contents are natively supported in the preview view of primary text. Additionally, when the table needs to be edited it will provide the option to convert on the user’s demand.

	-Ddng.rtftableupload=true

By default this is false because the low occurrence of these tables and the additional time to re-read a DOORS module.

Strict Linking

In some cases it is not desirable to migrate all links from your DOORS repository. The chosen method to filter out links is the exclusion of link modules from the migration. In the default mode unspecified link module mappings in the link type mappings will be assigned the default link type. In strict mode, all link modules not explicitly mapped will be ignored from the migration.

	-Ddng.strictLinking=true

Autocomplete for Changesets

The standard behavior for changesets is to keep them open for migrations. This is to enable the inspection of the migrated artifacts prior to delivering. In earlier versions of ELM support it was necessary to deliver changesets to enable a synchronous link flow. This is no longer necessary with the separation of the migration from the linking phase. It was identified that some users may want to automatically deliver their change sets to be consistent with past behaviors.

	-Ddng.autodelivery=true

It is recommended to leave this setting as false and inspect the changeset before delivery.

Linking Style

The default linking style within the migration tool is to link to module bound artifacts. The motivation for this is the similarity to the linking mode in DOORS Classic which only had Module bound artifacts. If desirable, linking can be triggered to occur to the base artifacts. To do so use the following configuration:

	-Ddng.baseArtifactLinking=true