Get notified when Go1 content has been flagged for decommissioning, so you can provide alerts and remove content in your application.

Overview

This article explores how to utilise the Content Decommission Webhook to get notified when content has been flagged for removal from the Go1 library.

The Go1 library is continually evolving and being updated. On occasion, a Go1 content provider may mark their content for decommissioning when they can no longer offer this content.

When this occurs, the responsibility falls on you to let your users know that content will no longer be available after a certain date - giving them time to organise any learners currently enrolled in the content to complete it before it becomes unavailable. Additionally, it is your responsibility to prevent new enrolments in content that has been flagged for decommissioning and remove this content on the decommissioned date. Actioning content removals this way will ensure you provide a consistent experience for your users - and won't serve them content that has been removed.

How it works

To successfully set up and utilise the content decommission webhook, we'll walk through the following implementation steps below.

1. Creating the content_decommission webhook
2. Receiving the content_decommission event payloads
3. Actioning the content decommissioning in your application

How the content decommission webhook works

The content_decommission event is triggered when a content provider marks some of their content within the Go1 library for decommissioning. This often occurs when our content providers choose to retire or replace old content.

When content is flagged for decommissioning, a payload will be sent containing the ID of the content that has been flagged for decommissioning (see example payload below).

Any content that is flagged for decommissioning will be archived (removed) from the Go1 Library after a minimum of 60 days.

Note, during the 60 days, access to decommissioned content will be removed immediately for any new users who try to access the content. Users who are already enrolled in the content will still be able to access and complete the learning within the 60 day period - after which the content will be archived.

Example payload:

{
      "type": "content_decommission",
      "fired_at": "2020-06-17T00:24:40+0000",
      "data": {
        "id": "21911801",
        "title": "Communication Skills 101",
        "type": "course",
        "decommission_time": 1592353475,
        "remove_time": 1623889431
      }
}

It's important to note, that these notifications are ignorant of the content that you may have synced to your application - the events will fire for any content that is marked for decommissioning across the entire Go1 library regardless of if you have access to this content or not. It is your responsibility to identify if the notifications are relevant to the content your users have access to.

Preparation

Before setting up a webhook, you will need a establish a service in your application that can receive the webhook payload from Go1. As part of this process, your service will need a URL that will be used as the location for Go1 to send webhook events to. This URL location will be configured when you initially create the webhook via the Go1 API - more on this below.

Implementation steps

Step 1. Creating the content_decommission webhook

To create the content_decommission webhook, make a POST request to the https://api.go1.com/v2/webhooks, specifying the following values in the body:

• content_decommission, set this value to true, this tells Go1 which events this webhook would like to receive (you can enable multiple webhook events via this single webhook).
• URL, the URL location you wish Go1 to send event notifications to - must be a valid URL.
• (optional) secret_key, a secret string of our choice, used for security purposes, learn more here.

Here is an example request (see the API Reference: POST /v2/webhooks):

A successful response will return the created webhook ID. The webhook ID can be used later to view, update or delete the webhook - see the Webhook API reference to learn more about these functions.

With the webhook created, you are now ready to receive payload events to the URL you have configured.

Step 2. Receiving the content_decommission event payloads

When content is flagged for decommissioning by a content partner, Go1 will trigger a content_decommission event that will be sent to your configured webhook URL. The payload will contain the details for the content (learning object) that has been decommissioned.

Within the payload, make note of the following attributes:

• type: content_decommission, is the type of event that’s fired. Remember, a single webhook may have multiple events enabled.
• id, is the id of the Learning Object that has been decommissioned.
• title, is the Learning Object title
• type, is the content type (eg. course, video, document, etc).
• decommission_time, is the UNIX timestamp for when the Learning Object was flagged for decommission
• remove_time, is a UNIX timestamp for when the Learning Object will no longer be available - typically 60 days from the decomission_time.
  

Step 3. Actioning the content decommissioning in your application

Utilising the content decommission notification to action content removals within your application is key to providing your users with a consistent user experience within the content you provide access to. To enable the best user experience for your customers and users, we recommend that you implement the following actions when you receive a payload from Go1 that content is being decommissioned:

• Provide a notification to your customers and users, notifying them that the content has now been archived and will no longer be available.
• Prevent any new users from enrolling in the decommissioned content.
• Implementing a method to automatically remove this content from your application on the decommissioned date.

Learn more

• API Reference - POST /v2/webhooks
• Full API Reference