How to Add User Transformations in RudderStack

A step-by-step guide on adding your custom transformation function in RudderStack

Introduction

With RudderStack, you can now implement your own custom transformation functions that leverage the event data, to implement specific use-cases based on your business requirements. You can find more information on these user transformation functions in our GitHub repository.

In this guide, we walk you through the steps involved in creating and testing your user transformation functions in RudderStack.

Please note that the user transformations only work for the cloud mode destinations.

To know more about the cloud mode in RudderStack, check out the RudderStack Connection Modes guide.

Creating a User Transformation

Please follow the steps mentioned below:

Transformations option on the RudderStack dashboard
  • Click on the Create New option as shown:

Create New option on the Transformations page
  • In the following screen, please enter the name you would like to assign to the custom transformation. Enter the transformation function's code in the Transformation window, as shown in the figure below:

  • You need to add your user transformation's code within the transform function in the Transformation window. You can also add other functions and call them from within transform.

You can copy-paste the entire code of any of the functions in this repository into the Transformation window. Do remember to delete the pre-populated transform function in such cases, before pasting your code.

  • You can also test your transformation function by running a test, as shown:

Accessing Metadata

RudderStack injects a function metadata(event) into your transformations. This allows you to access environment variables that will help in customizing your transformations.

metadata() takes the event as input and returns the metadata of the event.

The following are the properties, if available, present in the metadata response:

Property name

Description

sourceId

SOURCE ID from RudderStack dashboard (this is different from the write key).

Refer to the image below.

destinationId

DESTINATION ID from the RudderStack dashboard

messageId

Unique ID for each event

sessionId

If sessions are enabled, this has the value of session ID

function transform(events) {
events = events.map(ev => {
const meta = metadata(ev);
ev.sourceId = meta.sourceId
return ev;
});
return events
}
Source Details

External API requests

You can make any external API requests in your transformer functions and use the response to enrich your events data. RudderStack injects an asynchronous fetch(url) function into your transformations. It makes an API call to the given url and returns the response in JSON format.

Examples of how to use fetch function in transformations are as shown:

Basic
POST
Headers
Basic
async function transform(events) {
const res = await fetch("any_api_endpoint");
events.map(e=>{
e.response = JSON.stringify(res);
return e;
})
return events;
}
POST
async function transform(events) {
const res = await fetch("post_url", {
method: "POST", // POST, PUT, DELETE, GET, etc.
body: JSON.stringify(events),
headers: {
"Content-Type": "application/json;charset=UTF-8",
},
});
events.map(e=>{
e.response = JSON.stringify(res);
return e;
})
return events;
}
Headers
async function transform(events) {
const res = await fetch("post_url", {
method: "POST", // POST, PUT, DELETE, GET, etc.
headers: {
"Content-Type": "application/json;charset=UTF-8",
"Authorization": "Bearer <your_authorization_token>"
},
body: JSON.stringify(events),
});
events.map(e=>{
e.response = JSON.stringify(res);
return e;
})
return events;
}

You can check out the Clearbit enrichment example which uses the fetch function.

Use batch API requests instead of a separate API request for each event whenever possible for improved performance.

Limits

Take into account the memory and time limits when adding a new user transformation. Each invocation of the user transformation should not exceed these limits. User transformation fails when these limits are exceeded.

Memory limit: 128 MB

Time limit: 4 Seconds

Contact Us

If you want to know more about user transformations in RudderStack, feel free to contact us. You can also talk to us on our Slack channel.