Source Insert Functions

Use Source Insert Functions to enrich, transform, or filter your data before it flows downstream to destinations.

There are two ways you can access source insert functions from your Segment workspace:

• From the Connections catalog.
• From the Sources tab.

Create a Source Insert Function

To create a source insert function from Segment’s catalog:

1. Navigate to Connections > Catalog > Functions and click New Function.

2. In the Select Function Type screen, select Source Insert and click Next: Build Function.

3. Write and test your function code. Enter a sample event and click Run to test the function.

4. Click Next: Configure & Create to add a function name, description (optional), and function logo (optional).

5. Click Create Function to save your insert function. The new source insert function displays in the Functions tab.

You can also go to Conections > Sources to create a source insert function in the Sources tab.

Coding the source insert function

Insert functions can define handlers for the following message types:

• onIdentity
• onTrack
• onPage
• onScreen
• onGroup
• onAlias
• onDelete

The default source code template includes handlers for all event types. Implement the types you need. For event types you want to send through, return the event in the respective event handler.

Settings

You can add and edit settings for source insert functions in the code editor. Settings allow you to configure the behavior of your source insert function, which changes how it is displayed to anyone using your function. To set up:

1. Go to the Settings tab in the code editor and click Add Setting.
2. Add the details about this setting.
3. Click Add Setting to save the configuration.

As you change values, such as Label, Name, Type, and Description, a preview updates showing how your setting will look and work. Once saved, the new setting appears in the Settings tab of the function. Here, you can edit or delete the setting.

Testing

You can test your source insert function with sample events or a manual configuration in the code editor. This allows you to test the functions behavior with real incoming data. To do this:

1. Go to the Test tab in the code editor and click Use Sample Event or customize the event yourself to set up your test data.
2. Click Run to execute the test.

Test results appear under Output, showing whether the function ran successfully or failed.

Connect a source insert function to a source

For data to flow downstream after transformation, connect your source insert function to a source. To do this:

1. Select the insert function you want to connect to the source. You can edit, delete, and connect the insert function on the side pane.
2. Click Connect a source.
3. Select the source you want to connect to and click Connect to Source.

Errors and error handling

Segment considers a function’s execution successful if it completes without error. You can throw an error to create a failure on purpose. Use these errors to validate event data before processing to make sure the function works as expected.

You can throw the following pre-defined error types to indicate that the function ran successfully, but the data was not deliverable:

• EventNotSupported
• InvalidEventPayload
• ValidationError
• RetryError
• DropEvent

This is similar to Source, Destination, and Insert Functions.

The errors listed are all permanent errors, except RetryError. When a RetryError is thrown, Segment reattempts to run the function a set number of times before permanently erroring out.

FAQs

Why does the Delivery Overview tab not display any errors that occur within the source insert function?

Errors in the Delivery Overview tab are not yet visible and is a work in progress.

Can I test the function with different event types?

You can test the function with different event types from the Test tab in the code editor, similar to other functions.

Can I use source insert functions for all types of sources?

Source insert functions only work for event sources, not object sources or rETL.

What is the expected latency for a source insert function?

The source insert function typically completes in 200 milliseconds to 5 seconds, depending on its complexity. The default timeout is 5 seconds but can be increased to 60 seconds.

What is the runtime environment?

Segment supports Node.js V18 and installs the dependencies listed here in the function. Segment also installs the following dependencies:

• @azure/identity exposed as azure.identity
• @azure/event-hubs exposed as azure.eventHubs
• @azure/synapse exposed as azure.synapse
• jsftp exposed as jsftp
• crypto-js exposed as cryptojslib.cryptojs
• akeyless exposed as akeylessLabs.akeyless
• akeyless-cloud-id exposed as akeylessLabs.akeylessCloudId
• @onesignal/node-onesignal exposed as oneSignal.oneSignal
• pg exposed as pg.pg
• snowflake-sdk exposed as snowflakesdk.snowflakesdk
• @clickhouse/client exposed as clickHouseClient.clickHouseClient
• aws4 exposed as aws4.aws4
• @sentry/node exposed as sentrylib.sentry