Migrate from Sitecore to Agility

Last verified: 2026-10-03 against Sitecore's developer documentation for Sitecore XP and XM 10.x and for XM Cloud. Sitecore products and versions differ, so check the documentation for your version before relying on a detail here.

This guide applies the phases in Migrating to Agility to a Sitecore site. It covers the export options Sitecore documents, and how Sitecore's templates, items, presentation details and languages map to Agility's models, pages, components and locales.

1. The Sitecore concepts you will map

• Items in a content tree. Content is stored as items arranged in a tree. Each item is based on a data template.
• Data templates, sections and fields. A template defines an item's fields, and every field belongs to a template section. Templates can inherit fields from base templates, and a template with no base template inherits from Sitecore's Standard template.
• Standard values. A template's standard values are its defaults: when an item's field value is NULL, the item uses the standard value for that field.
• Presentation details. An item's layout is stored as XML in two of its standard fields: __Renderings, a shared layout for all languages and versions, and __Final Renderings, a versioned layout per language and version. Sitecore merges the two to produce the final presentation. A layout contains placeholders where renderings are inserted, and many renderings take their content from data source items stored elsewhere in the content tree, so the same rendering can be reused on many pages.
• Languages and versions. Items have versions per language, and Sitecore supports item-level and field-level language fallback.
• Media library. Images and files are items in the media library.

2. Export from Sitecore

Option	What you get	Notes
ItemService REST API	JSON for individual items, their children and search results	Base route /sitecore/api/ssc/item. Log in first with POST /sitecore/api/ssc/auth/login, which only responds over HTTPS.
Sitecore Content Serialization (Sitecore CLI)	Items serialized to .yml files on disk	dotnet sitecore ser pull writes the items configured in your module files. Needs elevated permissions.
XM Cloud: Authoring and Management GraphQL API	Items through a GraphQL endpoint	https://<your-instance>/sitecore/api/authoring/graphql/v1/. Needs at least the sitecore\Sitecore Client Users role.

Walking the tree with the ItemService

Request	Returns
GET /sitecore/api/ssc/item/{id}	One item by its ID
GET /sitecore/api/ssc/item/?path=/sitecore/content/Home	One item by its path
GET /sitecore/api/ssc/item/{id}/children	The item's direct children

Each response includes the item's ItemID, ItemName, ItemPath, ParentID, TemplateID, TemplateName, ItemLanguage and ItemVersion, plus its field values. Start at your site's home item and request children recursively, once per language you are migrating.

The database, language and version parameters default to the context database, the context language and the latest version. Set them explicitly so you know exactly which content you exported. fields limits the response to the fields you name. includeStandardTemplateFields=true adds the standard template fields to the response; the layout fields __Renderings and __Final Renderings are among an item's standard fields, so use it when you export presentation details.

3. Map Sitecore to Agility

Sitecore	Agility	Notes
Data template for structured content (articles, people, products)	Content model plus a list container	Store the Sitecore ItemID in a SourceID Text field.
Template section	A Tab in the model	Tabs only group fields in the editor.
Base templates	Fields on each model that needs them, or a linked item	List every inherited field a template really uses before you design the model.
Standard values	Default values, or values written into each item	Check what your export returns for a field that relies on its standard value.
Page items under the home item	Pages in the sitemap	The tree position becomes the sitemap position.
Page items of one template with many instances	A list plus a dynamic page	See Generating Dynamic Pages From Content.
Layout and placeholders	A page model and its zones
Renderings	Component models placed in zones
Data source items	The component's own fields, or a shared list item the component links to	Shared data sources used on many pages fit a shared list.
Media library items	The Agility media library
Languages	Agility locales

Field types

Sitecore field type	Agility field type
Single-Line Text	Text
Multi-Line Text	Multi-Line Text
Rich Text	HTML
Image	Image
File	File
Date, Datetime	Date/Time
Checkbox	True/False
Integer	Number
Number	Decimal
Droplist	Drop-down List
Droplink, Droptree	Linked Content (a dropdown for a single item)
Multilist, Treelist	Linked Content (a search list box)
General Link	URL

See Fields and Linked Content Field Types.

4. Presentation: from renderings to components

This is usually the largest design decision in a Sitecore migration. For each page template:

1. Read the merged presentation for a few representative pages: which renderings appear, in which placeholders, with which data sources.
2. Define an Agility page model whose zones match the placeholders you keep.
3. Define a component model per rendering you keep, with fields for the content its data source held.
4. Decide, per rendering, whether its content belongs to the page (component fields) or is shared across pages (a list item the component links to).

Renderings that only existed for layout or personalization may not need a component. Page-level fields such as titles and meta descriptions belong in the page's SEO fields or on a component.

5. Languages and versions

• Export each language you are migrating, and choose which version you export (the latest by default).
• In Agility the same content item has the same content ID in every locale. Create the item in your main locale, then save the same content ID in each other locale. See Creating Content and Pages in Other Locales.
• Where Sitecore relied on language fallback, decide whether to write the fallback language's values into the Agility locale or leave the locale variant out.

6. Import into Agility

Import in dependency order, keeping a map from Sitecore ItemID to Agility content ID, page ID or asset URL:

1. Media library files, uploaded to the Agility media library.
2. Shared items: data sources used on many pages, taxonomy and people.
3. Structured content items.
4. Pages, then the components on each page.

Use the Management SDK, saving in sequential batches and checking every result, as shown in Migrating Content into Agility with an AI Agent. Pages are created with the SDK's page methods; see Pages. Before saving, rewrite links and media references inside Rich Text fields to the new Agility URLs. Throughput guidance is in Migrating to Agility.

7. URLs and redirects

A Sitecore site's public URLs depend on its site and link settings, so don't derive them from item paths. Get the real list from the live site's sitemap, a crawl and your analytics. Compare it with the new paths and add a 301 redirect in Agility's URL Redirections for every URL that changes. Redirects can be limited to specific locales, which helps if each language has its own URL prefix. See Keep Your Search Rankings Through a Migration.

Checklist

• You know which database, language and version you exported.
• Every template you keep has a content, page or component model, including its inherited fields.
• Each page template's renderings and placeholders map to components and zones.
• Shared data sources became shared items, not copies on every page.
• Media files are in the Agility media library and Rich Text no longer points at the old media URLs.
• Each locale has the right values, with the same content ID across locales.
• Every changed URL has a 301 redirect.

Related

• Migrating to Agility
• Page Models
• Component Models
• Migrating Content into Agility with an AI Agent
• Migration Cutover Runbook