Skip to content
Arc XP

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.

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.

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
    }
  },
}

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.

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