API: enrollmentHistoryImport
  • 4 Minutes to read
  • Dark
    Light

API: enrollmentHistoryImport

  • 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 enrollmentHistoryImport method associates historical training courses with users. 

This method is only available for online and SCORM courses. To enroll users in a historical, instructor-led session, use the enrollSessionHistory method.

Who Has Access

The following users have access to the enrollmentHistoryImport method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>enrollmentHistoryImport</Method>
   <Parameters>

      <LearningModuleEnrollment>
         <Enrollment>
            <User>
               <Email><![CDATA[]]></Email>
                  - OR -
               <EmployeeID><![CDATA[]]></EmployeeID>
            </User>

            <Group>
               <GroupName><![CDATA[]]></GroupName>
                  - OR -
               <GroupID><![CDATA[]]></GroupID>
            </Group>

            <LearningModuleID><![CDATA[]]></LearningModuleID>
            <EnrollmentStatus><![CDATA[]]></EnrollmentStatus>
            <Passed><![CDATA[]]></Passed>
            <Grade><![CDATA[]]></Grade>

            <EnrollmentSettings>
               <EnrolledDate><![CDATA[]]></EnrolledDate>
               <StartedDate><![CDATA[]]></StartedDate>
               <CompletionDate><![CDATA[]]></CompletionDate>
               <DueDate><![CDATA[]]></DueDate>
               <PostDueDateAccessEndDate><![CDATA[]]></PostDueDateAccessEndDate>
               <CompletionAccessDays><![CDATA[]]></CompletionAccessDays>
            </EnrollmentSettings>

         </Enrollment>
      </LearningModuleEnrollment>
   </Parameters>
</SmarterU>

LearningModuleEnrollment Tag Group

The LearningModuleEnrollment tag group is a container for historical enrollments in online or SCORM courses.

<LearningModuleEnrollment>
   <Enrollment>
      <User>
         <Email><![CDATA[]]></Email>
            - OR -
         <EmployeeID><![CDATA[]]></EmployeeID>
      </User>

      <Group>
         <GroupName><![CDATA[]]></GroupName>
            - OR -
         <GroupID><![CDATA[]]></GroupID>
      </Group>

      <LearningModuleID><![CDATA[]]></LearningModuleID>
      <EnrollmentStatus><![CDATA[]]></EnrollmentStatus>
      <Passed><![CDATA[]]></Passed>
      <Grade><![CDATA[]]></Grade>

      <EnrollmentSettings>
         <EnrolledDate><![CDATA[]]></EnrolledDate>
         <StartedDate><![CDATA[]]></StartedDate>
         <CompletionDate><![CDATA[]]></CompletionDate>
         <DueDate><![CDATA[]]></DueDate>
         <PostDueDateAccessEndDate><![CDATA[]]></PostDueDateAccessEndDate>
         <CompletionAccessDays><![CDATA[]]></CompletionAccessDays>
      </EnrollmentSettings>

   </Enrollment>
</LearningModuleEnrollment>

The LearningModuleEnrollment tag contains the following.

Enrollment

A container for a historical enrollment in an online or SCORM course. Refer to Enrollment Tag Group.

Enrollment Tag Group

The Enrollment tag group is a container for a historical enrollment in an online or SCORM course. 

<Enrollment>
   <User>
      <Email><![CDATA[]]></Email>
         - OR -
      <EmployeeID><![CDATA[]]></EmployeeID>
   </User>

   <Group>
      <GroupName><![CDATA[]]></GroupName>
         - OR -
      <GroupID><![CDATA[]]></GroupID>
   </Group>

   <LearningModuleID><![CDATA[]]></LearningModuleID>
   <EnrollmentStatus><![CDATA[]]></EnrollmentStatus>
   <Passed><![CDATA[]]></Passed>
   <Grade><![CDATA[]]></Grade>

   <EnrollmentSettings>
      <EnrolledDate><![CDATA[]]></EnrolledDate>
      <StartedDate><![CDATA[]]></StartedDate>
      <CompletionDate><![CDATA[]]></CompletionDate>
      <DueDate><![CDATA[]]></DueDate>
      <PostDueDateAccessEndDate><![CDATA[]]></PostDueDateAccessEndDate>
      <CompletionAccessDays><![CDATA[]]></CompletionAccessDays>
   </EnrollmentSettings>

</Enrollment>

Each enrollment is contained an Enrollment tag may contain the following. 

The enrollmentHistoryImport method supports up to 100 enrollments per call. 

User

The user to enroll in a historical course. The User tag contains one of the following.

TagDescription

Email

The user's email. This tag is mutually exclusive with the EmployeeID tag. This is the Email returned by the getUser and listUsers methods.

EmployeeID

The user's employee ID. This tag is mutually exclusive with the Email tag. This is the EmployeeID returned by the getUser and listUsers methods.

Group

The enrollment group.

The user you are trying to enroll must already be assigned to the group.

The Group tag contains one of the following.

TagDescription

GroupName

The group's name. This tag is mutually exclusive with the GroupID tag. This is the Name returned by the getGroup and listGroups methods. 

GroupID

The group's user-specified identifier. This tag is mutually exclusive with the GroupName tag. This is the GroupID returned by the getGroup and listGroups methods.

LearningModuleID

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

EnrollmentStatus

The course enrollment's status. Acceptable values are:

  • Enrolled - The user is enrolled in the course, but has not started it.
  • In Progress - The user has not finished the course and is less than 75% through the course's allotted completion time.
  • Warning - The user has not finished the course although over 75% of the course's allotted completion time has passed.
  • Overdue - The user has exceeded the amount of time allotted to complete the course.
  • Completed - The user finished the course. 

Passed (optional)

This tag only applies when the EnrollmentStatus tag is set to Completed. Indicates whether the learner passed or failed. Acceptable values are:

  • 1 - The learner passed the course. 
  • 0 - The learner did not pass the course.

Grade (optional)

This tag only applies when the session is graded and the EnrollmentStatus tag is set to Completed. The user's grade. Acceptable values will depend on the grade type:

  • LetterGrade - Up to 5 characters.
  • PassFail - Pass or Fail.
  • Percentage - A number between 0-100.

EnrollmentSettings

The enrollment's settings. The tag may contain the following. 

TagDescription

EnrolledDate

The date of the enrollment.

StartedDate (optional)

The date the learner started the course.

CompletionDate (optional)

The date the learner completed the course.

DueDate (optional)

The date the learner's course completion is due.

PostDueDateAccessEndDate (optional)

The date after the due date that the course is still available.

CompletionAccessDays (optional)

The number of days after the learner completes the course that they still have access to it.

API Response XML Package

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

<SmarterU>
   <Result></Result>
   <Info>
      <Enrollments>
         <Enrollment>
            <User><![CDATA[]]></User>
            <LearningModuleID></LearningModuleID>
         </Enrollment>
      </Enrollments>
   </Info>
   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The Enrollments tag is a container for the course enrollments processed by the enrollmentHistoryImport method. Each course enrollment is contained in an Enrollment tag and may contain the following.

User

The user's identifier. This returns the same value that was provided in the Enrollment tag group .

LearningModuleID

The course's system-generated identifier. This returns the same value that was provided in the Enrollment tag group .

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <Enrollments>
         <Enrollment Block="1">
            <User><!--[CDATA[robin.atkins@finashoes.com]]--></User>
            <LearningModuleID>3850</LearningModuleID>
         </Enrollment>
      </Enrollments>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

Error CodeMessage
EHI:01
The email address provided is not valid.
EHI:02
The employee ID provided is not valid.
EHI:03
The group name provided is not valid.
EHI:04
The group ID provided is not valid.
EHI:05
The learning module ID provided is not valid.
EHI:06
The enrollment status provided is not valid. Acceptable values are Enrolled and Completed.
EHI:07
The passed value provided is not valid. Allowed values are 1 and 0.
EHI:08
The grade provided is not valid.
EHI:09
The enrolled date provided is not valid.
EHI:10
The started date provided is not valid.
EHI:11
The completion date provided is not valid.
EHI:12
The due date provided is not valid.
EHI:13
The post due date access end date provided is not valid.
EHI:14
The completion access days provided is not valid.



Was this article helpful?