Developer Platform (October 2019)

ePortfolio Objects

«  Learning Repository objects   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Artifacts  »

Contents

Attributes

Context chain

Sometimes actions provided by the EP object service can operate upon objects within a particular EP context: that is an EP object can be visible within the context of another EP object, which can be visible within the context of yet another object. You can envision this structure as a tree where each object is a node in the tree, within the context of parentage all the way back to a root object that you as an EP user have ownership or direct permissions upon.

The context chain for an object is the linear (inclusive) list of nodes between an object all the way back to this root object, and is typically expressed as a comma-separated list.

EPASSOC_T

Two kinds of EP objects can support association: Reflections, and Learning Objectives. We use the term EPASSOC_T to stand in for an appropriate identifying integer value.

Object association type

Value

Reflection

1

LearningObjective

2

EPOBJ_T

EP objects provide a generic data structure base from which a number of specific forms derive. In EpObject blocks, the ObjectTypeId property encodes the specific type of the data structure, as an integer value. In this reference we use the term EPOBJ_T to stand in for an appropriate integer value.

Object type

Value

EpObject

0

Collection

100

StaticCollection

110

DynamicCollection

120

Reflection

200

Artifact

300

FileArtifact

310

FormArtifact

320

LEArtifact

330

LECompetencyArtifact

331

LEGradeArtifact

332

LEQuizArtifact

333

LEDropboxArtifact

334

UrlArtifact

340

Presentation

400

LearningObjective

600

OBJRIGHT_T

The rights that EP users can be granted on an EP object when it is shared to them; the rights are organized into a discrete list of rights. We use the term OBJRIGHT_T to stand in for an appropriate integer value.

Object right type

Value

View

1

SeeComments

2

AddComments

3

ViewAssessments

4

AddAssessments

5

Edit

6

PERMPROFILE_T

Permission profiles are organized into several general groups. We use the term PERMPROFILE_T to stand in for an appropriate integer value.

Permission profile type

Value

Container

1

OrgUnit

2

Individual

3

THUMBSZ

The EP service supports thumbnailing of objects, at several preset sizes. We use the term THUMBSZ to stand in for an appropriate integer value.

Thumbnail size

Value

ReallySmall

24

Small

36

Medium

50

Large

300

ReallyLarge

800

EP.EpObject

Create. When you use actions that provide EP object data to the service, you should provide a block that looks like this:

{
    "ObjectId": <number:D2LID>,
    "Name": <string>,
    "Description": <string>,
    "Tags": [ <EP.TagObject>, ... ],
    "GeoTag": { <composite:EP.GeoTag> },
    "AllowComments": <boolean>
}

Warning

You should never seek to modify the ObjectId property of an EP object once the service has established it; rather, if you use an action to update an EP object, you should just reflect back the ObjectId value provided to you by the service for the object in the first place.

However, when you use an action to create a new EP object (and the service hasn’t yet given you an ObjectId you can use), you should be sure to set the ObjectId property to zero ("ObjectId":0) to indicate to the service that you want it to create a new object and allocate a new ID.

Fetch. When you use actions that retrieve EP object data, the service provides a block like this:

{
    "ObjectId": <number:D2LID>,
    "Name": <string>,
    "Description": <string>,
    "UserId": <number:D2LID>,
    "ObjectTypeId": <number:EPOBJ_T>,
    "ViewLink": <string>,
    "CommentsCount": <number>,
    "HasUnreadComments": <boolean>,
    "Tags": [ <EP.TagObject>, ... ],
    "Comments": [ <EP.ObjectComment>, ... ],
    "Created": <string:UTCDateTime>|null,
    "Modified": <string:UTCDateTime>|null,
    "GeoTag": { <composite:EP.GeoTag> },
    "AllowComments": <boolean>,
    "Permissions": [ <number:OBJRIGHT_T>, ... ]
}
Permissions

If this property is present, it contains an array of object right type values to encapsulate the permissions granted to EP users when the object gets shared to them.

EP.ObjectComment
{
    "CommentId": <number:D2LID>,
    "UserId": <number:D2LID>|null,
    "FirstName": <string>,
    "LastName": <string>,
    "CommentBody": <string>,
    "CreatedDate": <string:UTCDateTime>,
    "CommentedObjectId": <number:D2LID>,
    "ContextObjectId": <number:D2LID>|null,
    "ContextObjectTypeId": <number>|null
}
ContextObjectTypeId

When it appears, this value is a simplified version of an EPOBJ_T value. It can have a value of 0 (for a generic EP object) or one of the EPOBJ_T values evenly divisible by 100 (that is, the values for Collection, Reflection, Artifact, Presentation, Learning Objective). It can also have a value of 5 indicating an EP Form.

EP.GeoTag

The GeoTag object gets used to encode the geo-tagging information to describe the real-world location associated with an EP object.

{
    "Latitude": <number>,
    "Longitude": <number>,
    "Altitude": <number>|null,
    "Bearing": <number>|null,
    "Precision": <number>|null
}

Note

All the properties in a GeoTag structure get interpreted by the service as a C# decimal numeric type, that is, a high-precision, small-range floating point value.

EP.UserObject
{
    "UserId": <number:D2LID>,
    "FirstName": <string>,
    "LastName": <string>
}
EP.Share
{
    "ProfileId": <number:D2LID>,
    "Id": <number:D2LID>,
    "Type": <number:PERMPROFILE_T>,
    "Name": <string>,
    "Permissions": [ <number:OBJRIGHT_T>, ... ]
}
ProfileId

Profile identifier for the EP sharing group (note that this is not the same thing as a Brightspace user’s ProfileId for the user profile).

Id

System identifier for the share target (i.e. UserId if the target is a user)

Permissions

If present, an array of object right type values to encapsulate the permissions granted to the user being shared to.

EP.ShareTarget
{
    "Id": <number:D2LID>,
    "TargetId": <number:D2LID>,
    "Name": <string>,
    "ProfileType": <number:PERMPROFILE_T>
}
Id

Identifier for the EP sharing group.

TargetId

System identifier for the share target (i.e. UserID if the target is a user).

Object query filters

The actions provided by the EP object service allow you to set a complex query filter string to narrow the number of elements in the returned result set. An object query filter consists of one or more simple relational expressions chained together with the .AND. and .OR. conjunctive operators. Each simple relational expression tests a single property against a value with a relational operator.

Property

Operators

Test against…

type

=, !=

Type of the object

id

=

Object ID

user

=, !=

ID for the user owning the object

name

=, ^, ^^

Object name string

desc

=, ^, ^^

Object description string

created

=, >, <, >=, <=

Date object was created (in ISO 8601 forma

modified

=, >, <, >=, <=

Date object was last modified (in ISO 8601 format)

^

Produces true if the L-value property starts with the R-value string.

^^

Produces true if the R-value string occurs somewhere within the L-value property.

type

Filters can only sift on type at a granularity of basic EP object types (that is, collections, reflections, artifacts, and presentations – those with a type value evenly divisible by 100). If you use a type expression to specify any derived type, the filter will select for its associated basic type and any objects derived from it (for example, if you provide ?q="type=110", this will fetch all objects of type 100, 110, or 120).

Example. If you want to select for all results shared to user ID 2046 but created after 20 May, 2004: ?q="user=2046.AND.created>=2004-05-20".

Actions

GET /d2l/api/eP/(version)/object

Retrieve an EP object using a context chain of object IDs.

Parameters
Query Parameters
  • context (Context chain) – Context chain of object IDs to follow to find the EP object.

  • c (boolean) – Optional. If “true”, include any comments attached to the object.

Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a EpObject JSON data block containing the properties of your identified EP object.

GET /d2l/api/eP/(version)/object/content

Retrieves the associated resource for an EP object (identified by a provided context chain of object ID).

Parameters
Query Parameters
  • context (Context chain) – Context chain of object IDs to follow to find the EP object.

Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a file stream containing the contents of the identified EP object’s associated resource.

GET /d2l/api/eP/(version)/object/thumbnail

Retrieves a thumbnail of the associated resource for an EP object (identified by a provided context chain of object IDs).

Parameters
Query Parameters
  • context (Context chain) – Context chain of object IDs to follow to find the EP object.

  • size (THUMBSZ) – Thumbnail size to generate.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid thumbnail size parameter provided.

  • 403 Forbidden – No permission to see EP object.

  • 404 Not Found – EP object not found, or EP object resource’s format does not support thumbnailing.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a file stream containing a thumbnail of the contents of the identified EP object’s associated resource.

Note

For the size query parameter, you can provide either the name, or value, of a supported THUMBSZ type (i.e. “Medium”, or “50”, and so forth).

GET /d2l/api/eP/(version)/object/(objectId)

Retrieve an EP object by ID.

Parameters
Query Parameters
  • c (boolean) – Optional. If “true”, include any comments attached to the object.

Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a EpObject JSON data block containing the properties of your identified EP object.

GET /d2l/api/eP/(version)/object/(objectId)/associations/

Retrieve the list of EP objects associated with a particular EP object.

Parameters
  • version – API version.

  • objectId (D2LID) – EP object ID.

Query Parameters
  • type (EPASSOC_T) – Optional. Assocation type to act as a filter.

Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a paged result set containing, in a single page, the resulting EpObject data blocks associated with the identified EP object. Use the type query parameter to control the kind of EP associations to retrieve.

GET /d2l/api/eP/(version)/object/(objectId)/content

Retrieves the associated resource for an EP object (identified by object ID).

Parameters
Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a file stream containing the contents of the identified EP object’s associated resource.

GET /d2l/api/eP/(version)/objects/my/

Retrieve all the EP objects owned by the current user context.

Parameters
Query Parameters
  • c (boolean) – Optional. If “true”, include any comments attached to the object.

  • q (string) – Optional. Query filter expression to narrow results.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid query string filter provided, or invalid page size provided, or unable to create list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

Note that results are sorted by ObjectId.

Object Sharing

GET /d2l/api/eP/(version)/object/sharetargets

Retrieve a list of all targets an EP object is currently shared with.

Parameters
Query Parameters
  • search (string) – Optional. Name to search for.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid page size provided, or unable to create list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

Note that results are sorted by the enclosed Id property.

Changed in version 2.5: As of EP’s API version 2.5, this route can return share targets of profile type OrgUnit. Older versions of this route will not return share targets of the OrgUnit profile type.

GET /d2l/api/eP/(version)/object/sharetargets/my

Retrieve a list of all the sharing targets owned by the current user context.

Parameters
Query Parameters
  • search (string) – Optional. Name to search for.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid page size provided, or unable to create a list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

Note that results are sorted by the enclosed Id property.

GET /d2l/api/eP/(version)/object/sharetargets/sharinggroups

Retrieve a list of the available sharing groups that an EP object can be shared with.

Parameters
Query Parameters
  • search (string) – Optional. Name to search for.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid page size provided, or unable to create list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

GET /d2l/api/eP/(version)/object/sharetargets/users

Retrieve a list of all available users that an EP object can be shared with.

Parameters
Query Parameters
  • search (string) – Optional. Name to search for.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid page size provided, or unable to create list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

GET /d2l/api/eP/(version)/object/(objectId)/shares/

Retrieve all the shares for a particular EP object.

Parameters
Status Codes
API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action returns a paged result set containing the resulting Share JSON data blocks in a single page.

Changed in version 2.5: As of EP’s API version 2.5, this route can return share targets of profile type OrgUnit. Older versions of this route will not return share targets of the OrgUnit profile type.

GET /d2l/api/eP/(version)/objects/my/shared/modified/

Retrieve all the EP objects shared by the current user context, and recently modified by others.

Parameters
Status Codes
  • 200 OK – Action succeeded.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action returns a paged result set containing the resulting EpObject JSON data blocks in a single page.

GET /d2l/api/eP/(version)/objects/shared/

Retrieve all EP objects that others have shared to the current user context.

Parameters
  • version (D2LID) – API version.

Query Parameters
  • c (boolean) – Optional. If “true”, include any comments attached to the objects.

  • q (string) – Optional. Query filter expression to narrow results.

  • bookmark (string) – Optional. Bookmark to use for fetching the next data set segment.

  • pagesize (integer) – Optional. Number of entries to retrieve in a single data set segment; if present, must be 1 or greater.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid query string filter provided, or invalid page size provided, or unable to create list of results.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

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

Note that the results are sorted by ObjectId.

GET /d2l/api/eP/(version)/users/sharing/

Retrieve all users sharing EP objects to the current user context.

Parameters
  • version (D2LID) – API version.

Query Parameters
Status Codes
  • 200 OK – Action succeeded.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action returns a paged result set containing the resulting UserObject JSON data blocks in a single page.

Note that the results are sorted by UserId.

POST /d2l/api/eP/(version)/object/(objectId)/share/delete

Unshare a particular EP object from a sharing profile.

Parameters
Form Parameters
  • profileTargetId – Target sharing profile ID to hide object from.

  • profileTypeType of profile to unshare from.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Attempt to remove sharing to an invalid profile type.

  • 403 Forbidden – No permission to unshare object, or no permission to remove sharing from profile.

  • 404 Not Found – Profile not found, or EP object not found.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Input. Provide a simple POST form data set with profileTargetId and profileType values.

Changed in version 2.5: As of EP API version 2.5, you can unshare from a container, individual, or org unit sharing profile type. Older versions of this route remain restricted to only container or individual sharing profile types.

POST /d2l/api/eP/(version)/object/(objectId)/share/new

Share a particular EP object to a sharing profile.

Parameters
Form Parameters
  • profileTargetId – Target sharing profile ID.

  • profileTypeType of profile to share to.

  • permissions – Permission to grant (an object right type value); may appear more than once.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Attempt to share to an invalid profile type.

  • 403 Forbidden – No permission to share object, or no permission to share to profile.

  • 404 Not Found – Profile not found, or EP object not found.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Input. Provide a simple POST form data set with profileTargetId, profileType, and permissions values. You can grant more than one permission with a single action by providing the permissions query parameter more than once: &permissions=2&permissions=3&permissions=4, and so forth. Note that the service sets the view permission (1) on all share targets by default, so you do not need to explicitly set it with this action.

Changed in version 2.5: As of EP API version 2.5, you can unshare from a container, individual, or org unit sharing profile type. Older versions of this route remain restricted to only container or individual sharing profile types.

Ignored users

Each eP user can have a list of ignored users: a calling user will not see any objects shared to them by a user on this list.

GET /d2l/api/eP/(version)/ignoredusers/

Retrieve all the users on the calling user’s ignored-users list.

Parameters
Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to view the list of ignored users.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Return. This action retrieves a list of user IDs currently on the calling user’s ignored-users list.

POST /d2l/api/eP/(version)/ignoredusers/add

Add a user to the calling user’s ignored-user list.

Parameters
JSON Parameters
  • UserId (D2LID as single JSON number) – User to add to the ignored-user list.

Status Codes
  • 200 OK – Action succeeded.

  • 400 Bad Request – Invalid user ID provided, or calling user’s own ID provided.

  • 403 Forbidden – No permission to edit the list of ignored users.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to add user with ID 1234 to the calling user’s ignored list, your POST body would be:

1234
POST /d2l/api/eP/(version)/ignoredusers/remove

Remove a user from the calling user’s ignored-user list.

Parameters
JSON Parameters
  • UserId (D2LID as single JSON number) – User to remove from the ignored-user list.

Status Codes
  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to edit the list of ignored users.

API Versions
  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4-Obsolete as of LMS v10.7.0.

Input. Note that you must pass a single JSON number in the body of this request; for example, if you want to remove user with ID 1234 from the calling user’s ignored list, your POST body would be:

1234

«  Learning Repository objects   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Artifacts  »