Skip to main content

Changeset Hydration

When you select items for deployment, HubSpot Deploy stores them as lightweight references (URNs) in your changeset. Before deployment, these references are "hydrated" - converted into complete metadata with all the information needed for deployment.

What is Hydration?​

Hydration is the process of converting a lightweight reference into a full deployment package.

Before Hydration (Lightweight)​

Your changeset contains URN references like:

urn:property:contact:favorite_color
urn:workflow:lead_nurture_v2
urn:schema:custom_project

These are just identifiers - they don't contain the actual metadata.

After Hydration (Complete)​

Each URN is expanded into a complete item with:

  • Full metadata payload (all fields and values)
  • Operation type (create, update, or delete)
  • Parent-child relationships
  • Target IDs for updates
  • Owner mappings

Why Use URNs?​

Efficiency​

Storing URNs instead of full metadata:

  • Saves space - A URN is ~50 bytes vs. full metadata which can be 5-50 KB
  • Faster comparisons - Lightweight changesets load instantly
  • Reduces storage - Thousands of changesets don't bloat the system

Freshness​

Hydrating at deployment time ensures:

  • Latest data - Metadata is fetched fresh from storage
  • Accurate state - Reflects any changes since the comparison was created
  • No stale data - You're always deploying current information

Flexibility​

URN-based changesets allow:

  • Easy editing - Add or remove items without reloading full metadata
  • Reusable changesets - Same changeset can be deployed multiple times
  • Version independence - Changesets work even if metadata is updated

How Hydration Works​

Step 1: Validate Changeset Format​

The system checks that your changeset contains valid URNs:

✓ Valid: ["urn:property:contact:email", "urn:workflow:welcome"]
✗ Invalid: Legacy format or malformed URNs

If you have an old changeset in legacy format, you'll need to refresh the comparison to regenerate it.

Step 2: Determine Operation Type​

For each URN, the system determines what operation is needed:

  • Create - Item exists in source but not in target
  • Update - Item exists in both source and target (and they're different)
  • Delete - Item exists in target but not in source

The operation is determined by checking the current state in the system, not from the URN itself.

Step 3: Fetch Full Metadata​

The system retrieves the complete metadata from storage:

  • Queries metadata items by URN
  • Fetches the YAML content
  • Converts YAML to JSON payload
  • Includes all fields and nested data

Step 4: Resolve URN Overrides​

If you've created manual URN overrides, they're applied during hydration:

  • Checks for overrides on both source and target connections
  • Resolves the real URN if an override exists
  • Ensures the correct metadata is fetched

See URN Management for details on overrides.

Step 5: Handle Parent-Child Relationships​

For items with parent-child relationships:

Creating Parent Objects​

If you're creating a custom object, pipeline, or standard object:

  1. System finds all child items (properties or stages) in the changeset
  2. Includes children in the parent's creation payload
  3. Marks children as "skip deployment" (they're deployed with the parent)

Example: Creating a custom object with 10 properties deploys everything in one operation.

Creating Child Items​

If you're creating a property for a new object that's also in the changeset:

  1. System detects the parent is being created
  2. Marks the property to skip individual deployment
  3. Property is included in the parent object's creation

Step 6: Map Owners​

If metadata references HubSpot owners (team members):

  1. System looks up the owner's email from the source portal
  2. Finds the matching owner in the target portal by email
  3. Replaces the owner ID with the target portal's ID

This ensures owner references work correctly across portals.

Step 7: Resolve Target IDs​

For update operations on certain metadata types:

  • Lists - Fetches the target list ID
  • Forms - Fetches the target form ID
  • Email Templates - Fetches the target template ID
  • CTAs - Fetches the target CTA ID
  • Campaigns - Fetches the target campaign ID

This ensures updates are applied to the correct existing items.

Step 8: Build Deployment Item​

Finally, the system creates a complete deployment item with:

{
  metadataType: "custom_object_property",
  internalName: "project_status",
  operation: "create",
  payload: { /* full metadata */ },
  objectType: "custom_project",
  parentObject: "custom_project",
  status: "new"
}

This item is ready for deployment.

What You See​

During Comparison​

When you create a comparison, you see:

  • Item names and types
  • Status (new, different, deleted)
  • Structured diff view

Behind the scenes, these are stored as URNs.

During Deployment​

When you start a deployment:

  1. "Hydrating changeset..." - Converting URNs to full items
  2. Progress indicator - Shows hydration progress
  3. "Deployment starting..." - Hydration complete, deployment begins

Hydration typically takes 1-3 seconds for most changesets.

Delete Operations​

Important: Delete operations are not supported and will cause deployment to fail.

If your changeset contains items marked for deletion:

  • Hydration will detect them
  • Deployment will stop with an error
  • You must remove delete items from the changeset

To handle deletions:

  1. Review the changeset
  2. Deselect any items marked for deletion
  3. Deploy only creates and updates
  4. Handle deletions manually in HubSpot if needed

URN Override Resolution​

If you've created URN overrides, hydration handles them automatically:

Example Scenario​

You have a property named deal_value in both portals, but they have different internal names:

  • Source portal: deal_value_v2
  • Target portal: deal_value_legacy

You create an override:

urn:property:deal:deal_value_v2 → urn:property:deal:deal_value_legacy

During hydration:

  1. Changeset contains urn:property:deal:deal_value_v2
  2. System checks for overrides
  3. Finds the override to deal_value_legacy
  4. Fetches metadata for deal_value_legacy from target
  5. Deploys as an update to the existing property

Common Scenarios​

Scenario 1: Simple Property Creation​

Changeset:

["urn:property:contact:favorite_color"]

Hydration:

  1. Validates URN format ✓
  2. Determines operation: create (not in target)
  3. Fetches metadata from source portal
  4. No parent-child relationships
  5. No owner mappings needed
  6. Builds deployment item

Result: Ready to create property

Scenario 2: Custom Object with Properties​

Changeset:

[
  "urn:schema:custom_project",
  "urn:property:custom_project:project_name",
  "urn:property:custom_project:project_status",
  "urn:property:custom_project:project_owner"
]

Hydration:

  1. Validates all URNs ✓
  2. Determines operations: all create
  3. Fetches metadata for all items
  4. Detects parent-child relationships
  5. Includes 3 properties in custom object payload
  6. Marks properties as "skip deployment"

Result: One deployment item (custom object with properties)

Scenario 3: Workflow Update with Owner​

Changeset:

["urn:workflow:lead_nurture"]

Hydration:

  1. Validates URN ✓
  2. Determines operation: update (exists in both)
  3. Fetches metadata from source
  4. Detects owner reference: hubspot_owner_id: 12345
  5. Maps owner: john@company.com → target owner ID 67890
  6. Replaces owner ID in payload
  7. Fetches target workflow ID
  8. Builds deployment item with target ID

Result: Ready to update workflow with correct owner

Troubleshooting​

"Legacy changeset format not supported"​

Cause: Your changeset was created with an older version of the system.

Solution: Refresh the comparison to regenerate the changeset in the new URN format.

"URN not found"​

Cause: The URN in your changeset doesn't exist in the system.

Solution:

  • The item may have been deleted from the source
  • Refresh the comparison to update the changeset
  • Remove the invalid URN from the changeset

"Delete operations are not supported"​

Cause: Your changeset contains items marked for deletion.

Solution:

  • Review the changeset
  • Deselect items marked for deletion
  • Deploy only creates and updates

Hydration Takes a Long Time​

Cause: Large changesets (500+ items) take longer to hydrate.

Expected behavior:

  • 100 items: ~1 second
  • 500 items: ~5 seconds
  • 1000 items: ~10 seconds

If hydration takes significantly longer, there may be a connectivity issue.

"Parent object not found"​

Cause: You're trying to create a property for an object that doesn't exist.

Solution:

  • Include the parent object in your changeset
  • Or ensure the parent object already exists in the target portal

Best Practices​

Keep Changesets Focused​

Smaller, focused changesets:

  • Hydrate faster
  • Are easier to review
  • Have clearer deployment logs
  • Are simpler to troubleshoot

Refresh Stale Comparisons​

If a comparison is more than a few days old:

  • Refresh it before deploying
  • This ensures you're working with current data
  • Prevents deploying outdated metadata

Review Before Deploying​

After hydration completes, review:

  • The number of items being deployed
  • The operation types (create vs. update)
  • Any warnings or messages

Use URN Overrides When Needed​

If you have naming mismatches between portals:

  • Create URN overrides before deployment
  • Hydration will automatically apply them
  • This prevents creating duplicate items

Performance​

Hydration is designed to be fast:

Changeset SizeHydration Time
10 items< 1 second
50 items~1 second
100 items~2 seconds
500 items~5 seconds
1000 items~10 seconds

Most changesets contain 10-100 items and hydrate in 1-2 seconds.