> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/studio/features-and-functionality/reparenting-records.md).

# Reparenting Records

### Overview <a href="#overview" id="overview"></a>

Reparenting moves an existing Record, or a Record together with its descendants, under a different valid parent. Only the parent link changes: the Origin Studio ID, metadata and all other relationships are preserved.

**The problem it solves.** Until now a Record's position in the hierarchy was fixed once created. Correcting it meant deleting and recreating the Record, which:

* destroyed its Origin Studio ID, history and every relationship pointing at it;
* left structural errors from upstream sources with no in-product fix;
* pushed some customers to build separate review tools to fix hierarchies before data reached the Studio Library;
* forced whole branches (a Season and its Episodes) to be handled Record by Record, if at all.

**Key facts**

* Works on both draft and published Records. A Record does not change status to be restructured.
* Part of update-record functionality, available from the Library, a Record page and a Working Set, with identical behaviour in each.
* Available via UI, API and MCP (AI-driven moves). All three produce the same result.
* A generic capability for all customers. BBC is the first client using it.

### How a move works <a href="#how-a-move-works" id="how-a-move-works"></a>

1. **Select and choose Move.** Pick a Record, or a parent with its descendants, from the Library, a Record page or a Working Set.\
   ![](https://2273874994-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpbuQPZAuVlwuAEzIi462%2Fuploads%2F1mGDAo1slJz6QOKKq9S4%2Fimage.png?alt=media\&token=ae12f92d-b265-4d1d-99c9-fa5d3346511b)
2. **Pick a valid parent.** Studio shows the hierarchy and offers only parents the configured rules permit for that Record type. Invalid targets cannot be selected.\
   ![](https://2273874994-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpbuQPZAuVlwuAEzIi462%2Fuploads%2F44QKisXiZM3tkjjvWXnv%2Fimage.png?alt=media\&token=34dc85f4-1fb0-4405-9661-4eb82cb198a1)
3. **Review the impact.** Before anything is applied, Studio shows the current parent, the proposed parent and every descendant that moves with it.
4. **Confirm.** The move applies immediately, to draft and published Records alike.
5. **Audit.** Each moved Record keeps its ID, metadata and relationships, and gains an audit entry with original parent, new parent, user and date.

**What Studio does not do.** It does not detect Records sitting under the wrong parent, and it keeps no history of corrections against the source. Reparenting happens only when triggered, by API ingest or by a user. Every import is treated as new: if a source resends the same data, the same process runs and any conflict is shown to the user.

### Permitted and blocked moves <a href="#permitted-and-blocked-moves" id="permitted-and-blocked-moves"></a>

Shows sit at the top level; Seasons sit under Shows; Episodes sit under Seasons or directly under Shows. Moves that break this shape are blocked.

| Move                                      | Within the same Show                    | To a different Show            |
| ----------------------------------------- | --------------------------------------- | ------------------------------ |
| Episode → another Season                  | Permitted                               | Permitted                      |
| Episode → directly under a Show           | Permitted                               | Permitted                      |
| Season (with its Episodes) → another Show | n/a: a Season's parent is always a Show | Permitted (BBC's central case) |
| Edit → Edits                              | Permitted                               | Permitted                      |
| Season → under another Season             | Blocked                                 | Blocked                        |
| Season → under an Episode                 | Blocked                                 | Blocked                        |
| Show → under another Show                 | Blocked: Shows are top level            | Blocked                        |

The blocked rows follow the EIDR-aligned model and should be checked against each tenant's configured parent-child rules, which are what Studio actually enforces.

**Moving a parent with children.** A Season that has Episodes must move with them. Moving the Season alone and leaving its Episodes without a parent is not possible. An empty Season can be moved on its own.

### Access, audit and channels <a href="#access-audit-and-channels" id="access-audit-and-channels"></a>

**Permissions.** Reparenting is governed by its own policy, which can be added to any role. The default Records Editor role created with each tenant has it.

**Audit.** Every move writes an audit entry per Record: original parent, new parent, user and date. There is no undo; a mistaken move is corrected with another move.

**Where it is available**

| Channel  | Typical use                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------ |
| UI       | A reviewer selects Records in the Library, on a Record page or in a Working Set and chooses Move |
| API      | An ingest or mapping pipeline moves Records that need structural correction                      |
| MCP (AI) | An assistant moves Records on a user's behalf after showing the impact and getting confirmation  |

**How the API behaves today.** These details come from the Origin Studio MCP tool definition, not the spec page:

* Runs as a background job: `POST /record-jobs` with `type=moveRecord`. It returns a jobId to poll until it succeeds or fails.
* Up to 25 Records per call, all sharing one parent. Records with different parents need one call each.
* Descendants always move with the Records selected.
* Series, Movies and Compilations cannot be moved.
* If any Record in the request is not allowed to move, the whole request is refused and nothing changes.
* While a move runs, other moves and deletes on the same hierarchy are refused until it finishes.
* Sequence numbers are kept as they were, so Records may need renumbering after the move.

### Worked example: Torchwood: Miracle Day <a href="#worked-example-torchwood-miracle-day" id="worked-example-torchwood-miracle-day"></a>

BBC's Mapping Engine receives Torchwood Seasons 1–3, then "Miracle Day". The titles don't match, so it proposes Miracle Day as a separate Show with one Season and ten Episodes. The metadata is correct; the shape is wrong.

1. The Mapping Engine creates a Working Set for the uncertain Torchwood Records. A Jira ticket links to it and a notification is sent.
2. A structural reviewer opens the ticket and lands in the Working Set, with the new Records highlighted.
3. She spots a Show, "Torchwood: Miracle Day", that shouldn't exist, holding one Season and ten Episodes.
4. She compares the Season's identifiers with the existing Torchwood Seasons and confirms it is the same programme.
5. She selects the Season and chooses Move. Torchwood is offered as a valid parent; the Episodes below are not.
6. The impact review shows the Season moving from Miracle Day to Torchwood, with all ten Episodes.
7. She confirms. The Season is now Season 4 of Torchwood, after the existing Seasons, with Episodes, identifiers and history intact. The empty Miracle Day Show is left for her to remove.
8. She closes the Working Set. The Records were never locked; the move applied the moment she confirmed.
9. Next day the Mapping Engine resends the same data. The same process runs and the conflict is shown to her, so she can see the Season is already under Torchwood.

### Limitations and edge cases <a href="#limitations-and-edge-cases" id="limitations-and-edge-cases"></a>

**Out of scope**

* Deduplication: a Record that turns out to duplicate an existing one belongs to the separate deduplication feature.
* Split and Combine: not needed by BBC, as Rightsline represents these upstream as Configurations.
* Changing a Record's work type.
* Undo after a move is applied.

**Edge cases**

* **Name clash at the destination.** If a Record with the same name already exists under the new parent, how the user resolves it during the move is still a design question.
* **Empty parent left behind.** When everything under a parent is moved away, Studio does not flag the empty parent. Users must clean it up themselves.
* **Branch moves.** Moving a Season may require its whole subtree to be in the Working Set.
