Overview

Amazon Simple Storage Service (Amazon S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance. AWS Identity and Access Management (IAM) enables you to securely manage access to AWS services and resources.

Once you've set up a connection between Cordial and Amazon S3, Cordial can fetch data files from your S3 buckets for import into the Cordial database. You can also export data such as contacts, activities, or analytics. Using Amazon S3 for imports and exports allows for a secure and reliable data transfer between Cordial and your organization.

Configure connection

To start using the import and export data functionality with S3, you first you need to configure a connection between Cordial and Amazon S3.

1. Log in to Cordial, navigate to Integrations > Partners, and locate the Amazon S3 card. 

2. Click Enable to establish a connection between Cordial and your S3 bucket.

3. After the partner card is configured, a new option will appear on the data import and export pages within the UI.

Configure the Amazon S3 partner card

This is only required if you're using IAM Console authentication instead of access key authentication.

In order to configure the S3 partner card in Cordial, you need to:

1. Create an AWS role in your AWS account with the required permissions enabled.

2. Enter your AWS account ID and role name into the AWS Account ID and AWS Role Name fields.

Create AWS role

This is only required if you're using IAM Console authentication instead of access key authentication.

You need to create an AWS role that will have the required permissions to access the S3 bucket that will be used with Cordial. There are two ways to create a role: automatic and manual.

Automatic (recommended)

1. On the S3 partner card, select Automatically create new role. This opens the AWS Console and loads the CloudFormation stack. All the parameters are pre-filled but one: BucketName.

2. Enter the name of the bucket that Cordial will be reading from and writing to. Note the name of the role, which is set to CordialS3IntegrationRole by default.

3. Click Create stack and wait until it is created within AWS.

Manual

1. Create a new role in the AWS IAM Console.

2. Select Another AWS account for the Role Type.

3. For Account ID, enter 063772531253 if your Cordial account is us-west-1 or us-west-2, 362778264086 if your Cordial account is eu-west-1, or 160808713288 if your account is us-east-1. This means that you are granting Cordial access to your AWS data.

4. Select Require external ID and enter the ID generated on the S3 partner card. Make sure you leave Require MFA disabled.

5. Click Next: Permissions.

6. If you’ve already created the policy, search for it on this page and select it, then skip to step 12. Otherwise, click Create Policy, which opens in a new window.

7. Select the JSON tab. Use the policy snippet below in the text box.

8. Click Next: Tags and Review Policy.

9. Name the policy CordialS3IntegrationPolicy (or a name of your own choosing), and provide an apt description.

10. Click Create Policy, then close this window.

11. Back in the Create role window, refresh the list of policies and select the policy you just created.

12. Click Next: Tags and Next: Review.

13. Give the role a name such as CordialS3IntegrationRole, as well as an apt description.

14. Click Create Role.

Policy snippet

For your policy snippet, use the following JSON. Make sure to either replace <bucketName> with your bucket name, or to enable access to all buckets.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::<bucketName>",
            "Effect": "Allow"
        },
        {
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:GetObjectAttributes",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::<bucketName>/*",
            "Effect": "Allow"
        }
    ]
}

Enter role details on the S3 card

This is only required if you're using IAM Console authentication instead of access key authentication.

1. After the role is created, enter the AWS Account ID, which is your account ID, and AWS Role Name, which is the name of the role you created in AWS.

2. Click Test Connection to verify that the setup is complete.

3. Save the configuration. You are ready to import data from and export data to S3.

Send data from Amazon S3 to Cordial via the UI

Once the integration with S3 is set up successfully, you'll see the option to select AWS S3 as a data source when initiating data jobs via the UI.

1. Navigate to Data Jobs > Create New Data Job.

2. Choose the appropriate data job:

• Import: Contacts or supplements
• Export: Contacts, events, orders, or supplements

3. Select Edit in the Data Source pane.

4. Choose AWS S3 Bucket under Data location.

5. Choose your authentication method and fill in the remaining fields.

• IAM role: AWS bucket, AWS region, and Path

• Access Key: AWS key ID, Secret access key, AWS bucket, AWS region, and file Path

Send data from Cordial to Amazon S3 via the UI

You can send data from Cordial to S3 via the UI by selecting S3 as a destination for:

• Data Jobs and transformations
• Message reports
• Event data reports
• Audience Trends data
• Dashboard data

Import or export data via the API

Once enabled, Amazon S3 will be a source and destination option for importing and exporting data via the API. To learn more, you can visit our API documentation.