Classic Story Maps Conversion Guide

Before you start

• Sign in from Classic Story Explorer to search public and private scopes. The resulting short-lived token needs permission to create items.
• The token stays in browser localStorage and is sent only to ArcGIS REST endpoints. It can be reused in another tab until it expires or you sign out; sessionStorage is only a fallback when localStorage is unavailable.
• Every converted item is created as a private draft. Publishing and sharing remain manual author decisions.
• Start in Classic Story Explorer if you need to find public Classic items or assemble a batch.

Common conversion rules

• The converter creates a draft item so authors can review and edit before publishing.
• Converted item titles use a (Converted) prefix so they are easy to identify.
• After the converted draft is published and shared, owners or administrators can open the Classic item in ArcGIS and use Select replacement to choose the new item.
• Classic title, subtitle, owner/byline, text, links, images, maps, captions, and credits are preserved when the source exposes them in a usable form.
• Classic HTML is cleaned and mapped to ArcGIS StoryMaps text blocks, buttons, image blocks, embeds, map blocks, sidecars, swipe blocks, tours, or Collection entries.
• Referenced ArcGIS web maps are kept as ArcGIS item references when possible. Classic web maps used in Collection-style output are opened through a Map Viewer URL for now.
• Images that live directly under the Classic source item's /info/ or same-item /resources/ URLs are copied into the converted item when possible, and converted item thumbnails are uploaded as image bytes.
• Clearly broken non-ArcGIS external image URLs are replaced with a StoryMaps placeholder image and caption note. ArcGIS item resource URLs from other items are kept as URI references and are not browser-probed.
• Unsupported Classic behavior is flattened into the closest editable StoryMaps structure instead of trying to recreate retired viewer behavior exactly.
• Authors should review the draft for missing media, private dependencies, map extents, section order, styling differences, and any links that require cleanup.

Recipe anchors

• Classic Map Tour
• Classic Shortlist
• Classic Swipe
• Classic Map Series
• Classic Map Journal
• Classic Cascade
• Known limitations

Classic Map Tour

Tour points become places in a guided map tour. If the Classic configuration references a web map and source layer, the converter reads the layer features and preserves the configured order when possible.

• layout: integrated maps to a map-focused guided tour.
• layout: side-panel maps to a media-focused guided tour.
• Empty point titles or descriptions are kept empty so StoryMaps can hide optional UI.

Classic Shortlist

When your ArcGIS token can create items and publish hosted features, the converter creates a private hosted point layer and uses it in one Explorer grid tour. Multiple tabs become categories in a categorized grid.

• One non-empty category becomes a regular Explorer grid; two or more become one categorized Explorer grid.
• Places are grouped by category when the source layer exposes that relationship, including copied CSV layers that store categories in fields such as TAB_NAME.
• If hosted publishing is unavailable or fails, separate embedded Explorer grids preserve the categories without requiring a feature layer.
• All populated categories and places stay together in the backing feature layer for the single categorized Explorer grid.
• StoryMaps Builder supports eight visible categories. For a larger Shortlist, duplicate the tour and split the categories between two tours; the backing layer still contains all converted data.
• The hosted layer and StoryMap draft start private. Review, publish, and share both items for the intended audience.

Classic Swipe

Two-web-map Swipe apps become a StoryMaps swipe block with two web map panels. Single-web-map layer swipe apps can also be converted when the Classic configuration exposes the compared layer ids. The Classic spyglass layout does not have a direct StoryMaps equivalent, so it is converted to the standard swipe interaction.

• Best-supported source shape: Classic dataModel:"TWO_WEBMAPS".
• The first Classic web map is preserved as the left/before side, and the second Classic web map is preserved as the right/after side.
• Layer swipe uses the same web map resource on both sides, with opposite mapLayers visibility overrides on each side.

Classic Map Series

Series entries are converted into ordered Collection items. Hidden Classic entries are preserved as hidden Collection items so authors can review or re-enable them later.

• Web pages and iframe sources become embed/link entries.
• ArcGIS URLs are converted to ArcGIS item entries when a usable item id is present.
• Web map entries currently use a Map Viewer URL so the map remains directly openable.

Classic Map Journal

Journal sections become sidecar slides with fixed narrative panels. Panel HTML is parsed into supported StoryMaps text, list, image, button, embed, and link structures.

• Panel links and button-like links are preserved when possible.
• Standalone media-action links become StoryMaps sidecar action buttons that replace the slide media panel when clicked.
• Inline media-action links still become regular links to the target media. Web map links open Map Viewer with the Classic action extent when available.
• Navigation actions are mapped to StoryMaps anchor links when the destination section can be identified.
• Sidecar media can be web maps, images, embeds, web apps, or web pages.

Classic Cascade

Cascade sections are converted into StoryMaps narrative blocks and immersive sidecars. Floating-panel sidecars are used for Cascade because they better match the original scrolling presentation style.

• Cover images, titles, subtitles, and byline are preserved when usable.
• Large Classic text is mapped conservatively to readable StoryMaps text blocks.
• Immersive web map views preserve Classic extents, layer visibility overrides, and pinned pop-up targets when those are stored in the Cascade view.
• Inline images use supported StoryMaps media sizing, usually standard size for images embedded inside text flow.
• Credits are converted into StoryMaps credits children with title, paragraph, and attribution rows when possible.

Known limitations

The converter is intentionally transparent. These are areas we have tested or investigated where the current output may still need author cleanup.

• Inline text colors: Classic stories can include arbitrary colored spans. The converter maps supported Classic colors to StoryMaps Builder text color classes when possible. Some custom colors may still need author review.
• Credit links: Credits support text and attribution rows. The converter emits Builder-style attribution links, but authors should still verify credit links after conversion because Builder may normalize unsupported markup.
• Logos: Classic logo images, links, and alt text are preserved on the generated StoryMaps root node when the converter can identify the source logo fields.
• Classic-only interactions: Retired behaviors such as Swipe spyglass, highly customized Cascade transitions, custom JavaScript actions, or template-specific navigation widgets are mapped to the closest editable StoryMaps block rather than recreated exactly.
• Swipe layer mode: Classic Swipe could compare layers inside a single web map. The converter can map this to one StoryMaps swipe block when the source exposes usable layer ids, but authors should verify that each side shows the intended layer visibility.
• Shortlist category tabs: With hosted publishing permission, all Classic tabs are preserved in one data-driven categorized Explorer grid. Otherwise the converter creates one embedded Explorer grid per category. Authors should review category labels, order, images, links, and sharing on the new hosted layer.
• Private or broken dependencies: Web maps, images, videos, feature layers, and embeds must still be reachable by the author and intended audience. The converter can reference discovered dependencies, but it cannot repair private or missing source content.
• Image resources: Images stored directly on the Classic source item are copied into the converted item when possible. Images that belong to other ArcGIS items are treated as separate dependencies; if those items are later deleted or restricted, authors may still need to replace the affected media.
• HTML cleanup: Classic panel text may contain old inline styles, nested tables, unsupported classes, empty paragraphs, or embedded iframes. The converter cleans and preserves the useful parts, but authors should review spacing, link behavior, and media placement.
• Map Series target shape: Map Series entries are mapped to a StoryMaps-compatible output using Collection-style entries and links. Web map entries currently use a Map Viewer URL because native web map Collection support is still being handled conservatively. Authors should verify that every converted Collection item opens correctly before publishing.
• Theme matching: The converter chooses the closest built-in StoryMaps theme from Classic color signals. This is a best-effort match, not a pixel-perfect recreation of the Classic visual design.
• Draft review is required: A converted draft should always be reviewed in ArcGIS StoryMaps Builder before publishing. The goal is to preserve structure and content well enough to accelerate author migration, not to guarantee a finished publication.
• Set replacement after publishing: The converter does not change the Classic item. After reviewing, publishing, and sharing the converted item, open the Classic item details in ArcGIS, choose Select replacement, and select the converted item.
• Existing replacements remain unchanged: The Explorer displays an existing replacement so authors can review it, but the converter never creates or replaces that relationship.