How to Override Display and Publish Dates in a Document

The purpose of this guide is to demonstrate how to set the display_date or publish_date of a document.

Requirements

If you haven’t already done so, read Getting Started with the Draft API.

This guide assumes that:

You have already created a document.
The document is circulated to 1 website.
You want to publish the document with a pre-defined date
You are familiar with the basic usage of the API (HTTP, Auth, etc).

Use Cases

There are many different date fields available in Arc XP which all serve different purposes. (For a refresher on all of the available fields, see the documentation How ANS date fields are set when publishing documents).

This guide will be focusing on the two date fields that can be overridden in the Arc XP APIs to be set to a user-generated value rather than an automatic one -- display_date and publish_date.

The key difference between overriding display_date and publish_date is that display_date will remain overridden with the value you choose until you choose a new value or unpublish the document. publish_date will default to the current time on each new publish, even if you’ve previously overridden it.

For most use cases where a user-set date is required, we recommend the usage of display_date. display_date can hold any user-set timestamp, and, once set, does not need to be updated again and again.

publish_date, on the other hand, must be overridden each time a user-set value is desired. This makes overriding publish_date ideal for scenarios where you would normally want a date to be updated automatically except for a particular revision. For the most part, that falls into two major workflows:

1. Historical Content

When moving content into Arc XP, you may have content that was published in the past. For these stories, you want to ensure that the publish_date remains unchanged as it is migrated into a new system.

2. Hidden Updates

Often, we use publish_date as the date that is exposed to viewers on your site. In the event that an update is made to the story, this date would be updated. If an update is made to your story that does not warrant a timestamp update to the viewer, you can use the publish_date field to ensure it does not change.

As a reminder, there are many different date fields available in Arc XP. See How ANS date fields are set when publishing documents. publish_date is intended to reflect any major updates to the document, and is meant to be updated with each publish. If your document has a date associated with it that should never change, consider using display_date for that purpose.

Setting the `display_date` Field

Let’s assume we already have a document created, for which we want a user-set, static display date. First, let’s look at the document:

  --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/VV3QREASU5FGXI3HJ3ECUMWNRU

#RESPONSE
{
    "id": "VV3QREASU5FGXI3HJ3ECUMWNRU",
    "type": "STORY",
    "created_at": "2020-05-28T20:02:05.136Z",
    "draft_revision_id": "U2OSKRMWFRH7VMNMAFKK5P5HEQ"
}

In order to update the display_date, we need to create a new draft revision that holds the date. To do that:

curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/VV3QREASU5FGXI3HJ3ECUMWNRU/revision/draft \
  --data '{
        "ans": {
            "_id": "VV3QREASU5FGXI3HJ3ECUMWNRU",
            "type": "story",
            "version": "0.10.5",
            "canonical_website": "the-herald",
            "headlines": {
                "basic": "Wow, Did You Hear About Thing!?"
            },
            "display_date":"1994-07-19T15:47:52.747Z"
        }
    }'


# RESPONSE
{
    "id": "UY5JW35BMFF3THE42JMFC2RPZY",
    "document_id": "VV3QREASU5FGXI3HJ3ECUMWNRU",
    "ans": {
        "additional_properties": {
            "has_published_copy": false
        },
        "canonical_website": "the-herald",
        "created_date": "2020-05-28T20:04:43.564Z",
        "display_date": "1994-07-19T15:47:52.747Z", 
        "headlines": {
            "basic": "That Thing Happened at that Place."
        },
        "last_updated_date": "2020-05-28T20:04:43.564Z",
        "owner": {
            "id": "staging"
        },
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-05-28T20:04:43.564Z",
    "type": "DRAFT"
}

Now that the field has been set, we can use the normal publish endpoints to publish our document:

curl --request POST \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/VV3QREASU5FGXI3HJ3ECUMWNRU/revision/published
  
# RESPONSE
{
    "id": "IQ3XZ4FXM5AETBHUI3TVE6IM2M",
    "document_id": "VV3QREASU5FGXI3HJ3ECUMWNRU",
    "ans": {
        "additional_properties": {
            "has_published_copy": false
        },
        "canonical_website": "the-herald",
        "created_date": "2020-05-28T20:06:22.416Z",
        "display_date": "1994-07-19T15:47:52.747Z",
        "first_publish_date": "2020-05-28T20:06:22.519Z",
        "headlines": {
            "basic": "That Thing Happened at that Place."
        },
        "last_updated_date": "2020-05-28T20:06:22.416Z",
        "publish_date": "2020-05-28T20:06:22.519Z",
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-05-28T20:06:22.416Z",
    "type": "PUBLISHED"
}

And done. We can now see that the display_date has been set in our published revision.

Updating the `publish_date` Field

Let's start fresh with a new document, U56T47XH3RGY7IOEFJ5AZX2ZNE. Let's take a look at the document:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE

# RESPONSE
{
    "id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
    "type": "STORY",
    "created_at": "2020-05-28T19:52:31.603Z",
    "draft_revision_id": "PQA6ZS4J5VHFNIP5PDW5MCV6U4"
}

Now, let’s get ready to publish our story. To do this with an auto-generated date, we would normally make a call to the publish endpoint:

curl --request POST \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE/revision/published

However, since we want a date set within the document, we need to first update the document’s Draft Revision with the desired publish_date, as below:

curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE/revision/draft \
  --data '{
        "ans": {
            "_id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
            "type": "story",
            "version": "0.10.5",
            "canonical_website": "the-herald",
            "headlines": {
                "basic": "Wow, Did You Hear About Thing!?"
            },
            "publish_date":"2020-01-01T15:47:52.747Z" 
        }
    }'


# RESPONSE

{
    "id": "LAN244JWOZDLNJV36CALBGTKQM",
    "document_id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
    "ans": {
        "additional_properties": {
            "has_published_copy": false
        },
        "canonical_website": "the-herald",
        "created_date": "2020-05-28T19:54:49.804Z",
        "headlines": {
            "basic": "Wow, Did You Hear About Thing!?"
        },
        "last_updated_date": "2020-05-28T19:54:49.804Z",
        "owner": {
            "id": "staging"
        },
        "publish_date": "2020-01-01T15:47:52.747Z", 
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-05-28T19:54:49.804Z",
    "type": "DRAFT"
}

As we can see here, we’re now returned the publish_date field as a part of the document ANS. We can now publish as we normally would.

curl --request POST \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE/revision/published
  
# RESPONSE
{
    "id": "PLIR5GK2AVEONEQ6ZQQGIVIKLI",
    "document_id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
    "ans": {
        "additional_properties": {
            "has_published_copy": false
        },
        "canonical_website": "the-herald",
        "created_date": "2020-05-28T19:55:38.359Z",
        "display_date": "2020-01-01T15:47:52.747Z", 
        "first_publish_date": "2020-05-28T19:55:38.449Z",
        "headlines": {
            "basic": "Wow, Did You Hear About Thing!?"
        },
        "last_updated_date": "2020-05-28T19:55:38.359Z",
         "publish_date": "2020-01-01T15:47:52.747Z", 
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-05-28T19:55:38.359Z",
    "type": "PUBLISHED"
}

In this response, you’ll see that, even though we only set publish_date, display_date has been updated as well. Since display_date needs to be set for some Content API implementations, and no value was user-provided, display_date will default to the same as your publish_date.

The Differences Between Display Date and Publish Date

The major different between publish_date and display_date is that overriding publish_date only applies to that specific revision. When Draft API publishes the revision, it creates a new PUBLISHED revision with those dates, and then creates a new DRAFT revision that will become the new “working” revision of the document.

First, let’s find our new DRAFT revision ID:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE
  
# RESPONSE
{
    "id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
    "type": "STORY",
    "created_at": "2020-05-28T19:52:31.603Z",
    "first_published_at": "2020-05-28T19:55:38.449Z",
    "last_published_at": "2020-05-28T19:55:38.449Z",
    "draft_revision_id": "UMLB424OHZDLXCBJHIM2KT7YJQ",
    "published_revision_id": "PLIR5GK2AVEONEQ6ZQQGIVIKLI"
}

And now, we can get the latest DRAFT revision:

curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/U56T47XH3RGY7IOEFJ5AZX2ZNE/revision/UMLB424OHZDLXCBJHIM2KT7YJQ
  
# RESPONSE
{
    "id": "UMLB424OHZDLXCBJHIM2KT7YJQ",
    "document_id": "U56T47XH3RGY7IOEFJ5AZX2ZNE",
    "ans": {
        "additional_properties": {
            "has_published_copy": false
        },
        "canonical_website": "the-herald",
        "created_date": "2020-05-28T19:55:38.415Z",
        "headlines": {
            "basic": "Wow, Did You Hear About Thing!?"
        },
        "last_updated_date": "2020-05-28T19:55:38.415Z",
        "owner": {
            "id": "staging"
        },
        "type": "story",
        "version": "0.10.5"
    },
    "created_at": "2020-05-28T19:55:38.415Z",
    "type": "DRAFT"
}

In this new DRAFT revision, we can see that publish_date is no longer in the revision! If we were to now make a change to the headline and republish, the new PUBLISHED revision will now reflect a current timestamp.

Finding `publish_date` and `display_date` in Content API

In order to now use our overridden publish_date field, we need to know how to access it through Content API. To do that, we can use Content API to request our story specifically:

curl --request POST \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/content/v4?_id=WP43G2QWL5HFTHLPBJXJHNMRZM&website=the-herald
  
# RESPONSE
...
publish_date: "2020-01-01T15:47:52.747Z",
...

Here, we can see that the new publish_date and display_date can be found in the Content API response.

Summing it up

1. We learned different use cases for using display_date and publish_date

2. We successfully set display_date using Draft API.

3. And we successfully overrode publish_date using Draft API.

In this section:

How to Override Display and Publish Dates in a Document

Requirements

Use Cases

Setting the display_date Field

Updating the publish_date Field

The Differences Between Display Date and Publish Date

Finding publish_date and display_date in Content API

Summing it up

Search results

Setting the `display_date` Field

Updating the `publish_date` Field

Finding `publish_date` and `display_date` in Content API