Skip to main content
Kinetic Community

Tree Converter

In Kinetic Task v3.2 and v4.0 we removed the ability to use erb tags (embedded ruby tags) in connector expressions. The Tree Converter is a utility that does its best to automatically convert the connector expressions it can. It essentially scans every tree in the Task environment and scans each connector to see if it matches certain patterns it can convert.  Connectors that match these patterns can be converted automatically. For connectors that do not match, it provides a way to define the replacement expressions and update them in batch without going into each tree and making modifications.

Support

We understand that updating connectors to remove erb tags can be an involved task. If you have questions about modifying connectors or any questions regarding the Tree Converter utility please feel free to contact Kinetic Data Support. 

Contact Info

Phone: (651) 556-1020

Email: support@kineticdata.com

Hours: Monday through Friday, 8AM to 5PM US Central Time

Download

The tree converter comes packaged as a jar file that can be executed from a command prompt. It requires a Java Development Kit (JDK) 1.6 or greater installation to run.

tree-converter.jar

Commands

This section documents each of the commands made available by the tree-converter.jar file.

Setup

The setup command prompts for the information necessary to connect to a Kinetic Task environment. It stores the server information and login credentials in a file name config.yml.

java -jar tree-converter.jar -setup

If you enter an incorrect value or wish to run the tree converter against another environment just re-run the setup command and it will overwrite any existing config.yml.

Note that all of the following commands require the presence of the config.yml file and will raise an error if one is not present.

Backup

The backup command retrieves every tree in the specified Task environment and saves their xml definitions in a backup csv file named something like backup.2015-01-07T094146-0600.csv.

java -jar tree-converter.jar -backup

This backup file can then be used by the restore command (see below) to revert any changes that have been made. For more details about the backup csv file see the Files section below.

Restore

The restore command takes a backup file and sets all of the trees to the xml definitions found in that file. This is useful whenever you would like to revert back to a previous state.

java -jar tree-converter.jar -restore BACKUP_FILE_NAME

Inspect

The inspect command retrieves every tree in the specified Task environment and scans each connector on those trees. It checks each connector to see whether or not it can be converted automatically. For connectors that can be converted automatically, it simply provides a count in the terminal output. Connectors that need translations are added to the translations.csv file

java -jar tree-converter.jar -inspect

The translations.csv file is used by the update command. Note that every time you run the inspect command it will create a new translations.csv file (overwriting the old one if present). For more details about the translations csv file see the Files section below.

An example of the inspect output is shown below.

inspect_output.png

Update

The update command uses the translations.csv file to update connectors in the specified Task environment. It scans through every tree and every connector, converting connectors that can be converted automatically. For connectors that cannot be converted automatically it looks for replacements defined in the translations.csv. Connectors with replacements defined will be updated, connectors with no replacements in translations.csv will be left untouched. Also note that all of the changes made throughout this process are tracked in an audit csv file named something like audit.2015-01-07T115619-0600.csv.

java -jar tree-converter.jar -update

For more details about the audit csv file see the Files section below.

Usage

The following is the recommended usage pattern of the tree converter utility.

  1. Run the setup command. This will create the config.yml file that contains connection information for the Kinetic Task environment.
  2. Run the backup command. This retrieves all of the trees in the specified Task environment and saves their xml definitions to a local csv file.
  3. Run the inspect command. This scans every tree in the Task environment for connectors that need to be modified. It prints a count of connectors that can be modified automatically. Connectors that cannot be converted automatically are added to the translations csv file. Note that this step will not make any changes within your environment.
  4. Open the translations.csv file, review and add replacement expressions where necessary.
  5. Run the update command. This scans all of the connectors in the Task environment and performs the conversions. All of the changes made are audited in a local csv file.
  6. Test.

At any point after changes are made, you can revert to the backup created in Step 2 by using the restore command.

Files

This section provides some examples and descriptions of all of the files mentioned above.

Configuration

The config.yml file is generated by running the setup command. It contains the server information and credentials necessary to connect to the Kinetic Task environment. The contents of an example config.yml are shown below.

The tree converter expects this file to be present when any of the other commands are run.

Backup

A backup csv file is created whenever the backup command is run. The file name will contain a timestamp so that multiple backups can be stored, for example backup.2015-01-07T094146-0600.csv. Below is an example of what the contents of the backup csv look like.

Note that in this screenshot the csv is opened in a spreadsheet editor rather than a text editor because it makes the data much easier to read.

Column Descriptions

Source The source root of the tree
Source Group The source group of the tree
Tree Name The name of the tree
XML Definition The XML definition of the tree

Translations

A translations csv file is created when the inspect command is run. It contains all of the connector expressions that cannot automatically be converted. Note that if the same exact expression is found on multiple connectors it is only shown once in the csv and the count of occurrences is noted. Below is an example translations.csv.

translations_csv.png

Once the replacements have been defined, this file is then used by the update command to perform the translations. 

Column Descriptions

Expression Contains the connector expression that did not match any of the patterns we can convert automatically.
Count The number of times the expression was used throughout the environment. For example, the same exact expression could be used in every tree in the environment.
Type Tells us what we need to do, either review the suggested replacement or define a replacement. For connector expressions that have erb tags surrounding the entire contents we suggest a replacement that simply removes those erb tags. Although this replacement will work most of the time there are some edge cases in which this is not the correct translation so we want to review them before making the change. See below for details about this particular edge case.
Replacement Contains the equivalent connector expression without erb tags.

Edge Case

Like stated above, most expressions where the erb tags surround the entire expression can be converted by simply removing the erb tags. But most is not all, take the expression below for example.

<%= @answers['Phone Required'] %>

Suppose that the two possible answers to the Phone Required question are "true" and "false". In older versions of Kinetic Task, this connector would have worked as expected. After the erb tags are resolved we would have the string "true" or the string "false". Then the engine would evaluate those strings to either the boolean true or the boolean false, which would be the result of the connector.

Now lets suppose that we convert this expression by simply removing the erb tags.

@answers['Phone Required']

When the engine evaluates this expression the result is always true because in ruby the string "true" and the string "false" are both treated as true values in expressions. Therefore this connector would always evaluate to true, regardless of the answer.

Below is one of the correct translations for this expression.

@answers['Phone Required'] == "true"

In summary, this is the reason we mark some connectors as "Needs Review" and do not convert them automatically. Most of the time the suggested replacement will be correct, but we should take a quick look at them to make sure its not a case like the one above.

Audit

An audit csv file is created each time the update command is run. It tracks all of the changes made by the update action. The file name will contain a timestamp so that multiple audits can be stored, for example audit.2015-01-07T115619-0600.csv. Below is an example of the audit csv file.

audit_csv.png

Column Descriptions

Source The source root of the tree
Source Group The source group of the tree
Tree Name The name of the tree
Parent Node The node at the head of the connector
Child Node The node at the tail of the connector
Action Tells us what action was performed to the connector. The updated (automatic) action means the connector matched a pattern we could convert automatically. The updated (manual) action means the connector was given a replacement in the translations csv file. Finally, the no action value means that we could not convert the connector automatically and no translation was provided so it was not changed.
Before The expression of the connector before update
After The expression of the connector after update