Transformation Libraries

RudderStack’s transformation libraries feature lets you reuse the same code in multiple transformations.

RudderStack now supports writing transformation libraries in Python for the RudderStack Cloud Growth and Enterprise plans.

Adding a library

1. In the RudderStack dashboard, go to Enhance > Transformations and click the Libraries tab.

2. Click Create library.
3. Add the library Name, Description and select the Language to write the library function. You can also add multiple functions in a single library.

4. Click Run Test to ensure the library code has the correct syntax.

Using libraries

To use the libraries in your existing transformations, note the Import Library Name option in the RudderStack dashboard:

RudderStack converts the library name into camel case without spaces; this becomes your library handle which you can use across multiple transformations. For example, if your library name is Sample Transformation Library, then the library handle would be sampleTransformationLibrary.

You can then use the library in a transformation with a simple import statement. Refer to the below use case for more information.

Use case

Suppose you want to filter the events that don’t contain an email address with the RudderStack domain. To do so, you can import a rudderEmail function from the transformation library isRudderEmail.

The rudderEmail function containing the filtering logic is shown below:

export function rudderEmail(email) {
    return /@(rudderlabs|rudderstack)| \+ruddertest/.test(email);
}

import re

def rudderEmail(email):
  match = re.search('@(rudderlabs|rudderstack)|\+ruddertest', email)
  if match:
    return True
  return False

The following snippets demonstrate how you can import this function in a transformation:

import { rudderEmail } from "isRudderEmail";
export function transformEvent(event) {
  const email =
    event.context && event.context.traits && event.context.traits.email;
  if (email) {
    if (!rudderEmail(email)) return;
  }
  return event;
}

from isRudderEmail import rudderEmail

def transformEvent(event, metadata):
    email = event.get("context", {}).get("traits", {}).get("email")
    if email:
        if not rudderEmail(email):
            return
    return event

On clicking Run Test, a sample event not containing the RudderStack email domain is filtered out:

Importing multiple functions from a single library

The following snippets highlight how to correctly import functions from a library:

// ---------------
import { getLoss } from "getFinanceData";

// OR

import { getLoss, getRevenue, getProfit } from "getFinanceData";
import {
  getLoss,
  getRevenue,
  getProfit
} from "getFinanceData";

// For default getPrice import
import getPrice, { getRevenue, getProfit } from "getFinanceData";

// alias imports
import getPrice as gp, { getRevenue as gr, getProfit } from "getFinanceData";
// usage: gp(event), gr(event), getProfit(ev)

import * as GFD from "getFinanceData";
// usage: GFD.getRevenue(ev), GFD.getProfit(ev)
// for default import: GFD.default(ev)

from getFinanceData import getRevenue, getProfit
// usage: getRevenue(event), getProfit(event)

from getFinanceData import getRevenue as gr, getProfit
// usage: gr(event), getProfit(ev)

import getFinanceData
// usage: getFinanceData.getRevenue(event), getFinanceData.getProfit(event)

The following snippets highlight the incorrect way of importing the library functions:

// -----------------
import * from "getFinanceData";
getPrice(ev)

// OR

import getPrice as gp from "getFinanceData";
getPrice(ev)

import getRevenue, getProfit from getFinanceData
import { getRevenue, getProfit } from getFinanceData

from getFinanceData import *

Deleting a library

You cannot delete a library that is referenced or imported in a transformation.

To delete a library, go to Enhance > Transformations > Libraries and click the Delete button next to the library that you want to delete.

RudderStack libraries

By default, RudderStack provides three predefined libraries which you can directly import into your transformations. Refer to the GitHub codebase for the code and implementation-specific details for these libraries.

Currently, RudderStack libraries are available only for JavaScript. Python support (applicable for Growth/Enterprise customers) is coming soon.

Use the following structure to import the Rudderstack libraries:

@rs/<libraryname>/v1

A sample import statement is shown below:

import { JSEncrypt } from "@rs/encrypt/v1";

Encrypt/Decrypt PII

This library lets you encrypt and decrypt PII, including those stored in cookies.

User agent parser

The Parse user agent transformation template imports this library to add the user’s browser, engine, OS, device, and CPU-related information to the events.

Hashing PII

This library has three hash functions that hide sensitive PII like the user’s email, birthday, social security number, etc. You can use either MD5, SHA256, or cyrb53 to hash your PII.

Questions? Contact us by email or on Slack