Working with different systems such as dedicated development, testing and productive environments can be a nightmare from a Kofax Developer’s point of view. There is no convenient way to copy the entire configuration from one system to the other. Fortunately, KTM 6.1 has been a game changer thanks one feature: Configuration Sets. And while deploying Batch Classes and KIC configurations still remain a nightmare, this article shows you how easy deployment can be with Kofax Transformations.
The scenario
Usually, a Kofax ecosystem is represented by a n-tier environment, with the following three tiers being the most common ones:
- A development system, sometimes your own machine,
- A test system, where the developed solutions will (and should) be tested thoroughly,
- A production system, where users will work on on a daily basis.
Note that some ecosystems include a UAT (user acceptance testing) system as well, but the proposed solution for release management stays the same. The following graphic shows an example of such an ecosystem: three different systems by themselves, they all have a KC and KTM installation, and their databases and file shares are separated as well (the latter ones may reside on clusters, of course).
The problem
Kofax Transformations relies on external files and sources – a lot. For example, the database locator uses a flat file as its datasource. There can be links to external libraries, and the online learning directory essentially is just a pointer to a path. So, here’s the catch: on each one of your systems, those sources and paths differ from one another.
That’s good, you want to keep it that way: you don’t want your test system to access live data from the production Search and Matching Server (KSMS) as you don’t want to put more load on said server. In a similar way, you don’t want your productive system to point to the same flat file as source for a fuzzy database that you use on your development machine – maybe you want to try adding a new column, temper with word separators – whoops, you just broke the whole productive environment.
So, you want to clearly separate every single project folder, all its databases, external sources, and so on. Release management was a nightmare, and here’s why:
The Dark Times
Before KTM 6.1, after we copied our KTM project from one system to the other, we had to change a lot by hand: paths to our relational databases, script variables that would point to a non-existing directory on the other system, the path to the online learning folder, and so on. Without any script or external helper we were forced to do that manually. Just to give you an impression, here’s what we’ve been doing over the past years when we wanted to deploy a KTM project:
- In the project builder, click on properties, databases tab
- For each database, change the source file path
- Re-import the database
- Go to the dictionaries tab
- For each dictionary, change the source file path
- Go to the script variables, adjust the paths
- Open the script(s), change constants, …
So you see – lots of manual steps, lots of potential for error. Due to this quite tedious work we developers became create, well, let’s call it creative. Here’s what I’ve seen over the years:
- Instead of maintaining two separated projects, have one single project located on a file share somewhere,
- Have all three projects point to the same source files, regardless of the risks involved,
- Maintain separated projects, but instead of replacing all files just copy & paste the changes you made,
- Stick to a very strict check list when deploying from one system to another,
- Have other people double-check all settings when deploying.
Even the best solution was just sub-optimal as it required lots of manual work attention. The lazy approaches were, as said, error-prone and likely to affect your productive systems at some point.
The Golden Age
With KTM 6.1 one of the most important features for efficient and accurate release management finally was released: Configuration Sets. They allows you not only to define different settings and paths per system, configuration sets also get loaded automatically depending on the system the whole project runs on. This is what KTM’s help says about them:
The settings that are controlled by configuration sets include:
- The path to the online learning files
- Dictionary import paths
- Local fuzzy database import paths
- Relational database connections
- Kofax Search and Matching Server settings
- Script variables
They got it all covered! In the screenshot below you’ll see my setup for the development (DEV) and test (UAT) systems, respectively. While the DEV system points to local paths and files, on the UAT system a network share is used.
So, how does the system know which configuration set to pick? That’s easy as well: just append the following section to the ACConfig.xml, and then state which set should be used on that system. Here’s the configuration for UAT:
<Transformation> <ConfigurationSet Name="UAT"/> </Transformation>
Beyond Configuration Sets
Configuration sets help a great deal, but how can we deploy the Transformation project as a whole from one system to another? As stated earlier, Transformations usually relies on external files. In the screenshot above you’ll see that I’m using a dictionary and a database – both point to a path on the respective systems. So, if we were to deploy the process as a whole, we need to copy those files as well. Here’s my approach: first, I like to create several folders to separate things as shown in the example below: there’s a folder for databases (and dictionaries), another one for KTM projects, and a third one for saved xdocs. I like to keep those folders in a another folder I call “Configuration“, and I store this folder in the respective CaptureSV folder (Server Files) to make it accessible to anyone with the proper permissions.
Then, within each folder, I create another folder per project. In our example we’re looking at a project called “CustomerLookup”. So, there’s a folder in db, another one in ktm, and so on. Within those folders, you’ll find the respective files – in db, there are two pain text files. In ktm, there’s the whole Transformations project.
+---db | \---CustomerLookup | db-customers.txt | dict-months.txt | +---ktm | \---CustomerLookup | | CustomerLookup.fpr | | CustomerLookup.lck | | CustomerLookup_ScriptVariables.xml | | Customers_db-customers.crp2 | | Customers_db-customers.txt | | Months_dict-months.txt | | | +---ClassificationTraining | | DocStorage.ds | | | +---Configuration Sets | | Transformation_DEV.xml | | Transformation_PROD.xml | | Transformation_UAT.xml | | | \---ExtractionTraining | DocStorage.ds | \---xdocs
With setup like that it is easy to move your whole (Transformation) configuration from one system to another. I like to use Robocopy for this task – it can copy individual files or entire directories, and it can be set up to resume copying after a timeout occurred, should the connection be interrupted (hence the name “robust” copy). It also ships with the most recent client and server operating systems. So, let’s assume the following use case: we would like to deploy the whole project from our DEV system to UAT, and let’s assume that those are our Server Files locations (where our entire configuration resides, of course):
- DEV system: \\fclust01\kfxdev\Configuration
- UAT system: \\fclust01\kfxuat\Configuration
Here’s a simple Robocopy call. The /E option tells robocopy to include the contents of all folders, which we want. The /Z option copies in restart mode (should the connection be lost at any point, robocopy will wait 30 seconds and then try to resume – you can also resume later on from where you left off with this command).
robocopy /Z /E "\\fclust01\kfxdev\Configuration" "\\fclust01\kfxuat\Configuration"
So – that’s all there is to do for Kofax Transformations! Of course, after copying the files you’d have to fire up Kofax Administration, synchronize the project, and then publish the batch class – guess there’s no way around that.
Conclusion and Outlook
Configuration Sets definitely make our lives as Kofax developers easier. Instead of reopening the Project Builder and replacing paths and values by hand or maintaining a different, isolated project we can just deploy the whole setup from one system to another – by using a simple copy command. Of course, sync and publish still has to be done manually, I know – well, maybe Kapow can automate that in the future, who knows. I’d like to see something similar to configuration sets in different products, for example in the Kofax Import Connector. Any additional thoughts? Let me know.