Custom Transforms Development Guide

When creating chained transforms, you have the flexibility to combine those built with OpenText Contivo and JavaScript, as well as mix custom and standard transforms. However, chained transforms cannot be chained together.

If you are creating a chained transform, please create each transform in the chain and then proceed with the upload and use step, where the execution order is defined. For the example above you would send us details such as:

Please execute these transforms in the order below

• Transform A
• Transform B
• Transform C
• Transform D

At this point you should have your validated mapping specification file and know which method you will use to create your transform. 

Create a Transform

In this step you will create the transform itself using your chosen method of creation. At the end of this step your transform will be a .jar or .js file. 

Creating Transforms with OpenText Contivo

The table below reviews the required materials for creating a transform using OpenText Contivo: 

Import the external system schema file and TraceLink’s canonical schema file to create your mappings in OpenText Contivo, using your mapping specification file for reference.

When complete, compile into a .jar file. This is what you will need to provide TraceLink in the upload and use step.

Creating Transforms with JavaScript

This step walks you through how to create a transform using Javascript, with the output being a .js file.

The code sample below shows the overall structure of a transform created with JavaScript. 

let response = {};
    try {
    // get input file contents
    // transform content
    // put output file
      response.result = "SUCCESS";
    } catch (e) {
      context.log().error(`Transform Javascript Activity: Error encountered while executing Javascript transform: ${e}`);
      response.result = "FAILURE";
      response.resultErrorText = e.message;
    }
    return response;

The following attributes are available for use:

context.log allows you to log messages

context.log().info('Transform Javascript Activity: Executing Javascript transform');

context.s3.getInputFileString returns a promise<string> to get the contents of the input file to be transformed

const inputFileString = await context.s3.getInputFileString();

context.s3.uploadOputFileString(data); returns a promise<S3PutOpjectResponse> to upload the transformed data to an object in S3

const uploadFileResponse = await context.s3.uploadOutputFileString(data);

context.sendEvent(event, appName, data) sends event handler requests and returns a Promise<object> for the event’s response. This can be used with any endpoints in our API reference documentation. For example, if your external system can provide a product’s ID, but not the name, you can make a call to product master data to retrieve and insert it.

const data = {
      transformName: 'TL_JSONtoCSV_1_0_OB',
      transformVersion: 1
    };
    const eventResponse = await context.sendEvent('masterdata-manager:get-product-by-itemcode:v1', 'masterdata-manager', data);

All JavaScript transforms should return a response object that is used to communicate success or failure of the transform execution. The response object should contain a result string attribute with either success or failure. If the result is FAILURE, the response should also have a resultErrorText string attribute to provide details about the cause. 

let response = {};
    try {
    // get input file contents
    // transform content
    // put output file
      response.result = "SUCCESS";
    } catch (e) {
      context.log().error(`Transform Javascript Activity: Error encountered while executing Javascript transform: ${e}`);
      response.result = "FAILURE";
      response.resultErrorText = e.message;
    }
    return response;

Sample JavaScript Transform

//Log the start of the transform activity
    context.log().info('Transform Javascript Activity: Executing Javascript transform');
    //Function to convert JSON object to XML format
    function JSONtoXML(obj) {
      let xml = '';
      for (let prop in obj) {
        xml += obj[prop] instanceof Array ? '' : '<' + prop + '>';
        if (obj[prop] instanceof Array) {
          for (let array in obj[prop]) {
            xml += '\n<' + prop + '>\n';
            xml += JSONtoXML(new Object(obj[prop][array]));
            xml += '</' + prop + '>';
          }
        } else if (typeof obj[prop] == 'object') {
          xml += JSONtoXML(new Object(obj[prop]));
        } else {
          xml += obj[prop];
        }
        xml += obj[prop] instanceof Array ? '' : '</' + prop + '>\n';
      }
      xml = xml.replace(/<\/?[0-9]{1,}>/g, '');
      return xml;
    }
    let response = {};
    try {
      //Get the input file as a string
      const inputFileString = await context.s3.getInputFileString();
      //Parse the input file string into a JSON object
      const inputFileObject = JSON.parse(inputFileString);  
      //Convert the inputFileObject to XML 
      const xml = JSONtoXML(inputFileObject);
      //Upload the resulting XML string as the output file
      const uploadFileResponse = await context.s3.uploadOutputFileString(xml);
      //Log the response from the upload output file indicating a SUCCESS or a FAILURE with an error message
      context.log().info(`Transform Javascript Activity: Response returned from upload output file api is: ${JSON.stringify(uploadFileResponse)}`);
      response.result = "SUCCESS";
    } catch (e) {
      context.log().error(`Transform Javascript Activity: Error encountered while executing Javascript transform: ${e}`);
      response.result = "FAILURE";
      response.resultErrorText = e.message;
    }
    return response;

Your transform should now be a .js file, ready for upload to TraceLink.

Upload and Use a Transform

Now that you have a .jar or .js containing your transform and are ready to upload it for use, please send an email with the information below below to partner-operations [at] tracelink.com (partner-operations[at]tracelink[dot]com).

You should receive an immediate, automated response if we successfully receive your request. A member of our team will follow up with you validating the required details and requesting your transform file.

Once we receive the file and upload it to our system, we will confirm when your transform is ready for use. At that time, we recommend testing your transform in your validation environment before proceeding to production. Please let us know if you encounter any issues that require our assistance. 

Change Management

Your custom transform cannot automatically account for any new or modified fields. Therefore, you will need to go through the steps above to generate a new .js or .jar file containing the changes. The uploaded changes will overwrite previous files unless otherwise specified. If you have any questions about this process please email partner-operations [at] tracelink.com (partner-operations[at]tracelink[dot]com).