Automated deployment - Predictive Segmentation Using Amazon Pinpoint and Amazon SageMaker

Automated deployment

Before you launch the automated deployment, review the considerations in this guide. Follow the step-by-step instructions in this section to configure and deploy the solution into your account.

Time to deploy: Approximately 10 minutes

Prerequisites

Before you deploy this solution, you must deploy the Digital User Engagement Events Database solution that will create an Amazon Pinpoint project, configure the project’s event stream, and a queryable database of engagement data in Amazon Athena.

Updating the stack from version 1.0.1 or earlier

If you have previously deployed version 1.0.1 or an earlier version of this solution, follow this procedure to fully delete the previous Amazon CloudFormation stack before following the steps in this guide.

  1. Sign in to the AWS CloudFormation console.

  2. On the Stacks page, choose the stack created from the earlier version of this solution.

  3. Choose Delete to open the confirmation dialog and choose Delete stack.

    Note

    The solution is configured to retain all Amazon S3 buckets, Amazon CloudWatch logs, and any previously imported Amazon Pinpoint segments in order to retain all data. The SageMaker model that was previous deployed will also be retained. Deleting the stack will remove all other configured service artifacts. In AWS CloudFormation, choose the Resources tab to view all service artifacts.

Deploy the Digital User Engagement Events Database solution

This solution relies on the Digital User Engagement Events Database solution to set up an Amazon Kinesis Data Firehose to route the Amazon Pinpoint events into Amazon S3 where they can be queried with Amazon Athena. The Digital User Engagement Events Database solution also configures an Amazon Pinpoint project, removing the requirement for you to create one separately. Outputs from the Digital User Engagement Events Database solution will be used as inputs in this solution.

  1. Download the template to deploy the Digital User Engagement Events Database solution.

    Note

    For complete deployment instructions, refer to the separate Digital User Engagement Events Database solution implementation guide.

  2. Navigate to the AWS CloudFormation console.

  3. On the Stacks page, choose the stack created for the Digital User Engagement Events Database solution.

  4. On the stack details page, choose the Outputs tab and, under the Key column, locate DUES3DataLakeName and PinpointProjectId. These keys identify the Amazon S3 bucket that was created to store the Amazon Pinpoint engagement data and the Amazon Pinpoint Project ID. Copy the values of these outputs to use as inputs in this solution.

  5. Choose the Parameters tab and, under the Key column, locate the EventAthenaDatabaseName. This key identifies the Amazon Athena database name used for querying the engagement events. Copy the value of the output to use as an input in this solution.

Deployment overview

Deploying this architecture on AWS consists of the following steps. For detailed instructions, follow the links for each step.

Step 1. Launch the stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Review the other template parameters, and adjust if necessary.

Step 2. (Optional) Upload the sample Pinpoint segment

  • Upload the sample Pinpoint segment data for demonstration of the working solution.

Step 3. Run the notebook

  • Run the Jupyter Notebook to train the ML model.

Step 4. Run the state machine

  • Execute the AWS Step Functions state machine.

Step 5. Verify the segment exists and is receiving records

  • Verify that the solution created the Amazon Pinpoint segment, and that the churn segment shows records.

Step 1. Launch the stack

This automated AWS CloudFormation template deploys this solution in the AWS Cloud. Make sure that you have deployed the Digital User Engagement Events Database solution before launching the stack.

Note

You are responsible for the cost of the AWS services used while running this solution. Refer to the Cost section for more details. For full details, refer to the pricing webpage for each AWS service you will be using in this solution. Refer to Additional resources for links to the webpages for all services used in this solution.

  1. Sign in to the AWS Management Console and click the button below to launch the predictive-segmentation-using-amazon-pinpoint-and-amazon-sagemaker AWS CloudFormation template.

    
                                Predictive Segmentation Using Amazon Pinpoint and Amazon SageMaker launch button

    You can also download the template as a starting point for your own implementation.

  2. The template launches in the US East (N. Virginia) Region by default. To launch this solution in a different AWS Region, use the Region selector in the console navigation bar.

    Note

    This solution uses Amazon Pinpoint, which is currently available in specific AWS Regions only. Therefore, you must launch this solution in an AWS Region where Amazon Pinpoint is available. For the most current service availability by Region, refer to the AWS Regional Services List.

  3. On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.

  4. On the Specify stack details page, assign a name to your solution stack, for example, predictive-segmentation.

  5. Under Parameters, review the parameters for the template, and modify them as necessary.This solution uses the following default values.

    Parameter Default Description
    Amazon Pinpoint Project ID <Requires input>

    Specifies the Amazon Pinpoint project ID that contains the endpoints to be exported and where the churn segment will be created.

    Database Name due_eventdb Displays the name of the Amazon Athena database that was created from the Digital User Engagement Events Database solution.
    Amazon S3 <Requires input> Displays the Amazon S3 bucket created by the Digital User Engagement Events Database solution where the Amazon Pinpoint engagement events are stored.
    Load Sample Events <Requires selection> Indicates whether the sample customer data should be loaded into the Amazon S3 bucket for demonstration purposes.
    Model Training Instance Type ml.m4.xlarge Displays the SageMaker instance type used for model training.
    Transform Instance Type ml.m5.large Displays the SageMaker instance type used for batch transform requests.
    VPC Id <Requires selection> Specifies the identifier of Amazon Virtual Private Cloud where the SageMaker notebook instance is deployed.
    Subnet Id <Requires selection> Specifies the identifier of Amazon Virtual Private Cloud Subnet where the SageMaker notebook instance is deployed.
  6. Choose Next.

  7. On the Configure stack options page, choose Next.

  8. On the Review page, review and confirm the settings. Be sure to check the box acknowledging that the template will create AWS Identity and Access Management (IAM) resources.

  9. Choose Create stack to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation console in the Status column. You should see a status of CREATE_COMPLETE in approximately 10 minutes.

Note

In addition to the primary AWS Lambda functions, this solution includes the CustomResourceHelper Lambda function, which runs only during initial configuration or when resources are updated or deleted.

When running this solution, the CustomResourceHelper Lambda function is inactive. However, do not delete the function because it is necessary to manage associated resources.

Step 2. (Optional) Upload the sample Pinpoint segment

You can use a provided sample set of Amazon Pinpoint endpoint data to test the deployed solution end-to-end. The following steps outline how to import the sample data into Amazon Pinpoint for the solution to use. This is intended for demonstration purposes only.

  1. Download the SampleImport.csv sample segment file.

  2. Navigate to the Amazon Pinpoint console.

  3. In the All projects section, select the project to configure.

  4. In the navigation pane, choose Segments.

  5. Choose Create a Segment.

  6. Choose Import a segment and upload the SampleImport.csv file and choose Create segment.

Step 3. Run the notebook

For the solution to work, you must train and deploy an SageMaker model. The following steps outline how to run the supplied SageMaker notebook using the sample training data to deploy a model.

  1. Navigate to the Amazon SageMaker console.

  2. In the navigation pane, select Notebook instances.

  3. Select PredictiveChurnNotebookInstance.

    The notebook instance will already be running.

  4. Select Open Jupyter.

  5. In the Jupyter notebook interface, open the xboost_customer_churn.ipynb file.

  6. In the Cell dropdown menu, select Run All to run the file.

Note

After you run the notebook, you can terminate the notebook instance to reduce costs.

Step 4. Run the state machine

The solution is configured to run an AWS Step Functions state machine daily to update Amazon Pinpoint endpoints with a churn score from the SageMaker model. The following steps outline how to run the AWS Step Functions state machine manually to ensure that it runs successfully.

  1. Navigate to the AWS Step Functions console.

  2. In the navigation pane, select State machines.

  3. Select the the solution’s state machine. The name starts with DailyChurnListStateMachine.

  4. Choose Start execution.

    Wait for the state machine to finish executing. It can take up to 10 minutes to complete all of the steps.

Step 5. Verify the segment exists and is receiving records

To verify successful deployment, check that there is a segment in Amazon Pinpoint that contains all of the endpoints that are predicted to churn by the SageMaker model. The following steps outline how to verify in that the Amazon Pinpoint segment exists and contains endpoints.

  1. Navigate to the Amazon Pinpoint console.

  2. In the All Projects list, select the applicable project.

  3. In the navigation pane, choose Segments.

  4. Select the Predicted to Churn segment.

  5. Under Number of Records, verify there are entries.