GCP event file configuration tutorial

This guide steps you through configuring Google Cloud Platform (GCP) for Pismo real-time event delivery via Pub/Sub. You'll create a GCP project (a container for your Google Cloud resources) and a Pub/Sub topic where Pismo publishes events.

Prerequisites:

  • A Google Cloud account
⚠️

File retention and download responsibility. Pismo retains files in the bucket while your organization is active. However, we strongly recommend downloading files to your own infrastructure as soon as they are produced — either in real time (triggered by event notifications) or within 24 hours if you use a batch/polling strategy. These files belong to your organization, and keeping a local copy ensures you always have access. Please note that Pismo may charge additional fees for recovery requests of files older than 30 days.

Step 1: Select or create a project

  1. In the Google Cloud Console, click the project dropdown.
Screen capture of Select a project selection.
  1. Select an existing project, or click New Project to create a new one. If you select an existing project, skip the next two steps.

  2. Enter a project name and click Create.

  3. Select your project from the Notifications menu or from the projects dropdown menu.

Step 2: Create a Google Cloud Storage (GCS) bucket

  1. Navigate to Cloud Storage.
Screen capture of GCP Console.
  1. Click + Create Bucket.
Screen capture of the area to Name your bucket.
  1. Enter a bucket name, then click Create at the bottom of the form.

Step 3: Open a service desk ticket

  1. Go to: https://pismolabs.atlassian.net/servicedesk/customer/portal/10
  2. Click Settings.
  3. Enter a short description of the incident you are reporting in the Summary field.
  4. In Category, select Data.
  5. In Sub-Category, select File Integration.
  6. Copy the template below into the Description field and fill in your values:
INTEGRATION REQUEST — GCP Cloud Storage (Batch File Delivery)
=============================================================

Org ID:            TN-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment:       Production / Sandbox
Requester Name:    Your Name
Contact Email:     [email protected]

GCP Project ID:    my-project-123
GCS Bucket Name:   my-pismo-data-bucket
  1. When a Control Center request fails, the application automatically displays a popup message. You can add this message in the Report Log field.
  2. In Priority, select a priority level.
  3. In Environment, select the environment for the configuration.
  4. Click Send to submit the request.
📘

The Project ID is found in the GCP Console project selector — use the ID column (for example, my-project-123), not the display name. Bucket names must be globally unique, lowercase.

⏱️

Important: After Pismo completes the initial configuration, you have 24 hours to adjust permissions/access on your side. If Pismo cannot deliver events within this window, the integration will be paused and you will need to open a new ticket to resume.

📘

Need Pismo-specific details? Information such as Pismo's AWS Account ID, single-tenant SFTP endpoints, consumer role ARNs, or external IDs can be obtained from your Technical Account Manager (TAM) or the Implementation Engineer assigned to your project.

Step 4: Grant Pismo access

After Pismo processes your ticket, you'll receive a GCP IAM Service Account ID. Then:

  1. Go to your GCS bucket, select the Permissions tab, then click Add.
Permissions screen capture of the GCP bucket.
  1. Paste the Service Account ID in the New Principals field.
Screen capture of the New Principals field.
  1. Click in the Select a role field, and select Cloud Storage > Storage Object Creator.
Screen capture of the filter.
  1. Click Save. Pismo will start delivering files to your bucket.
Screen capture showing how to save changes.

CLI alternative: All steps via gcloud/gsutil

# Variables — replace with your values
PROJECT_ID="my-project-123"
BUCKET_NAME="my-pismo-data-bucket"
LOCATION="us-east1"

# Step 1 — Set project
gcloud config set project "$PROJECT_ID"

# Step 2 — Create bucket
gsutil mb -p "$PROJECT_ID" -l "$LOCATION" "gs://${BUCKET_NAME}/"

echo "Project ID:      $PROJECT_ID"
echo "GCS Bucket Name: $BUCKET_NAME"

Step 3: Grant Pismo access (after receiving the Service Account ID):

PISMO_SA="<service-account-id-from-pismo>@<project>.iam.gserviceaccount.com"

gsutil iam ch "serviceAccount:${PISMO_SA}:objectCreator" "gs://${BUCKET_NAME}"

echo "Granted Storage Object Creator to $PISMO_SA"

Download files:

# List files in the bucket
gsutil ls "gs://${BUCKET_NAME}/main_stream/"

# Download all files
gsutil -m cp -r "gs://${BUCKET_NAME}/main_stream/*" ./downloads/

# Download a specific file
gsutil cp "gs://${BUCKET_NAME}/main_stream/FILENAME" ./downloads/

Validate integration

Run this diagnostic script to validate your integration. It checks all configuration steps and provides troubleshooting guidance:

#!/bin/bash
# ============================================================
#  GCP Cloud Storage File Troubleshooting — Pismo
# ============================================================
PROJECT_ID="my-project-123"            # ← replace
BUCKET_NAME="my-pismo-data-bucket"     # ← replace
PISMO_SA=""                            # ← from Pismo
PASS=0; FAIL=0

echo "============================================================"
echo "  GCP Cloud Storage File Integration Diagnostics"
echo "============================================================"

# 1. gcloud authenticated?
echo "[1/5] Checking gcloud auth..."
if gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>/dev/null | head -1 | grep -q "@"; then
    echo "  ✅ PASS — Authenticated"
    PASS=$((PASS+1))
else
    echo "  ❌ FAIL — Not authenticated → gcloud auth login"
    FAIL=$((FAIL+1))
fi

# 2. Project accessible?
echo "[2/5] Checking project..."
if gcloud projects describe "$PROJECT_ID" >/dev/null 2>&1; then
    echo "  ✅ PASS — Project accessible"
    PASS=$((PASS+1))
else
    echo "  ❌ FAIL — Cannot access project $PROJECT_ID"
    FAIL=$((FAIL+1))
fi

# 3. Bucket exists?
echo "[3/5] Checking bucket..."
if gsutil ls -b "gs://${BUCKET_NAME}/" >/dev/null 2>&1; then
    echo "  ✅ PASS — Bucket exists"
    PASS=$((PASS+1))
else
    echo "  ❌ FAIL — Bucket not found: $BUCKET_NAME"
    echo "  → gsutil mb -p $PROJECT_ID gs://${BUCKET_NAME}/"
    FAIL=$((FAIL+1))
fi

# 4. Pismo SA has access?
echo "[4/5] Checking IAM binding..."
if [ -n "$PISMO_SA" ]; then
    IAM=$(gsutil iam get "gs://${BUCKET_NAME}" 2>/dev/null)
    if echo "$IAM" | grep -q "$PISMO_SA"; then
        echo "  ✅ PASS — Pismo SA has bucket access"
        PASS=$((PASS+1))
    else
        echo "  ❌ FAIL — Pismo SA not in bucket IAM"
        echo "  → gsutil iam ch serviceAccount:${PISMO_SA}:objectCreator gs://${BUCKET_NAME}"
        FAIL=$((FAIL+1))
    fi
else
    echo "  ⚠️  SKIP — PISMO_SA not set"
fi

# 5. Files present?
echo "[5/5] Checking for files..."
FILES=$(gsutil ls "gs://${BUCKET_NAME}/main_stream/" 2>/dev/null | head -5)
if [ -n "$FILES" ]; then
    echo "  ✅ PASS — Files found in main_stream/"
    echo "     $(echo "$FILES" | head -3)"
    PASS=$((PASS+1))
else
    echo "  ⚠️  INFO — No files yet in main_stream/"
    echo "     Files appear after events are generated"
fi

# Save diagnostic output to log file
LOG_FILE="/tmp/pismo-diagnostic-$(date +%Y%m%d-%H%M%S).log"

# Capture everything to log file
{
    echo "=================================================================="
    echo "  PISMO DATA PLATFORM — DIAGNOSTIC LOG"
    echo "=================================================================="
    echo ""
    echo "Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
    echo "Integration Type: GCP Cloud Storage File Delivery"
    echo ""
    echo "=== CONFIGURATION ==="
    echo "Org ID: $ORG_ID"
    echo "Project: $PROJECT_ID"
    echo "Bucket: $BUCKET_NAME"
    echo ""
    echo "=== TEST RESULTS ==="
    echo "Passed: $PASS"
    echo "Failed: $FAIL"
    echo ""
    echo "=== BUCKET IAM POLICY ==="
    gsutil iam get "gs://$BUCKET_NAME" 2>/dev/null || echo "Could not retrieve"
    echo ""
    echo "=== RECENT FILES (last 5) ==="
    gsutil ls -l "gs://$BUCKET_NAME/" 2>/dev/null | tail -5 || echo "Could not retrieve"
} > "$LOG_FILE" 2>&1

# Display results summary
echo ""
echo "============================================================"
echo "  RESULTS: $PASS passed, $FAIL failed"
echo "============================================================"

if [ $FAIL -eq 0 ]; then
    echo ""
    echo "  ✅ All checks passed — your infrastructure is correctly configured."
    echo ""
    echo "  If events are still not arriving, there may be a potential issue in:"
    echo "    • File Copier component (S3-to-GCS sync)"
    echo "    • Event Router configuration (org/destination mapping)"
    echo "    • Event generation (no events for your org in the selected period)"
    echo ""
else
    echo ""
    echo "  ❌ Some checks failed — review the errors above."
    echo ""
    echo "  These failures indicate configuration issues in your infrastructure."
    echo "  Follow the suggested fixes (→) for each failed check."
    echo "  After fixing, run this script again to verify."
    echo ""
fi

echo "============================================================"
echo "  📋 SUPPORT TICKET INSTRUCTIONS"
echo "============================================================"
echo ""
echo "  Diagnostic log saved to: $LOG_FILE"
echo ""
echo "  To open a support ticket:"
echo "  ┌─────────────────────────────────────────────────────────┐"
echo "  │  1. Portal: https://pismolabs.atlassian.net/servicedesk │"
echo "  │     /customer/portal/10                                 │"
echo "  │  2. Category: Settings → Data → File Integration"
echo "  │  3. Attach the log file OR paste its content below      │"
echo "  └─────────────────────────────────────────────────────────┘"
echo ""
echo "  Copy to clipboard (macOS):  cat $LOG_FILE | pbcopy"
echo "  Copy to clipboard (Linux):  cat $LOG_FILE | xclip -selection clipboard"
echo ""
echo "  ────────────── LOG FILE CONTENT ──────────────"
echo ""
cat "$LOG_FILE"
echo ""
echo "  ──────────────────────────────────────────────"
echo ""```

Did this page help you?