Tag: EB

Posted on

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.