Skip to main content

Preserving or changing migrated content's 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 ANS for a Minimum Viable Video Document and How to Write ANS for a Viable Gallery 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 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

URL Format Rules

Other URL Information

In this section: