Merge branch 'master' into develop

Author: forstisabella

src/_data/sidenav/main.yml

@@ -191,6 +191,8 @@ sections:
       title: Source Functions
     - path: /connections/functions/destination-functions
       title: Destination Functions
+    - path: /connections/functions/insert-functions
+      title: Destination Insert Functions
     - path: /connections/functions/environment
       title: Functions Environment
     - path: /connections/functions/usage

src/_includes/content/functions/caching.md

@@ -0,0 +1,21 @@
+Functions execute only in response to incoming data, but the environments that functions run in are generally long-running. Because of this, you can use global variables to cache small amounts of information between invocations. For example, you can reduce the number of access tokens you generate by caching a token, and regenerating it only after it expires. Segment cannot make any guarantees about the longevity of environments, but by using this strategy, you can improve the performance and reliability of your Functions by reducing the need for redundant API requests.
+
+This example code fetches an access token from an external API and refreshes it every hour:
+
+```js
+const TOKEN_EXPIRE_MS = 60 * 60 * 1000 // 1 hour
+let token = null
+async function getAccessToken () {
+  const now = new Date().getTime()
+  if (!token || now - token.ts > TOKEN_EXPIRE_MS) {
+    const resp = await fetch('https://example.com/tokens', {
+      method: 'POST'
+    }).then(resp => resp.json())
+    token = {
+      ts: now,
+      value: resp.token
+    }
+  }
+  return token.value
+}
+```

src/_includes/content/functions/errors-and-error-handling.md

@@ -0,0 +1,53 @@
+<!-- Use for destination and insert functions -->
+
+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 })
+    })
+  } 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.
+

src/_includes/content/functions/logs.md

@@ -0,0 +1,20 @@
+If your function throws an error, execution halts immediately. Segment captures the event, any outgoing requests/responses, any logs the function might have printed, as well as the error itself.
+
+Segment then displays the captured error information in the [Event Delivery](/docs/connections/event-delivery/) page for your function. You can use this information to find and fix unexpected errors.
+
+You can throw [an error or a custom error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error){:target="_blank"} and you can also add helpful context in logs using the [`console` API](https://developer.mozilla.org/en-US/docs/Web/API/console){:target="_blank"}. For example:
+
+```js
+async function onTrack(event, settings) {
+  const userId = event.userId
+
+  console.log('User ID is', userId)
+
+  if (typeof userId !== 'string' || userId.length < 8) {
+    throw new ValidationError('User ID is invalid')
+  }
+
+  console.log('User ID is valid')
+}
+```
+

src/connections/functions/destination-functions.md

@@ -81,56 +81,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.
-
-You can `throw` the following pre-defined error types to indicate that the function ran as expected, but that data was 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 })
-    })
-  } 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.
+{% include content/functions/errors-and-error-handling.md %}
 
 You can read more about [error handling](#destination-functions-logs-and-errors) below.
 
@@ -379,43 +330,7 @@ You can also choose to **Save & Deploy** to save the changes, and then choose wh
 
 ## Destination functions logs and errors
 
-A function can throw errors, or Segment might encounter errors while invoking your function. You can view these errors in the [Event Delivery](/docs/connections/event-delivery/) tab for your Destination as in the example below.
-
-![A screenshot of the event delivery tab, showing 519 failed events broken into categories explaining why they failed](images/event-delivery.png)
-
-### Destination functions error types
-
-- **Bad Request** - Any error thrown by the function code that is not covered by the other errors.
-- **Invalid Settings** - A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/){:target="_blank"}.
-- **Message Rejected** - Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
-- **Unsupported Event Type** - Your code doesn't implement a specific event type (for example, `onTrack()`) or threw an `EventNotSupported` error.
-- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
-
-Segment only attempts to send the event to your destination function again if a **Retry** error occurs.
-
-You can view Segment's list of [Integration Error Codes](/docs/connections/integration_error_codes/) for more information about what might cause an error.
-
-### Destination functions logs
-
-If your function throws an error, execution halts immediately. Segment captures the event, any outgoing requests/responses, any logs the function might have printed, as well as the error itself.
-
-Segment then displays the captured error information in the [Event Delivery](/docs/connections/event-delivery/) page for your destination function. You can use this information to find and fix unexpected errors.
-
-You can throw [an error or a custom error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error){:target="_blank"} and you can also add helpful context in logs using the [`console` API](https://developer.mozilla.org/en-US/docs/Web/API/console){:target="_blank"}. For example:
-
-```js
-async function onTrack(event, settings) {
-  const userId = event.userId
-
-  console.log('User ID is', userId)
-
-  if (typeof userId !== 'string' || userId.length < 8) {
-    throw new ValidationError('User ID is invalid')
-  }
-
-  console.log('User ID is valid')
-}
-```
+{% include content/functions/logs.md %}
 
 > warning ""
 > **Warning:** Do not log sensitive data, such as personally-identifying information (PII), authentication tokens, or other secrets. Avoid logging entire request/response payloads. The **Function Logs** tab may be visible to other workspace members if they have the necessary permissions.

src/connections/functions/environment.md

@@ -16,7 +16,7 @@ When you create a function, write code for it, and save it, the function appears
 Only [Functions admins](#functions-permissions) can create or edit functions.
 
 1. From your workspace, go to the Catalog and click the [Functions tab](https://app.segment.com/goto-my-workspace/functions/catalog){:target="_blank"}.
-2. Click **New Function**.
+2. Click **Create function**.
 3. Select the type of function you want to build, and click **Build**.
 
    When you click **Build**, a code editor appears. Different template code is available depending on which type of function you created.

src/connections/functions/index.md

@@ -10,7 +10,7 @@ Functions let you create your own sources and destinations directly within your
 ![An image illustrating source functions and destination functions in a Segment workspace](images/functions_overview.png)
 
 ## What can you do with Functions?
-Functions can help you bring external data into Segment ([Source functions](/docs/connections/functions/source-functions)) and send data in Segment out to external destinations ([Destination functions](/docs/connections/functions/destination-functions)). Functions are scoped to your specific workspace. If you're a technology partner and want to build a new integration and publish it in Segment's catalog, see the [Developer Center documentation](/docs/partners/).
+Functions can help you bring external data into Segment ([Source functions](/docs/connections/functions/source-functions)) and send data in Segment out to external destinations ([Destination functions](/docs/connections/functions/destination-functions)). Use [Insert functions](/docs/connections/functions/insert-functions) to transform data before it reaches your downstream destinations. Functions are scoped to your specific workspace. If you're a technology partner and want to build a new integration and publish it in Segment's catalog, see the [Developer Center documentation](/docs/partners/).
 
 #### Source functions
 Source functions receive external data from a webhook and can create Segment events, objects, or both. Source functions have access to the full power of JavaScript so you can validate and transform the incoming data and even make external API requests to annotate your data.
@@ -31,3 +31,16 @@ Use cases:
 - Enrich outgoing data using external APIs
 
 Learn more about [destination functions](/docs/connections/functions/destination-functions).
+
+#### 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.
+
+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 
+
+To learn more, visit [destination insert functions](/docs/connections/functions/insert-functions).