REST API reference for applications

REST API base URLs

Base URL for production: https://restapi.itslearning.com/LearningObjectService.svc

API methods

All method names correspond to C# SDK functions found in the LearningObjectServiceClient.

In C# the serialisation/deserialisation is done automatically through our SDK. In our Java SDK we have implemented this manually. If you need to use another language for which we don't provide an SDK, you can have a look at the Java SDK to see how it is done or you can call the GET method of the different REST API calls to get an XML. This is possible for all calls except SendNotification which does not have a corresponding GetNotification call. The XML format of each entity is also shown below.

Retrieving and updating LearningObjectInstance objects

Method name

GetLearningObjectInstance

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45

HTTP method

GET

Description

Get instance of learning object instance. Course extended data included.

Data format example

<LearningObjectInstance xmlns="http://schemas.datacontract.org/2004/07/DataContractSerialization" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ActiveFromUtc>1900-01-01T23:59:59Z</ActiveFromUtc>
<ActiveToUtc>9999-12-31T23:59:59Z</ActiveToUtc>
<AssessmentId>0</AssessmentId>
<AssessmentStatusId>0</AssessmentStatusId>
<CourseCode>nyn01</CourseCode>
<CourseId>1082-9</CourseId>
<CourseOrganisationID>0</CourseOrganisationID>
<CourseOrganisationSyncKey i:nil="true" />
<CourseSyncKey>NO-ACCESS-EXTENDED-DATA</CourseSyncKey>
<CourseTitle>Some title</CourseTitle>
<CreatedByUserId>670</CreatedByUserId>
<CreatedUtc>2011-06-02T11:18:57Z</CreatedUtc>
<DeadlineUtc i:nil="true" />
<SoftGraceInMinutes i:nil="true">33</SoftGraceInMinutes>
<HasLearningObjectiveAssessmentCriteria>false</HasLearningObjectiveAssessmentCriteria>
<IsAssessmentVisible>true</IsAssessmentVisible>
<IsObligatory>false</IsObligatory>
<LearningObjectId>2799</LearningObjectId>
<LearningObjectInstanceId>4548</LearningObjectInstanceId>
<MaxScore>100.0</MaxScore>
<ModifiedUtc>2011-06-09T11:15:24Z</ModifiedUtc>
<SubmissionType>0</SubmissionType>
<Title>New Java SDK Local test</Title>
<UseAnonymousSubmission>false</UseAnonymousSubmission>
<UsePlagiarism>false</UsePlagiarism>
<UseScore>false</UseScore>
</LearningObjectInstance>

Additional information

Extended data for learningObjectInstance

(What is extended data?)

The course extended data will only be included in the XML if the app has been approved by a site admin to receive such data.

Course extended data:

  • CourseId – ID of the course instance belongs to. String. Globally unique (format is [CustomerId]-[CourseId]).

  • CourseCode – Code of the course instance belongs to. String.

  • CourseSyncKey – SyncKey of the course instance belongs to. String. Globally unique (format is [CustomerId]-[CourseSyncKey]).

Person extended data:

The person extended data will only be sent in the SSO if the app has been approved by a site admin to receive such data. Empty fields will not be sent.
All are strings.

  • Email - Person email address

  • Mobile - Person mobile phone

  • SyncKey - Person synchronization key

  • Custom1Id - Custom field 1 name used on the site

  • Custom1 - Custom field 1 value for the person

  • Custom2Id - Custom field 2 name used on the site

  • Custom2 - Custom field 2 value for the person

  • Custom3Id - Custom field 3 name used on the site

  • Custom3 - Custom field 3 value for the person

  • Custom4Id - Custom field 4 name used on the site

  • Custom4 - Custom field 4 value for the person

  • Custom5Id - Custom field 5 name used on the site

  • Custom5 - Custom field 5 value for the person

Method name

UpdateLearningObjectInstance

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45

HTTP method

PUT

Description

Update instance of learning object instance.

Data format example

See GetLearningObjectInstance

Additional information

Known Issue
Currently we have a known issue when trying to remove a deadline date that has been set on a learning object instance. Removing a deadline date by setting the deadline to "nil" and then updating the learning object instance, will not remove the deadline date from the learning object instance.

Workaround
To remove a deadline date that has been set on a learning object instance, update the learning object instance with a deadline date set to a distant future. This will not actually remove the deadline, but the desired result will be achieved.

Method name

UpdateLearningObjectInstanceUserReportForCollaboration

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports/Collaborations/{collaborationId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/100/instances/704/Reports/Collaborations/2

HTTP method

PUT

Description

Sets a report (assessment and etc) for all participants of a collaboration

Method name

GetLearningObjectInstanceCollaborationsParticipants

URL

[start]/LearningToolElements/{elementId}/Collaborations/Participants?collaborationIds={collaborationIds}

Example URL

https://restapi.itslearning.com/LearningToolElements/100/Collaborations/Participants?collaborationIds=1,2,3

HTTP method

GET

Description

Get a list of collaboration's participants.

Data format example

<GetLearningObjectInstanceCollaborationsParticipants xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GetLearningObjectInstanceCollaborationsParticipant>
<UserId>1</UserId>
<FirstName>Oleg</FirstName>
<LastName>Tarusov</LastName>
</GetLearningObjectInstanceCollaborationsParticipant>
</GetLearningObjectInstanceCollaborationsParticipants>

Method name

DeleteLearningObjectInstanceUserReports

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports

Example URL

https://restapi.itslearning.com//learningObjects/100/instances/704/Reports

HTTP method

DELETE

Description

Deletes learning object instance user reports specified user ids

Method name

DeleteLearningObjectInstanceUserReportsForCollaborations

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Collaborations/Reports

Example URL

https://restapi.itslearning.com//learningObjects/100/instances/704/Collaborations/Reports

HTTP method

DELETE

Description

Deletes learning object instance user reports for specified collaboration Ids

Assessment of the learning object

See assessment options in applications for a description of the different assessment options.

Method name

GetPossibleAssessments

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/PossibleAssessments

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/PossibleAssessments

HTTP method

GET

Description

Get possible assessments for learning object instance

Data format example

<ArrayOfAssessment xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Assessment>
<AssessmentId>-1</AssessmentId>
<Description/>
<Title>Score</Title>
</Assessment>
<Assessment>
<AssessmentId>1</AssessmentId>
<Description/>
<Title>GradesA-F</Title>
</Assessment>
<Assessment>
<AssessmentId>2</AssessmentId>
<Description/>
<Title>Passed/Notpassed</Title>
</Assessment>
<Assessment>
<AssessmentId>3</AssessmentId>
<Description/>
<Title>Grades10,0-1,0</Title>
</Assessment>
<Assessment>
<AssessmentId>4</AssessmentId>
<Description/>
<Title>Grades6-1</Title>
</Assessment>
<Assessment>
<AssessmentId>6</AssessmentId>
<Description>Assessmentscaleusedforassessingbehavior</Description>
<Title>Behaviorassessment</Title>
</Assessment>
</ArrayOfAssessment>

Method name

GetAssessmentStatusItems

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/AssessmentStatusItems

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects12/instances/45/AssessmentStatusItems

HTTP method

GET

Description

Get assessment status items that can be used for setting status on learning object instance

Data format example

<ArrayOfAssessmentStatusItem xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <AssessmentStatusItem> <AssessmentStatusId>1</AssessmentStatusId> <AssessmentStatusItemId>1</AssessmentStatusItemId> <Title>StatusItem<Title> </AssessmentStatusItem></ArrayOfAssessmentStatusItem>

Method name

GetAssessmentItems

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/AssessmentItems

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/AssessmentItems

HTTP method

GET

Description

Get assessment items that can be used for evaluating on an learning object instance

Data format example

<ArrayOfAssessmentItem xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<AssessmentItem>
<AssessmentId>1</AssessmentId>
<AssessmentItemId>11</AssessmentItemId>
<Description>You Fail</Description>
<PercentFromAndIncl>0</PercentFromAndIncl>
<PercentTo>33.3</PercentTo>
<Title>Fail</Title>
</AssessmentItem>
<AssessmentItem>
<AssessmentId>1</AssessmentId>
<AssessmentItemId>12</AssessmentItemId>
<Description>You Pass</Description>
<PercentFromAndIncl>3.3</PercentFromAndIncl>
<PercentTo>100</PercentTo>
<Title>Pass</Title>
</AssessmentItem>
</ArrayOfAssessmentItem>

Method name

GetPossibleAssessmentStatuses

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/PossibleAssessmentStatuses

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/PossibleAssessmentStatuses

HTTP method

GET

Description

Get possible assessment statuses for a learning object instance

Data format example

<ArrayOfAssessmentStatus xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<AssessmentStatus>
<AssessmentStatusId>1</AssessmentStatusId>
<Title>Status</Title>
</AssessmentStatus>
</ArrayOfAssessmentStatus>

Getting users

Method name

GetLearningObjectInstanceUsers

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Users?userIds={userIds}&includeTeachers={includeTeachers}&pageIndex={pageIndex}&pageSize={pageSize}&orderBy={orderBy}&orderDirection={orderDirection}

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/Users?userIds=33,87,89&includeTeachers=True&pageindex=0&pagesize=5&orderBy=FirstName&orderDirection=DESC

HTTP method

GET

Description

Get student (or any) users with access to learning object instance. Paging/sorting is possible (see below under Additional information) .

Data format example

<ArrayOfLearningObjectInstanceUser xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<LearningObjectInstanceUser>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<UserId>670</UserId>
</LearningObjectInstanceUser>
</ArrayOfLearningObjectInstanceUser>

Additional information

Paging and sorting Report items

userIds, includeTeachers, pageIndex, pageSize, orderBy, orderDirection are optional parameters to GetLearningObjectInstanceUsers

Not having all of these in the request or having incorrect values will provide you with the whole report collection. They can be used all together or separately (see below).

userIds

Provide the comma-separated list of user IDs to filter by. If the value is not provided, users won't be filtered by their IDs (all users are retrieved).

includeTeachers

By default only students are retrieved. If you want to additionally include all users who have an access to learning object instance regardless of profile setting, specify includeTeachers=True.

pageIndex/pageSize

If you are going to use these parameters, you have to specify at least pageSize, which has to be a positive integer.
If only pageSize is defined, you will get the top N records. Maximum size is limited to 100 entries.

Adding pageIndex to the query will let you get data page by page with specified size.
The value should be greater or equal to 0 (0 means the first page). If only pageIndex is defined without pageSize in the query, it will be ignored.

orderBy/orderDirectionorderBy and orderDirection parameters can be used along with paging or separately.Possible values for orderBy are listed in LearningObjectInstanceUserReport.OrderBy (see SDK). These are the following:

  • None (default one, which means no specified order)

  • FirstName

  • LastName

For orderDirection, use ASC or DESC. ASC is default if undefined in URL.NB: Using paging parameters while not using ordering might lead to repeatable or misordered data results. You have to use the same semantics to obtain a full ordering across requests.

Extended data for LearningObjectInstanceUser

(What is extended data?)


Person extended data:

The person extended data will only be sent in the SSO if the app has been approved by a site admin to receive such data. Empty fields will not be sent.
All are strings.

  • ProfileImageUrl - The URL of user's profile image (192px size).

  • ProfileImageSmallUrl - The URL of user's profile image (64px size).

  • Email - Person email address

  • Mobile - Person mobile phone

  • SyncKey - Person synchronization key

  • Custom1Id - Custom field 1 name used on the site

  • Custom1 - Custom field 1 value for the person

  • Custom2Id - Custom field 2 name used on the site

  • Custom2 - Custom field 2 value for the person

  • Custom3Id - Custom field 3 name used on the site

  • Custom3 - Custom field 3 value for the person

  • Custom4Id - Custom field 4 name used on the site

  • Custom4 - Custom field 4 value for the person

  • Custom5Id - Custom field 5 name used on the site

  • Custom5 - Custom field 5 value for the person

Method name

GetLearningObjectInstanceUsersCount

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Users/count?userIds={userIds}&includeTeachers={includeTeachers}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/Users/count?userIds=33,87,89&includeTeachers=True

HTTP method

GET

Description

Get total count of users with access to learning object instance.

Data format example

integer

Additional information

userIds, includeTeachers are optional parameters to GetLearningObjectInstanceUsersCount

Use the same values as for GetLearningObjectInstanceUsers method to receive the correct number of users.

userIds

Provide the comma-separated list of user IDs to filter by. If the value is not provided, users won't be filtered by their IDs (all users are counted).

includeTeachers

By default only students are counted. If you want to additionally include all users who have an access to learning object instance regardless of profile setting, specify includeTeachers=True.

Interacting with user reports

User reports contain an assessment item and an assessment status. The report can be updated with a new assessment/status by setting the AssessmentItemId/AssessmentstatusId.

When using simple grading, you can simply set SimplePercentScore (DEPRECATED USE SCORE Assessment options in applications) and/or SimpleStatus.

The flow to update/set a grade when using advanced assessment is roughly as follows:

  • Get report (GetLearningObjectInstanceUserReports or GetLearningObjectInstanceUserReport)

  • Determine desired AssessmentItem (GetAssessmentItems)

  • Set AssessmentItemId for the report. For "Score" scale set Score value.

  • Update the report (UpdateLearningObjectInstanceUserReports or UpdateLearningObjectInstanceUserReport)

Example code:

/// <summary>
/// Updates the grade in Itslearning, by calling on the RestAPI.
/// </summary>
/// <param name="grade">The updated grade.</param>
private void UpdateGradeWithRest(double? grade)
{
// Retrieve the ApiSession, to be able to open a connection with the RestAPI client.
var session = GetApiSession(ApiSessionId);
using (var proxy = new LearningObjectServiceClient(session))
{
// Get the report to be updated.
var report = proxy.GetLearningObjectInstanceUserReport(LearningObjectId, LearningObjectInstanceId, UserId);
if (report == null)
{
// No report means no grade can be set.
return GradesResponseCode.unsupported;
}
var assessItem = 0;
// If the grade is null, it is a Delete, so no correct AssessmentId has to be found.
if (grade != null)
{
// Make sure the grade is in percentages.
var decimalGrade = grade*100;
// Check the AssessmentItems, to be able to set the correct grade:
var assessItems = proxy.GetAssessmentItems(LearningObjectId, LearningObjectInstanceId);
foreach (var item in assessItems.Where(item => decimalGrade >= item.PercentFromAndIncl && decimalGrade < item.PercentTo))
{
assessItem = item.AssessmentItemId;
break;
}
}
// And send it back to Itslearning.
report.AssessmentItemId = assessItem;
proxy.UpdateLearningObjectInstanceUserReport(report, LearningObjectId, LearningObjectInstanceId, UserId);
}
}
}
 

Method name

GetLearningObjectInstanceUserReports

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports?pageIndex={pageIndex}&pageSize={pageSize}&orderBy={orderBy}&orderDirection={orderDirection}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/Reports?pageindex=0&pagesize=5&orderBy=FristName&orderDirection=DESC

HTTP method

GET

Description

Get reports (assessment etc) for users with access to learning object instance. Paging/sorting is possible (see below under Additional information).

Requirements

The application must have type "Learning activity with simple assessment" or "Learning activity with advanced assessment" to be able to call this method.

Data format example

<ArrayOfLearningObjectInstanceUserReport xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<LearningObjectInstanceUserReport>
<AssessmentItemId>12</AssessmentItemId>
<AssessmentItemTitle>Pass</AssessmentItemTitle>
<AssessmentStatusItemId>51</AssessmentStatusItemId>
<AssessmentStatusItemTitle>StatusItem</AssessmentStatusItemTitle>
<AttemptId i:nil="true" />
<CollaborationId i:nil="true" />
<Comment>A comment</Comment>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<NumberOfTimesRead>1</NumberOfTimesRead>
<NumberOfAttemptsTaken i:nil="true" />
<NumberOfTimesRead>0</NumberOfTimesRead>
<Reviewed>1900-01-01T23:59:59Z</Reviewed>
<ReviewedBy>12345</ReviewedBy>
<Score>105.5</Score>
<SimplePercentScore>10.0</SimplePercentScore>
<SimpleStatus>OnGoing</SimpleStatus>
<UserId>670</UserId>
</LearningObjectInstanceUserReport>
</ArrayOfLearningObjectInstanceUserReport>

Additional information

Score

Look Assessment options in applications

Paging and sorting Report items

pageIndex, pageSize, orderBy, orderDirection are optional parameters to GetLearningObjectInstanceUserReports

Not having all of these in the request or having incorrect values will provide you with the whole report collection. They can be used all together or separately (see below)pageIndex/pageSize

If you are going to use these parameters, you have to specify at least pageSize, which has to be a positive integer.
If only pageSize is defined, you will get the top N records. Maximum size is limited though, now it is 100 of entries.

Adding pageIndex to the query will let you get data page by page with specified size.
The value should be greater or equal to 0 (0 means the first page). If only pageIndex is defined without pageSize in the query, it will be ignored.

orderBy/orderDirectionorderBy and orderDirection parameters can be used along with paging or separately.Possible values for orderBy are listed in LearningObjectInstanceUserReport.OrderBy (see SDK). These are the following:

  • None (default one, which means no specified order)

  • FirstName

  • LastName

  • AssessmentItemTitle

  • NumberOfTimesRead

  • AssessmentStatusTitle

  • SimplePercentScore DEPRECATED USE SCORE

  • SimpleStatus

  • Score

For orderDirection, use ASC or DESC. ASC is default if undefined in URL.NB: Using paging parameters while not using ordering might lead to repeatable or misordered data results. You have to use the same semantics to obtain a full ordering across requests.

Extended data for LearningObjectInstanceUserReport

(What is extended data?)


Person extended data:

The person extended data will only be sent in the SSO if the app has been approved by a site admin to receive such data. Empty fields will not be sent.
All are strings.

  • ProfileImageUrl - The URL of user's profile image (192px size).

  • ProfileImageSmallUrl - The URL of user's profile image (64px size).

  • Email - Person email address

  • Mobile - Person mobile phone

  • SyncKey - Person synchronization key

  • Custom1Id - Custom field 1 name used on the site

  • Custom1 - Custom field 1 value for the person

  • Custom2Id - Custom field 2 name used on the site

  • Custom2 - Custom field 2 value for the person

  • Custom3Id - Custom field 3 name used on the site

  • Custom3 - Custom field 3 value for the person

  • Custom4Id - Custom field 4 name used on the site

  • Custom4 - Custom field 4 value for the person

  • Custom5Id - Custom field 5 name used on the site

  • Custom5 - Custom field 5 value for the person

Method name

GetNextLearningObjectInstanceUserReport

URL

[start]learningObjects/{learningObjectId}/instances/{instanceId}/NextReport/{currentUserId}?userIds={userIds}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/{learningObjectId}/instances/12/NextReport/23?userIds=35,47,52

HTTP method

GET

Description

Get report (assessment etc) for next user with access to learning object instance.

Data format example

See GetLearningObjectInstanceUserReports

Method name

GetLearningObjectInstanceUserReportsCount

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports/count

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/Reports/count

HTTP method

GET

Description

Get total count of reports (assessment etc) for users with access to learning object instance

to help with paging)

Data format example

integer

Method name

UpdateLearningObjectInstanceUserReports

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/Reports

HTTP method

POST

Description

Update reports (assessment etc) for multiple users with access to learning object instance

Data format example

See GetLearningObjectInstanceUserReports

Method name

GetLearningObjectInstanceUserReport

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports/{userId}

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/Reports/5

HTTP method

GET

Description

Get report (assessment etc) for a single user with access to learning object instance.

Data format example

See GetLearningObjectInstanceUserReports

Method name

UpdateLearningObjectInstanceUserReport

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports/{userId}

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/Reports/5

HTTP method

PUT

Description

Update report (assessment etc) for a single user with access to learning object instance

Data format example

See GetLearningObjectInstanceUserReports

Method name

UpdateLearningObjectInstanceUserReportComment

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Reports/{userId}/comments

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/Reports/5/comments

HTTP method

PUT

Description

Updates comment log on report (assessment etc.) for user with access to learning object instance.

Data format example

Data format example
<LearningObjectInstanceUserReportCommentOnComment xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CommentText>Some text</CommentText>
<CommentSyncKey>22345200abe84f6090c80d43c5f6c0f6</CommentSyncKey>
<ModifiedUtc>2011-06-09T11:15:24Z</ModifiedUtc>
<UserId>7</UserId>
</LearningObjectInstanceUserReportCommentOnComment>

Additional information

CommentSyncKey should be a GUID string with dashes removed, unique to each comment.

ModifiedUtc should be in UTC format.

UserId is a user who has submitted the changes.

Method name

UpdateLearningObjectInstanceUserReportCommentForCollaboration

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Collaborations/{collaborationId}/Report/comments

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/Collaborations/8/Report/comments

HTTP method

PUT

Description

Updates comment log on report (assessment etc.) for all participants on the collaboration.

Data format example

See UpdateLearningObjectInstanceUserReportComment

Method name

UpdateLearningObjectInstanceTaskStatus

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Tasks/Type/{taskType}?status={status}

Example URL

https://restapi.itslearning.com//learningObjects/100/instances704/Tasks/Type/1?status=1

HTTP method

PUT

Description

Updates the status of a task specified with type which is being handled by a student for a particular learning object instance

Learning Objectives and Rubrics

Method name

GetLearningObjectives

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/LearningObjectives

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/LearningObjectives

HTTP method

GET

Description

Gets learning objectives for given learning object.

Data format example

Data format example
<ArrayOfLearningObjective xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<LearningObjective>
<Id>33</Id>
<Title>Arts and crafts</Title>
<Description>Test description</Description>
<LearningObjectiveId>33</LearningObjectiveId>
<Obsolete>False</Obsolete>
</LearningObjective>
<LearningObjective>
<Id>34</Id>
<Title>Math</Title>
<Description>Elementary math</Description>
<Obsolete>False</Obsolete>
</LearningObjective>
<LearningObjective>
<Id>35</Id>
<Title>Removed from repository</Title>
<Description>That LO was incorrectly used in repository and removed from it afterwards</Description>
<Obsolete>True</Obsolete>
</LearningObjective>
</ArrayOfLearningObjective>

Additional information

Method name

GetRubricCriteria

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/RubricCriteria

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/12/instances/45/RubricCriteria

HTTP method

GET

Description

Gets learning objective rubric criteria attached to given learning object.

Data format example

Data format example
<ArrayOfRubricCriteriaItem xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<RubricCriteriaItem>
<Id>1</Id>
<Title>First criteria item</Title>
<LearningObjectiveId>33</LearningObjectiveId>
<AchievementLevels>
<RubricAchievementLevel>
<Id>1</Id>
<Text>Advanced</Text>
<OrderNo>1</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>2</Id>
<Text>Proficient</Text>
<OrderNo>2</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>3</Id>
<Text>Basic</Text>
<OrderNo>4</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>4</Id>
<Text>Below basic</Text>
<OrderNo>4</OrderNo>
</RubricAchievementLevel>
</AchievementLevels>
<UniqueId>12345abcdef</UniqueId>
</RubricCriteriaItem>
<RubricCriteriaItem>
<Id>2</Id>
<Title>Second criteria item</Title>
<LearningObjectiveId>34</LearningObjectiveId>
<AchievementLevels>
<RubricAchievementLevel>
<Id>5</Id>
<Text>Advanced</Text>
<OrderNo>1</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>6</Id>
<Text>Proficient</Text>
<OrderNo>2</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>7</Id>
<Text>Basic</Text>
<OrderNo>4</OrderNo>
</RubricAchievementLevel>
<RubricAchievementLevel>
<Id>8</Id>
<Text>Below basic</Text>
<OrderNo>4</OrderNo>
</RubricAchievementLevel>
</AchievementLevels>
<UniqueId>5454abcdef</UniqueId>
</RubricCriteriaItem>
 
</ArrayOfRubricCriteriaItem>

Additional information

Method name

GetLearningObjectiveReportSettings

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/LearningObjectiveReportSettings?assessUserId={assessUserId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/11/instances/3/LearningObjectiveReportSettings?assessUserId=5

HTTP method

GET

Description

Gets learning objective report settings for given learning object instance.

Data format example

Data format example
<LearningObjectiveReportSettings xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<AchievementLevelOrder>HighestToLowest</AchievementLevelOrder>
<UseMastery>True</UseMastery>
<LearningObjectiveMasteryRecurrenceType>TwoAssessmentsInRow</LearningObjectiveMasteryRecurrenceType>
<Statuses>
<LearningObjectiveAssessmentStatus>
<LearningObjectiveAssessmentStatusId>33</LearningObjectiveAssessmentStatusId>
<Enabled>True</Enabled>
<StartsAtPercentage>10</StartsAtPercentage>
<Label>Custom not assessed</Label>
<Type>NotAssessed</Type>
<MasteryThreshold>False</MasteryThreshold>
</LearningObjectiveAssessmentStatus>
<LearningObjectiveAssessmentStatus>
<LearningObjectiveAssessmentStatusId>34</LearningObjectiveAssessmentStatusId>
<Enabled>True</Enabled>
<StartsAtPercentage>100</StartsAtPercentage>
<Label i:nil="true" />
<Type>Meets</Type>
<MasteryThreshold>False</MasteryThreshold>
</LearningObjectiveAssessmentStatus>
</Statuses>
<ClientMasterySettings>
<MasterySettingsItem>
<LearningObjectiveId>99</LearningObjectiveId>
<LearningObjectiveMasterySettings>
<AffectsByLevel>True</AffectsByLevel>
<AffectsByResettingMastery>True</AffectsByResettingMastery>
<MasteredWithoutOverride>True</MasteredWithoutOverride>
<BreaksRecurrence>False</BreaksRecurrence>
<IsReportMastered>True</IsReportMastered>
</LearningObjectiveMasterySettings>
</MasterySettingsItem>
<MasterySettingsItem>
<LearningObjectiveId>100</LearningObjectiveId>
<LearningObjectiveMasterySettings>
<AffectsByLevel>True</AffectsByLevel>
<AffectsByResettingMastery>True</AffectsByResettingMastery>
<MasteredWithoutOverride>True</MasteredWithoutOverride>
<BreaksRecurrence>False</BreaksRecurrence>
<IsReportMastered>True</IsReportMastered>
</LearningObjectiveMasterySettings>
</MasterySettingsItem>
</ClientMasterySettings>
<ShowReportStatusForStudents>True</ShowReportStatusForStudents>
<ConnectAssessmentCriteriaToScale>False</ConnectAssessmentCriteriaToScale>
</LearningObjectiveReportSettings>

Additional information

If we are not assessing a student then assessUserId should be 0.

Method name

GetLearningObjectiveUserAssessments

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/LearningObjectiveUserAssessments?userId={userId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/11/instances/3/LearningObjectiveUserAssessments?userId=5

HTTP method

GET

Description

Gets learning objective assessments of given learning object instance and user.

Data format example

Data format example
<ArrayOfLearningObjectiveAssessment xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<LearningObjectiveAssessment>
<LearningObjectiveId>33</LearningObjectiveId>
<UserId>8</UserId>
<RubricCriteriaItemId>99</RubricCriteriaItemId>
<PercentScore>33</PercentScore>
<Comment>The comment</Comment>
<Mastery>False</Mastery>
<Override>True</Override>
<AssessedAchievementLevelId>3</AssessedAchievementLevelId>
<Reportable>True</Reportable>
</LearningObjectiveAssessment>
</ArrayOfLearningObjectiveAssessment>

Additional information

Method name

UpdateLearningObjectiveUserAssessments

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/LearningObjectiveUserAssessments?userIds={userIds}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/11/instances/3/LearningObjectiveUserAssessments?userIds=5,6,7

HTTP method

PUT

Description

Updates learning objective assessments for users with access to learning object instance.

Data format example

See GetLearningObjectiveUserAssessments

Additional information

Method name

UpdateLearningObjectiveCollaborationAssessments

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/LearningObjectiveCollaborationAssessments/{collaborationId}

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/11/instances/3/LearningObjectiveCollaborationAssessments/9

HTTP method

PUT

Description

Updates learning objective assessments for collaboration of people with access to learning object instance.

Data format example

See GetLearningObjectiveUserAssessments

Additional information

Notifications

Notifications are messages displayed to users in dedicated content blocks. They notify about changes in courses and projects, such as new elements, feedback on assignments, and new discussion posts. The content block is available from 'My dashboard', the main dashboard, and course dashboards. Here are some examples of notifications in the main dashboard:

images/download/attachments/15271014/mainDashboard.png

Here's how the notifications look in a course dashboard:

images/download/attachments/15271014/notificationsContentBlock.PNG

Method name

SendNotification

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Notification

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/Notifcation

HTTP method

POST

Description

Send new Notification to all persons with access to learning tool element.

Data format example

<Notification xmlns="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities" 
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<LaunchParameter>launchParam=X_LaunchParameter</LaunchParameter>
<LocalizedMessages xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a:KeyValueOfstringstring>
<a:Key>nn-no</a:Key>
<a:Value>Dette er ein beskjed på nynorsk</a:Value>
</a:KeyValueOfstringstring>
<a:KeyValueOfstringstring>
<a:Key>nb-no</a:Key>
<a:Value>Dette er en beskjed på bokmål</a:Value>
</a:KeyValueOfstringstring>
</LocalizedMessages>
<Message>This is a message in the standard language.</Message>
<ReciverPermission>Read</ReciverPermission>
</Notification>

Method name

SendNotificationToUsers

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/NotificationToUsers

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/learningObjects/12/instances/45/NotifcationToUsers

HTTP method

POST

Description

Send new Notification to specified persons with access to learning tool element.

Data format example

<CreateNotificationForUsers xmlns="http://tempuri.org/">
<notification xmlns:a="http://schemas.datacontract.org/2004/07/Itslearning.Platform.RestApi.Sdk.LearningToolApp.Entities"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:LaunchParameter/>
<a:LocalizedMessages xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:KeyValueOfstringstring>
<b:Key>nb-NO</b:Key>
<b:Value>A change has been made to </b:Value>
</b:KeyValueOfstringstring>
<b:KeyValueOfstringstring>
<b:Key>en-GB</b:Key>
<b:Value>A change has been made to </b:Value>
</b:KeyValueOfstringstring>
</a:LocalizedMessages>
<a:Message>A change has been made to </a:Message>
<a:ReciverPermission>Read</a:ReciverPermission>
</notification>
<receiverPersonIds xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:int>2</a:int>
<a:int>3</a:int>
<a:int>4</a:int>
</receiverPersonIds>
<senderPersonId>1</senderPersonId>
</CreateNotificationForUsers>

Organisations for current user

Method name

GetOrganisationsForCurrentUser

URL

[start]/OrganizationsForCurrentUser

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/OrganizationsForCurrentUser

HTTP method

GET

Description

Returns site and school(s) organisations that user is member of

Data format example

<ArrayOfOrganization xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Organization>
<HierarchyId>1</HierarchyId><LegalId/><Title>Site</Title><Type>Site</Type>
</Organization>
<Organization>
<HierarchyId>2</HierarchyId><LegalId>AutoGen</LegalId><Title>AutoGenHirerarchy</Title><Type>School</Type>
</Organization>
</ArrayOfOrganization>

Organisations for learning object instance

Method name

GetOrganisationsForLearningObjectInstance

URL

[start]/learningObjects/{learningObjectId}/instances/{instanceId}/Organizations

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/learningObjects/2/instances/3/Organizations

HTTP method

GET

Description

Returns current learning object instance organisations

Data format example

<ArrayOfOrganization xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Organization>
<HierarchyId>1</HierarchyId><LegalId/><Title>Site</Title><Type>Site</Type>
</Organization>
<Organization>
<HierarchyId>2</HierarchyId><LegalId>AutoGen</LegalId><Title>AutoGenHirerarchy</Title><Type>School</Type>
</Organization>
</ArrayOfOrganization>

Organisation roles for current user

Method name

GetOrganisationRolesForCurrentUser

URL

[start]/OrganizationRolesForCurrentUser

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/OrganizationRolesForCurrentUser

HTTP method

GET

Description

Returns roles in organisations that user is member of

Data format example

<ArrayOfOrganizationRoles xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<OrganizationRole>
<HierarchyId>1</HierarchyId>
<Role>Teacher</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>False</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
<OrganizationRole>
<HierarchyId>6</HierarchyId>
<Role>Teacher</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>True</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
<OrganizationRole>
<HierarchyId>8</HierarchyId>
<Role>Guest</Role> <!-- Enum (Administrator, Teacher, Student, Guest) -->
<HomeOrganization>False</HomeOrganization> <!-- Enum(True, False) -->
</OrganizationRole>
</ArrayOfOrganizationRoles>

Licenses for current user

Method name

GetAppLicensesForCurrentUser

URL

[start]/AppLicensesForCurrentUser

Example URL

https://restapi.itslearning.com/ LearningObjectService.svc/AppLicensesForCurrentUser

HTTP method

GET

Description

Returns licenses that current user has for the application

Data format example

<ArrayOfAppLicense xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<AppLicense>
<ExternalLicenseId>MyLicenseId</ExternalLicenseId>
<LicenseId>1</LicenseId>
</AppLicense>
</ArrayOfAppLicense>

Site for current user

Method name

GetSiteForCurrentUser

URL

[start]/GetSiteForCurrentUser

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/GetSiteForCurrentUser

HTTP method

GET

Description

Returns information about the site the user is logged on to

Data format example

<Site xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Segment>Other</Segment>
<CountryCode>NO</CountryCode>
<Name>Good site</Name>
<ShortName>gs</ShortName>
<BaseUrl>https://gs.itslearning.com</BaseUrl>
</Site>

Method name

GetCustomerSettings

URL

[start]/GetCustomerSettings

Example URL

https://restapi.itslearning.com/LearningObjectService.svc/GetCustomerSettings

HTTP method

GET

Description

Returns customer settings

Data format example

<CustomerSettings xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PlagiarismCode>23asfdxa3</PlagiarismCode>
<PlagiarismEmail>student@email.com</PlagiarismEmail>
<PlagiarismShowStudentName>Ben Franklin</PlagiarismShowStudentName>
<UsePlagiarism>true</UsePlagiarism>
</CustomerSettings>

Authorization and security

The calls to the API need to be authorized using a HTTP authorization header, using tokens issued to your application by itslearning when a user opens it.

Example request to REST API
GET https://restapi.itslearning.com/LearningObjectService.svc/SiteForCurrentUser HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: db426046-7a3a-4e40-908e-e0060bba81a3#rundhq45ase1yne212uqpu55#2014-01-04T17:50:06#eb564497cb86b99cc565a71317db2e5a
Host: restapi.itslearning.com
Accept-Encoding: gzip, deflate

The authorization header consists of:

  • Your application key,

  • The API session ID passed to you as a query string parameter when the application launched.

  • The session's timestamp, also from the query string parameters passed to you The timestamp is presented in sortable ISO 8601 format, for example: "2014-01-04T17:50:08".

  • A computed signature.

These components are concatenated and separated with "#" characters, as follows:

How authorization header for REST API is calculated
authorization header = application key + "#" + session id + "#" + session timestamp + "#" + signature

The signature is calculated as follows:

  1. Concatenate your application key, shared secret, sessionid and timestamp into a single string without any separators or white spaces.

  2. Create an MD5 hash of the above string.

  3. Convert each byte in the MD5 hash to hexadecimal format (see code example below). You now have the signature.

UTF-8 encoding must be used through the whole process.At the end, the authorization header is appended to the request to ensure secure communication together with HTTPS protocol. Then, the request is sent and the server returns a response:

Example response from REST API
HTTP/1.1 200 OK
Content-Length: 165
Content-Type: application/xml; charset=utf-8
Date: Thu, 16 Jan 2014 09:10:41 GMT
<Site xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><CountryCode>NO</CountryCode><Name>Site1</Name><Segment>Higher</Segment><ShortName>site1</ShortName></Site>

Code example for creating the authorization header:

/* This returns the full hash string with the correct concatenated string as input */
public static string ComputeHash(ApiSession session, string sharedSecret)
{
return ComputeHash(session.ApplicationKey + sharedSecret + session.SessionId + session.TimeStamp, Encoding.UTF8);
}
 
/* This is to convert to generate the hash and convert to hex*/
public static string ComputeHash(string input, Encoding encoding)
{
var md5Hasher = new MD5CryptoServiceProvider();
byte[] data = md5Hasher.ComputeHash(encoding.GetBytes(input));
var sb = new StringBuilder();
// Loop through each byte of the hashed data and format each one as a hexadecimal string.
for (int i = 0; i < data.Length; i++)
{
sb.Append(data[i].ToString("x2"));
}
return sb.ToString();
}
 
 
/* This is to build the Authorization header string */
 
public static string ToAuthorizationHeader(this ApiSession session)
{
if (session == null)
{
throw new ArgumentNullException("session");
}
return string.Format("{0}#{1}#{2}#{3}",
session.ApplicationKey,
session.SessionId,
session.TimeStamp,
session.Hash); //Hash calculated from application key, shared secret and sessionID
}