Skip to main content

How to bulk recirculate articles using a script and the Draft API

Summary

When looking to update the circulations on hundreds or thousands of published articles, manual updates through the UI are impractical. How can recirculations be achieved programmatically?

Procedure

Write a script that operates on a subset of your content that needs to be recirculated and applies the following steps.  Before you begin, make sure you know what the new circulation target(s) will be and you have constructed the new circulation JSON structure. The script outlined below describes use of the bulk circulation Draft API endpoint, and so the JSON payload would be an array of circulation objects. 

  1. Query Content API for a subset of articles. This subset can be as small or as large as is manageable for your needs. Ideally, the query will return content items that all require the same circulation changes.  Alternatively you can build the script to accept script arguments that can adjust the transformations that are made to create the new target circulations.

  2. Loop over the query results.

  3. Prepare the new target circulation JSON payload that will be next associated with the story.

    [
    {
        "website_id": "{website_id}",
        "website_url": "/url-with-ending-slash/", #optional. if not included url will be generated by URL format rules
        "website_primary_section": {
            "type": "reference",
            "referent": {
                "type": "section",
                "id": "{section_id}",
                "website": "{website_id}"
            }
        },
        "website_sections": [
            {
                "type": "reference",
                "referent": {
                    "type": "section",
                    "id": "{section_id}",
                    "website": "{website_id}"
                }
            }
        ]
    },
    {
        "website_id": "{website_id}",
        "website_url": "/url-with-ending-slash/", #optional. if not included url will be generated by URL format rules
        "website_primary_section": {
            "type": "reference",
            "referent": {
                "type": "section",
                "id": "{section_id}",
                "website": "{website_id}"
            }
        },
        "website_sections": [
            {
                "type": "reference",
                "referent": {
                    "type": "section",
                    "id": "{section_id}",
                    "website": "{website_id}"
                }
            }
        ]
    }
]

  4. Apply the bulk decirculate Draft API endpoint to the current item in the loop of query results /draft/v1/story/{story id}/bulk-circulation?website={site id}.  This will remove all attached circulations to the story. 

    curl --request DELETE \
  --url 'https://api.{{org}}.arcpublishing.com/draft/v1/story/{{story_id}}/bulk-circulation?website={{site_id}}' \
  --header 'Authorization: Bearer {{token}}'

  5. Apply the bulk circulate Draft API endpoint to the current item in the query results, using the new target circulation JSON payload /draft/v1/story/{story id}/bulk-circulation.  This will attach the new circulations to the story 

    curl --request PUT \
  --url 'https://api.{{org}}.arcpublishing.com/draft/v1/story/{{story_id}}/bulk-circulation' \
  --header 'Authorization: Bearer {{token}}' \
  --data '[{{circulation JSON objects}}]'

  6. Apply the publish Draft API endpoint to the current item in the query results.  This will publish the item, making your new circulation change active /draft/v1/story/{story id}/revision/published/.

    curl --request POST \
  --url 'https://api.{{org}}.arcpublishing.com/draft/v1/story/{{story_id}}/revision/published?regenerate=true&collision_behavior=increment' \
  --header 'Authorization: Bearer {{token}}'

Be aware of your Draft API rate limits.  The above plan will require three hits to the Draft API. You should ensure that each iteration goes no faster than 1 per second if your Draft API rate limit is at the default of 4 r/s.

More Information

In this section: