Developer Platform (November 2024)

News service (news items, user feed)

«  Discussions (forums, topics, posts)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Calendar (Events and scheduling)  »

Attributes

Feed.UserFeedResource

The feed service returns generically formed blocks that wrap around particular kinds of resources. For example, a UserFeedResourceNewsItem variant of the generic container contains a Resource composite that’s actually a NewsItem structure.

{
    "Type": <string>,
    "MessageMetaData": {
        "Identifier": <string>,
        "Title": <string>,
        "Summary": { <composite:RichText> },
        "Date": <string:UTCDateTime>,
        "ApiViewUrl": <string:URL>,
        "WebViewUrl": <string:URL>
    },
    "Resource": { <composite> }  // Generic resource composite wrapper
}
News.NewsFeed

If you use an action that retrieves a news feed from the service, it sends the data back to you in a block like this:

{
    "OrgUnitId": <numeric:D2LID>,
    "Resource": { <composite:News.NewsItem> }
}
News.NewsItem

If you use an action that retrieves a news item from the service, it sends the data back to you in a block like this:

{
    "Id": <number:D2LID>,
    "IsHidden": <boolean>,
    "Attachments": [ // Array of File blocks
        {
            "FileId": <number:D2LID>,
            "FileName": <string>,
            "FileSize": <number>
        },
        { <composite:File> }, ...
    ],
    "Title": <string>,
    "Body": { <composite:RichText> },
    "CreatedBy": <number:D2LID>|null,
    "CreatedDate": <string:UTCDateTime>|null,
    "LastModifiedBy": <number:D2LID>|null,
    "LastModifiedDate": <string:UTCDateTime>|null,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "IsGlobal": <boolean>,
    "IsPublished": <boolean>,
    "ShowOnlyInCourseOfferings": <boolean>,
    "IsAuthorInfoShown": <boolean>,
    "IsPinned": <boolean>,  // Added with LE API v1.72
    "PinnedDate": <string:UTCDateTime>|null,  // Added with LE API v1.81
    "IsStartDateShown": <boolean>,  // Added with LE API v1.75
    "SortOrder": <number>  // Added with LE API v1.75
}
News.NewsItemData

If you use an action where you must provide news item data, then the service expects you to send it in a block like this:

{
    "Title": <string>,
    "Body": { <composite:RichText> },
    "StartDate": <string:UTCDateTime>,
    "EndDate": <string:UTCDateTime>|null,
    "IsGlobal": <boolean>,
    "IsPublished": <boolean>,
    "ShowOnlyInCourseOfferings": <boolean>,
    "IsAuthorInfoShown": <boolean>,
    "IsPinned": <boolean>,  // Added with LE API v1.72
    "IsStartDateShown": <boolean>,  // Added with LE API v1.75
    "SortOrder": <number>|null // Added with LE API v1.75
}

Note

When you provide a RichText composite Body in a NewsItemData structure, you should not provide an empty-string “Html” property field if your intention is to provide a text-only news body. Rather, you should pass in an explicit NULL for the field.

Actions

DELETE /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Delete a particular news item from an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)

Delete an attachment from an org unit’s news item.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

  • fileId (D2LID) – File attachment ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

GET /d2l/api/lp/(version)/feed/

Fetch the feed for the current user context.

Parameters:
Query Parameters:

  • since (UTCDateTime) – Optional. Earliest publication time to retrieve.

  • until (UTCDateTime) – Optional. Latest publication time to retrieve.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.4.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

This call retrieves and aggregates a list of user messages gathered from various sources in the back-end service. The original sources for those messages determine when a user event message gets made available for aggregation, and when the events expire from the pool available to this API call.

Note that, unlike many Brightspace APIs, there is currently no direct functional equivalent for this API call in the web UI.

Input. This route accepts two query parameters (since and until) to specify a time window for retrieved results:

  • If you do not provide a since value, this call returns only a list of “recent” feed items: those with a publication time sometime within the twenty-four hours preceding the time when the back-end service handles your call.

  • If you provide a since value, and do not provide an until value, this call returns all the feed items from your provided since time up until the time when the back-end service handles your call.

  • If you provide a since value, and do provide an until value, this call returns all the feed items between your two provided time parameters. Note that, if your since parameter is more recent than your until parameter, this action returns success and an empty feed list.

Return. This action returns a JSON array of UserFeedResource data blocks. Note that each element in this list will be named appropriately for the kind of resource it envelopes.

GET /d2l/api/le/(version)/news/user/(userId)/

Retrieve a list of news items for specific user.

Parameters:
Query Parameters:

  • since (UTCDateTime) – Optional. Earliest publication time to retrieve.

  • until (UTCDateTime) – Optional. Latest publication time to retrieve.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a paged result set containing the resulting NewsFeed blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

GET /d2l/api/le/(version)/(orgUnitId)/news/

Retrieve a list of news items for an org unit.

Parameters:
Query Parameters:

  • since (UTCDateTime) – Optional. Earliest publication time to retrieve.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of NewsItem data blocks containing news items’ properties.

GET /d2l/api/le/(version)/(orgUnitId)/news/deleted/
Parameters:
Query Parameters:

  • global (boolean) – Optional. Show only global news items if present and true; otherwise, show no global items.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.2.

Return. This action returns a JSON array of NewsItem data blocks containing the properties of deleted news items. Note that this action will also retrieve deleted news item that have the IsHidden property set to true.

GET /d2l/api/le/(version)/(orgUnitId)/news/user/(userId)/

Retrieve a list of news items from an org unit for specific user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • userId (D2LID) – User ID.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a JSON array of NewsItem data blocks containing news items’ properties.

Note

This action is subject to user privacy controls. The calling user context must belong to a role granted permission to see all user fields via User Information Privacy.

GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Retrieve a particular news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a NewsItem JSON data block containing the news item’s properties.

GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/access/

Retrieve a list of users with access to a specified news item.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Query Parameters:

  • userId (D2LID) – Optional. Retrieve access for a single user.

  • roleId (D2LID) – Optional. Retrieve access for users with the given role.

Oauth2 Scopes:

news:access:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a paged result set containing the resulting UserAccess blocks for the segment following your bookmark parameter (or the first segment if that parameter is empty or missing).

GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)

Retrieve an attachment for an org unit’s news item.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

  • fileId (D2LID) – File attachment ID.

Oauth2 Scopes:

news:newsitems:read

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Return. This action returns a file stream containing the attachment file data.

POST /d2l/api/le/(version)/(orgUnitId)/news/

Create a news item for an org unit.

Parameters:
JSON Parameters:

  • NewsItemData (News.NewsItemData) – Data for new news item (see input description).

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Input. Provide a multipart/mixed POST body: the first part must be the news item data JSON; other parts may include file attachments to go along with the news item.

If you want to create a new item as a draft, make sure to set the news item’s IsPublished property to false. In order to publish such a created news item, you must then use the Publish action.

The calling user must have permission to manage author information to use this action.

Return. Returns a NewsItem JSON data block for the newly created news item.

POST /d2l/api/le/(version)/(orgUnitId)/news/deleted/(newsItemId)/restore
Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • unstable – Route first appears in LMS v10.5.2.

Return. Returns a NewsItem JSON data block for the newly restored news item.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/

Add an attachment to a news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Input. Use a multipart/form-data POST body to provide the attachment data to add to the news item, with the part’s Content-Disposition header’s name field set to “file”.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/dismiss

Dismiss (hide) a news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/publish

Publish a draft news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/restore

Restore (unhide) a news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Update a news item for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • newsItemId (D2LID) – News Item ID.

JSON Parameters:
Oauth2 Scopes:

news:newsitems:manage

Status Codes:
API Versions:

  • 1.67+ – Route first appears in LMS v20.23.1.

  • 1.61-66 – Deprecated as of LMS v20.24.1.

  • 1.60- – Obsolete as of LMS v20.24.1.

Input. The calling user must have permission to manage author information to use this action.

Note

If the org unit’s news item has already been published, then you may not provide an update with the IsPublished property set to false (i.e. once an item is no longer a draft item, you can’t turn it back into a draft item). However, if the org unit’s news item is in draft state, you can publish it with this action by setting the IsPublished property to true.

«  Discussions (forums, topics, posts)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Calendar (Events and scheduling)  »