> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/editor/mappings-and-episode-groups.md). # Mappings and episode groups Use mappings when providers disagree about a title or an episode. Use episode groups when one provider has a combined episode and another lists its separate parts. This is a child guide to [Editor](/crosswatch/main-dashboard/navigation/editor.md). It covers creating and managing rules. For editing watch dates, ratings, or progress, see the main Editor page. ### Choose the right tool | Situation | Use | | ----------------------------------------------------- | ------------------------------------------------------------------------------- | | An item matches the wrong movie or show | An ordinary mapping correction. | | An episode has the wrong season or episode number | An ordinary mapping correction. | | One episode represents two or more episodes elsewhere | An episode group. | | Numbering shifts after a combined episode | A group for the combined episode, plus ordinary corrections for later episodes. | | An item should be excluded from sync | A block. | Mappings describe how CrossWatch should interpret items. They do not change episode files or rename records in your provider library. ### Where to open mapping In **Editor โ†’ Current State**, use the mapping icon in the row actions beside an item. It is available in both Simple and Advanced views. * **Individual provider account:** the icon opens that item's mapping workspace. * **All providers:** choose the account to correct, click **Open provider**, then use the item's mapping icon in that provider view. * **Mapping** in the toolbar opens **Mappings & blocks** for saved rules. For a History episode, the mapping workspace also offers **Map split episodes**. Save or discard pending Editor changes first if that button is unavailable. Interactive Sync and Analyzer use the same mapping workspace, with the relevant sync pair selected by default. ### Choose where a correction applies For ordinary corrections, Editor defaults to **Every sync with this account**. To limit a correction, open **Advanced** and use **Fixes for**. | Scope | Where the rule applies | | ---------------------------- | ------------------------------------------------------------------ | | Every sync with this account | All sync pairs using that provider instance for the selected list. | | Only a selected pair | That sync pair only. | A pair correction takes precedence over a shared correction for the same original item. Editing an existing saved mapping keeps its scope. Check the provider account, list, and scope before saving. A shared provider instance can be used by several users; shared rules follow that instance. Episode groups always belong to a specific History pair and its provider instances. They are not shared rules. ### Fix a wrong match 1. Select the provider account and list in Current State. 2. Set **Fixes for** if this correction should apply to only one pair. 3. Open the row's mapping action. 4. Check **Search in**, enter a title, and click **Find matches**. 5. Select the correct result. 6. For an episode, verify the show identity, season, and episode number. 7. Review the correction and save it. When the Editor has no other pending changes, **Save fix** saves the correction immediately. Otherwise, **Use correction** stages it: close the workspace and click **Save changes** in Editor. Saving a correction does not run a sync or immediately change the provider's history. #### Search, suggestions, and manual IDs Shared Editor corrections use TMDb metadata search. Selecting a pair enables searches supported by that pair's configured destination. Some destinations use a TMDb metadata fallback, which does not confirm that the item exists in the destination library. Search and automatic suggestions require the relevant connection and metadata settings. **Advanced ยท Manual IDs** lets you enter known identifiers when search is unavailable or cannot find the right item. Where offered, **Auto match** prepares suggestions for review. Suggestions are drafts until saved. Episode suggestions use TMDb numbering; always check the destination's actual season and episode layout. Changing a show match does not automatically fix every episode number. Review the coordinates separately. #### Numbering shifts An ordinary correction maps one item to one corrected identity. For example, if source S04E25 corresponds to destination S04E24, correct that episode's coordinates. If the shift started because two earlier episodes were combined, create a group for those episodes. Then correct the later shifted episodes separately. A group does not renumber the rest of a season. ### Split and combined episodes An episode group links one combined episode on one side to two or more separate episodes on the other. The separate side can contain up to 20 episodes. CrossWatch uses the coordinates you enter. It does not detect episode boundaries or determine the right layout automatically. #### Create a group 1. Open **Mapping โ†’ Episode groups**, or open a History episode's mapping workspace and click **Map split episodes**. 2. Select the **History sync pair**. 3. Enter a recognizable **Group name**. 4. For each provider, choose the **ID type** and enter the **Show ID**. 5. Enter each side's episode coordinates, separated by commas. 6. Optionally enable **Also use for completed scrobbles**. 7. Click **Save group**. Use show IDs, not individual episode IDs. Each side should describe the show and numbering used by that provider. When opened from an episode, the dialog offers pairs containing that exact provider account and prefills its episode details. Complete the other side. If no pair matches, configure a History pair for that account first. **Reset** clears the current form. **New group** starts another group. When opened from the mapping workspace, **Back to mapping** returns to it. #### Example: two parts become one episode Suppose one provider lists a finale as two episodes, while the other has one combined episode. | Field | Provider with separate parts | Provider with combined episode | | -------- | -------------------------------------- | -------------------------------------- | | Show ID | The show's ID for the selected ID type | The show's ID for the selected ID type | | Episodes | S04E23, S04E24 | S04E23 | The show IDs may be the same when both use the same catalog, or different when they use different catalogs. If this is a one-way pair from the separate side to the combined side, CrossWatch waits until both S04E23 and S04E24 are watched before marking the combined S04E23 watched. In the reverse direction, a watched combined episode can mark both separate parts watched. A two-way pair supports both directions; a one-way pair only writes to its configured target. #### What happens during History sync? * A watched combined episode fills in missing watched parts. * Separate parts produce a combined watch only when every part is watched. * Existing watched parts and their dates are preserved. * Newly completed entries use the latest available watch time from the contributing episodes. * Unknown dates remain unknown, subject to the destination's normal write support. Saving a group does not start a sync. Run your next History sync, or refresh an open Interactive Sync review, to apply it. Group evaluation reuses the stored History snapshots. It adds no metadata searches or polling of its own. Provider writes still use the normal sync paths. #### Watch removals and holds If a previously observed group member becomes unwatched, CrossWatch holds the group instead of restoring the removed watch or deleting another part automatically. Resolve the watched states on the providers, then refresh their History through sync. The hold clears when both sides are fully watched or both sides are fully unwatched. Partial states remain untouched while held. An explicit block on a member also holds the group. Remove the block if the group should participate again. Excluded specials are not written. Groups synchronize watched state, not grouped rewatch events. History group processing is held when the pair uses supported History rewatch synchronization. #### Rules that overlap An ordinary correction and an episode group cannot claim the same source or destination episode. Groups cannot overlap each other within the same pair. If saving reports a conflict, remove or adjust the conflicting rule first. Keep later numbering corrections outside the grouped episodes. ### Completed Watcher and webhook scrobbles Enable **Also use for completed scrobbles** when the group should also handle new playback completions. It is off by default. The scrobble route must use the same provider instances and profile as the pair. Keep the pair and its History feature enabled. A reverse route requires a two-way pair. An unassigned pair does not match a route that resolves to a user profile. Assign the pair to the same profile when you want that route to use its groups. #### Completion behavior | Playback | Group behavior | | --------------------------------------------------- | ------------------------------------------------------------- | | Combined episode completes | Sends a completed watch for each mapped part. | | One separate part completes | Remembers that completion and waits for the other parts. | | All separate parts complete | Sends the combined episode's completed watch. | | Start, pause, or a stop below the watched threshold | Does not forward a mapped playback update to the destination. | The destination's watched threshold applies. These groups do not translate live progress or calculate boundaries inside a combined episode. All parts must complete after the option is enabled. Earlier watches are handled by History sync. Completion tracking survives restarts, and different accounts, servers, profiles, and provider instances do not share partial completions. Each destination episode is sent once per group and account; grouped rewatch scrobbles are not supported. Confirmed parts are retained when another write fails, so a retried event only sends missing parts. Webhook retries depend on another delivery from the source. Ordinary mapping corrections still apply only to sync. Enabling completed scrobbles on an episode group does not make ordinary corrections apply to Watcher or webhook events. Destinations must support an eligible History pair. BingeBase cannot use these groups because it has no History sync provider. Other destinations retain their normal connection, matching, and anime mapping requirements. ### Find and manage saved rules Open **Mapping** in the Editor toolbar to display **Mappings & blocks**. #### Ordinary mappings Use **Search**, **Source and profile**, and **Feature** to find a correction. The list shows the original item, corrected item, and where the rule applies. Use the pencil to open it in Editor. Save with **Save fix**, or use **Use correction** followed by **Save changes** when other edits are pending. Deleting a mapping takes effect immediately and also removes its automatically associated original-identity block. It does not delete provider records. If a shared correction remains beneath a deleted pair correction, the shared correction applies again. #### Episode groups and badges Open **Episode groups**, choose the pair, and use **Edit** or the delete action on a saved group. History rows belonging to a saved group show an **Episode group** badge, including in All providers. Hover for the pair, episode coordinates, and scrobble setting. With write access, click it to open the group. The badge identifies a saved rule, not a successful sync or completed watch. Editor rows refresh after group changes; when returning through the mapping workspace, they refresh after you leave that workspace. #### Blocks To create a standalone block, open **Blocked items**, choose the source account and feature, check the scope, and enter the item key. Click **Block item** to save it immediately. **Unblock** removes that standalone rule. Blocks created automatically for a mapping's original identity belong to that mapping. Manage those by editing or deleting the correction. Save or discard pending Editor edits before changing saved rules or importing a file. ### Export and import #### Export rules Click **Export** in **Mappings & blocks** to download the mapping transfer JSON. The export follows the selected scope, source, and feature. Search text and the selected Mappings or Blocked items tab do not limit it to visible rows. Version 3 includes episode groups and their completed-scrobble setting. Groups are included for History or all features when an endpoint matches the selected source and both accounts are accessible. **Shared-only exports exclude episode groups**, because groups belong to pairs. To export a group's rules from Editor, select its pair under **Advanced โ†’ Fixes for** before opening **Mapping** and exporting. #### Import rules 1. Click **Import** and select a mapping transfer JSON file. 2. Review the confirmation, including the episode group count. 3. Confirm, then check the imported and skipped results. Versions 1, 2, and 3 are accepted, up to 20 MB. Import follows the scopes stored in the file; the current dialog filters do not restrict it. Episode groups require an existing History pair with the same pair ID and provider instances. Identical groups are skipped. Conflicting group settings, overlapping groups, or conflicts with ordinary corrections reject the entire import without changing saved rules. #### Rules versus runtime state Mapping exports and full policy backups contain group definitions. They do not contain watched-state observations or scrobble completion tracking. Database backups preserve that runtime state too. Resetting pair state clears group observations and completion tracking. It is not required to create or edit a group. ### Interactive Sync and Analyzer Interactive Sync identifies grouped additions and shows watched-part counts. Refresh an existing review after changing a group. Analyzer uses saved History data and the same group rules as sync. It shows group status and watched-part counts, reports incomplete groups or holds in **System health**, and explains ready groups with missing destination watches in **Snapshot differences**. Analyzer does not fetch new provider metadata or inspect live scrobble completion tracking. Use a fresh History sync when its saved provider data is out of date. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/editor/mappings-and-episode-groups.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.