Skip to content
Arc XP

Using arcAdditionalProperties in the Migration Center JSON Object

As discussed in the Migration Center pipeline overview, the Migration Center API /ans and /bulk APIs accept a Migration Center JSON object which includes an arcAdditionalProperties key. This article discusses the use of arcAdditionalProperties, the specific sub-keys and values that are allowed there, and how these keys control the behavior of the downstream requests that Migration Center creates.

Unlike the additional_properties key in ANS which can accept any manner of custom sub-keys and values, the Migration Center JSON’s arcAdditionalProperties only accepts specific elements. If non valid key names are included in arcAdditionalProperties, the request will still go through to Migration Center without error, but only valid keys will trigger useful changes in the Migration Center requests.

Story ANS

arcAdditionalProperties.story.publish - If a piece of content should be published when ingested to Arc XP, include arcAdditionalProperties.story.publish: true.

arcAdditionalProperties.story.circulation.collision_behavior - When Arc XP detects a story’s URL will be the same as an existing story, there must be a way of handling the URL collision. By default, Arc XP will fail the publish request of the newer story, leaving the story’s website_url field in its circulation blank, and causing the request to throw a 400 error. Another option is to set collision_behavior: increment. This parameter will add the next logical numerical suffix to the URL in order to make it unique, for example, /duplicated-url-made-unique-2/.

collision_behavior Property and Values

ValueDescriptionExample
incrementThe increment behavior will avoid a collision with an existing URL by appending a -2, (or -3, -4, etc.) to the end of the requested or generated URL.URL /news/man-bites-dog/ currently points to live story ABC. An API user requests to assign the URL /news/man-bites-dog/ to story DEF using collision_behavior: increment. URL Service assigns /news/man-bites-dog``-2/ to story DEF. The URL /news/man-bites-dog/ remains assigned to ABC.
failThe fail behavior immediately aborts the request with a 400 response code and returns an error to the API client if a request collides with an existing URL. Clients can then react appropriately using their own custom logic and subsequent requests to the URL Service. This is the strongly recommended behavior.URL /news/man-bites-dog/ currently points to live story ABC. An API user requests to assign the URL /news/man-bites-dog/ to story DEF using collision_behavior: fail. URL Service returns a 400 response code, and DEF is not assigned a URL.
{
  "ANS": {...},
  "circulations": [...],
  "arcAdditionalProperties": {
    "story": {
      "publish": true,
      "circulation": {
        "collision_behavior": "fail (default) | increment"
      }
    }
  }
}

Video ANS

arcAdditionalProperties.video.transcoding - When an organization has a video transcoding profile set up with Video Center, they have the ability to create videos through the API and enable the transcoding profile. When enabled, the transcoding profile will use the first item in the ANS streams key as the basis to create multiple specific video formats as set up in the organization’s transcoding profile. Otherwise if the encoding command is not included or specifically set to false, the import will create the video formats that are explicitly sent through in the streams key. The Migration Center JSON key that controls this is arcAdditionalProperties.video.transcoding: true | false (default).

arcAdditionalProperties.video.thumbnailTimeInSeconds - A video’s promotional image can be clipped automatically from the frame at a timestamp in the video. This key turns on thumbnail generation. Its value is a time location in seconds within the video.

arcAdditionalProperties.video.useLastUpdated - The Video Center UI is ordered by the most recently created video, the ANS last_updated_date field. Usually last_updated_date can only be set by the ARC XP system. However, when migrating videos, you are often importing ones created years in the past. In order to keep the Video Center UI showing actual recent videos at the top of the list, you are able to set the last_updated_date field in the Video ANS manually, and if you also pass arcAdditionalProperties.video.useLastUpdated: true in the Migration Center JSON object then your last_updated_date will be respected, stopping the Arc XP System from overriding the value with the current date. The video will then be properly sorted in the Video Center UI, rather than showing up at the top of the Video Center list.

{
  "ANS": {...},
  "arcAdditionalProperties": {
    "video": {
      "transcoding": true,
      "thumbnailTimeInSeconds": 1,
      "useLastUpdated": true // use with last_updated_date in the ANS
    }
  }
}

Updating arcAdditionalProperties

arcAdditionalProperties can be updated using the PATCH /inventory-data API. This eliminates the need to pass in the entire ANS object when you want to change the options around how the downstream requests created by Migration Center are processed. The /inventory-data API endpoint requires query params that identify the Migration Center record to receive the update: one of the combination of ansId= and ansType= or sourceId= and sourceType= query parameters. In the request body you need pass only the arcAdditionalProperties key. When the request is sent, the already stored ANS will be processed through again, this time sending the updated commands from arcAdditionalProperties to the downstream Arc XP API.

curl --location --request PATCH 'https://api.{{org}}.arcpublishing.com/migrations/v3/inventory-data
  ?ansId=ANSIDAND26CHARACTERS
  &ansType=story' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data-raw '{
    "arcAdditionalProperties": {
        "story": {
            "publish": true
        }
    }
}'


// Response
{
    "success": true,
    "message": "Inventory data has been accepted."
}