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 https://www.weblearn.ox.ac.uk/direct/describe).

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

announcement

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

/direct/announcement/site/siteId.json

e.g @Oxford

https://weblearn.ox.ac.uk/direct/announcement/site/d1506490-a468-46ca-a915-417d9d11be2f.json

assignment

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

/direct/assignment/site/siteId.json

e.g @Oxford

https://weblearn.ox.ac.uk/direct/assignment/site/d1506490-a468-46ca-a915-417d9d11be2f.json

content

Gets the contents of the Resources tool.

/direct/content/resources/group/siteId[/subFolderPath].json[?depth=noOfSteps]

where:

  • 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

https://weblearn.ox.ac.uk/direct/content/resources/group/1e969f60-9ebf-48b7-bb0f-54f598de05da/Online%20assessments%20documents.json?depth=2

forums (including topic, thread and message)

Get all fora for a site:

/direct/forums/site/siteId.json

Get all topics for a forum:

/direct/forums/site/siteId/forum/forumId.json

Get all conversations for a topic:

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

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 :

/portal/hierarchytool/siteId/discussionForum/forum/dfForumDirect.jsf?forumId=forumId

Direct forum_topic link is :

/portal/hierarchytool/siteId/discussionForum/message/dfAllMessagesDirect.jsf?topicId=topicId

Direct link to individual message is :

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

group

Get the membership of a group.

/direct/membership/group/groupId.json

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

https://weblearn.ox.ac.uk/direct/membership/group/8513fad8-656f-4265-9573-f00b8a781d02.json

lesson

Get the contents of a lesson.

/direct/lessons/lesson/lessonId.json

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

e.g @Oxford

https://weblearn.ox.ac.uk/direct/lessons/lesson/35538.json

lessons

Get a list of the lessons in a site.

/direct/lessons/site/siteId.json

e.g @Oxford

https://weblearn.ox.ac.uk/direct/lessons/site/1e969f60-9ebf-48b7-bb0f-54f598de05da.json

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:\/\/weblearn.ox.ac.uk\/direct\/lessons\/lesson\/78676",
    "gradebookPoints": null,
    "id": 78676,
    "lessonTitle": "Module 1",
    "releaseDate": null,
    "hidden": false,
    "entityReference": "\/lessons\/78676",
    "entityURL": "https:\/\/weblearn.ox.ac.uk\/direct\/lessons\/78676",
    "entityId": "78676"
    }
]}

As an access user:

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

]}

membership

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

/direct/membership/userId::site:siteId.json

where:

  • 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

https://weblearn.ox.ac.uk/direct/membership/d00ca345-4e31-485c-00e9-0fc880da2dc0::site:d1506490-a468-46ca-a915-417d9d11be2f.json

polls

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

Get poll text and options

/direct/polls/pollId/poll-view.json?includeOptions=true

where:

  • 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

https://weblearn.ox.ac.uk/direct/polls/pollId/poll-view.json?includeOptions=true

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.

/direct/portal-hierarchy/site.json?portalpath=pathFromRoot

e.g @Oxford

https://weblearn.ox.ac.uk/direct/portal-hierarchy/site.json?portalpath=/medsci

user

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

/direct/user/current.json

e.g @Oxford

https://weblearn.ox.ac.uk/direct/user/current.json

more..

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

Migrating MedLearn to Moodle

Medical Sciences Division hosts its teaching material in a system called MedLearn. The pages are mixed with 2D and 3D images, video, interactive content and self test questions.

For 10 years we’ve used Magnolia CMS. It was a good, simple system. In the last 4 years they’ve released 5.x.x which requires significant effort to migrate. We tried to find an upgrade path but couldn’t without spending more than our budget. Staying on the 4.x.x branch was fine until a recent Java security changed stopped us from publishing new pages. We have decided to migrate.

There are plenty of CMS and VLEs to choose from but they need to be maintainable and free. We chose Moodle because it’s free, extensible and fits with our technology strategy. We were particularly happy with the variety of questions available through the Question Bank.

Moodle doesn’t really support our mix of teaching materials with self test question. The Book module provides a good structure for the teaching material; the Quiz Activity provides assessment. We wanted to mix these together. Lesson tool was discounted because the questions are too restrictive, the authoring is confusing and the questions are on separate pages

We think that we’ve found the solution with the Generico filter plugin and its accompanying Atto plugin. The filter will write in an iFrame showing a preview of the question. In due course we may change it to call Javascript which writes preview content into the page. All that’s missing is a method of browsing the Question Bank.