Skip to content

PROD-1506: create/update URL redirections on sync/push with ID mappings#186

Merged
jules-exel merged 1 commit into
mainfrom
feature/PROD-1506-url-redirect
Jul 15, 2026
Merged

PROD-1506: create/update URL redirections on sync/push with ID mappings#186
jules-exel merged 1 commit into
mainfrom
feature/PROD-1506-url-redirect

Conversation

@jules-exel

@jules-exel jules-exel commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

URL redirections were downloaded on pull (via the Content Sync SDK) but never pushed to the target. This adds a full create/update push path with source→target ID mappings, using the new Management API batch endpoint:

POST /api/v1/instance/{guid}/url-redirections — accepts up to 250 redirections per request (one transaction per request). Items without a urlRedirectionID are created; items with one are updated (full replace). Per-item results come back grouped into created / updated / skipped.

How it works

  • New UrlRedirections element, included in the default --elements list and registered as a guid-level push operation. It runs after Containers and before Templates — the template pusher deliberately throws on mapping inconsistencies (rename protection), which aborts the rest of the guid-level loop, and dependency-free redirections must not be collateral damage of that stop.
  • Change detection is a direct field diff of pulled source vs target items (redirections carry no modifiedOn): mapped + identical → skip; mapped + different → update; same origin URL without a mapping → map-on-adopt (self-heal, consistent with galleries/models); otherwise → create. A mapped redirect deleted on the target is re-created. Deletes do not propagate (consistent with all other pushers).
  • Batching: creates and updates are sent together in chunks of 250 sequential requests. The response's per-item index (position within that request's payload) is used to write sourceUrlRedirectionID → targetUrlRedirectionID rows to a new central mapping file at agility-files/mappings/{source}-{target}/urlredirections/mappings.json. API-side skips (validation failures / origin URL collisions) are logged with their reason. A failed batch marks only its own items failed and the run continues with the next batch; re-runs self-heal via the diff + map-on-adopt.
  • Field mapping: pulled sync data uses id/statusCode; the payload sends urlRedirectionID/httpCode.
  • Preflight: full --preflight support under a "URL Redirections" phase; mapping writes remain behind the existing preflight hard guard.
  • The endpoint isn't in @agility/management-sdk yet, so url-redirection-api.ts calls it directly with the same token/base-URL resolution the SDK client uses.

Behavior notes

  • A plain agility sync now pushes redirections by default (they were already always downloaded). Scope with --elements to exclude them.
  • Target-only redirections are never touched; a source redirect deleted after a previous sync stays on the target (delete propagation would need an API delete endpoint — future work).

URL redirections were downloaded on pull (via the Content Sync SDK) but never
pushed to the target. Add a full push path using the new Management API batch
endpoint POST /api/v1/instance/{guid}/url-redirections (up to 250 per request,
one transaction per request; items without a urlRedirectionID are created,
items with one are updated).

- New "UrlRedirections" element, included in the default --elements list and
  registered as a guid-level push operation. Runs after Containers and BEFORE
  Templates: the template pusher deliberately throws on mapping
  inconsistencies, which aborts the rest of the guid-level loop, and
  dependency-free redirections must not be collateral damage of that stop.
- Pusher diffs pulled source vs target items directly (redirections carry no
  modifiedOn): mapped+identical -> skip, mapped+different -> update,
  same origin URL without mapping -> map-on-adopt, otherwise -> create.
  A mapped redirect deleted on the target is re-created. Deletes do not
  propagate (consistent with the other pushers).
- Creates and updates are sent together in batches of 250; the per-item
  response indexes are used to write sourceUrlRedirectionID ->
  targetUrlRedirectionID rows to a new central mapping file
  (mappings/{source}-{target}/urlredirections/mappings.json). API-side skips
  (validation/origin collisions) are logged with their reason. A failed batch
  marks only that batch failed and continues.
- Full --preflight support under a "URL Redirections" phase; mapping writes
  stay behind the existing preflight hard guard.
- New urlRedirection log namespace; README and --help updated.
- Tests: 47 new tests across getter, mapper, API caller, and pusher.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@jules-exel jules-exel requested a review from 5PK July 14, 2026 20:35
@jules-exel jules-exel merged commit 5a5482c into main Jul 15, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants