diff --git a/src/_includes/content/functions/errors-and-error-handling.md b/src/_includes/content/functions/errors-and-error-handling.md index 3ecccdc9e1..3ec02f99e1 100644 --- a/src/_includes/content/functions/errors-and-error-handling.md +++ b/src/_includes/content/functions/errors-and-error-handling.md @@ -1,4 +1,4 @@ - + Segment considers a function's execution successful if it finishes without error. You can also `throw` an error to create a failure on purpose. Use these errors to validate event data before processing it, to ensure the function works as expected. diff --git a/src/connections/functions/index.md b/src/connections/functions/index.md index ce35ab0ab7..2cb759185d 100644 --- a/src/connections/functions/index.md +++ b/src/connections/functions/index.md @@ -35,10 +35,10 @@ Learn more about [destination functions](/docs/connections/functions/destination #### Destination insert functions Destination insert functions help you enrich your data with code before you send it to downstream destinations. -> info "Destination Insert Functions in Private Beta" -> Destination Insert Functions is in Private Beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions. +> info "Destination Insert Functions in Public Beta" +> Destination Insert Functions is in Public Beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions. -Use cases: +Use cases: - Implement custom logic and enrich data with third party sources - Transform outgoing data with advanced filtration and computation - Ensure data compliance by performing tokenisation, encryption, or decryption before sending data downstream diff --git a/src/connections/functions/insert-functions.md b/src/connections/functions/insert-functions.md index 51a8395154..5415a908bb 100644 --- a/src/connections/functions/insert-functions.md +++ b/src/connections/functions/insert-functions.md @@ -14,8 +14,8 @@ Use Destination Insert Functions to enrich, transform, or filter your data befor **Customize filtration for your destinations**: Create custom logic with nested if-else statements, regex, custom business rules, and more to filter event data. -> info "Destination Insert Functions in Private Beta" -> Destination Insert Functions is in Private Beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions. +> info "Destination Insert Functions in Public Beta" +> Destination Insert Functions is in Public Beta, and Segment is actively working on this feature. Some functionality may change before it becomes generally available. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with any feedback or questions. ## Create destination insert functions @@ -91,6 +91,9 @@ async function onTrack(event) { timestamp: event.timestamp }) }) + + return event; + } ``` @@ -101,7 +104,60 @@ To change which event type the handler listens to, you can rename it to the name ### Errors and error handling -{% include content/functions/errors-and-error-handling.md %} +Segment considers a function's execution successful if it finishes without error. You can `throw` an error to create a failure on purpose. Use these errors to validate event data before processing it to ensure the function works as expected. + +You can `throw` the following pre-defined error types to indicate that the function ran as expected, but the data was not deliverable: + +- `EventNotSupported` +- `InvalidEventPayload` +- `ValidationError` +- `RetryError` + +The examples show basic uses of these error types. + +```js +async function onGroup(event) { + if (!event.traits.company) { + throw new InvalidEventPayload('Company name is required') + } +} + +async function onPage(event) { + if (!event.properties.pageName) { + throw new ValidationError('Page name is required') + } +} + +async function onAlias(event) { + throw new EventNotSupported('Alias event is not supported') +} + +async function onTrack(event) { + let res + try { + res = await fetch('http://example-service.com/api', { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ event }) + }) + + return event; + + } catch (err) { + // Retry on connection error + throw new RetryError(err.message) + } + if (res.status >= 500 || res.status === 429) { + // Retry on 5xx and 429s (ratelimits) + throw new RetryError(`HTTP Status ${res.status}`) + } +} + +``` +If you don't supply a function for an event type, Segment throws an `EventNotSupported` error by default. + You can read more about [error handling](#destination-insert-functions-logs-and-errors) below.