Sample RudderStack Transformations

RudderStack's Transformations feature gives you the ability to code custom JavaScript functions to implement specific use-cases on your event data. This repository contains some useful transformation templates that you can use to create your own transformations.

For more information on RudderStack Transformations, refer to the documentation.

Table of contents

• Getting Started
• Filtering
  • Denylist Event Names
  • Allowlist Email Domains
• Sampling
  • User Based
• Enrichment
  • Geolocation Data
  • User Data
  • User Agent Data
  • Dynamic Header
  • Dynamic Path
• Masking
  • Replace PII
• Cleaning
  • Remove Null Properties
• Miscellaneous
  • Source ID
  • Change Event Type
  • Batch

Getting started

The sample transformations and libraries included in this repository can be added via the RudderStack dashboard. Follow these steps:

1. In the RudderStack dashboard, go to Enhance > Transformations.
2. Click New Transformations.
3. Enter a name and description and add the code for the transformation or library.
4. Click Save.

For detailed steps on adding a new transformation or library, refer to the documentation.

Filtering

Denylist Event Names

Filter out event if a property (event name in this example) is included in a denylist.

1. Drop event if denylist includes event name
2. Return event otherwise

export function transformEvent(event, metadata) {
    const eventNames = ["game_load_time", "lobby_fps"];
    const eventName = event.event;
    if (eventName && eventNames.includes(eventName)) return;
    return event;
}

Example Input and Output

Input	Output
{  "event": "game_load_time" }
{  "event": "players" }	{  "event": "players" }

Allowlist email domains

Filter out event if a property (email domain in this example) is not included in a allowlist.

1. Return event if allowlist includes email domain
2. Drop event otherwise

export function transformEvent(event, metadata) {
    const domains = ["rudderstack.com", "rudderlabs.com"];
    const email = event.context?.traits?.email;
    if (email && domains.includes(email.split("@").pop())) return event;
    return;
}

Example Input and Output

Input	Output
{  "context": {   "traits": {    "email": "john@gmail.com"   }  } }
{  "context": {   "traits": {    "email": "john@rudderstack.com"   }  } }	{  "context": {   "traits": {    "email": "john@rudderstack.com"   }  } }

Sampling

User-based

Drop a random sample of events based on a property (user ID in this example)

1. Import cyrb53 function from hash library
2. Drop event if remainder of hashed user ID less than 5
3. Return event otherwise

import { cyrb53 } from "hash";

export function transformEvent(event, metadata) {
    const userId = event.userId;
    if (userId && cyrb53(userId) % 10 < 5) return;
    return event;
}

Example Input and Output

Input	Output
{  "userId": "54321" }
{  "userId": "12345" }	{  "userId": "12345" }

Enrichment

Geolocation data

Enrich event with geolocation data using an external API and IP address

1. Fetch geolocation data from external IP2Location API
2. Add data to event
3. Return event

export async function transformEvent(event, metadata) {
    if (event.request_ip) {
        const res = await fetch("<YOUR_API_ENDPOINT>" + event.request_ip); // Use your paid IP-to-geolocation API endpoint.
        event.context.geolocation = res;
    }
    return event;
}

Example Input and Output

Input	Output
{  "context": {   "ip": "64.233.160.0"  } }	{  "context": {   "ip": "64.233.160.0",   "geolocation": {    "country_code": "US",    "country_name": "United States",    "region_name": "California",    "city_name": "Mountain View",    "latitude": "37.405992",    "longitude": "-122.078515",    "zip_code": "94043",    "time_zone": "-07:00"   }  } }

User data

Enrich event with user data using an external API and email address

1. Get user data from external Clearbit API
2. Add data to event's traits
3. Return event

export async function transformEvent(event) {
    const email = event.context?.traits?.email;
    if (email) {
        const res = await fetch("https://person.clearbit.com/v2/combined/find?email=" + email, {
            headers: {
                "Authorization": "Bearer <your_clearbit_secure_key"
            }
        });
        event.context.traits.enrichmentInfo = res;
    }
    return event;
}

Example Input and Output

Input

Output

{  "context": {   "traits": {    "email": "alex@alexmaccaw.com"   }  } }

{  "context": {   "traits": {    "email": "john@gmail.com",    "enrichmentInfo": {     "id": "d54c54ad-40be-4305-8a34-0ab44710b90d",     "name": {      "fullName": "Alex MacCaw",      "givenName": "Alex",      "familyName": "MacCaw"     },     "email": "alex@alexmaccaw.com",     "location": "San Francisco, CA, US",     "timeZone": "America/Los_Angeles",     "utcOffset": -8,     "geo": {      "city": "San Francisco",      "state": "California",      "stateCode": "CA",      "country": "United States",      "countryCode": "US",      "lat": 37.7749295,      "lng": -122.4194155     },     "bio": "O'Reilly author, software engineer & traveller. Founder of https://clearbit.com",     "site": "http://alexmaccaw.com",     "avatar": "https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/d54c54ad-40be-4305-8a34-0ab44710b90d",     "employment": {      "domain": "clearbit.com",      "name": "Clearbit",      "title": "Co-founder, CEO",      "role": "leadership",      "subRole": "ceo",      "seniority": "executive"     },     "facebook": {      "handle": "amaccaw"     },     "github": {      "handle": "maccman",      "avatar": "https://avatars.githubusercontent.com/u/2142?v=2",      "company": "Clearbit",      "blog": "http://alexmaccaw.com",      "followers": 2932,      "following": 94     },     "twitter": {      "handle": "maccaw",      "id": "2006261",      "bio": "O'Reilly author, software engineer & traveller. Founder of https://clearbit.com",      "followers": 15248,      "following": 1711,      "location": "San Francisco",      "site": "http://alexmaccaw.com",      "avatar": "https://pbs.twimg.com/profile_images/1826201101/297606_10150904890650705_570400704_21211347_1883468370_n.jpeg"     },     "linkedin": {      "handle": "pub/alex-maccaw/78/929/ab5"     },     "googleplus": {      "handle": null     },     "gravatar": {      "handle": "maccman",      "urls": [       {        "value": "http://alexmaccaw.com",        "title": "Personal Website"       }      ],      "avatar": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",      "avatars": [       {        "url": "http://2.gravatar.com/avatar/994909da96d3afaf4daaf54973914b64",        "type": "thumbnail"       }      ]     },     "fuzzy": false,     "emailProvider": false,     "indexedAt": "2016-11-07T00:00:00.000Z"    }   }  } }

User agent data

Enrich event with parsed user agent data

1. Import UAParser function from user agent parser library
2. Add parsed user agent data
3. Return event

import { UAParser } from "userAgentParser";

export function transformEvent(event, metadata) {
    const userAgent = event.context?.userAgent;
    if (userAgent) {
        const parser = new UAParser();
        const parsedUserAgent = parser.setUA(userAgent).getResult();
        event.context.parsedUserAgent = parsedUserAgent;
    }
    return event;
}

Example Input and Output

Input

Output

{  "context": {   "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:98.0) Gecko/20100101 Firefox/98.0"  } }

{  "context": {   "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:98.0) Gecko/20100101 Firefox/98.0",   "parsedUserAgent": {    "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:98.0) Gecko/20100101 Firefox/98.0",    "browser": {     "name": "Firefox",     "version": "98.0",     "major": "98"    },    "engine": {     "name": "Gecko",     "version": "98.0"    },    "os": {     "name": "Mac OS",     "version": "10.15"    },    "device": {},    "cpu": {}   }  } }

Dynamic header

Add a dynamic header to event payload

1. Add dynamnic header to event
2. Return event

export function transformEvent(event, metadata) {
    event.header = {
        dynamic_header_1: "dynamic_header_1_value",
        dynamic_header_2: "dynamic_header_2_value"
    };
    return event;
}

Example Input and Output

Input	Output
{  "event": "Button Clicked" }	{  "event": "Button Clicked",  "header": {   "dynamic_header_1": "dynamic_header_1_value",   "dynamic_header_2": "dynamic_header_2_value"  } }

Dynamic path

Dynamically append the event endpoint

1. Add dynamic path to event's endpoint base URL
2. Return event

export function transformEvent(event, metadata) {
    const email = event.context?.traits?.email;
    if (email) event.appendPath = `/search?email=${email}`;
    return event;
}

Example Input and Output

Input	Output
{  "context": {   "traits": {    "email": "john@gmail.com"   }  } }	{  "context": {   "traits": {    "email": "john@gmail.com"   }  },  "appendPath": "/search?email=john@gmail.com" }

Masking

Replace PII

Fuzzy find and replace PII properties (social security number in this example)

1. Import walk function from fuzzy find replace library
2. Replace values where keys approximately match target keys
3. Return event

import { walk } from "fuzzyFindReplace";

export function transformEvent(event, metadata) {
    const targetKeys = [
        "SSN",
        "Social Security Number",
        "social security no.",
        "social sec num",
        "ssnum"
    ];
    walk(event, targetKeys, "XXX-XX-XXXX");
    return event;
}

Example Input and Output

Input	Output
{  "context": {   "traits": {    "socialSecurityNumber": "123-45-6789"   }  } }	{  "context": {   "traits": {    "socialSecurityNumber": "XXX-XX-XXXX"   }  } }

Cleaning

Remove null properties

Remove all properties with null values

1. Remove properties with null values
2. Return event

export function transformEvent(event) {
    if (event.properties) {
        const keys = Object.keys(event.properties);
        if (keys) {
            keys.forEach(key => {
                if (event.properties[key] === null) delete event.properties[key];
            })
        }
    }
    return event;
}

Example Input and Output

Input	Output
{  "properties": {   "revenue": null,   "quantity": 4  } }	{  "properties": {   "quantity": 4  } }

Miscellaneous

Source ID

Perform action if event is from a specific source

1. Do something if event from specified source
2. Return event

export function transformEvent(event, metadata) {
    if (metadata(event).sourceId === "12345") {
        // Do something
    }
    return event;
}

Change event type

Change the type of an event (track to identify in this example)

1. Change event from track to identify if conditions are met
2. Return event

export function transformEvent(event) {
    let updatedEvent = event;
    if (
        event.type === "track" && 
        event.event === "ide-authentication" && 
        event.properties?.email && 
        event.properties.email !== ""
    ) {
        updatedEvent.type = "identify";
        let updatedContext = event.context || {}; 
        updatedContext.traits = updatedContext.traits || {};
        updatedContext.traits.email = event.properties.email;
        updatedEvent.context = updatedContext;
    }
   return updatedEvent;
}

Example Input and Output

Input	Output
{  "type": "track",  "event": "ide-authentication",  "properties": {   "email": "john@gmail.com"  } }	{  "type": "identify",  "event": "ide-authentication",  "properties": {   "email": "john@gmail.com"  },  "context": {   "traits": {    "email": "john@gmail.com"   }  }

Batch

Perform action for each event in a batch

1. Do something for each event
2. Return events

export function transformBatch(events, metadata) {
    events.forEach(event => {
        // Do something
    });
    return events;
}

License

MIT