# Preserving or changing migrated content's canonical URLs

Source: https://dev.arcxp.com/migration-center/developer-docs/preserving-or-changing-migrated-contents-canonical-urls/

When you send a story’s Arc XP Native Specification (ANS) through Migration Center, the story’s circulation information and canonical URL are processed through the `circulations` property in the Migration Center JSON object.

If you are migrating a story from a previous CMS, you either migrate the story and preserve the story’s URL, or migrate the story and create a new URL.

To generate the URLs, Migration Center interacts with Draft API, which generates URLs for the content or assigns predefined URLs to the content. This document shows you how to configure the way Arc XP processes your URLs.

> **Important:**
> 
> Arc XP recommends maintaining previously existing URLs when migrating historical content.
> 
> Not maintaining your existing URLs can _negatively impact your site’s SEO scores_ because you must reindex the new URLs and create redirect rules in case the articles are back-linked on other pages.

## Maintaining existing canonical URLs

To maintain existing canonical URLs, you must place the URL in the `website_url` field in the `circulations` property of the Migration Center JSON object.

> **Tip:**
> 
> Alternatively, you can let Arc XP generate URLs for your stories automatically. The default URL format in Draft API is `%publish_date|year()%/%publish_date|month()%/%publish_date|day()%/%headlines.basic|slugify()%/`

You may send a `circulation` object with a URL explicitly set, as shown below:

```
# Migration Center JSON object includes the website_url field in the circulations property, and includes a publish instruction in arcAdditionalProperties so the provided URL applies when the story is published# Migration Center JSON object includes website_url in the circulations property and includes publish instruction in arcAdditionalProperties so that the provided url will be applied when the story is published
{
  "ANS": { ... },
  "circulations": [
    {
      "document_id": "XYZABC789123",
      "website_id": "the-herald",
      "website_url": "/old/cms/headline",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "the-herald"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "the-herald"
          }
        }
      ]
    }
  ],
  "arcAdditionalProperties": {
    "story": {
        "publish": true
    }
  },
}
```

> **Note:**
>
> For guidance on maintaining an existing URL for gallery or video content, review the **How to Reuse an Existing URL** sections in the articles [How to write the minimum ANS for a viable video document](https://dev.arcxp.com/concepts/content-model-ans/how-to-write-the-minimum-ans-for-a-viable-video-document/) and [How to write the minimum ANS for a viable gallery document](https://dev.arcxp.com/concepts/content-model-ans/how-to-write-the-minimum-ans-for-a-viable-video-document/)\[\].

## Generating new canonical URLs

When you create story ANS content using Migration Center, you include a `circulations` object in the Migration Center JSON object.

This `circulations` object has the same structure as the Draft API `circulations` object because Migration Center creates a call to Draft API to generate the story circulations.

When you omit the `website_url` property in the `circulations` object, a new URL is generated after publishing the story. The URL is created following the URL format rules in your organization’s Arc XP Canonical URL application.

If an error occurs during the URL creation process, usually because the URL format rule requires an ANS field missing from the submitted ANS, the resulting `website_url` value is empty, and the story is not published.

> **Note:**
>
> Story URL generation happens _after_ a publishing event. A story can be circulated—assigned to a primary website and section, as well as additional websites and sections—without being published.

## Using URL format rules

You can also specify a URL format for Arc XP to use by configuring a URL format rule in the Canonical URL application. See [Configuring URL formats](https://docs.arcxp.com/en/products/publishing-platform/configuring-url-formats.html) for more details.

If you set a URL format rule, consider the following:

- The rule must be activated _only_ by stories that have been migrated and ignored by stories authored in Composer. To do this, use the format’s `Criteria` property.
- The rule must contain a `Format` property that uses only a format tag of `<website_id>.website_url%`. For example, if your website ID is `the-gazette`, this property value is `%websites.the-gazette.website_url%`.

## Regenerating a URL using format rules

To remove a previously submitted URL and regenerate a new one based on format rules, omit the `website_url` property to retrigger the generation when publishing the story, as shown below.

```
# Migration Center JSON object omits website_url in the circulations property to generate a new URL according to the URL format rules when executes the publish instruction in arcAdditionalProperties.
{
  "ANS": {...},
  "circulations": [
    {
      "document_id": "XYZABC789123",
      "website_id": "the-herald",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "the-herald"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "the-herald"
          }
        }
      ]
    }
  ],
  "arcAdditionalProperties": {
    "story": {
      "publish": true
    }
  }
}
```

## Resources

The following articles give you detailed information on how to maintain and generate canonical URLs.

**Draft API and URLs**

- [Deep dive: URLs in Draft API](https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/deep-dive-urls-in-draft-api/)
- [How Draft API uses format rules to generate Content URLs](https://docs.arcxp.com/en/products/publishing-platform/how-draft-api-uses-format-rules-to-generate-content-urls.html)
- [How to circulate with Draft API and auto-generate the circulation URL](https://docs.arcxp.com/en/products/publishing-platform/how-to-circulate-with-draft-api-and-auto-generate-the-circulation-url.html)
- [How to use Draft API to regenerate and redirect a document URL](https://docs.arcxp.com/en/products/publishing-platform/how-to-use-draft-api-to-regenerate-and-redirect-a-document-url.html)

**URL Format Rules**

- [Configuring URL formats](https://docs.arcxp.com/en/products/publishing-platform/configuring-url-formats.html)
- [How Draft API uses format rules to generate content URLs](https://docs.arcxp.com/en/products/publishing-platform/how-draft-api-uses-format-rules-to-generate-content-urls.html)

**Other URL Information**

- [How to set up canonical URL service for Themes](https://dev.arcxp.com/themes/developer-docs/how-to-setup-canonical-url-service-for-themes/)
- [Canonical URL Service and Photo Center Integration](https://dev.arcxp.com/photo-center/developer-docs/canonical-url-service-and-photo-center-integration/)