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:

version (D2LVERSION) – API version.

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:

200 OK – Action succeeded.
403 Forbidden – No permission to see EP object.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

Query Parameters:

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

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see EP object.
404 Not Found – EP object not found, or EP object is not a file artifact.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API verison.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.
objectId (D2LID) – EP object ID.

Query Parameters:

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

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see EP object.
429 Too Many Requests – API call-rate limit exceeded.

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:

200 OK – Action succeeded.
403 Forbidden – No permission to see list of associated EP objects.
404 Not Found – EP object not found.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.
objectId (D2LID) – EP object ID.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see EP object.
404 Not Found – EP object not found, or EP object is not a file artifact.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

2.5+ – Route first appears in LMS v10.4.0.
2.4- – Obsolete as of LMS v10.7.0.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.
objectId (D2LID) – EP object ID.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see shares for EP object.
429 Too Many Requests – API call-rate limit exceeded.

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.

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:

version (D2LVERSION) – API version.

Status Codes:

200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.

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.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

2.5+ – Route first appears in LMS v10.4.0.
2.4- – Obsolete as of LMS v10.7.0.

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:

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

Status Codes:

200 OK – Action succeeded.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.
objectId (D2LID) – EP object ID.

Form Parameters:

profileTargetId – Target sharing profile ID to hide object from.
profileType – Type 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.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.
objectId (D2LID) – EP object ID.

Form Parameters:

profileTargetId – Target sharing profile ID.
profileType – Type 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.
429 Too Many Requests – API call-rate limit exceeded.

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.

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:

version (D2LVERSION) – API version.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to view the list of ignored users.
429 Too Many Requests – API call-rate limit exceeded.

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:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

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

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

Parameters:

version (D2LVERSION) – API version.

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.
429 Too Many Requests – API call-rate limit exceeded.

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:

Developer Platform (April 2024)

ePortfolio Objects

Attributes ¶

Object query filters ¶

Actions ¶

Ignored users ¶

Developer Platform (April 2024)

ePortfolio Objects

Attributes¶

Object query filters¶

Actions¶

Object Sharing¶

Ignored users¶

Attributes ¶

Object query filters ¶

Actions ¶

Object Sharing ¶

Ignored users ¶