Skip to main content

Migration Center ANS Maps: Creating a story with related images

You can ingest a single source document into Arc XP that includes multiple related objects, for example, a story with several related images. The Migration Center ANS Maps tool supports this use case, but you must map each part of your source content (such as text and images) to the appropriate ANS templates.

This guide walks you through the required steps.

Before you begin, keep the following key concepts in mind:

  • Images and stories are separate entities in Arc XP.

  • Each has a unique ID (_id or ANS ID) and its own ANS structure.

  • Stories can reference images, and images can be reused across stories.

  • When retrieving a story through the Content API, Arc XP returns denormalized image data automatically. However, when creating story content containing other Arc XP entities, these entities are written in a normalized, reference syntax, different from what you see returned from Content API.

  • We recommend creating images before referencing them in a story that is transformed by an ANS map. This is not required, but recommended.

Minimum ANS reference example

To reference an image in a story, include the following structure in fields like promo_items.basic or content_elements:

{
    "type": "reference",
    "referent": {
        "id": "RW6FY26ERFJYVXRCUXGPIAOWHE",
        "type": "image"
    }
}

To do this, you need to know only the image's _id.

Managing IDs with generateArcHash

You control how ANS IDs are generated in your Migration Center mapping templates. To ensure consistent ID generation, use the generateArcHash function. This function must receive the same input when creating an image and when referencing the same image in a story.

Mapping images and stories

You need two mapping templates:

Image mapping template

An image mapping template transforms each image in the source content into an ANS object of the type image, which the system submits to Photo Center.

This is an example of image ANS transformed from an image source by the ANS map. It is not an ANS map.

{
  "id": "RW6FY26ERFJYVXRCUXGPIAOWHE",
  "version": "0.10.7",
  "type": "image",
  "owner": {
    "id": "sandbox.<yourorgid>"
  },
  "additional_properties": {
    "originalName": "imageName.jpg",
    "originalUrl": "https://example.com/imageName.jpg"
  }
}

Story mapping template

A story mapping template shows how a story can reference an image using its ANS ID.

The following sample is partial ANS for a story with a referenced image. It's not an ANS map, but instead, the resulting ANS output of a story referencing an image.

{
    "type":"story",
    ...
    "promo_items":{
    "basic": {
        "type": "reference",
        "referent": {
            "id": "RW6FY26ERFJYVXRCUXGPIAOWHE",
            "type": "image"
        }
    }
}

Example workflow

To summarize, you perform the following steps to ingest a story with related images:

  1. Create an ANS map for images. As part of that image map:

    • Generate the image _id correctly using the generateArcHash function.

    • Send your images through the ANS map.

  2. Create an ANS map for stories. As part of that story map:

    • Identify where an image belongs.

    • Calculate proper image IDs when you identify an image that is included in the story.

      Note

      To ensure image IDs are calculated correctly, your story source must include the same image fields and values as your image source. This is typically already configured, because generating an image _id generally uses the image URL, and that URL is usually present in the story source where the image appears.

      If these fields are not already present, you must update your story source to include the necessary image data. This ensures that Migration Center can properly generate the image _id during the ANS mapping process.

    • Write a reference for the image using the properly calculated image _id.

    • Send a story through the ANS map.

In this section: