API: createHistoricalSession
  • 4 Minutes to read
  • Dark
    Light

API: createHistoricalSession

  • Dark
    Light

Article Summary

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

Description

The createHistoricalSession method adds a historical session for an instructor-led course. 

Who Has Access

Administrators and owners have access to the createHistoricalSession method.

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>createHistoricalSession</Method>

   <Parameters>
      <LearningModule>
         <CourseSession>
            <LearningModuleID><![CDATA[]]></LearningModuleID>
            <StartDate><![CDATA[]]></StartDate>
            <StartTime><![CDATA[]]></StartTime>
            <DurationHour><![CDATA[]]></DurationHour>
            <DurationMinute><![CDATA[]]></DurationMinute>
            <GradeType></GradeType>
            <InstructorType><![CDATA[]]></InstructorType>
            <InstructorNotes><![CDATA[]]></InstructorNotes>
            <InternalInstructors>
               <Instructor>
                  <Email><![CDATA[]]></Email>
                     - OR -
                  <EmployeeID><![CDATA[]]></EmployeeID>
               </Instructor>
            </InternalInstructors>

            <ExternalInstructors><![CDATA[]]></ExternalInstructors>
         </CourseSession>
      </LearningModule>
   </Parameters>

</SmarterU>

LearningModule Tag Group

The LearningModule tag group is a container for the historical sessions. 

<LearningModule>
   <CourseSession>
      <LearningModuleID><![CDATA[]]></LearningModuleID>
      <StartDate><![CDATA[]]></StartDate>
      <StartTime><![CDATA[]]></StartTime>
      <DurationHour><![CDATA[]]></DurationHour>
      <DurationMinute><![CDATA[]]></DurationMinute>
      <GradeType></GradeType>
      <InstructorType><![CDATA[]]></InstructorType>
      <InstructorNotes><![CDATA[]]></InstructorNotes>
      <InternalInstructors>
         <Instructor>
            <Email><![CDATA[]]></Email>
               - OR - 
            <EmployeeID><![CDATA[]]></EmployeeID>
         </Instructor>
      </InternalInstructors>
      <ExternalInstructors><![CDATA[]]></ExternalInstructors>
   </CourseSession>
</LearningModule>

The LearningModule tag may contain the following.

CourseSession

A container for the historial session's details. Refer to CourseSession Tag Group.

CourseSession Tag Group

The CourseSession tag group is a container for the historical session's details. 

<CourseSession>
   <LearningModuleID><![CDATA[]]></LearningModuleID>
   <StartDate><![CDATA[]]></StartDate>
   <StartTime><![CDATA[]]></StartTime>
   <DurationHour><![CDATA[]]></DurationHour>
   <DurationMinute><![CDATA[]]></DurationMinute>
   <GradeType><![CDATA[]]></GradeType>
   <InstructorType><![CDATA[]]></InstructorType>
   <InstructorNotes><![CDATA[]]></InstructorNotes>
   <InternalInstructors>
      <Instructor>
         <Email><![CDATA[]]></Email>
            - OR -
         <EmployeeID><![CDATA[]]></EmployeeID>
      </Instructor>
   </InternalInstructors>

   <ExternalInstructors><![CDATA[]]></ExternalInstructors>
</CourseSession>

Each session is contained in a CourseSession tag and contains the following.

LearningModuleID

The course's system-generated identifier. This is the LearningModuleID returned by listLearningModules, and the ID returned by getLearnerReport.

StartDate

The session's start date in DD-MMM-YYYY format (e.g., 01-Jan-2000).

StartTime

The session's start time.

DurationHour

The session's duration in hours. For example, if a session's duration is 4 hours and 30 minutes, the DurationHour would be 4.

DurationMinute

The session's duration in minutes. Acceptable values are in the range 00-59. For example, if a session's duration is 4 hours and 30 minutes, the DurationMinute would be 30.

GradeType

The session's grade type. Acceptable values are: 

  • None - No grade is given to learners.
  • LetterGrade - Learners are assigned a text grade by an instructor, such as B+, C-, Needs Improvement, or any text string that the instructor wants to assign.
  • PassFail - Learners are given a pass or fail grade.
  • Percentage - Learners are given a percentage grade.

InstructorType

The type of instructors for this session:

  • Internal - Session instructors have a SmarterU user account.
  • External - Session instructors do not have a SmarterU user account.
  • Both - Some instructors for the session have a SmarterU user account, while others do not.

InstructorNotes

The session's instructor notes

InternalInstructors

This is required when the InstructorType tag is set to Internal or Both.

A container for the session's internal instructors. The instructor provided must already exist within your SmarterU account. If any of the provided instructors are not found, an error will occur.

Each instructor is contained in an Instructor tag and contains the following.

TagDescription

Email

The instructor's email address. This is mutually exclusive with the EmployeeID tag.

EmployeeID

The instructor's employee ID. This is mutually exclusive with the Email tag.

ExternalInstructors

This is required when the InstructorType tag is set to External or Both.

The session's external instructors. To specify multiple external instructors, separate each with a comma.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <CourseSessionID><![CDATA[]]></CourseSessionID>
   </Info>

   <Errors>
      <Error>
         <ErrorID><![CDATA[]]></ErrorID>
         <ErrorMessage><![CDATA[]]></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The response may also contain the following.

CourseSessionID

The session's system-generated identifier. 

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
 
   <Result>Success</Result>
   <Info>
      <CourseSessionID>48983</CourseSessionID>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

Error CodeMessage
CHS:01
The Learning Module ID provided is not valid.
CHS:02
The Start Date provided is not valid. Must be in format DD-MMM-YYYY (01-Jan-2099).
CHS:03
The Start Time provided is not valid. Must be in format HH:MM AM/PM (12:30 PM).
CHS:04
The Duration Hour provided is not valid. Must be between 0 and 99.
CHS:05
The Duration Minutes provided is not valid. Must be between 00 and 59, with leading zeroes.
CHS:06
The Grade Type provided is not valid.
CHS:07
The Instructor Type provided is not valid.
CHS:08
The Instructor Notes provided exceeds the maximum length of 1000 characters.
CHS:09
The Email provided is not valid.
CHS:10
The Employee ID provided is not valid.
CHS:11
The External Instructors provided are not valid. Must be a comma-separated list between 1 and 1000 characters.
CHS:12
The required permissions are not met to call the createHistoricalSession method.
CHS:13
The Instructor Type is not valid. Valid types are Internal, External and Both.
CHS:14
An Internal Instructor is required when Instructor Type is set to Internal or Both.
CHS:15
An Internal Instructor requires an Email or an Employee ID.
CHS:16
The Internal Instructor was not found.
CHS:17
The External Instructor is invalid. External Instructors must be a string of names separated by commas.
CHS:18
The Learning Module ID provided is not valid.
CHS:19
The Learning Module ID provided is not of type ILT.
CHS:20
The Start Date provided is not in the correct format. The date must be in the format ""DD-MMM-YYYY"" (01-Jan-2000).
CHS:21
The Start Time provided is not in the correct format. The time must be in the format ""HH:MM AM/PM"" (12:30 PM).
CHS:22
The Duration Hours provided is not in the correct format. The hour must be a number without decimals.
CHS:23
The Duration Minutes provided is not in the correct format. The time must be between 00 - 59.
CHS:24
The Grade Type is not valid. Valid types are PassFail, LetterGrade, Percentage and None.
CHS:25
Historical session creation failed.

Was this article helpful?