User-defined transformations

Customers that requires functionality not provided by Replicate's built-in transformations can write their own transformations, and then access them from the Replicate Expression Builder.

It is also recommended to use the Replicate Add-ons API which allows you to take advantage of Replicate's memory management and logging capabilities, while eliminating the need to create independent memory and logging routines.

For more information, see Replicate add-ons API.

The procedure below is based on the sample files located in:

<INSTALL_DIR>\addons\samples\MyTransformation

Changing the default addon name

You can change the default addon name (MyTransformation) simply by renaming the <INSTALL_DIR>\addons\samples\MyTransformation\MyTransformation.dll file as desired. Note that if you rename the DLL, you may also need to specify the new name when editing the addons_def.json.sample file described below (depending on which parameters you use).

Creating a user-defined transformation

To create a user-defined transformation:

1. Create a shared library that implements the following exported initialization function:

   typedef int AR_ADDON_INIT_FUNC(AR_ADDON_CONTEXT *context);

   All of the types and prototypes are defined in the ar_addon.h and

   ar_addon_transformation.h files located under <INSTALL_DIR>\addons\include.

1. Make sure your shared library is in the following location:

   <INSTALL_DIR>\addons\samples\addon_name

   Information note

   When working in a High Availability setup, the created binaries should be installed on all of the cluster instances.

2. Compile the transformation.

   The DLL is automatically created in the following location:

   <installation_dir>\addons\addon_name\addon_name.dll

3. Register the library in the addons_def.json.sample file located under <INSTALL_DIR>\addons.

   {
   	"addons": [{
   		"name": "MyTransformation",
   		"type": "STARTUP",
   		//"lib_path": "C:\\Program Files\\Attunity Replicate\\addons\\samples\\MyTransformation\\MyTransformation.dll",
   		//"lib_path": "/opt/attunity/replicate/addons/samples/MyTransformation/MyTransformation.so",
   		"init_function": "my_transformation_init_func"
   	}]
   }

   Where:

   • name is the logical name of the DLL (can be any name). If you do not use the lib_path parameter to specify the DLL path (see below), then the DLL file must reside in <INSTALL_DIR>\addons\<addon_name>. On Linux, the <addon_name> folder needs to be created manually and should either be the default addon name (MyTransformation) or its new name (if you changed it).

   • type is an optional parameter that specifies when to load the DLL. The only value that is currently supported is STARTUP.
   • lib_path is the full path of your DLL (e.g. C:\Transformations\MyManipulator.dll). This is required only if the DLL does not reside in <INSTALL_DIR>\addons\<addon_name> (as mentioned in the description of the name parameter above).
   • init_function is the function name, as it appears in the C file used to generate the DLL.
4. Save the file as addons_def.json.

5. Register the new function in the addon initialization function (mentioned in Step 1) as in the following example:

   USER_DEFINED_TRANSFORMATION_DEF	*transdef = GET_AR_AO_TRANSFORMATION_DEF();
   transdef->displayName = "prefix_with(X, Y)";
   transdef->functionName = "prefix_with";
   transdef->description = "prefix_with adds the prefix <Y_> to a given string X";
   transdef->func = trans_prefix_with;
   transdef->nArgs = 2;
   AR_AO_REGISRATION->register_user_defined_transformation(transdef);

6. Restart the Qlik Replicate Server service.

The new "prefix_with" function will be available in the Expression Builder under Functions->User Defined.