Skip to main content

Instance Observer

Instance Observer is a centralized dashboard for managing a single HubSpot portal. It provides a unified view of all backups, drift detection, and manual URN links for a specific portal, making it easy to monitor and maintain your HubSpot instance.

What is Instance Observer?​

Instead of navigating through multiple screens to manage different aspects of a portal, Instance Observer brings everything together in one place:

  • 📦 Backups — View and manage all metadata and data backups for this portal
  • 🔍 Drift Detection — Configure drift monitoring and view drift history
  • 🔗 URN Links — Manage manual URN overrides for cross-portal mappings
  • 👁️ Metadata Viewer — Browse all metadata items in read-only mode
  • 🔑 Scopes — View OAuth permissions granted to this portal

Accessing Instance Observer​

From Connections Screen​

  1. Go to Connections in the sidebar
  2. Find the HubSpot portal you want to manage
  3. Click on the portal card or click View Instance
  4. The Instance Observer dashboard opens

Direct URL​

You can also access Instance Observer directly:

/instance/{connection-id}

Instance Dashboard Overview​

The Instance Observer dashboard has three main tabs:

1. Backups Tab​

Displays all backup configurations for this portal:

Metadata Backups

  • Scheduled backups that export portal configuration to Git
  • Shows schedule (hourly/daily/weekly), target repository, and status
  • Quick actions: Run Now, View History, Edit, Pause/Resume

Data Backups

  • Scheduled backups that export CRM records to CSV
  • Shows object types, schedule, and storage destination
  • Quick actions: Run Now, View History, Edit, Pause/Resume

Actions Available:

  • Create New Backup — Set up a new metadata or data backup
  • Run Now — Trigger an immediate backup run
  • View History — See past backup runs and their status
  • Edit — Modify backup schedule or settings
  • Pause/Resume — Temporarily disable or re-enable a backup
  • Delete — Remove a backup configuration

2. Drift Detection Tab​

Configure and monitor drift detection for this portal:

Drift Configuration

  • Enable/disable drift detection
  • Select baseline repository and branch
  • Configure ignored metadata types
  • Configure ignored URNs

Drift History

  • List of all detected drift events
  • Shows when drift was detected and how many changes were found
  • Click "View Diffs" to see detailed comparison

See Drift Detection for full documentation.

Manage manual URN overrides for this portal:

What are URN Links? URN Links allow you to manually "stitch" metadata items with different names between portals. This is useful when:

  • An item was renamed in one portal but not the other
  • You want to map items that have different internal names
  • Automatic URN matching fails due to naming differences

URN Override Table

  • Natural URN (Real) — The actual URN of the item in this portal
  • Treat as (Effective) — The URN to use for comparisons and deployments
  • Actions — Remove the override

Creating a URN Link:

  1. Click Create Link
  2. Enter the Real URN (the actual URN in this portal)
  3. Enter the Override URN (the URN to treat it as)
  4. Click Save

Example Use Case:

Portal A has a property: "contact_lifecycle_stage"
Portal B has the same property but named: "lifecycle_stage"

Create a URN link in Portal B:
Real URN: crm.property:contacts:lifecycle_stage
Override URN: crm.property:contacts:contact_lifecycle_stage

Now comparisons will treat them as the same property.

Header Information​

The Instance Observer header displays:

Portal Name​

  • The app name (if set) or "HubSpot Portal"
  • Status indicator (completed, pending, error)

Portal ID​

  • The HubSpot portal ID in monospace font
  • Useful for identifying the portal in HubSpot

Permission Warning​

  • ⚠️ "Some permissions missing" — Appears if some OAuth scopes were denied
  • Click View Scopes to see which permissions are missing

Quick Actions​

View Scopes

  • Opens a modal showing all asked and granted OAuth scopes
  • Highlights denied scopes in yellow
  • See OAuth Scopes for details

View Metadata

  • Opens the Metadata Viewer in read-only mode
  • Browse all metadata items without creating a comparison
  • Useful for quick inspection or documentation

Metadata Viewer​

The Metadata Viewer provides a read-only, flat view of all metadata items in the portal.

Accessing Metadata Viewer​

  1. Open Instance Observer for a portal
  2. Click View Metadata in the header
  3. The viewer opens with all metadata types in the sidebar

Features​

Sidebar Navigation

  • Grouped by metadata type (Custom Objects, Standard Objects, Workflows, etc.)
  • Shows count of items in each category
  • Click to filter by type

Item List

  • Displays all items of the selected type
  • Shows label, internal name, and last updated date
  • Click "View Details" to see full YAML content

Search & Filter

  • Search by item name
  • Filter by status (all items are "identical" in view mode)
  • No selection checkboxes (read-only mode)

YAML Viewer

  • Click "View Details" on any item
  • See the full YAML representation
  • Useful for documentation or troubleshooting
Use Case

Use the Metadata Viewer to quickly check if a property exists, view workflow logic, or document your portal's configuration without creating a comparison.

Common Workflows​

Workflow 1: Setting Up Backups for a New Portal​

  1. Access Instance Observer

    • Go to Connections → Select portal → Instance Observer

  2. Create Metadata Backup

    • Click Backups tab
    • Click New Metadata Backup
    • Select target Git repository and branch
    • Set schedule (e.g., daily at 2:00 AM UTC)
    • Click Save

  3. Create Data Backup (optional)

    • Click New Data Backup
    • Select object types (Contacts, Companies, Deals, etc.)
    • Set schedule (e.g., weekly on Sunday)
    • Click Create Schedule

  4. Enable Drift Detection (optional)

    • Click Drift Detection tab
    • Toggle Status to enable
    • Select baseline repository and branch
    • Configure ignored types if needed
    • Click Save Configuration

  5. Run Initial Backups

    • Go back to Backups tab
    • Click Run Now on each backup
    • Wait for completion
    • Click View History to verify success

Workflow 2: Investigating Drift​

  1. Check Drift Alerts

    • Go to Instance Observer → Drift Detection tab
    • Review Drift History section
    • Look for recent drift reports

  2. View Drift Details

    • Click View Diffs on a drift report
    • Review the comparison showing all changes
    • Identify which items were modified manually

  3. Decide on Action

    • Accept Changes: Update your Git baseline to match
    • Revert Changes: Deploy the baseline version to restore consistency
    • Ignore Future Drift: Add the item to Ignored URNs

  4. Update Configuration

    • If ignoring specific items, add their URNs to Ignored URNs
    • If ignoring entire types, check them in Ignored Metadata Types
    • Click Save Configuration

Scenario: You're migrating from Portal A to Portal B, but some properties were renamed.

  1. Identify Mismatched Items

    • Create a comparison between Portal A and Portal B
    • Look for items marked as "new" in Portal B that should match items in Portal A
    • Note the URNs of both items

  2. Create URN Links in Portal B

    • Go to Portal B's Instance Observer
    • Click URN Links tab
    • Click Create Link
    • Enter the real URN (Portal B's actual URN)
    • Enter the override URN (Portal A's URN)
    • Click Save

  3. Verify the Link

    • Create a new comparison between Portal A and Portal B
    • The previously "new" item should now show as "identical" or "modified"
    • The link icon appears next to the item in the comparison

  4. Repeat for All Mismatches

    • Create links for all renamed or mismatched items
    • Test the comparison again to ensure all links work

Backup Management​

Viewing Backup History​

  1. Click View History on any backup card
  2. The history modal shows all past runs:
    • Status — Pending, Processing, Completed, Failed
    • Started At — When the backup began
    • Finished At — When it completed
    • Error Message — If the backup failed
    • Download Links — For data backups (CSV files)

Running Manual Backups​

When to Run Manual Backups:

  • Before making major changes in HubSpot
  • Before a deployment to another portal
  • After significant manual changes
  • For testing backup configuration

How to Run:

  1. Click Run Now on the backup card
  2. The backup is queued immediately
  3. Status changes to "Running"
  4. Click View History to monitor progress
  5. Backup completes within 1-5 minutes (depending on portal size)

Pausing Backups​

When to Pause:

  • During a major migration or restructuring
  • When you want to temporarily stop automatic backups
  • For testing or troubleshooting

How to Pause:

  1. Toggle the Active switch on the backup card
  2. Status changes to "Paused"
  3. Scheduled backups will not run
  4. You can still run manual backups
  5. Toggle again to resume

Editing Backups​

What You Can Edit:

  • Schedule frequency (hourly/daily/weekly)
  • Schedule time (for daily/weekly)
  • Target branch (for metadata backups)
  • Object types (for data backups)
  • Active status

What You Cannot Edit:

  • HubSpot connection (delete and recreate instead)
  • Target repository (delete and recreate instead)

How to Edit:

  1. Click Edit on the backup card
  2. Modify the settings
  3. Click Save Changes
  4. Changes take effect immediately

Troubleshooting​

"Some permissions missing" Warning​

Cause: Some OAuth scopes were denied during authorization.

Solution:

  1. Click View Scopes to see which scopes are missing
  2. Reconnect the portal and request the missing scopes
  3. Ensure the HubSpot admin approves all requested scopes

See OAuth Scopes for details.

Backup Stuck in "Pending"​

Cause: Background worker is overloaded or not running.

Solution:

  1. Wait 5-10 minutes
  2. If still pending, check the backup history for errors
  3. Try running the backup again
  4. If issue persists, contact support

Drift Detection Not Running​

Cause: Drift detection is disabled or baseline repository is not configured.

Solution:

  1. Go to Drift Detection tab
  2. Ensure Status is enabled
  3. Verify Baseline Repository and Baseline Branch are set
  4. Click Save Configuration
  5. Click Run Check Now to test

Cause: URN format is incorrect or the item doesn't exist.

Solution:

  1. Verify the URN format: type:subtype:internalName
  2. Check that both items exist in their respective portals
  3. Ensure the URN is spelled correctly (case-sensitive)
  4. Try creating a new comparison to see if the link is applied

Metadata Viewer Shows No Items​

Cause: Portal has no metadata or extraction hasn't completed.

Solution:

  1. Check the portal status in the header
  2. If status is "pending" or "in_progress", wait for extraction to complete
  3. If status is "error", check the connection and try reconnecting
  4. Ensure the portal has metadata items (properties, workflows, etc.)

Best Practices​

1. Use Instance Observer as Your Portal Hub​

Instead of navigating through multiple screens, bookmark the Instance Observer URL for your most important portals. This gives you quick access to all portal management features.

2. Set Up Backups Immediately​

As soon as you connect a new portal, set up at least one metadata backup. This ensures you have a baseline to fall back on if something goes wrong.

3. Enable Drift Detection for Production Portals​

Production portals should always have drift detection enabled. This helps you catch unauthorized changes quickly.

When creating URN links, add a comment or note explaining why the link was created. This helps future team members understand the mapping.

5. Review Backup History Regularly​

Check backup history weekly to ensure backups are running successfully. Failed backups can indicate API issues or permission problems.

6. Use Metadata Viewer for Documentation​

When documenting your HubSpot setup, use the Metadata Viewer to quickly reference property definitions, workflow logic, and other configuration details.

Security & Permissions​

Who Can Access Instance Observer?​

Both workspace admins and members can access Instance Observer. However, some actions are restricted:

ActionAdminMember
View Instance Observer✓✓
View Backups✓✓
Create Backups✓—
Edit Backups✓—
Delete Backups✓—
Run Manual Backups✓—
View Drift Detection✓✓
Configure Drift Detection✓—
View URN Links✓✓
Create URN Links✓✓
Delete URN Links✓✓
View Metadata✓✓
View Scopes✓✓

See Permissions for the complete permissions matrix.