/// /// Updates the grade in Itslearning, by calling on the RestAPI.
/// /// The updated grade.
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);
}
}
}
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:
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.
|
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
Workaround |
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 |
|
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 |
|
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 itemsuserIds, 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.
Adding pageIndex to the query will let you get data page by page with specified size. 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:
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?)
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.
|
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 setSimplePercentScore (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:
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 |
ScoreLook Assessment options in applications Paging and sorting Report itemspageIndex, 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.
Adding pageIndex to the query will let you get data page by page with specified size. 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:
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?)
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.
|
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:
Here's how the notifications look in a course dashboard:
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 > < 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.
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:
authorization header = application key + "#" + session id + "#" + session timestamp + "#" + signature
The signature is calculated as follows:
-
Concatenate your application key, shared secret, sessionid and timestamp into a single string without any separators or white spaces.
-
Create an MD5 hash of the above string.
-
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:
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
}