Sakai Entity Broker methods – the missing documentation

An attempt to collect together some understandable documentation on how to use the Sakai (@Oxford Sakai=WebLearn) Entity Broker (EB) methods in the face of continued frustration with Sakai documentation accessed via /direct/describe (@Oxford

I’m only going to cover methods to return JSON  as that’s all we ever use and am not bothering to describe the format of the returned JSON as it’s easier just to look at what’s returned in the browser.

  • Announcement
  • Assignment
  • Content
  • Forums (including Topic, Thread and Message)
  • Group
  • Lesson
  • Lessons
  • Membership
  • Polls
  • Portal-hierarchy
  • User


Gets the announcements for a site for the logged in user.


e.g @Oxford


Gets the assignments for a site for the logged in user.


e.g @Oxford


Gets the contents of the Resources tool.



  • subFolderPath (optional) is the path a subfolder (path relative to root of Resources)
  • noOfSteps (optional) is the no of ‘layers’ of content to return (seems to have a maximum value of 3?). If not specified defaults to 1.

e.g @Oxford

forums (including topic, thread and message)

Get all fora for a site:


Get all topics for a forum:


Get all conversations for a topic:


Get a fully populated conversation or message. This retrieves the message tree from the specified message downwards. If the messsageId is the top level message in a conversation, the entire conversation is returned:

/direct/forums/site/siteId/forum/forumId/topic/topicId/message/messsageId .json

…and to link directly to individual parts of forums:

For direct forum link url is :


Direct forum_topic link is :


Direct link to individual message is :

/portal/hierarchytool/siteId/discussionForum/message/dfViewMessageDirect.jsf?messageId=messsageId &topicId=topicId&forumId=forumId


Get the membership of a group.


whee groupId can be found by looking at the address of the page when editing a group in Siet Info | Manage Subgroups – may also be possible to find by name with /direct/site methods?

e.g @Oxford


Get the contents of a lesson.


where lessonId is the id or entityId returned by direct/lessons (above)

e.g @Oxford


Get a list of the lessons in a site.


e.g @Oxford

Note that, in Sakai 11 at Oxford anyway, the lessons EB method will not currently (03/10/16) return lessons to access users – only those with elevated rights e.g for the same call:

As a maintainer:

{"entityPrefix": "lessons", "lessons_collection": [
    "contentsURL": "https:\/\/\/direct\/lessons\/lesson\/78676",
    "gradebookPoints": null,
    "id": 78676,
    "lessonTitle": "Module 1",
    "releaseDate": null,
    "hidden": false,
    "entityReference": "\/lessons\/78676",
    "entityURL": "https:\/\/\/direct\/lessons\/78676",
    "entityId": "78676"

As an access user:

{"entityPrefix": "lessons", "lessons_collection": [



Get information about membership of a given user in a given site



  • userId is the id (Sakai’s internal reference) of user about which you want info (obtainable for logged in user from user/current.json as below)
  • siteId  is the Sakai siteId.

e.g @Oxford


Can’t find any way to get a list of polls for a site!

Get poll text and options



  • pollId is the id (Sakai’s internal reference) of the poll. This is most easily obtained by hovering over the poll name in the edit view and picking out the number(!)
  • includeOptions (boolean) specifies whether to also return the options for the poll and;
  • includeVotes (boolean) specifies whether to also return the votes cast

e.g @Oxford

portal-hierarchy (maybe only @Oxford?)

Provides a list of all the sites (to which the user has access) under a given site – one level down only.


e.g @Oxford


Information about the logged-in user – mainly used to get interal Sakai id for use in other methods.


e.g @Oxford


I’ll try to remember to add to these as I use them.

One Reply to “Sakai Entity Broker methods – the missing documentation”

Leave a Reply

Your email address will not be published. Required fields are marked *