Create a Lambda Function for MC Data APIs

There are many ways to fire a Trigger API (beta) request when uploading a file to an external location such as Amazon S3. This tutorial shows how to use Amazon Web Services (AWS) lambda functionality to authenticate with Marketing Cloud. Then, how to fire a trigger API request after you upload a file to an S3 bucket.

This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

Before you begin to use the Trigger API, you must opt in to the beta.

Your new AWS lambda function can access your Marketing Cloud data after you create an installed package in Salesforce Marketing Cloud.

  1. From Setup, find and select Platform Tools.
  2. From Platform Tools, find and select Apps.
  3. From Apps, find and select Installed Packages.
  4. Create a new installed package.

New Package Details dialog with "Name" required field filled in as "AWS Lambda Authentication".

Enter the Name and Description values that you want.

  1. Add a component under the newly created Installed Package.
    1. The component is an API integration type.
    2. The component is a Server-to-Server integration type.
    3. Give the component the permissions for your lambda task: automation_write, and automation_execute.

To encrypt your SFMC installed package information at rest, store the information in AWS Secrets Manager. To further restrict values, authenticate using identity and access management (IAM). Store the Marketing Cloud Client ID, Client Secret, Authentication Base URI, and REST Base URI in AWS Secrets Manager.

  1. In the AWS Web Console, navigate to Secrets Manager.

  2. Select Store a new secret.

  3. Select Other type of secret as the Secret type.

  4. Add your Client ID, Client Secret, Authentication Base URI, and REST Base URI from the end of Setup Installed Package [task topic 1]. The sample lambda code uses the following keys mapped to their associated values:

    1. MC_Client_ID.
    2. MC_Client_Secret.
    3. MC_Auth_URI.
    4. MC_Rest_URI.

    "Secret type" dialog with "Other type of secret" chosen and Key/Value pairs of "MC_Client_ID": "<YOUR_MC_CLIENT_ID>", "MC_Client_Secret": <YOUR_MC_CLIENT_SECRET>, "MC_Auth_URI": <YOUR_MC_AUTH_URI>, "MC_Rest_URI": <YOUR_MC_REST_URI>.

You can select any encryption key for this operation. The names of the keys can be whatever you need.

  1. To navigate to the Configure secret step, select Next
  2. Configure the name, description, tags, resource permissions, and replication as necessary for your use case. You're using SFMC_Installed_Package for this example.
  3. To navigate to the Configure rotation step, select Next.
  4. Configure rotation on this page as applicable to your own setup.
  5. Select Next and review the summary. When you're satisfied with it, select Store button to create your secret.

To allow your AWS lambda function to access your newly created secret, create an IAM user with access to Secrets Manager.

  1. Navigate to IAM in the AWS Web Console.

  2. To create a user, select Add users.

  3. Enter a username. This example uses SFMC_API_Client.

  4. To enable the IAM user to authenticate in your AWS Lambda function, select Access key - Programmatic access.

    Set User Details dialog with "User Name" required field set to "SFMC_API_Client" and "Select AWS credential type" required checkbox set to "Access key - Programmatic access".

  5. To configure the user’s permissions, click Next: Permissions.

  6. Enter a Group name for your AWS Secrets Manager. This example uses SecretsAccess.

  7. To give access to AWS Secrets Manager in that group, add SecretsManagerReadWrite policy.

  8. To move to the user’s tags, select Create group and Next: Tags.

  9. Add any applicable tags to your new IAM users, then select Next: Review.

  10. Select Create user.

Make an AWS Lambda function that creates a data extension in your SFMC account. This example uses Python 3.7 for setting up the lambda function. You need the Access Key ID and Secret Access Key from your IAM user for subsequent steps in this document.

  1. In the AWS Web Console navigate to Lambda.

  2. Select Create function.

  3. Select the Lambda type Author from scratch.

  4. Enter a function name. In this example, the lambda function is named FILE_TRIGGER_AUTOMATION.

  5. Select Runtime Python 3.7.

    Basic information dialog with "Author from scratch" selected, Function name is "FILE_TRIGGER_AUTOMATION", Runtime is "Python 3.7" and Architecture is set to "x86_64".

  6. Select Create function.

Selecting a different runtime can require importing more dependencies. The sample lambda code shown requires Python 3.7.

Tie all the previous steps together, set up environment variables and configure the lambda function to access the SFMC secrets and fire the trigger API request.

  1. In the AWS Web Console, navigate to the lambda function.
  2. Copy the Sample Lambda Code to the Code tab, and save your changes.

Sample Lambda Code

  1. In the Configuration tab, select Environment variables.

  2. Select Add environment variable for each key value pair.

    1. Enter the key AWS_ACCESS and the value <SECRET_ARN>.
    2. Enter key AWS_SECRET with value <IAM_ACCESS_KEY>.
    3. Enter key AWS_SECRET_NAME with value <IAM_ACCESS_KEY>.
    4. Enter key SFMC_FILE_LOCATION_EXTERNAL_KEY with value <SFMC_FILE_LOCATION_EXTERNAL_KEY> This is the external key used in Marketing Cloud’s File Location configuration.

    Environment variables dialog with key-value pairs "AWS_ACCESS": <SECRET_ARN>, "AWS_SECRET": <IAM_ACCESS_KEY>, "AWS_SECRET_NAME": <IAM_ACCESS_SECRET>, "SFMC_FILE_LOCATION_EXTERNAL_KEY": <SFMC_FILE_LOCATION_EXTERNAL_KEY>.

  3. Select the General configuration section.

  4. Select Edit, and then change the Timeout value to at least 30 seconds. That interval is the minimum time required for the lambda function to authenticate to Marketing Cloud and fire the Trigger API request.

  1. On the S3 bucket where files are uploaded, navigate to the Properties tab, and select Create event notification.
  2. Enter an Event name and any optional configuration parameters.
  3. Select the Event types that fire the lambda function.
  4. Choose the lambda function (File_Trigger_Automation) previously created, and then save your changes.

Destination dialog with button group "Destination" with selected button "Lambda function". There's a button group "Specify Lambda function" with selected button "Choose from your lambda functions". There's also a dropdown menu "Lambda function" where "File_Trigger_Automation" is selected in the menu.

  1. To test your new lambda function create a trigger automation in Automation Studio.
  2. Upload a qualifying file to the S3 bucket location.
  3. Confirm that your automation started.