Publishing Changes to Lists - Talis Aspire APIs Documentation

Recipes :: Publishing Changes to Lists

Background

There are some situations when you might want to trigger a list to be published. Typically this would be after modifying a draft list to update its structure (moving or creating items, sections, notes, etc.) or after changing an item’s properties (such as changing the importance).

Changes to resources do not require a list publish event to make the changes live to students.

Please see the reading list lifecycle and items and resources articles which go into these concepts in more detail.

Different API routes for different reasons

You will see that there are a few different routes that reference publishing of lists in the APIs. It is important to note the reasons why each route exists. One set of routes is for end users who are making live edits to a list and need to see their changes quickly. The other is for API users who are content to have a list republished at some point in the near future, but don’t need to see the changes now.

createListPublishAction and getListPublishAction allow the list editor to send a request for publishing and to then find out later if the list has been updated. These list publish actions are created by real users who are using the list editor to make changes to lists.

Important: Developers should NOT be using the above routes to publish lists. This will block a publish queue for end users and cause your academic and library staff to experience a delay in publishing their lists.

The createBulkListPublishAction route allows you to supply a set of draft lists to apply changes to. These publish actions are added to a queue which will not interfere with end user publish actions. You can push as many draft lists as you need.

What can’t be published

Only draft lists can be published. This includes lists which are published and have unpublished changes. Archived lists cannot be subsequently republished. Please see the reading list lifecycle for more information on different states that a reading list can be in.

Queued updates

By submitting a request to the createBulkListPublishAction endpoint, you are submitting a list to a background processing queue. The background queue is designed to do the heavy lifting for a publish action which can often take many seconds to complete because there are a lot of things to be updated when you change a list. There may already be work on this queue for another tenant and so there is no guarantee that the queue will take the same time to complete each time.

Each time you submit a bulk list publish action a new job is added to the Talis Aspire Reading Lists Review Jobs admin page. If you submit many hundreds of jobs for individual lists you may cause yourself lots of scrolling to check them all if you need to check on progress.

You are advised to keep track of lists you have updated and submit a single bulk list publish job at the end of your script.

Using the `createBulkListPublishAction`

The createBulkPublishListAction technical documentation is found in the API docs

While you have a choice to either specify one list at a time, or submit a number of draft lists to be published, it is recommended to batch the lists into as many as you can at a time (see queued updates above).

A workflow in a script might have these stages.

Make a change to a number of draft lists.
Keep track of which draft lists you have changed within your script.

Create an array of draft lists to be published.

  [
      {
          "type": "draft_lists",
          "id": "978C4A74-C5F3-69EE-CEF6-F7E2B1109975"
      },
      {
          "type": "draft_lists",
          "id": "E8EE3371-B5BC-C092-9929-D311192A4671"
      }
  ]

Put that array within the request body as the data.relationships.draft_lists.data property.

an example post request body

  {
      "data": {
          "type": "bulk_list_publish_actions",
          "relationships": {
              "draft_lists": {
                  "data": [
                      {
                          "type": "draft_lists",
                          "id": "978C4A74-C5F3-69EE-CEF6-F7E2B1109975"
                      },
                      {
                          "type": "draft_lists",
                          "id": "E8EE3371-B5BC-C092-9929-D311192A4671"
                      }
                  ]
              }
          }
      }
  }