Collecting data from Cordial

This guide explains how to collect data from Cordial. To learn how to collect data from a different data source, go back to the Available data sources in Adverity overview.

  • Cordial can collect a maximum of 1 million rows per single report. To fetch more data than this, split your fetch into smaller date ranges in the Initial Fetch step of creating a datastream.

Creating a datastream to collect data from Cordial

The basics of creating a datastream to collect data from any data source are explained in our guide to Creating a datastream. This guide contains information about the specific steps to create a datastream to fetch data from Cordial.

Authorization: Allow Adverity to access Cordial

Before creating an authorization to give Adverity access to Cordial, perform the following actions:

  1. Create an API key (also referred to as a Token) in the Cordial user interface as described in the Cordial documentation.

  2. Ensure that Adverity is whitelisted by Cordial. For more information, contact the Adverity Support team.

To set up a new authorization to fetch data from Cordial, follow these steps:

  1. In the Authorization step of the datastream wizard, click Access Cordial using your credentials.

  2. Click Next.

  1. In Token, enter the API key you created in the Cordial user interface.

  2. In AWS bucket, enter the name of the S3 bucket that contains the Cordial data.

  3. In Access key ID, enter the access key ID with which Adverity accesses the S3 bucket.

  4. In Secret access key, enter the secret access key with which Adverity accesses the S3 bucket.

  5. In AWS region, select the region associated with the Cordial data.

Configuration: Choose the data you want to collect from Cordial

To choose what data to collect and customize the Cordial datastream configuration, follow these steps:

  1. (Optional) Rename your datastream.

  1. In Report type, select the type of data to collect from Cordial.

  1. In Fields, change the list of fields that you want to see in your data extract.

  1. In Message type, select the type of message data to collect. Choose between batch and automation. This field is only available for certain report types.

  2. In Actions, choose the actions on which to collect data. This field is only available for certain report types.

  1. (Optional) In Time Zone, select the timezone of the time-related metrics.

What's next?

Advanced Cordial tips

Adverity cannot collect data directly from Cordial. Instead, Cordial sends data to an AWS S3 bucket, from which Adverity collects the Cordial data. The data collection process is as follows:

  1. Adverity makes an API call to Cordial, requesting a report.

  2. The report is generated by Cordial and then sent to an AWS bucket.

  3. Adverity can then collect the report from the AWS bucket.

Prerequisites

Before you read these tips, perform all of the following actions:

  • Ensure that you have access to your Cordial account.

  • Create an API token in the Cordial user interface. For more information, see the Cordial documentation.

  • Ensure you can access the AWS Policy Generator. For more information, see the AWS documentation.

  • Create an S3 bucket. For more information, see the AWS documentation.

  • Ensure you know the Bucketname and Pathname of your AWS S3 bucket. For more information on S3 bucket properties, see the AWS documentation.

Whitelisting the IP address of your Adverity instance

To whitelist the IP address of your Adverityinstance in the Cordial user interface, follow these steps:

  1. Find the IP address of your Adverity instance. To find the IP address of your Adverity instance, contact Adverity Customer Support.

  2. Add Adverity's IP address to the whitelist in the Cordial user interface.

Creating an AWS policy to collect Cordial data from an S3 bucket

To collect the Cordial data from an S3 bucket, create an AWS policy with the correct actions.

Below is a template for an AWS policy that collects the Cordial data from an S3 bucket. Change the template and assign the AWS policy to the IAM user associated with the S3 bucket. Change the following elements of the AWS policy:

  • In the Version field, enter a date as the version number.

  • In the ID field, enter an AWS Policy ID.

  • In the AWS field, enter the IAM user to which the AWS policy is applied. See the template below for formatting.

  • In the Resource field, enter the pathway to the S3 bucket. See the template below for formatting.

Find the template of the AWS policy to change below.

{
    "Version": "YYYY-MM-DD",
    "Id": "XYZNNNNNNN",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::45678:user/user"
            },
            "Action": [
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::bucket/*"
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::45678:bucket/user"
            },
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::bucket"
        }
    ]
}

For more information on creating and configuring AWS policies, see Advanced AWS policy configuration.