ExternalReference

Universal reference to records in external systems (Salesforce, SAP, Shopify, Stripe, QuickBooks, etc.) for integration purposes across all entity types

11 properties

Schema

Properties

Property	Type	Mode	Description	Required
entityType	string	stored	Type of entity being referenced (Customer, Product, Employee, Order, Invoice, Patient, etc.) Example: `"Customer"`	Required
entityId	string	stored	Unique identifier of the entity in the local system Example: `"CUST-2024-00123"`	Required
systemName	string	stored	Name of the external system Example: `"Salesforce"`	Required
systemType	string	enum	Category of the external system Values: `CRM, ERP, E-commerce, Payment, Accounting, HR, Healthcare, Marketing, Analytics, Other` Example: `"CRM"`	Optional
externalId	string	stored	Unique identifier in the external system Example: `"0031234567890ABC"`	Required
externalUrl	string	stored	Direct URL to the record in the external system Example: `"https://example.salesforce.com/0031234567890ABC"`	Optional
syncStatus	string	enum	Current synchronization status Values: `synced, pending, failed, disabled` Example: `"synced"`	Required
syncedAt	DateTime	stored	Timestamp of last successful synchronization Example: `"2024-11-12T10:00:00Z"`	Optional
syncDirection	string	enum	Direction of data synchronization Values: `bidirectional, push_only, pull_only` Example: `"bidirectional"`	Optional
lastSyncError	string	stored	Error message from last failed synchronization attempt Example: `"Authentication failed: Invalid API key"`	Optional
metadata	object	stored	Additional system-specific metadata (API version, region, etc.) Example: `{"apiVersion":"v52.0","region":"us-east-1","instanceUrl":"https://na1.salesforce.com"}`	Optional

Examples

Example 1

{
  "@type": "ExternalReference",
  "entityType": "Customer",
  "entityId": "CUST-2024-00123",
  "systemName": "Salesforce",
  "systemType": "CRM",
  "externalId": "0031234567890ABC",
  "externalUrl": "https://example.salesforce.com/0031234567890ABC",
  "syncStatus": "synced",
  "syncedAt": "2024-11-12T10:00:00Z",
  "syncDirection": "bidirectional",
  "metadata": {
    "apiVersion": "v52.0",
    "region": "us-east-1",
    "instanceUrl": "https://na1.salesforce.com"
  }
}

Example 2

{
  "@type": "ExternalReference",
  "entityType": "Product",
  "entityId": "PROD-2024-05678",
  "systemName": "Shopify",
  "systemType": "E-commerce",
  "externalId": "shopify_prod_7234567890",
  "externalUrl": "https://admin.shopify.com/store/mystore/products/7234567890",
  "syncStatus": "synced",
  "syncedAt": "2024-11-12T10:15:00Z",
  "syncDirection": "push_only",
  "metadata": {
    "storeName": "mystore",
    "productHandle": "premium-widget"
  }
}

Example 3

{
  "@type": "ExternalReference",
  "entityType": "Order",
  "entityId": "ORD-2024-9876",
  "systemName": "Stripe",
  "systemType": "Payment",
  "externalId": "pi_3O4KqN2eZvKYlo2C1234abcd",
  "externalUrl": "https://dashboard.stripe.com/payments/pi_3O4KqN2eZvKYlo2C1234abcd",
  "syncStatus": "synced",
  "syncedAt": "2024-11-12T10:30:00Z",
  "syncDirection": "pull_only",
  "metadata": {
    "paymentIntent": "pi_3O4KqN2eZvKYlo2C1234abcd",
    "stripeAccount": "acct_1234567890"
  }
}

Example 4

{
  "@type": "ExternalReference",
  "entityType": "Invoice",
  "entityId": "INV-2024-5432",
  "systemName": "QuickBooks",
  "systemType": "Accounting",
  "externalId": "145",
  "externalUrl": "https://app.qbo.intuit.com/app/invoice?txnId=145",
  "syncStatus": "failed",
  "syncedAt": "2024-11-12T09:00:00Z",
  "syncDirection": "bidirectional",
  "lastSyncError": "Rate limit exceeded: 429 Too Many Requests",
  "metadata": {
    "realmId": "1234567890",
    "companyId": "9876543210"
  }
}

Example 5

{
  "@type": "ExternalReference",
  "entityType": "Employee",
  "entityId": "EMP-2024-0042",
  "systemName": "Workday",
  "systemType": "HR",
  "externalId": "workday_worker_21-456",
  "externalUrl": "https://wd2.myworkday.com/company/d/inst/21-456",
  "syncStatus": "synced",
  "syncedAt": "2024-11-12T11:00:00Z",
  "syncDirection": "pull_only",
  "metadata": {
    "tenantName": "company",
    "workerId": "21-456"
  }
}

Example 6

{
  "@type": "ExternalReference",
  "entityType": "Patient",
  "entityId": "PAT-2024-1234",
  "systemName": "FHIR_Server",
  "systemType": "Healthcare",
  "externalId": "Patient/example-patient-123",
  "externalUrl": "https://fhir.example.org/Patient/example-patient-123",
  "syncStatus": "synced",
  "syncedAt": "2024-11-12T11:30:00Z",
  "syncDirection": "bidirectional",
  "metadata": {
    "fhirVersion": "R4",
    "serverUrl": "https://fhir.example.org",
    "resourceType": "Patient"
  }
}