How to Transform Field Data During a Backup

CopyStorm supports dynamic transformation of field data after reading it from Salesforce and before it is written to the target database. This article describes how to add a new custom transformation to CopyStorm.

History of This Feature

This issue first arose when a customer wanted to encrypt Salesforce data for certain fields before it was written to the target database. Since the customer needed total control over the encryption process, an extension was added to CopyStorm to dynamically add field transformations.

Most customers do not require this feature — it is only used when Salesforce data needs to be modified prior to being added to a local relational database.

Feature Overview

The process of adding a new data transformer is not difficult — all that is required are the following steps:

  1. Write a Java class that implements the Capstorm interface com.aslan.sfdc.extract.transform.ITransformer.
  2. Add a TransformerRegistry.xml file to CopyStorm’s config directory to register the new transformer with CopyStorm.
  3. Update the TableRuleRegistry.xml file to enable the new transformer for the appropriate fields.

The rest of this article describes the development and deployment process for adding a new data transformer to CopyStorm that reverses any input string.

Example: The transformer in this article will turn “Capstorm” into “mrotspaC”.

Step 1: Write a Java Class Implementing the Transformer

The following code is an example data transformer implementation. After creating a new data transformer, package it in a jar and store the jar file in the “lib” subdirectory of the CopyStorm installation directory.

package com.capstorm.extension;

import org.apache.commons.lang3.StringUtils;
import com.aslan.sfdc.extract.transform.ITransformer;

public class ReverseTransformer implements ITransformer {

    /**
    * Take a string and return the string with the letters reversed.
    *
    *@param table - name of the Saleforce table containing the value
    *@param column - name of the Salesforce column containing the value
    *@param columnWidth - the number of characters in the column
    *@param recordId - the unique Saleforce record id containing the value
    *@param value - the values whose letters are to be reversed.
    *
    *@return the value with its letters reversed
    */
    @Override
    public String transform(String table, String column, int columnWidth, String recordId, String value) {
        if( null != value ) {
            value = StringUtils.reverse(value);
        }
        return value;
    }
}

Step 2: Register the Transformer with CopyStorm

CopyStorm discovers available transformers by looking for a file named TransformerRegistry.xml in the CopyStorm config directory.

The following TransformerRegistry.xml will cause CopyStorm to load the “Reverse” transformer:

<Transformers>
    <Transformer name="Reverse" class="com.capstorm.extension.ReverseTransformer" />
</Transformers>

The Transformer directive adds a new custom transformer using the following attributes:

  • name — the friendly name used to apply the transformer to a particular Salesforce field.
  • class — the full name of a class that implements the ITransformer interface.

Step 3: Attach a Transformer to a CopyStorm Field

CopyStorm discovers field transformations by looking for FieldTransform elements in the TableRuleRegistryFile.xml configuration file in CopyStorm’s config directory. The general format of this file is described in this article.

The following TableRuleRegistry.xml will cause CopyStorm to reverse the letters in the LastName for all Contacts before writing the LastName to the database:

<TableRule name="Contact">
    <FieldTransform name="LastName" transformer="Reverse" />
</TableRule>

FieldTransform configuration directives have the following options:

  • name — the name of a field in the corresponding Salesforce table.
  • transformer — the name of a registered transformer that will be applied to the field data. This is the same as the name specified in Step 2.

My Transformer Does Not Work. What Should I Do?

If your custom transformer is having no effect on data then the problem is likely in the new XML configuration directives.

To verify that your entry to TableRuleRegistry.xml is correct, use one of the built-in CopyStorm transformers. Built-in transformers include:

  • Scramble — replace each letter with a different letter, replace each number with a different number.
  • Blank — return a blank string.

If CopyStorm’s built-in transformer works then the problem is either in your TransformerRegistry.xml file or in your code. Put some debugging in your transformer to see if it is ever being called.

  • If it is not being called, the problem is in the TransformerRegistry.xml file.
  • If it is being called, then fixing the code is up to you!