Warehouse Sync API v2 Tutorial

Use this tutorial to configure your first Warehouse Sync pipeline using the mParticle Postman collection, and use the data from your pipeline to create an mParticle Audience. Postman is an easy and friendly environment for both developers and non-developers to use APIs.

This tutorial is not a complete guide to all Warehouse Sync features. For a complete API reference, see the Warehouse Sync API Reference.

Prerequisites

• Install the latest version of the Postman desktop application. You can download Postman from https://www.postman.com/downloads/.

• Fork the mParticle Warehouse Sync Postman Collection to your workspace:

  

  A copy of the Warehouse Sync environment is included. You can download it again here.

Step 1. mParticle setup

Create Platform API credentials

You need credentials to use the Platform API to create Warehouse Sync pipelines.

To create a Platform API credential:

1. After signing in to the mParticle app as a user with the Admin role, click the user icon in the bottom left corner.

   
2. Click Settings.
3. Select the API Credentials tab.
4. Click the green Add Credential button in the top right.

5. Give the credential a name, check the Platform checkbox and select Admin from the Permissions dropdown menu. Click the green Save button.

   
6. Copy the Client ID and Client Secret values for use in a later step.
7. Click Done.

Step 2. Data warehouse setup

Work with your warehouse administrator or IT team to ensure your warehouse is reachable and accessible by mParticle.

1. Whitelist the mParticle IP address range so your warehouse will be able to accept inbound API requests from mParticle.
2. Ask your database administrator to perform the following steps in your warehouse to create a new role that mParticle can use to access your database. Select the correct tab for your warehouse (Snowflake, Google BigQuery, or Amazon Redshift) below.

USE ROLE ACCOUNTADMIN;

// Create a unique role for mParticle 
CREATE ROLE IF NOT EXISTS {{role_name}};

GRANT USAGE ON WAREHOUSE {{compute_wh}} TO ROLE {{role_name}};
GRANT USAGE ON DATABASE {{database}} TO ROLE {{role_name}};
GRANT USAGE ON SCHEMA {{database}}.{{schema}} TO ROLE {{role_name}};

// Grant SELECT privilege on any tables/views mP needs to access
GRANT SELECT ON TABLE {{database}}.{{schema}}.{{table}} TO ROLE {{role_name}};

// Recommend creating a unique user for mParticle
CREATE OR REPLACE USER {{user_name}} PASSWORD = "{{unique_secure_password}}";
GRANT ROLE {{role_name}} TO USER {{user_name}};

// Note: Don't change the name of the storage integration: plug in your mP POD, Org ID, 
// and Acct ID into the name, and be sure to leave the other characters as they are 
// ("mp_", underscores, and "_s3").
//
// Use the value for your mParticle instance for {pod_mp_aws_account_id}:
// US1 = 338661164609
// US2 = 386705975570
// AU1 = 526464060896
// EU1 = 583371261087
CREATE OR REPLACE STORAGE INTEGRATION {{storage_integration_name}}
          WITH TYPE = EXTERNAL_STAGE
          STORAGE_PROVIDER = S3
          ENABLED = TRUE
          STORAGE_AWS_ROLE_ARN = "arn:aws:iam::{{pod_mp_aws_account_id}}:role/ingest-pipeline-data-external-{{org_id}}-{{acct_id}}"
          STORAGE_AWS_OBJECT_ACL = "bucket-owner-full-control"
          STORAGE_ALLOWED_LOCATIONS = ("s3://{{pod}}-ingest-pipeline-data/{{org_id}}/{{acct_id}}");


GRANT USAGE ON INTEGRATION {{storage_integration_name}} TO ROLE {{role_name}};

-- Create a unique user for mParticle
CREATE USER {{user_name}} WITH PASSWORD '{{unique_secure_password}}'

-- Grant schema usage permissions to the new user
GRANT USAGE ON SCHEMA {{schema_name}} TO {{user_name}}

-- Grant SELECT privilege on any tables/views mP needs to access to the new user
GRANT SELECT ON TABLE {{schema_name}}.{{table_name}} TO {{user_name}}

{
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Resource": "arn:aws:iam::{{pod_mp_aws_account_id}}:role/ingest-pipeline-data-external-{{org_id}}-{{acct_id}}",
            "Sid": ""
        }
    ],
    "Version": "2012-10-17"
}

Step 3. Postman setup

Once you have installed Postman, configure the collection environment settings and variables.

Update Postman environment settings

1. Ensure you forked the mParticle Warehouse Sync API Postman Collection, as described in the Prerequisites section of this tutorial. In Postman, click the Environments tab from the left navigation menu.

2. If you successfully forked the Warehouse Sync API collection, you’ll see it in the list of Environment configurations. You can rename it to something more meaningful by right-clicking on the … next to the name and choosing the Rename option.

   

3. Replace the the placeholders (replace_me) with the correct values for your environment. You must update the values under column labeled Current value.

   • Replace PLATFORM_API_CLIENT_ID and PLATFORM_API_CLIENT_SECRET with your new Platform API credentials.

   • Replace WORKSPACE_ID, ACCOUNT_ID, and ORG_ID with the corresponding values for your mParticle account.

     • To find your Org ID, log into the mParticle app. View the page source. For example, in Google Chrome, go to View > Developer > View Page Source. In the resulting source for the page, look for “orgId”:xxx. This number is your Org ID.
     • Follow a similar process to find your Account ID (“accountId”:yyy) and Workspace ID (“workspaceId”:zzz).
   • Replace POD with the regional pod your mParticle account is deployed on. Look at the URL in your browser where you are signed into mParticle. The POD is one of the following values: US1, US2, EU1, AU1.

4. Enter the data warehouse usernames and passwords you saved from “Step 2. Data Warehouse Setup.” according to the data warehouse you are using:

   • For Snowflake, replace SNOWFLAKE_PASSWORD and SNOWFLAKE_STORAGE_INTEGRATION with the values you saved in step 2.
   • For BigQuery, replace BIG_QUERY_SERVICE_ACCOUNT_ID with the service account ID you used in BigQuery, and BIG_QUERY_SERVICE_ACCOUNT_KEY with the key from the generated JSON file in step 2.
   • For Redshift, replace REDSHIFT_USER, REDSHIFT_PASSWORD, and REDSHIFT_AWS_IAM_ROLE_ARN with the values created in step 2.
5. After updating all necessary values, run COMMAND-S (or CTRL-S) to save your changes.

Update the Postman collection

1. Ensure you forked the mParticle Warehouse Sync API Postman Collection as described in the Prerequisites section. In Postman, click the Collections tab on the left hand navigation.
2. Once successfully forked, you’ll see the collection in the list of available collections.
3. Click Warehouse Sync API, then select the Variables tab.

4. Replace replace_me placeholders with the values corresponding to your environment. Ensure you update the values in the Current value column.

   • Replace INGEST_PIPELINE_SLUG and INGEST_PIPELINE_NAME with the slug and name you want to use to identify your new pipeline.

   • Replace SQL_QUERY with the database SQL query mParticle will use to retrieve data from your warehouse. SQL is a powerful language and you can use advanced expressions to filter, aggregate, join, etc. your data. Work with your database administrator if you need help crafting the right SQL query:

     • Your query can contain a timestamp column that mParticle will use to keep track of which rows need to be loaded.
     • Your query should contain one or more user identity columns that mParticle will use to perform identity resolution to ensure that data ends up on the correct user profile.

     • As part of the SQL query, you must specify how columns in the query will map to attributes on a user’s profile. You do this by using column aliasing in SQL. For example, in the following query, the column cid in Snowflake is being mapped to the mParticle attribute customer_id.

       

       If you don’t provide an alias, mParticle will use the name of the column in your database. If an attribute of this name does not already exist on the user’s profile, mParticle will create a new attribute with this name.

   • Before using the query in mParticle, test the query outside of mParticle to ensure it returns the data you expect.
   • To learn more checkout the Warehouse Sync SQL reference
5. After updating all necessary values, run COMMAND-S (or CTRL-S) to save your changes.

Step 4: Create your first Warehouse Sync pipeline

Creating a Warehouse Sync pipeline takes four steps:

1. Create the partner feed.
2. Create the connection.
3. Create the data model.
4. Create the pipeline.

After configuration, you can monitor the pipeline.

Create the partner feed

First, you must create a data feed by submitting a request to the Feeds API. mParticle uses this feed for rules and connections in your workspace. You must provide a value for module_name that corresponds with the data warehouse you are using.

Valid values for module_name are:

• Redshift
• BigQuery
• Snowflake

These values are case sensitive. For example, if you use snowflake instead of Snowflake, you will encounter errors later in your configuration.

1. In Postman, ensure the environment drop-down is pointed to the Environment configuration you recently imported.
2. Expand the Warehouse Sync Collection and open the Feeds folder.
3. Click Create Warehouse Sync Feed.

4. Click the Body tab to see the information you will pass to the API in order to create the feed.

   
   • module_name must be one of Snowflake, BigQuery, or Redshift

   Values surrounded by double braces (for example: {{WORKSPACE_ID}}) are taken from the variables you updated in previous steps of this tutorial.

5. Verify all values you changed, and click the blue Send button. mParticle returns a success message with details about your new feed. If the request fails, mParticle returns an error message with additional information.

Create the connection

The next step is to create a connection between mParticle and your data warehouse.

1. In Postman, ensure the environment drop-down is pointed to the Environment configuration you recently imported.
2. Expand the Warehouse Sync Collection and open the Connections folder.
3. Click POST Create Snowflake/BigQuery/Redshift Connection, selecting the appropriate endpoint for the data warehouse you are using.

4. Click the Body tab and replace each "replace_me" placeholder with the correct value for your specific warehouse.

   The values in {{Sample Values}} are taken from the environment variables you updated in earlier steps. Make sure these values match the values for your organization’s data warehouse. You may need to work with your database administrator to ensure you have the correct values.

5. Verify all values you changed, and click the blue Send button. mParticle returns a success message with details about the configuration you just created. If the request fails, mParticle returns an error message with additional information.

   

Create the data model

The next step is to create a data model. mParticle uses this information to determine what data should be extracted from your database and how it should map to mParticle’s data model.

1. In Postman, expand Warehouse Sync API and click Data Models.
2. Click Create Data Model.

3. Select the Body tab and enter your data model.

   
4. The values in {{Sample Values}} are taken from the variables you updated in previous steps.
5. Once you are confident all values are correct, click the blue Send button. mParticle returns a success message with details about the data model you just created. If the request fails, mParticle returns an error message with additional information.

Create the field transformation

After you have decided which data to ingest into mParticle from your warehouse, create a field transformation to map event data fields in your warehouse to fields in the mParticle JSON schema.

Field transformations are required for all warehouse sync pipelines that ingest event data. Field transformations are not available for pipelines that ingest user data.

While your data model maps user data from your warehouse to mParticle user attributes, any simple event data must be mapped to the mParticle JSON schema using a field transformation.

For detailed instructions on how to create a field transformation, see the Field Transformations API reference. To use your field transformation, add the field_transformation_id to the request body of your API call when creating your pipeline in the next step.

Create the pipeline

The final step is to create the pipeline. You pass in the connection and data model configurations previously created along with your sync mode and scheduling settings.

1. In Postman, expand Warehouse Sync Collection and open the Pipelines folder.
2. Click Create Pipeline.

3. Select the Body tab, and update the sync_mode and schedule settings as follows:

   • For sync_mode:

     • Set type to either incremental or full
     • If you set type to incremental, Set iterator_field to the name of the column in your sql query mParticle will monitor to track changes that need to be synced

     • If you set type to incremental, Set iterator_data_type to the datatype of your iterator

       • Valid values for Snowflake are: timestamp_ltz, timestamp_ntz, timestamp_tz, datetime, date, timestamp_unixtime_ms, timestamp_unixtime_s.
       • Valid values for Google BigQuery are datetime, date, timestamp, timestamp_unixtime_ms, timestamp_unixtime_s.
       • Valid values for AWS Redshift are date, timestamp, timestamptz, timestamp_unixtime_ms, timestamp_unixtime_s.

   • For schedule:

     • Set type to interval, once, or on_demand
     • If you set type to interval, set frequency to hourly, daily, weekly, or monthly
     • Set start to the date-time value you want recurring syncs to begin
   

   The values in {{Sample Values}} will be taken from the variables you updated in previous steps. You can optionally update the environment variable. It is currently set to target your mParticle development environment, but you can change it to target your production environment.

4. Set the field_transformation_id to the ID of a a custom field transformation to map data from your warehouse to specific fields in the mParticle JSON schema. To learn more about custom field transformations and how to create them, see Field Transformations API.
5. You can associate an optional data plan with your pipeline to help improve the quality of, and grant you more control over, the data imported to mParticle. In the request body of API request, include the body parameters plan_id and plan_version and set these to the values of the data plan and version you want to use. You must use a data plan version that is active and exists in the mParticle workspace you are using.
6. Once you are confident all values are correct, click the blue Send button. If successful, mParticle returns a success message with details about the configuration you just created. If it was not successful, mParticle returns an error message with additional information.

Monitor the pipeline

Once a pipeline has been created, you can monitor its status using the additional requests provided in the Postman collection.

1. In Postman, expand the Warehouse Sync Collection and open the Pipelines folder.
2. Click Get Pipeline Report.
3. Click the blue Send button.

4. mParticle sends a detailed message with the pipeline’s current status. After creating a pipeline, there is an approximate one-minute delay until the pipeline is created in the mParticle backend, so submitting a Get Pipeline Report request results in a Not Founderror. Try again after several minutes.

   

5. While a pipeline is ingesting data, you can monitor it in mParticle as you would with any other input. From mParticle, go to Data Master > Live Stream to inspect the incoming data from Snowflake.

   

6. Once the data is ingested, the data points appear on the user’s profile. Go to Activity > User Activity and look up a sample profile. If the attributes do not appear as expected, validate the mapping you provided in the SQL query provided earlier.

   

Step 5. Activate the data

Now that the data has been loaded into mParticle, it’s time to put it to use by creating an audience using the newly ingested data and sending it to a downstream integration.

Create an audience

Create an audience that uses one of the attributes we ingested as a qualifying criteria for it:

1. In the mParticle app, go to Audiences > Standard.
2. Click the green New Standard Audience in the upper right corner.
3. Give the audience a name.
4. Select a date range, or choose “All available data.”
5. Select the Warehouse Sync feed you created in mParticle Setup.

6. Add an audience criteria that leverages one of the data points you ingested from your warehouse. In the example below, we only want to consider users who have a propensity-to-buy score that’s greater than 0.7.

   
7. Add any other criteria you want to be considered. Click Save As Draft when you are done.
8. Click Calculate to run the audience calculation.

Connect the audience to an output

In the final step, we will send users who qualified for this audience to Iterable for further targeting. If your organization doesn’t use Iterable, pick a different integration that your organization uses.

After the audience has been fully calculated, connect it to an output:

1. If you aren’t still there, go to Audiences > Standard.

2. In the row for the audience you just created, click the Connect button in the Actions column.

   

3. Click Connect Output.

   
4. Click the Add Output green button.
5. Click the Iterable tile in the integrations directory, or pick another integration your organization uses if you don’t have Iterable.

6. Select the Audience checkbox and click Configure.

   

7. Enter a configuration name, your Iterable API key, and the user ID that is used to identify users, and then click Save & Open in Connections.

   

8. Provide the ID of the list in Iterable that the user data should be loaded into, and click Add Connection.

   

9. Click the Send button to send the audience to Iterable.

   

10. Data starts flowing to Iterable.

    

Now you can open the audience in Iterable.