Merge branch 'master' into markettailor

Author: abcdefghijohn

src/connections/destinations/actions.md

@@ -26,6 +26,24 @@ Each Actions-framework Destination you see in the Segment catalog represents a f
 - If you are using Protocols, Destination Actions actions are applied *after* [schema filters](/docs/protocols/enforce/schema-configuration/) and [transformations](/docs/protocols/transform/). If you are using [destination filters](/docs/connections/destinations/destination-filters/), Actions are applied after the filters - meaning that they are not applied to data that is filtered out.
 - Destination Actions can not yet be accessed or modified using the Segment APIs.
 
+## Components of a Destination Action
+
+A Destination Action contains a hierarchy of components, that work together to ensure the right data is sent to the destination. 
+
+At the top level, is the Destination itself. It has two children: **Global Settings** and **Subscriptions**. 
+
+**Global Settings** are where you include authentication information like API keys, and other connection-related information. 
+
+**Subscriptions** handle the individual calls to the destination. In them, you define what type of call you want to make to the destination, and what triggers that call. Individual Destination Actions come enabled with some predefined subscriptions to handle common events like Screen calls, Identify calls, and Track calls. Subscriptions have two components that make this possible: **Triggers** and an **Action**. 
+
+**Triggers** enable you to define *when* the corresponding Action fires. As part of a Trigger, you can use condition-based filters to narrow the scope of the trigger.
+
+**Actions** determine the information sent to the destination. In the Configure action section, you map the fields that come from your source, to fields that the destination expects to find. Fields on the destination side depend on the type of action selected
+
+For example, in the Amplitude (Actions) destination, you define your API and Secret keys in the destination's global settings. Then, the provided Page Calls subscription:
+
+1. Triggers the action on all incoming Page events.
+2. Runs the Log Event action, to map your incoming data to Amplitudes properties.
 
 
 ## Set up a destination action
@@ -87,6 +105,13 @@ The following type filters and operators are available to help you build conditi
 
 You can combine criteria in a single group using **ALL** or **ANY**.  Use an ANY to “subscribe” to multiple conditions. Use ALL when you need to filter for very specific conditions. You can only create one group condition per destination action. You cannot created nested conditions.
 
+> info "Destination Filters"
+> Destination filters are compatible with Destination Actions. Consider a Destination Filter when:
+> - You need to remove properties from the data sent to the destination
+> - You need to filter data from multiple types of call (for example, Track, Page, and Identify calls)
+> 
+> If your use case does not match these criteria, you might benefit from using Subscription-level triggers to match only certain events.
+
 
 
 <!--

src/connections/destinations/catalog/actions-amplitude/index.md

@@ -45,6 +45,9 @@ Session tracking is only available when using Segment's new libraries: [Analytic
 Once you have a mapping, you can follow the steps in the Destinations Actions documentation on [Customizing mappings](/docs/connections/destinations/actions/#customizing-mappings).
 
 
+### Device ID Mappings
+The Amplitude destination requires that each event include either a Device ID or a User ID. If a User ID isn't present, Amplitude uses the a Device ID, and vice versa, if a Device ID isn't present, Amplitude uses the User ID. By default, Segment maps the Segment property `context.device.id` to the Amplitude property `Device ID`. If `context.device.id` isn't available, Segment maps the property `anonymousId` to the Amplitude `Device ID`. This is indicated by the following text in the Device ID field: `coalesce(` `context.device.id` `anonymousId` `)`. 
+
 ### Enable session tracking for Analytics.js 2.0
 
 The session tracking is automatically enabled on Javascript sources.

src/connections/destinations/catalog/amazon-kinesis/index.md

@@ -24,16 +24,18 @@ This document was last updated on February 05, 2020. If you notice any gaps, out
               "Effect": "Allow",
               "Action": [
                   "kinesis:PutRecord",
-                  "kinesis:PutRecords"
+                  "kinesis:PutRecords",
+                  "iam:SimulatePrincipalPolicy"
               ],
               "Resource": [
-                  "arn:aws:kinesis:{region}:{account-id}:stream/{stream-name}"
+                  "arn:aws:kinesis:{region}:{account-id}:stream/{stream-name}",
+                  "arn:aws:iam::{account-id}:role/{role-name}"
               ]
           }
       ]
    }
    ```
-   **Note:** A previous version of this policy document only granted `PutRecord` access, which could slow down Kinesis write times by disallowing file batching. Substitute the updated policy document above to grant Kinesis `PutRecords` (plural) and allow batching.
+   **Note:** A previous version of this policy document only granted `PutRecord` access, which could slow down Kinesis write times by disallowing file batching. Substitute the updated policy document above to grant Kinesis `PutRecords` (plural) and allow batching. We've also requested `iam:SimulatePrincipalPolicy`, which will allow us to verify that the IAM Role has the appropriate Kinesis permissions without invoking the Kinesis API.
 
 3. Create an IAM role.
    Follow these instructions to [Create an IAM role](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) to allow Segment permission to write to your Kinesis Stream. When prompted to enter an Account ID, enter "595280932656". Make sure to enable 'Require External ID' and enter your Segment Source ID as the External ID*. This can be found by navigating to Settings > API Keys from your Segment source homepage. When adding permissions to your new role, find the policy you created above and attach it.
@@ -178,6 +180,30 @@ Replace that snippet with the following, and replace the contents of the array w
 }
 ```
 
+### Update IAM to Support PutRecords
+
+The Kinesis destination defaults to use PutRecords. A previous version of the IAM policy document only granted `PutRecord` access, which can slow down Kinesis write times and degrade data deliverability. Substitute the updated policy document above to grant Kinesis `PutRecords` (plural) and allow batching, like this: 
+   ```json
+   {
+      "Version": "2012-10-17",
+      "Statement": [
+          {
+              "Effect": "Allow",
+              "Action": [
+                  "kinesis:PutRecord",
+                  "kinesis:PutRecords",
+                  "iam:SimulatePrincipalPolicy"
+              ],
+              "Resource": [
+                  "arn:aws:kinesis:{region}:{account-id}:stream/{stream-name}",
+                  "arn:aws:iam::{account-id}:role/{role-name}"
+              ]
+          }
+      ]
+   }
+   ```
+After you update the IAM policy, Segment systems default to use PutRecords for more efficient data transmission. This is a zero-downtime change and does not impact your data other than increasing the deliverability success rate.
+
 ### Use a single secret ID
 If you have so many sources using Kinesis that it is impractical to attach all of their IDs to your IAM role, you can instead opt to set a single ID to use instead. This approach should be avoided in favor of the above approach if possible since it will result in you having to keep track of a secret value. To set this value, go to the Kinesis destination settings from each of your Segment sources and set the 'Secret ID' to a value of your choosing. This value is a secret and should be treated as sensitively as a password. Once all of your sources have been updated to use this value, find the IAM role you created for this destination in the AWS Console in Services > IAM > Roles. Click on the role, and navigate to the **Trust Relationships** tab. Click **Edit trust relationship**. You should see a snippet that looks something that looks like this:
 

src/connections/destinations/catalog/salesforce-marketing-cloud/index.md

@@ -281,14 +281,12 @@ In order to do this, you must have access to **Personas**. To learn more, [conta
 > **Tip**: We recommend that you use [SFMC batching](#optional-set-up-sfmc-batching) with Personas to help reduce the number of API calls that you send to SFMC, but this is optional. If you choose to set up batching, do this _before_ you set up the SFMC destination in your Segment workspace.
 
 1. In your Personas space, add the SFMC destination to a computed trait or audience.
-2. You can either sync to an existing Data Extension or you can make the sync create a new Data Extension in SFMC.
-   - To **Create a new Data Extension** leave the Data Extension External Key blank. This creates a new Data Extension in the default location configured for your SFMC instance, with all the required columns.
-   - To **Sync to an existing Data Extension**: enter the Data Extension External Key for the existing Data Extension. When your audience syncs to it, Segment adds a new column which stores the computed trait or audience membership.
+2. Enter the Data Extension External Key for the existing Data Extension. When your audience syncs to it, Segment adds a new column which stores the computed trait or audience membership.
 
-If you sync to an existing Data Extension, there are additional requirements:
+When you sync to an existing Data Extension, note these additional requirements:
 - The table cannot have an existing **Primary Key**, unless it is the `Contact Key` field, and the field type is `Text`.
 - All fields in the Data Extension must be nullable (meaning optional, or not required), except the `Contact Key` field.
-- Any fields that you will send with Segment, and which already exist in the Data Extension must be of the correct data type. If they do not exist, Segment creates them for you. The standard identifiers Segment sends come from the [Context object](https://segment.com/docs/connections/spec/common/#context), and appear in the image below.
+- Any fields that you send with Segment, and which already exist in the Data Extension, must be of the correct data type. If they do not exist, Segment creates them for you. The standard identifiers Segment sends come from the [Context object](https://segment.com/docs/connections/spec/common/#context), and appear in the image below.
 
 ![](images/existing-dext-data-types.png)