Skip to main content
Kofax

Synchronise the configuration and content of two KCM installations

Article # 3039404 - Page views: 110

Issue

This article describes how all configuration and content of two KCM installations (or instances) can be synchronised. 

The following components can be synchronised

  • Configuration and service scripts of KCM Core. Optionally custom tools.
  • Content of Repository Server (Designer projects)
  • Configuration of the Contract Manager

All these components can be synchronised using command line tools. All steps can be scripted to automate this process.

This is also possible using KCM Core Scripting. The RunCommand Core scripting command can be used for running command line applications. The exit point HourlyTask.dss is an exit point that is executed every hour. It could be used to start the script to automatically transfer all Designer projects every day at 01:00h. Another interesting component is the Directory Watch API which automatically starts a new job for a Core Script when a new file is placed in a folder (E.g. Start an import job when an export file is placed in this folder).

For more information on RunCommand and Exit Points see the chapter RunCommand and chapter KCM Core exit point scripts in the Core Scripting Developer's guide (link).

For more information on the Directory Watch interface, refer to the chapter Directory Watch interface client in the Core Developer's guide (link).

All the tools discussed in the next chapters are documented in the Getting Started Guide (link).

Solution

KCM Instance configuration (including KCM Core scripts)

KCM 5.4 and earlier

For transferring the KCM Instance Configuration (including KCM Core scripts) the ConfigureInstance.exe tool can be used. This tool will create an export of

  • KCM Core scripts and user defined libraries (MyLibrary.cds).
  • Global constants (excluding internal global constants such as _RepositoryHost).
  • All environment settings (dm.ini).
  • Optionally custom tools.
Note-Icon.png

NOTE: Technically this ConfigureInstance.exe tool can also be used with KCM 5.5. However the ExportInstanceConfiguration.exe tool (discussed in the next chapter "KCM 5.5 and later") is introduced as the replacement for ConfigureInstance.exe in KCM 5.5. It is advised to use ExportInstanceConfiguration.exe instead of ConfigureInstance.exe on KCM 5.5 and later.

The ConfigureInstance.exe tool resides at:

..\KCM\Programs\<version>\ITP Server\Bin\ConfigureInstance.exe

Creating an instance export

To create an export the following parameters can be used:

  • /Export [mandatory]
  • /version=<version> [optional]: KCM version who's instance is exported. Relevant when two KCM versions are installed.
  • /file=<file> [mandatory]: Path to XML file to write the configuration to.
  • /instance=<instance number> [mandatory]: Instance number of the to be exported instance (1-99).
  • /pathglobal=<absolute path> [optional]: Comma-separated list of global directories to be included (e.g. C:\tools).
  • /pathinstance=<relative path> [optional]: Comma-separated list of per-instance to be included. Path starts from ..\KCM\Work\<version>\instance_nn\core. To include the folder  "..\KCM\Work\<version>\instance_nn\core\tools", use the value "tools".
Example: Create an export of instance 1 for a KCM 5.4 installation:

ConfigureInstance.exe /export /version=5.4 /file=C:\temp\InstanceExport.xml /instance=1

Example: Create an export of instance 1 for a KCM 5.4 installation with custom tools in the tools folder of Core:

ConfigureInstance.exe /export /version=5.4 /file=C:\temp\InstanceExport.xml /instance=1 /pathinstance=tools

Note-Icon.png

NOTE: pathinstance is relative. /pathinstance=tools is equal to ..\KCM\Work\5.4\instance_01\core\tools\

Importing an instance export

For importing an instance export the following parameters can be used:

  • /Import [mandatory]
  • /version=<version> [mandatory]: KCM version who's instance is imported.
  • /file=<file> [mandatory]: Path to XML file with the configuration.
  • /instance=<instance number> [mandatory]: Instance number of the to be imported instance (1-99).
Example: Import an instance export on instance 2 for a KCM 5.4 installation

ConfigureInstance.exe /import /version=5.4 /file=C:\temp\InstanceExport.xml /instance=2

Post-import steps

After importing a new instance export, the changes are not immediately applied. For the new configuration to become effective the Document Processors must be restarted. The Document Processor services have the display name "[core_instance_number_version] Aia ITP/Server Document Processor number". For example:

[core_01_5.4] Aia ITP/Server Document Processor 1

 

KCM 5.5 and later

For transferring the KCM instance configuration (including KCM Core) the ExportInstanceConfiguration.exe tool can be used. In KCM 5.5 and later this tool is used instead of ConfigureInstance.exe. This tool will create an export of

  • The dp.ini, dm.ini and itp.cfg configuration files of KCM Core.
  • The itprep.ini and pwdblacklist.txt configuration files of KCM Repository.
  • The itpmdkapi.ini configuration file of KCM RestAPI.
  • The log configuration of the KCM Designer.
  • The log configuration of the KCM Composer.
  • The custom KCM Core scripts and libraries.
  • The contents of the Did, Watermarks and Resources subfolders of the KCM Core work folder.
  • If exported with infrastructure, configuration includes as well the registration information (partner, customer, contract manager host etc).

The ExportInstanceConfiguration.exe tool cannot include user-defined folders with custom tools. If custom tools must be included, consider placing these in the Resources folder in the KCM Core folder (..\KCM\Work\5.5\instance_01\Core\Resources\). The Resources folder is included by th ExportInstanceConfiguration.exe tool.

The tool resides at:

..\KCM\Programs\<version>\Management\Instance\ExportInstanceConfiguration.exe.

Creating an export

To create an export the following parameters can be used:

  • KCM!Version [Optional]: KCM: KCM version who's instance is exported. Relevant when two KCM versions are installed. Mandatory if no KCM installation is active.
  • Instance!Number [Mandatory]: Instance number of the to be exported instance (1-99).
  • Instance!ExportConfigurationFile [Mandatory]: The ZIP file (export file) to write the export to.
  • Instance!ExportInfrastructure [Mandatory]: True or False. Determines whether infrastructure information must be included.
Example: Create an export of instance 1 for a KCM 5.5 installation:

ExportInstanceConfiguration.exe KCM!Version=5.5 Instance!Number=1 Instance!ExportConfigurationFile=C:\temp\InstanceExport.zip Instance!ExportInfrastructure=False

Importing an export

ImportInstanceConfiguration.exe is the tool used for importing an instance configuration export.
For importing an instance export the following parameters can be used:

  • Instance!Number [Mandatory]: Instance number of the to be exported instance (1-99).
  • Instance!ExportConfigurationFile [Mandatory]: The ZIP file (export file) to read the export from.
  • Instance!ExportInfrastructure [Mandatory]: True or False. Determines whether infrastructure information is imported.
  • Registration!ContractManagerHost [Optional]: When importing with infrastructure, overrides the Contract Manager hostname in the instance registration.
  • Registration!InstanceHost [Optional]: When importing with infrastructure, overrides the hostname of the KCM instance in the instance registration.
Example: Import an instance export on instance 2 for a KCM 5.5 installation

ImportInstanceConfiguration.exe Instance!Number=2 Instance!ExportConfigurationFile=C:\temp\instanceExport.zip Instance!ExportInfrastructure=False

Post-import steps

After importing a new instance export, the changes are not immediately applied. For the new configuration to become effective the instance must be stopped and started using StopInstance.exe and StartInstance.exe.

  1. Navigate to ..\KCM\Programs\<version>\Management\Instance
  2. Run StopInstance.exe Instance!Number=xx where xx is the instance number where the export was imported on.
  3. Run StartInstance.exe Instance!Number=xx where xx is the instance number where the export was imported on. 

Content of Repository Server (Designer projects)

Designer projects can be exported via two different methods.

  • The Core scripting commands RepositoryExportProject and RepositoryImportProject. These commands have the limitation that only a single project at a time can be transferred. This is the easiest method for transferring a Designer project.
  • The command line tools RepExport.exe and RepImport.exe. These tools can be used via batch/PowerShell scripts. It is possible to create exports that contain multiple projects.
Core scripting commands RepositoryExportProject and RepositoryImportProject

For more information for using the Core scripting commands RepositoryExportProject and RepositoryImportProject, please refer to chapter RepositoryExportProject and chapter RepositoryImportProject in the Core Scripting Language Developer's guide (link).

RepExport.exe and RepImport.exe

The command line tools for exporting and importing Designer projects are located at:

..\KCM\Programs\<version>\ITPMDKRepositoryServer\

Exporting a Designer project

RepExport.exe has the following parameters:

  • /file=<file> [mandatory]
  • /transfer <project(s)> [mandatory]: Space-separated list of projects to be exported. Enclose each project within double quotes in case the project name contains a space.
  • /user=<user> [mandatory]: Username of Designer user.
  • /password=<password> [mandatory]: Password of Designer user.
  • /cfg=<itprep.ini file> [mandatory]: Path to itprep.ini file of the Designer instance (KCM Repository server).
Example: Export two Designer projects

RepExport.exe /file=C:\temp\export.mdk /transfer "Project 1" "Project 2" /user=kcm /password=password /cfg=C:\kcm\work\5.5\instance_01\designer\config\itprep.ini

Importing a Designer project

RepImport.exe has the following parameters:

  • /file=<file> [mandatory]
  • /replace [mandatory]: Indicates the imported Designer project overwrites the existing project.
  • /user=<user>: Username of Designer user.
  • /password=<password>: Password of Designer user.
  • /cfg=<itprep.ini file>: Path to itprep.ini file of the Designer instance (KCM Repository server).
Example: Import a Designer project

RepImport.exe /file=C:\temp\export.mdk /replace /user=kcm /password=password /cfg=C:\kcm\work\5.5\instance_01\designer\config\itprep.ini

Configuration of the Contract Manager

The configuration of the Contract Manager rarely needs to be synchronised. In general this is only required when a new interface and/or contract type is introduced. Before transferring the contract manager configuration, first the KCM instance must be synchronised (See the earlier section "Configuration and service scripts of KCM Core"). 

KCM 5.5 and later

In KCM 5.5+ all interfaces and contract types can be transferred to another Contract Manager using the tools ExportContractManagerConfiguration.exe and ImportContractManagerConfiguration. This leaves only the step of re-registering the instances and adding the new contract type to the contract. The tools ExportContractManagerConfiguration.exe and ImportContractManagerConfiguration can be used for transferring this configuration. These tools will transfer:

  • The log configuration of the Contract Manager.
  • The log configuration of the Contract Manager Registration.
  • The custom interfaces and custom contract types that are registered on the Contract Manager.

The tools reside at:

..\KCM\Programs\<version>\Management\Contract Manager

Export the configuration

ExportContractManagerConfiguration.exe has the following parameters:

  • KCM!Version=Major.Minor [optional]: : KCM version who's Contract Manager configuration is exported. Relevant when two KCM versions are installed.
  • ContractManager!ExportConfigurationFile=<file> [mandatory]: Path to zip archive to write with the configuration.
  • ContractManager!ExportInfrastructure=false [mandatory]

ExportContractManagerConfiguration.exe ContractManager!ExportConfigurationFile=C:\temp\CMExport.zip ContractManager!ExportInfrastructure=false

Import the configuration

ImportContractManagerConfiguration.exe has the following parameters:

  • ContractManager!ImportConfigurationFile=<file> [mandatory]: Path to zip archive with the configuration.
  • ContractManager!ImportInfrastructure=false [mandatory]

ImportContractManagerConfiguration.exe ContractManager!ImportConfigurationFile=C:\temp\CMExport.zip ContractManager!ImportInfrastructure=false

Post-Import steps

After the configuration has been loaded, there are still some steps that must be executed.

  • Restart the Contract Manager to make the new configuration active.
  • In case a new contract type is introduced, add the new contract type to the contract using ManageCM.exe.

All relevant tools reside at:

..\KCM\Programs\<version>\Management\Contract Manager

  1. Open command prompt as administrator and navigate to ..\KCM\Programs\<version>\Management\Contract Manager
  2. StopContractManager.exe
  3. StartContractManager.exe
  4. ManageCM.exe /registerinstance /host=<hostname> /instance=<instance number> /update
  5. ManageCM.exe /addcontracttypetocontract /partner=<partner> /customer=<customer> /name=<CT name> /version=<CT version> /force
  6. managecm.exe /reloadconfiguration

ManageCM.exe in the previous steps requires some parameters:

  • /host=<hostname>: The hostname of the KCM instance machine. To retrieve the hostname, run the command hostname via command prompt.
  • /instance=<instance number>: The instance number of the instance (1-99).
  • /partner=<partner>: The partner of the contract. For a default installation the value is CCM.
  • /customer=<customer>: The customer of the contract. For a default installation the value is Local.
  • /name=<CT name>: The name of the contract type to add to the contract.
  • /version=<CT version>: The version of the contract type to add to the contract (1-99).

KCM 5.4 and earlier

In KCM 5.4 and earlier all interfaces and contract types can be transferred to another Contract Manager using the ManageCM.exe tools. This leaves only the step of re-registering the instances and adding the new contract type to the contract.

The tool resides at:

..\KCM\Programs\<version>\Management\Contract Manager

If KCM 5.3 or earlier is used, then two extra parameters must be provided to ManageCM.exe. Add these parameters to all ManageCM.exe commands in the following sections.

  • /user=<user> : Username of database user for accessing the KCM database
  • /password=<password> :  Password of database user for accessing the KCM database
Export the configuration

ManageCM.exe has the following parameters:

  • /ExportDatabase [mandatory]
  • /file=<file> [mandatory]: Path to XML file to be written with the Contract Manager configuration.
  • /contracttypes [mandatory]
Example:

ManageCM.exe /ExportDatabase /file=C:\temp\CMExport.xml /contracttypes

Import the configuration

ManageCM.exe has the following parameters:

  • /ImportDatabase [mandatory]
  • /file=<file> [mandatory]: Path to XML file with the Contract Manager configuration.
  • /update [mandatory]
Example:

ManageCM.exe /ImportDatabase /file=C:\temp\CMExport.xml /update

Post-Import steps

After the configuration has been loaded, there are still some steps that must be executed.

  • In case a new contract type is introduced, add the new contract type to the contract using ManageCM.exe.
  • Reload the Contract Manager to make the new configuration active.
  1. ManageCM.exe /registerinstance /host=<hostname> /instance=<instance number> /update
  2. ManageCM.exe /addcontracttypetocontract /partner=<partner> /customer=<customer> /name=<CT name> /version=<CT version> /force
  3. managecm.exe /reloadconfiguration

ManageCM.exe in the previous steps requires some parameters:

  • /host=<hostname>: The hostname of the KCM instance machine. To retrieve the hostname, run the command hostname via command prompt.
  • /instance=<instance number>: The instance number of the instance (1-99).
  • /partner=<partner>: The partner of the contract. For a default installation the value is CCM.
  • /customer=<customer>: The customer of the contract. For a default installation the value is Local.
  • /name=<CT name>: The name of the contract type to add to the contract.
  • /version=<CT version>: The version of the contract type to add to the contract (1-99).

 

Level of Complexity 

Moderate

 

Applies to  

Product Version Build Environment Hardware
Kofax Communications Manager n/a n/a n/a n/a

 

Article # 3039404
  • Was this article helpful?