Skip to main content

URN Management

URN (Uniform Resource Name) Management allows you to manually control how metadata items are matched between portals. This is essential for handling renamed items, custom mappings, and complex migration scenarios where automatic matching fails.

What are URNs?​

A URN is a unique identifier for a metadata item in HubSpot Deploy. URNs follow a structured format:

urn:namespace:identifier

Examples:

urn:schema:contacts                    # Contacts object schema
urn:property:contacts:email            # Email property on Contacts
urn:pipeline:deals:default             # Default deals pipeline
urn:workflow:12345678                  # Workflow with ID 12345678
urn:form:contact-us                    # Contact Us form

URN Components​

ComponentDescriptionExample
PrefixAlways urn:urn:
NamespaceThe type of metadataschema, property, pipeline, workflow, form
IdentifierThe unique ID or namecontacts, email, 12345678

Why URN Management?​

Problem: Automatic Matching Fails​

When comparing two portals, HubSpot Deploy automatically matches items by their URNs. However, this fails when:

  1. Items were renamed in one portal but not the other
  2. Different naming conventions were used (e.g., contact_status vs status)
  3. Items were recreated with different IDs
  4. Custom objects have portal-specific prefixes

Solution: Manual URN Overrides​

URN overrides allow you to tell HubSpot Deploy:

"When you see URN A in this portal, treat it as if it were URN B"

This "stitches" items together that would otherwise be seen as different.

URN Namespaces​

HubSpot Deploy uses a registry of valid URN namespaces. Common namespaces include:

NamespaceDescriptionExample URN
schemaObject schemas (standard and custom)urn:schema:contacts
propertyObject propertiesurn:property:contacts:firstname
property_groupProperty groupsurn:property_group:contacts:contactinformation
pipelinePipelines and stagesurn:pipeline:deals:default
workflowWorkflowsurn:workflow:12345678
formFormsurn:form:contact-us
email_templateEmail templatesurn:email_template:welcome-email
landing_pageLanding pagesurn:landing_page:product-demo
listListsurn:list:active-customers
associationAssociation definitionsurn:association:contacts:deals
tip

Namespaces are extensible. New metadata types can be added as the system evolves.

Creating URN Overrides​

From Instance Observer​

  1. Navigate to Instance Observer

    • Go to Connections → Select portal → Instance Observer

  2. Open URN Links Tab

    • Click the URN Links tab

  3. Create New Link

    • Click Create Link
    • The URN Override Modal opens

  4. Configure the Link

    • Source (Natural): The actual URN in this portal
      • Select Type (namespace)
      • Enter Identifier (the unique ID or name)
    • Target (Effective): The URN to treat it as
      • Select Type (must match source type)
      • Enter Identifier (the URN from the other portal)

  5. Save the Link

    • Review the final URN mapping
    • Click Link Items
    • The override is saved and applied immediately

From Comparison View​

When viewing a comparison, you can create URN overrides directly from diff items:

  1. Identify Mismatched Items

    • Look for items marked as "new" or "removed" that should match
    • Note the URNs of both items

  2. Click "Add Manual Link"

    • Click the link icon (🔗) next to the item
    • The URN Override Modal opens with the item's URN pre-filled

  3. Enter Target URN

    • Enter the URN from the other portal
    • Click Link Items

  4. Verify the Link

    • Refresh the comparison
    • The items should now show as "identical" or "modified"
    • A link icon appears next to the item

URN Override Examples​

Example 1: Renamed Property​

Scenario: A property was renamed from contact_status to status in Portal B.

Portal A URN: urn:property:contacts:contact_status
Portal B URN: urn:property:contacts:status

Solution: Create an override in Portal B:

Real URN:     urn:property:contacts:status
Override URN: urn:property:contacts:contact_status

Result: When comparing Portal A and Portal B, the status property in Portal B will be treated as contact_status, allowing proper matching.

Example 2: Custom Object with Portal Prefix​

Scenario: A custom object "Projects" has different IDs in each portal due to portal-specific prefixes.

Portal A URN: urn:schema:p12345_projects
Portal B URN: urn:schema:p67890_projects

Solution: Create an override in Portal B:

Real URN:     urn:schema:p67890_projects
Override URN: urn:schema:p12345_projects

Result: The custom object in Portal B will be matched with the one in Portal A.

Example 3: Workflow Recreated with New ID​

Scenario: A workflow was deleted and recreated in Portal B, resulting in a new ID.

Portal A URN: urn:workflow:11111111
Portal B URN: urn:workflow:22222222

Solution: Create an override in Portal B:

Real URN:     urn:workflow:22222222
Override URN: urn:workflow:11111111

Result: The workflow in Portal B will be treated as the same workflow from Portal A.

Example 4: Pipeline Stage Renamed​

Scenario: A deal pipeline stage was renamed from "Qualified Lead" to "SQL" in Portal B.

Portal A URN: urn:pipeline:deals:default:qualified_lead
Portal B URN: urn:pipeline:deals:default:sql

Solution: Create an override in Portal B:

Real URN:     urn:pipeline:deals:default:sql
Override URN: urn:pipeline:deals:default:qualified_lead

Result: The "SQL" stage in Portal B will be matched with "Qualified Lead" in Portal A.

How URN Resolution Works​

1. URN Override Context​

The UrnOverrideContext provides global access to URN overrides throughout the application:

interface UrnOverrideContextType {
  overrides: UrnOverride[]
  loading: boolean
  getEffectiveUrn: (connectionId, realUrn) => string
  getRealUrn: (connectionId, effectiveUrn) => string
  addOverride: (connectionId, realUrn, overrideUrn) => Promise<void>
  removeOverride: (id) => Promise<void>
  refreshOverrides: () => Promise<void>
}

2. URN Resolution Process​

When comparing or deploying metadata:

  1. Fetch Overrides

    • Load all URN overrides for the active workspace
    • Cache in memory for performance

  2. Apply Overrides

    • For each metadata item, check if an override exists
    • If yes, use the override URN instead of the real URN
    • If no, use the real URN

  3. Match Items

    • Compare items using effective URNs
    • Items with matching effective URNs are considered the same

  4. Display Indicators

    • Show link icon (🔗) next to items with overrides
    • Tooltip shows both real and effective URNs

3. URN Resolver Hook​

The useUrnResolver hook resolves URNs to full metadata items:

const { resolved, loading, error } = useUrnResolver(comparisonId, urns)

Features:

  • Fetches metadata items by URN
  • Caches results to avoid repeated queries
  • Returns a map of URN → ResolvedItem

Use Cases:

  • Displaying item details in dependency views
  • Showing referenced items in tooltips
  • Validating URN overrides

Managing URN Overrides​

Viewing Active Overrides​

  1. Go to Instance Observer → URN Links tab
  2. See all active overrides for this portal
  3. Each row shows:
    • Natural URN (Real) — The actual URN in this portal
    • Treat as (Effective) — The URN used for matching
    • Actions — Remove the override

Editing Overrides​

URN overrides cannot be edited directly. To change an override:

  1. Delete the existing override

    • Click the trash icon (🗑️) next to the override
    • Confirm deletion

  2. Create a new override

    • Click Create Link
    • Enter the new URN mapping
    • Click Link Items

Deleting Overrides​

  1. Go to Instance Observer → URN Links tab
  2. Find the override you want to remove
  3. Click the trash icon (🗑️)
  4. The override is deleted immediately
  5. Future comparisons will use the real URN
warning

Deleting an override affects all future comparisons. Existing comparisons are not retroactively updated.

URN Override Best Practices​

1. Document Your Overrides​

When creating an override, document why it was created:

  • Keep a spreadsheet or wiki page with all overrides
  • Include the reason (e.g., "Property renamed during migration")
  • Note the date and who created it

2. Use Overrides Sparingly​

Overrides are powerful but can make comparisons harder to understand. Only use them when:

  • Automatic matching fails
  • The items are genuinely the same
  • Renaming the item in HubSpot is not feasible

3. Validate Overrides After Creation​

After creating an override:

  1. Create a new comparison
  2. Verify the items now match correctly
  3. Check that no unintended side effects occurred

4. Clean Up Unused Overrides​

Periodically review your overrides and remove any that are no longer needed:

  • Items that have been renamed back
  • Portals that are no longer in use
  • Temporary overrides for one-time migrations

5. Use Consistent Naming Conventions​

To minimize the need for overrides:

  • Establish naming conventions for properties, workflows, etc.
  • Use the same names across all portals
  • Avoid renaming items unless absolutely necessary

6. Test in Sandbox First​

Before creating overrides in production:

  1. Test the override in a sandbox portal
  2. Verify it works as expected
  3. Document the process
  4. Apply to production

Troubleshooting​

Override Not Working​

Symptoms: Created an override, but items still don't match in comparisons.

Possible Causes:

  1. Namespace mismatch — Source and target namespaces must be identical
  2. Typo in URN — URNs are case-sensitive and must be exact
  3. Wrong portal — Override was created in the wrong portal
  4. Comparison not refreshed — Old comparison cached the previous state

Solutions:

  1. Verify the namespace matches (e.g., both are property)
  2. Double-check the URN spelling and capitalization
  3. Ensure the override is in the correct portal (usually the target portal)
  4. Create a new comparison to see the override in effect

Items Still Show as "New" After Override​

Cause: The override URN doesn't match any item in the source portal.

Solution:

  1. Check the source portal to verify the item exists
  2. Verify the override URN matches the source item's URN exactly
  3. Use the Metadata Viewer to find the correct URN

Override Causes Unintended Matches​

Cause: The override URN matches multiple items or the wrong item.

Solution:

  1. Delete the override immediately
  2. Review the URN structure to ensure it's specific enough
  3. Create a more specific override (e.g., include parent object name)

Cannot Delete Override​

Cause: System permissions or connection issue.

Solution:

  1. Refresh the page and try again
  2. Check your workspace permissions (must be admin or member)
  3. If issue persists, contact support

Advanced Use Cases​

Use Case 1: Portal Migration with Bulk Overrides​

Scenario: Migrating 50+ properties from Portal A to Portal B, where many were renamed.

Approach:

  1. Export all properties from both portals
  2. Create a mapping spreadsheet (Portal A URN → Portal B URN)
  3. Create overrides one by one through the UI
  4. For large migrations, contact support for bulk import assistance
  5. Create a comparison to verify all overrides work

Tip: Start with a small batch (5-10 overrides) to test the approach before doing all 50+.

Use Case 2: Multi-Portal Sync with Shared Baseline​

Scenario: Syncing 3 portals (Dev, Staging, Prod) with a shared Git baseline, where each portal has slightly different naming.

Approach:

  1. Designate one portal as the "source of truth" (e.g., Prod)
  2. Create overrides in Dev and Staging to match Prod's URNs
  3. All comparisons will now use Prod's naming convention
  4. Deployments will work seamlessly across all portals

Use Case 3: Temporary Override for One-Time Migration​

Scenario: Migrating a single workflow that was recreated with a new ID.

Approach:

  1. Create the override before the migration
  2. Run the comparison and deployment
  3. After successful deployment, delete the override
  4. Future comparisons will use the new URN

Security & Permissions​

Who Can Manage URN Overrides?​

Both workspace admins and members can:

  • View URN overrides
  • Create URN overrides
  • Delete URN overrides

URN overrides are workspace-scoped, meaning they apply to all users in the workspace.