Veeva Vault Integration

This guide covers the setup and configuration of the Cohera Veeva Vault integration. Once configured, Cohera synchronizes documents, quality events, and controlled records with your Veeva Vault instance.

Prerequisites

Before you begin, ensure you have:

• Veeva Vault Quality or Vault QualityDocs license
• Vault API v20.1 or later
• API User with appropriate security profile
• Network connectivity from Cohera to your Vault instance
• The following Vault permissions:
  • Read/Write access to relevant document types
  • Object record access for quality events
  • Workflow participation permissions

Supported Data Objects

Veeva Vault Object	Cohera Entity	Sync Direction
Document	Certificate/Document	Bi-directional
Supplier	Supplier	Bi-directional
Product	Product	Vault to Cohera
Deviation	Quality Event	Bi-directional
CAPA	Quality Event	Bi-directional
Change Control	Workflow	Bi-directional
Audit Finding	Quality Event	Vault to Cohera

Setup Guide

1. Create Vault API User

   In Veeva Vault Administration:

   • Navigate to Admin > Users & Groups > Users
   • Create a new user for API integration
   • Assign the API User security profile
   • Add to application roles with required permissions

2. Generate API Credentials

   For production, use OAuth 2.0:

   • Navigate to Admin > Settings > OAuth 2.0 / OpenID Connect Profiles
   • Create a new OAuth profile for Cohera
   • Note the Client ID and configure the redirect URI

3. Create Cohera Connection

   Use the API or dashboard to create the connection:

curl

curl -X POST "https://api.cohera.io/v1/integrations/connections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Veeva Vault Quality Production",
    "type": "veeva_vault",
    "authentication": {
      "type": "oauth2",
      "client_id": "cohera-integration",
      "client_secret": "your_client_secret",
      "vault_dns": "yourcompany.veevavault.com",
      "authorization_url": "https://login.veevavault.com/auth/oauth/authorize"
    },
    "endpoints": {
      "vault_dns": "yourcompany.veevavault.com",
      "api_version": "v23.1"
    },
    "sync_config": {
      "direction": "bidirectional",
      "interval_minutes": 15
    }
  }'

Python

connection_config = {
    "name": "Veeva Vault Quality Production",
    "type": "veeva_vault",
    "authentication": {
        "type": "oauth2",
        "client_id": "cohera-integration",
        "client_secret": "your_client_secret",
        "vault_dns": "yourcompany.veevavault.com",
        "authorization_url": "https://login.veevavault.com/auth/oauth/authorize"
    },
    "endpoints": {
        "vault_dns": "yourcompany.veevavault.com",
        "api_version": "v23.1"
    },
    "sync_config": {
        "direction": "bidirectional",
        "interval_minutes": 15
    }
}

response = requests.post(
    "https://api.cohera.io/v1/integrations/connections",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json=connection_config
)

connection = response.json()["data"]
print(f"Connection created: {connection['id']}")

TypeScript

const connectionConfig = {
  name: "Veeva Vault Quality Production",
  type: "veeva_vault",
  authentication: {
    type: "oauth2",
    client_id: "cohera-integration",
    client_secret: "your_client_secret",
    vault_dns: "yourcompany.veevavault.com",
    authorization_url: "https://login.veevavault.com/auth/oauth/authorize",
  },
  endpoints: {
    vault_dns: "yourcompany.veevavault.com",
    api_version: "v23.1",
  },
  sync_config: {
    direction: "bidirectional",
    interval_minutes: 15,
  },
};

const response = await fetch(
  "https://api.cohera.io/v1/integrations/connections",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COHERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(connectionConfig),
  }
);

const { data: connection } = await response.json();
console.log(`Connection created: ${connection.id}`);

4. Authorize the Connection

   Complete the OAuth flow to authorize Cohera:

   curl -X POST "https://api.cohera.io/v1/integrations/connections/conn_veeva_123/authorize" \
     -H "Authorization: Bearer YOUR_API_KEY"

   This returns an authorization URL. Complete the Vault login to grant access.

5. Configure Object Mappings

   Define how Vault objects map to Cohera entities.

6. Enable Synchronization

   curl -X POST "https://api.cohera.io/v1/integrations/connections/conn_veeva_123/enable" \
     -H "Authorization: Bearer YOUR_API_KEY"

Authentication

OAuth 2.0 (Recommended)

OAuth 2.0 provides secure, token-based authentication:

{
  "authentication": {
    "type": "oauth2",
    "client_id": "cohera-integration",
    "client_secret": "your_client_secret",
    "vault_dns": "yourcompany.veevavault.com",
    "authorization_url": "https://login.veevavault.com/auth/oauth/authorize",
    "token_url": "https://login.veevavault.com/auth/oauth/token"
  }
}

Session Authentication

For simpler setups (not recommended for production):

{
  "authentication": {
    "type": "session",
    "username": "cohera.api@yourcompany.com",
    "password": "your_password",
    "vault_dns": "yourcompany.veevavault.com"
  }
}

Caution

Session authentication requires storing credentials and is not recommended for production. Use OAuth 2.0 whenever possible.

Document Sync

Certificate Document Mapping

Synchronize Certificates of Analysis and other compliance documents:

{
  "entity_type": "certificate",
  "source_object": "documents",
  "document_types": ["certificate_of_analysis__c", "certificate_of_conformity__c"],
  "field_mappings": [
    {
      "source": "document_number__v",
      "target": "document_number",
      "required": true
    },
    {
      "source": "name__v",
      "target": "name"
    },
    {
      "source": "type__v",
      "target": "type",
      "transformation": {
        "type": "lookup",
        "values": {
          "certificate_of_analysis__c": "coa",
          "certificate_of_conformity__c": "coc"
        }
      }
    },
    {
      "source": "supplier__c",
      "target": "supplier_ref",
      "transformation": {
        "type": "entity_lookup",
        "entity_type": "supplier",
        "lookup_field": "vault_id"
      }
    },
    {
      "source": "expiration_date__c",
      "target": "expiry_date"
    },
    {
      "source": "status__v",
      "target": "status",
      "transformation": {
        "type": "lookup",
        "values": {
          "Draft": "draft",
          "In Review": "pending",
          "Approved": "valid",
          "Superseded": "superseded"
        }
      }
    }
  ],
  "filters": {
    "status__v": ["Approved", "In Review"],
    "subtype__v": "cohera_managed__c"
  }
}

Document Content Sync

Optionally synchronize document content (PDFs):

{
  "content_sync": {
    "enabled": true,
    "rendition_type": "viewable_rendition__v",
    "storage": "cohera_s3",
    "on_update": "version"
  }
}

Quality Events Sync

Deviation Mapping

{
  "entity_type": "quality_event",
  "source_object": "deviation__v",
  "field_mappings": [
    {
      "source": "id",
      "target": "vault_id"
    },
    {
      "source": "name__v",
      "target": "number"
    },
    {
      "source": "title__c",
      "target": "title"
    },
    {
      "source": "description__c",
      "target": "description"
    },
    {
      "source": "classification__c",
      "target": "classification",
      "transformation": {
        "type": "lookup",
        "values": {
          "critical__c": "critical",
          "major__c": "major",
          "minor__c": "minor"
        }
      }
    },
    {
      "source": "state__v",
      "target": "status",
      "transformation": {
        "type": "lookup",
        "values": {
          "draft_state__c": "draft",
          "open_state__c": "submitted",
          "investigation_state__c": "investigation",
          "closed_state__c": "closed"
        }
      }
    },
    {
      "source": "root_cause__c",
      "target": "root_cause.description"
    },
    {
      "source": "related_supplier__c",
      "target": "related_entities",
      "transformation": {
        "type": "entity_reference",
        "entity_type": "supplier"
      }
    }
  ],
  "bidirectional": {
    "enabled": true,
    "cohera_to_vault_fields": [
      "impact_assessment",
      "ai_analysis_results"
    ]
  }
}

CAPA Mapping

{
  "entity_type": "quality_event",
  "source_object": "capa__v",
  "event_subtype": "capa",
  "field_mappings": [
    {
      "source": "id",
      "target": "vault_id"
    },
    {
      "source": "name__v",
      "target": "number"
    },
    {
      "source": "title__c",
      "target": "title"
    },
    {
      "source": "corrective_action__c",
      "target": "corrective_actions",
      "transformation": {
        "type": "json_parse"
      }
    },
    {
      "source": "preventive_action__c",
      "target": "preventive_actions",
      "transformation": {
        "type": "json_parse"
      }
    },
    {
      "source": "effectiveness_check_date__c",
      "target": "effectiveness_check_date"
    },
    {
      "source": "related_deviation__c",
      "target": "parent_event_ref",
      "transformation": {
        "type": "entity_lookup",
        "entity_type": "quality_event",
        "lookup_field": "vault_id"
      }
    }
  ]
}

Workflow Integration

Workflow State Mapping

Map Vault workflow states to Cohera workflow states:

{
  "workflow_sync": {
    "enabled": true,
    "vault_lifecycle": "deviation_lifecycle__c",
    "state_mappings": [
      {
        "vault_state": "draft_state__c",
        "cohera_state": "draft"
      },
      {
        "vault_state": "submitted_state__c",
        "cohera_state": "submitted"
      },
      {
        "vault_state": "investigation_state__c",
        "cohera_state": "investigation"
      },
      {
        "vault_state": "pending_approval_state__c",
        "cohera_state": "pending_approval"
      },
      {
        "vault_state": "closed_state__c",
        "cohera_state": "closed"
      }
    ],
    "transition_triggers": {
      "cohera_to_vault": true,
      "vault_to_cohera": true
    }
  }
}

E-Signature Sync

Synchronize electronic signatures between systems:

{
  "esignature_sync": {
    "enabled": true,
    "vault_signature_field": "signature__c",
    "sync_direction": "vault_to_cohera",
    "include_meaning": true
  }
}

Note

E-signature sync maintains compliance with 21 CFR Part 11 by preserving signature meaning and timestamp from the originating system.

Supplier Sync

Supplier Object Mapping

{
  "entity_type": "supplier",
  "source_object": "supplier__v",
  "field_mappings": [
    {
      "source": "id",
      "target": "vault_id"
    },
    {
      "source": "name__v",
      "target": "name"
    },
    {
      "source": "supplier_number__c",
      "target": "supplier_code"
    },
    {
      "source": "qualification_status__c",
      "target": "attributes.qualification_status",
      "transformation": {
        "type": "lookup",
        "values": {
          "qualified__c": "qualified",
          "conditionally_approved__c": "conditional",
          "disqualified__c": "disqualified",
          "pending__c": "evaluation"
        }
      }
    },
    {
      "source": "country__c",
      "target": "attributes.country"
    },
    {
      "source": "risk_rating__c",
      "target": "attributes.risk_level"
    }
  ],
  "bidirectional": {
    "enabled": true,
    "cohera_to_vault_fields": [
      "attributes.cohera_risk_score",
      "attributes.ai_risk_factors"
    ],
    "vault_custom_fields": {
      "cohera_risk_score__c": "attributes.cohera_risk_score",
      "cohera_risk_factors__c": "attributes.ai_risk_factors"
    }
  }
}

Sync Configuration

Change Detection

Veeva Vault provides change tracking through the modified_date__v field:

{
  "sync_config": {
    "change_detection": {
      "method": "modified_date",
      "field": "modified_date__v",
      "buffer_minutes": 5
    },
    "polling_interval_minutes": 15
  }
}

Webhooks (Spark Messages)

For real-time sync, configure Vault Spark Messages:

{
  "sync_config": {
    "realtime": {
      "enabled": true,
      "spark_message_endpoint": "https://api.cohera.io/v1/integrations/webhooks/veeva",
      "subscribed_events": [
        "document.created",
        "document.updated",
        "object.deviation.created",
        "object.deviation.updated",
        "lifecycle.state_change"
      ]
    }
  }
}

Conflict Resolution

Configure how conflicts are handled:

{
  "conflict_resolution": {
    "default_strategy": "vault_wins",
    "exceptions": {
      "quality_event.impact_assessment": "cohera_wins",
      "quality_event.ai_analysis": "cohera_wins",
      "supplier.cohera_risk_score": "cohera_wins"
    },
    "manual_review_fields": [
      "quality_event.root_cause"
    ]
  }
}

Error Handling

Common Errors

Error	Cause	Resolution
INVALID_SESSION	Session expired	Re-authenticate or use OAuth
NO_PERMISSION	Missing Vault permissions	Update security profile
RECORD_NOT_FOUND	Object deleted in Vault	Handle deletion gracefully
VALIDATION_ERROR	Required field missing	Check field mappings
RATE_LIMIT	API burst limit reached	Implement backoff

Retry Configuration

{
  "error_handling": {
    "max_retries": 3,
    "retry_delay_seconds": 30,
    "exponential_backoff": true,
    "skip_on_validation_error": false
  }
}

Monitoring

Sync Health Check

curl -X GET "https://api.cohera.io/v1/integrations/connections/conn_veeva_123/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "connection_id": "conn_veeva_123",
    "status": "healthy",
    "vault_status": {
      "api_available": true,
      "api_version": "v23.1",
      "response_time_ms": 145
    },
    "last_sync": {
      "timestamp": "2024-01-20T14:15:00Z",
      "status": "success",
      "objects_synced": {
        "documents": 23,
        "deviations": 5,
        "suppliers": 12
      }
    },
    "pending_changes": {
      "vault_to_cohera": 3,
      "cohera_to_vault": 1
    }
  }
}

Troubleshooting

OAuth Authorization Fails

1. Verify OAuth profile is configured correctly in Vault
2. Check redirect URI matches Cohera configuration
3. Ensure user has API access permissions
4. Verify Vault domain DNS is correct

Documents Not Syncing

1. Check document type filter matches your configuration
2. Verify document status is included in sync filters
3. Ensure API user has access to the document types
4. Check for document-level security restrictions

Workflow States Out of Sync

1. Verify state mappings cover all lifecycle states
2. Check for intermediate states in Vault workflows
3. Review conflict resolution settings
4. Enable detailed logging for state transitions