From e00195fee024d5e7cb5238c9f294b985458564f6 Mon Sep 17 00:00:00 2001 From: rchinn-segment Date: Fri, 30 Jun 2023 13:35:55 -0700 Subject: [PATCH 1/3] Insert Functions updates --- .../functions/errors-and-error-handling.md | 2 +- src/connections/functions/index.md | 6 +- src/connections/functions/insert-functions.md | 62 ++++++++++++++++++- 3 files changed, 63 insertions(+), 7 deletions(-) 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..bb78a25eeb 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 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. + +You can `throw` the following pre-defined error types to indicate that the function ran as expected, but that 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. From 0f5480955ee960238ac6e0860ffd7739647e1bb7 Mon Sep 17 00:00:00 2001 From: rchinn-segment <93161299+rchinn-segment@users.noreply.github.com> Date: Wed, 5 Jul 2023 09:13:06 -0700 Subject: [PATCH 2/3] Update src/connections/functions/insert-functions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/functions/insert-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/functions/insert-functions.md b/src/connections/functions/insert-functions.md index bb78a25eeb..3396dcc1ee 100644 --- a/src/connections/functions/insert-functions.md +++ b/src/connections/functions/insert-functions.md @@ -104,7 +104,7 @@ To change which event type the handler listens to, you can rename it to the name ### Errors and error handling -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. +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 that data was not deliverable: From 6c309196afe899d5e0a46f8e97a193e1d8fcace6 Mon Sep 17 00:00:00 2001 From: rchinn-segment Date: Wed, 5 Jul 2023 09:17:07 -0700 Subject: [PATCH 3/3] Apply suggestion from code review --- src/connections/functions/insert-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/functions/insert-functions.md b/src/connections/functions/insert-functions.md index bb78a25eeb..2ddef92f99 100644 --- a/src/connections/functions/insert-functions.md +++ b/src/connections/functions/insert-functions.md @@ -106,7 +106,7 @@ To change which event type the handler listens to, you can rename it to the name 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. -You can `throw` the following pre-defined error types to indicate that the function ran as expected, but that data was not deliverable: +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`