Developer Platform (August 2017)

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 format)
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  »