How To Write The Minimum ANS For A Viable Video Document

The ANS schema has a lot of specific keys and details that can vary widely between ANS content types. When planning to write ANS for a migration using the Arc XP APIs, which fields are the most necessary ones? Let’s narrow the focus, and pay attention to only the minimum selection of all the possible ANS fields necessary to create one kind of Arc XP content. What ANS fields are the most necessary ones when creating an Arc XP video that will be created programmatically using the Video Center API?

In this article we will discuss what is the minimum ANS that will result in a viable Arc XP video. There will still be other useful video ANS fields that are not included in this discussion. After reviewing this article, you will be equipped with a solid video ANS starting point.

Video ANS must first and foremost have an ANS version that is 0.8.0. This version number is constant and does not change when ANS versions increase.

Should you choose to, you can generate your own ANS ID and include that value in the _id field. By default, Video Center will generate a UUID and use that as the ANS ID if there is no _id field submitted.

{
  "_id": "VZSMIFNZKFKW5GG64JJQ4ND3UM",
  "type": "video",
  "owner": {
    "id": "sandbox.arctesting1"
  },
  "version": "0.8.0"
}

The url to the video binary at the original CMS is included in the ANS in the streams key. The url must be publicly available. If you can enter the url in a browser and a video plays, this is a good test to show that Video Center should be able to access and download it too. The video binary must be one of the file types that video center accepts: .mp4, .m4v, .mov, .mpg, .mpg2, .mxf

{
  "streams": [
    {
      "url": "https://vimeo.com/1141237875.mp4",
      "stream_type": "mp4"
    }
  ]
}

Videos are assigned to a category. The categories you can choose from are in the Video Center GUI, in the Utilities > Types menu item. When Video Center is provisioned, a few default categories, or types, are included in this list, including “sample”. Add additional_properties.videoCategory to the ANS and use one of these category/type values in it. Add to the types list in Video Center to create more categories.

{
  "additional_properties": {
    "videoCategory": "sample"
  }
}

Videos must be circulated to at least one website. The ANS field canonical_website records the primary website that owns the video. The same value is also used as a dictionary key value in the websites field. Both fields are required to set a video’s canonical website.

{
  "canonical_website": "arc_test1",
  "websites": {
    "arc_test1": {}
  }
}

In addition to a canonical website, a video must circulate to a section. To set the section in the canonical website, add taxonomy.primary_section. Complete this ANS field with an existing section in the primary website. As with other fields where an Arc XP document is embedded in another, use reference syntax. When used for a section, reference syntax will require an additional key to name the website to which the section belongs.

Add the same reference to the taxonomy.sections array. If the video will be circulated to multiple websites or multiple sections, the taxonomy.sections key is required.

{
  "taxonomy": {
    "primary_section": {
      "type": "reference",
      "referent": {
        "id": "/main",
        "type": "section",
        "website": "arc_test1"
      }
    },
    "sections": [
      {
        "type": "reference",
        "referent": {
          "id": "/main",
          "type": "section",
          "website": "arc_test1",
          "referent_properties": {
            "additional_properties": {
              "primary": true
            }
          }
        }
      }
    ]
  }
}

We have used a section reference to fill out the section documents contained in the taxonomy keys. This section reference includes some specific keys that are necessary when working with a video. referent.website must be set to the website where the section resides. primary: true is implied when the reference is used in the taxonomy.primary_section key. You can specifically describe primary:true by including the property referent.additional_properties.primary.

The taxonomy.sections key can be omitted if you are only creating the video in one website section. In this case the value in taxonomy.primary_section will be accepted alone, and once the ANS is submitted the taxonomy.sections key will be added automatically.

Video API Create Endpoint

At this point you have built the absolute minimal ANS needed to create a video. Send the video ANS using the Video Center API's Import Endpoint.

curl --request POST \
  --url https://api.sandbox.arctesting1.arcpublishing.com/goldfish/video/v2/import/ans \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "video",
    "version": "0.8.0",
    "owner": {
      "id": "sandbox.arctesting1"
    },
    "streams": [
      {
        "url": "https://vimeo.com/1141237875.mp4",
        "stream_type": "mp4"
      }
    ],
    "additional_properties": {
      "videoCategory": "sample"
    },
    "canonical_website": "arc_test1",
    "websites": {
      "arc_test1": {}
    },
    "taxonomy": {
      "primary_section": {
        "type": "reference",
        "referent": {
          "id": "/main",
          "type": "section",
          "website": "arc_test1"
        }
      }
    }
  }'

Additional Useful ANS Fields

Using the ANS we have built so far, a video will be imported from the url in the ANS streams key and you will find it in the Video Center GUI. However, you will notice that the video has an automatically generated name, contains no thumbnail, and is unpublished. To fix these effects we need to add more ANS fields.

To set a specific name, add the ANS field headlines.basic. This name will display on the video’s list card in video center.

{
  "headlines": {
    "basic": "a headline"
  }
}

An existing photo can be directly imported as a video thumbnail, or one can be clipped from the video itself. In order to import a photo as a thumbnail, it has to exist at a url that is accessible by a browser and referenced in the ANS key promo_items.basic. The Video Center API will itself call the Photo Center API and the image will be uploaded into Photo Center and automatically assigned to be the video thumbnail.

Note: It is not possible to use an ANS reference in the video’s promo_items.basic field. In order to select a pre-existing Photo Center image as a video thumbnail you will need to do so manually from within the Video Center interface.

{
  "promo_items": {
    "basic": {
      "type": "image",
      "url": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7",
      "version": "0.8.0"
    }
  }
}

Instead of sending in an image to use as the video’s promo item, you can tell Video Center to select a thumbnail from a frame of the video. In order to clip a thumbnail image from a video’s frames, you will add a query parameter to the Video Center API call and exclude entirely the promo_items.basic ANS field. The query parameter name is thumbnailTimeInSeconds and the value is the number of seconds into the start of the video where the frame will be clipped.

curl --request POST
  --url 'https://api.sandbox.arctesting1.arcpublishing.com/goldfish/video/v2/import/ans?thumbnailTimeInSeconds=1.0'

You can either send in an image to be the thumbnail or instruct the Video Center API to clip a thumbnail from the video frames. You cannot do both of these at the same time. Attempting to do so will result in an error from the Video Center API.

To cause a video to be re-encoded on import into the versions that have been arranged in the Video Center encoding profile for your organization, you will add a query parameter to the Video Center ApI call, encode=true. If this parameter is not included in the request, the video will be imported into video center exactly as it is at the original url.

curl --request POST
  --url 'https://api.sandbox.arctesting1.arcpublishing.com/goldfish/video/v2/import/ans?encode=true'

Add revision.published to the ANS to publish the video on import.

{
  "revision": {
    "published": true
  }
}

Add publish_date and display_date to the ANS to set date values on the video. The dates must be in UTC timezone and use the format YYYY-MM-DDThh:mm:ssZ.

{
  "display_date": "2021-06-07T00:00:00Z",
  "publish_date": "2021-06-07T00:00:00Z",
}

How to Circulate Video to Multiple Websites

When circulating a video to multiple websites you add additional data to the websites and taxonomy.sections keys. Add new websites as empty dictionaries to the websites key, where the name of the new dictionary is the id of the website from Site Service. For each new website add at least one of its sections to taxonomy.sections. One section for every added website must have a taxonomy.sections.primary: true value, which is the flag setting that section as the primary section for the added website. Every website a video is circulated to must have one primary section.

A video can be circulated to more than one section in a website as well. This is done by including a reference for each section in taxonomy.sections.

{
  "websites": {
    "arc_test1": {},
    "demo": {}
  },
  "taxonomy": {
    "primary_section": {
      "type": "reference",
      "referent": {
        "id": "/main",
        "type": "section",
        "website": "arc_test1"
      }
    },
    "sections": [
      {
        "type": "reference",
        "referent": {
          "id": "/main",
          "type": "section",
          "website": "arc_test1",
          "referent_properties": {
            "additional_properties": {
              "primary": true
            }
          }
        }
      },
      {
        "type": "reference",
        "referent": {
          "id": "/demo",
          "type": "section",
          "website": "demo",
          "referent_properties": {
            "additional_properties": {
              "primary": true
            }
          }
        }
      },
      {
        "type": "reference",
        "referent": {
          "id": "/section2",
          "type": "section",
          "website": "demo",
          "referent_properties": {
            "additional_properties": {
              "primary": false
            }
          }
        }
      }
    ]
  }
}

This ANS to circulate a video to multiple sections is correct if the following are true:

The websites ANS field has an entry for each website represented by the list of sections.
There is at least one section in taxonomy.sections for every website.
There is an entry in taxonomy.sections for the same section that is in taxonomy.primary_section.
There is only one taxonomy.sections.referent.referent_properties.additional_properties.primary: true per website.

How to Reuse an Existing URL

To import a video with a specific URL and stop Canonical URL service from generating a new URL to assign to the imported video, you need to take three steps.

Store the video URL in the ANS.
Store a value in the ANS that will identify all imported videos.
Configure a URL format rule just for imported videos using the Canonical URL tile in your Arc XP Admin dashboard.

The video URL must not include a domain, nor any query parameters. The URL must begin and end with a forward slash (/). You have some options as to which ANS field you use to store the URL.

{
  "additional_properties": {
    "website_url": "/existing/video/url/"
  }
}

The most straightforward ANS field you can use is additional_properties. The additional_properties key allows you to create custom keys in your ANS. This route is a good choice if your imported video will only be circulated to one website or, regardless of how many websites where the video will be circulated, the video URL will always remain the same. The name of the custom key in additional_properties may be whatever you like; it does not have to be additional_properties.website_url as it is in the example above.

{
  "websites": {
    "arc_test1": {
      "website_url": "/existing/video/url/"
    },
    "demo": {
      "website_url": "/existing/video/url/possibly/different/"
    }
  }
}

The second option is to save the URL in the ANS websites key. The websites key contains named keys for each website where the video will be circulated. Each named website dictionary will need its own value for websites.{{site id}}.website_url; the name of this ANS field can not be customized.

Choose one or the other of these two options and maintain consistency with all of the imported video ANS.

You also need to set an ANS field that can be used to differentiate imported videos from videos created using the Video Center GUI. Both kinds of videos use Canonical URL service to set their URLs when they are created in Arc XP. If you want Canonical URL service to respect the pre-existing urls that you are assigning to your imported videos, then you will create a specific format rule that will look for the ANS key you’ve chosen to store these URL values. So, you need an ANS field that can store information that will identify only videos that have been migrated. For this, use the source.system ANS key.

{
  "source": {
    "system": "legacy-cms",
    "source_id": "legacy-video-identifier"
  }
}

Set the value of source.system to the name of the legacy CMS where the video was imported. Use the same value for all imported videos. If you are importing videos from multiple legacy CMSes and there is business value in storing the proper legacy CMS name with each imported video, you will need to create multiple format rules in Canonical URL service. You can save the value of the legacy CMS video identifier in source.source_id. This field is not necessary for the format rule; it’s just a generally sound practice. Both source fields are searchable in Content API.

Finally open the Canonical URL tile in your Arc XP Admin and enter a new format rule. The Criteria field will need to contain just the subset of unique fields and shared values that will identify the set of ANS documents to which this rule applies. The keys and values in the Criteria field should be shared, exactly as written, amongst all the ANS content that will get the URLs this rule describes in the Format field.

Here you see that the Criteria is narrowing down the ANS objects that will fall under this rule to only those that contain both type: video and source.system: legacy-cms. These ANS objects will also contain a websites.demo.website_url value, which will become the url for the video.

To create a rule that would apply to a different website, we would switch the active website in the Canonical URL admin and enter a similar rule, only changing the value of the Format e.g. %websites.arc_test1.website_url%. If we had opted to record the url value in the ANS under additional_properties instead of website, then we would reference that key in Format e.g. %additional_properties.website_url% or whichever key name we opted to use.

You may leave websites.{{siteid}}.website_url out of the ANS if you do not want to supply the video URL when you post the ANS. In this case, the URL will be created automatically using the URL Format Rules.

Supporting ALC Documentation

Draft API Endpoint To Generate Arc ID: `/draft/v1/arcuuid`
Canonical URL Service and Photo Center Integration (specific instructions are for Photo Center, but generally also applies to Video Center)
URL Format Rules (discusses Draft API, but also applies to Video Center)

How do I upload a local video file into Arc?

The API needs to use a url to import a video file. You cannot use the Video Center API to load a physical video from an external or local machine unless that machine has a way to provide a public url for the file. For example, you could upload the video to an S3 bucket on AWS that creates a public url, and then use that url in the ANS streams key.