Create Transformations

This guide will help you add a new transformation in the RudderStack dashboard. It also contains the steps to capturing any event-related information in your transformation using the log function.

Add new transformation

1. Log in to the RudderStack dashboard.
2. Go to Collect > Transformations and click Create Transformation.
3. Choose a transformation template for implementing specific use cases on your event data. To create a transformation from scratch, click Custom transformation.

4. Name your transformation. It must contain at least 2 characters.

5. In the Transformation window, select the language to write your transformation. RudderStack provides two options - JavaScript and Python 3.11.

Note that:

• RudderStack uses Node.js version 18.x for JavaScript transformations and libraries.
• Python transformations are available only in the RudderStack Cloud Growth and Enterprise plans.

5. Add your transformation function. You can also add other functions and call them from within the transformEvent function.

6. To test your transformation, import a payload using the Import event button. Then, click the Run Test button next to it.

If you don’t import any event and click Run Test directly, RudderStack tests your transformation against a default track event payload.

You can also switch between the portrait and landscape views for better readability by clicking the button next to Save Transformation.

Save transformation

To save the transformation, click the Save Transformation button at the bottom right.

Note that to save a transformation, it must run successfully with a test event. You will not be able to save a transformation in the following cases:

• Transformation code is invalid.
• Transformation gives an error upon running it with a test event, as shown:

Test transformation

RudderStack lets you test your transformations to identify and prevent any transformation errors. With this feature, you can thoroughly test various scenarios and edge cases on your event payloads, and ensure effective event processing within RudderStack.

Import event payload

To import a test payload, click the Import Event button.

RudderStack gives you the following options to test your transformations:

• Use sample/placeholder event data within the RudderStack Events tab to test your transformations on default RudderStack event payloads. This is helpful when you don’t have any live events in your workspace.
• Edit an event payload and save it as a new event. You can then use it to test your transformation.
• Use the Live Events feature to test your transformations on live events generated from your source.

You can select any default RudderStack event to test your transformation. RudderStack provides four sample payloads (identify, track, page, and screen) that correspond to common RudderStack events.

From the dropdown, select the source. Then, send some events from this source - they will appear in this window automatically.

Choose a live event and click Import. You can then test your transformation on this payload.

Once you import a live event, all the live events shown in the window are lost. You need to send new events to import a live event again.

Limitations

• You cannot import multiple sample events to test your transformation.
• The live events contain payloads present at the source. They do not resemble the enriched events you see in the Live Events viewer in your transformation.

Capture event information with logs

Once you add a transformation, you can capture any event-related information in the form of logs while testing it. You can do this by including the log function in your transformation code, as shown:

export function transformEvent(event, metadata) {
  const meta = metadata(event);
  event.sourceId = meta.sourceId;

  log("Event Name is", event.event, ";", "Message ID is", event.messageId);
  log("Source ID is", meta.sourceId);

  return event;
}

def transformEvent(event, metadata):
    meta = metadata(event)
    event['sourceId'] = meta['sourceId']
    
    log("Event Name is", event['event'], ";", "Message ID is", event['messageId'])
    log("Source ID is", meta['sourceId'])
    
    return event

On adding the above transformation and clicking Run Test, you can see the resulting log in the Logs section of the dashboard:

You can pass a string, number, or an object as an argument to the log function.

Questions? Contact us by email or on Slack