AWS S3 and Google Cloud Storage Integration

Overview

When you configure a connection to your storage bucket, Gainsight PX periodically exports user, account, and event data rollups to the bucket in the format (JSON, XML or CSV) you choose.

Following are the advantages of integrating Gainsight PX with storage buckets:

• Store usage data for further processing by other services such as security logs and for future reference
• Integrate with data warehouse platforms
• Run machine-learning algorithms

Prerequisites

Ensure the following are configured to integrate PX with storage buckets:

• Storage bucket (AWS or Google) with valid credentials and write permission to the bucket.
• Time zone as per your location. PX exports data to your bucket once per day for the previous day. The job starts at 3 AM  according to your subscription's timezone. The data will be available in a timeframe anywhere between a few minutes to a few hours, depending on the size of the files. For example, to create daily rollups for user events, PX sums up all events for the day based on your time zone. To set your Time Zone, navigate to Administration > Company Details > Time Zone.

Authentication Methods

Gainsight PX allows you to integrate the following mechanisms with Gainsight PX to export usage data:

• AWS
• Google Cloud Storage

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::aptrinsic-test-bucket"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::aptrinsic-test-bucket/*"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::581300747314:user/gspx-ext-s3-exports"
                ]
            },
            "Action": "sts:AssumeRole",
            "Condition": {                
                "StringEquals": {
                    "sts:ExternalId": "PX subscription ID"
                }
            }
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "allow-access-px-bucket",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::99999:role/s3-export-role"
            },
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::aptrinsic-test-bucket/*"
        }
    ]
}

Configure Data Export

To establish connection between Gainsight PX and S3 bucket:

1. Navigate to Administration > Integrations.
2. Click the Settings icon or Authorize button on the Amazon S3 Export widget in the Data Integrations section. The AWS S3 Settings dialog appears.

4. From the Authorization Method dropdown menu, select the type of authentication.
5. Enter the following details based on the Authorization Method selected: 
   • User Access Keys:
     1. S3 Bucket Name: Bucket name and any optional sub-folder(s) separated by slashes. This is the name of the bucket that was created in S3. For Example, to export files to a bucket ABC123 with a folder “export” use ABC123/export.
     2. AWS Access Key and AWS Security Token credentials of your S3 bucket. Ensure you enter valid credentials to establish an S3 integration.
        
         
   • IAM User Roles:
     1. S3 Bucket Name: Bucket name and any optional sub-folder(s) separated by slashes. This is the name of the bucket that was created in S3. For Example, to export files to a bucket ABC123 with a folder “export” use ABC123/export.
     2. User Role ARN: Enter the ARN of the AWS user role that was created using the AWS Console. For more information, refer to the IAM Roles section.
        
         
6. Choose data type from the Export Format drop-down list:

• CSV
• JSON
• XML

7. Choose the Export Version of the file

•  1.0
•  2.0 (Latest)
  
  Note: Gainsight supports two versions of export; 1.0 and 2.0. Version 2.0 is the latest and supports environment variables and is the recommended export method. List of files, fields, and groups differ for both the versions. For more information, refer to the Export Files Definition 2.0 and Export Files Definition 1.0 sections.

8. Get the Data Exports feature flag enabled by Support. Click the Select Reports option to view the Data Export Reports and PX Generated Reports sections. You can select the files you want to export to the AWS S3 bucket. 
9. Click the Summary option to view the summary of reports exported to the selected destination source.
10. Click Apply. 

11. If the credentials of your S3 bucket are valid, the status of integration changes to Authorized. Also, the Synchronize button is displayed. PX exports the data every day based on your time zone and includes data for the previous day. For more information on how to configure your time zone, refer to the Prerequisites section.
12. Click on the Synchronize button to understand the schedule for next sync.

13. Click the Disable Integration icon to disable PX integration with S3.

List of Fields and Group by Options in 2.0

The list of fields and New Group by options available in Version 2.0 are as follows:

Export Files

Below are definitions of the output files, including field names and types. Once you receive the data from storage buckets, use the information below to help you write and process the data. The files are compressed using gzip.

Note: For JSON extracts, the null values are omitted from the output files.

Filename Structure:
The filenames are of the form:

GainsightPX_{ExtractType}_{ISODateTime}.{json|csv|xml}.gz

Below tables give an overview about each export at its summary level.

Export File Column Definitions