Package com.ssgllc.fish.service.util.published

Class LearningUtil

java.lang.Object
com.ssgllc.fish.service.util.published.LearningUtil
@Component public class LearningUtil extends Object
Learning packages (SCORM) from a Groovy script: store a package uploaded through a task form, find packages, and read a learner's result, interactions and objectives for course logic.

Called as the learningUtil bean.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LearningUtil(com.ssgllc.fish.service.learning.LearningLibraryService libraryService, com.ssgllc.fish.service.learning.LearningResultService resultService, com.ssgllc.fish.service.GuidanceEventService guidanceEventService)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static Map<String,Object>
    attemptSummary(String login, String packageId)
    A learner's result in the default attempt at a package, or null when they have none: completed (Boolean), completionStatus and successStatus (codes), and score (percent or null).
    static Map<String,Object>
    attemptSummary(String login, String packageId, String attemptKey)
    A learner's result in one attempt at a package (for example one attempt per enrollment), or null when they have none.
    static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo
    get(String idOrCode)
    A package by its id or code, or null when there is none.

    Groovy example:
    def pkg = learningUtil.get("VACCINE_STORAGE")
    static List<Map<String,Object>>
    interactions(String login, String packageId, String attemptKey)
    The interactions (question responses) a learner's module saved in one attempt at a package, for an application that copies them into its own records when it scores the course.
    static List<Map<String,Object>>
    interactions(String login, String packageId, String attemptKey, String itemIdentifier)
    The interactions a learner's module saved for one item of a package of several items.
    static List<com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo>
    list()
    Every package that is not retired, by name.
    static List<Map<String,Object>>
    objectives(String login, String packageId, String attemptKey)
    The objectives a learner's module saved in one attempt at a package.
    static List<Map<String,Object>>
    objectives(String login, String packageId, String attemptKey, String itemIdentifier)
    The objectives a learner's module saved for one item of a package of several items.
    static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo
    storeUpload(String fileName, byte[] bytes)
    Stores a package zip uploaded through a task form, with a code made from the package's title.
    static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo
    storeUpload(String fileName, byte[] bytes, String code)
    Stores a package zip uploaded through a task form under the given code, which names the package in every environment.
    static Instant
    tourCompletedAt(String login, String tourKey, Integer minVersion, Instant since)
    When the learner last completed a guided tour, for a "try it" lesson that counts only a recorded walkthrough.
    static Instant
    videoWatchedAt(String login, String videoKey, Instant since)
    When the learner last watched a lesson video to its end, as recorded by the video-watched field.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • LearningUtil

      public LearningUtil(com.ssgllc.fish.service.learning.LearningLibraryService libraryService, com.ssgllc.fish.service.learning.LearningResultService resultService, com.ssgllc.fish.service.GuidanceEventService guidanceEventService)

  • Method Details

    • storeUpload

      public static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo storeUpload(String fileName, byte[] bytes) throws IOException
      Stores a package zip uploaded through a task form, with a code made from the package's title.
      Parameters:
      fileName - The uploaded file's name.
      bytes - The zip, from bpmUtil.getFileFromUpload(id).
      Returns:
      The stored package: id, code, name, format, launch page, file name, size, retired flag and version.
      Throws:
      IllegalArgumentException - When the current user lacks the MANAGE_LEARNING admin permission, or the zip is not a package this server can play; the message suits the uploader.

      Groovy example:
      def info = learningUtil.storeUpload(fileName, bpmUtil.getFileFromUpload(docId))
      IOException

    • storeUpload

      public static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo storeUpload(String fileName, byte[] bytes, String code) throws IOException
      Stores a package zip uploaded through a task form under the given code, which names the package in every environment. A different zip under the code of a stored package is its new version: the package keeps its id and code, its packageVersion counts up, and at each learner's next launch an unfinished attempt starts over (a completed one keeps its result). The same zip again reuses the stored package.
      Parameters:
      fileName - The uploaded file's name.
      bytes - The zip, from bpmUtil.getFileFromUpload(id).
      code - Capital letters, digits and underscores, starting with a letter; null makes one from the title.
      Returns:
      The stored package, with its packageVersion.
      Throws:
      IllegalArgumentException - When the upload is refused; the message suits the uploader.

      Groovy example:
      def info = learningUtil.storeUpload(fileName, bpmUtil.getFileFromUpload(docId), "VACCINE_STORAGE")
      IOException

    • list

      public static List<com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo> list()
      Every package that is not retired, by name. It does not filter by the packages' roles.

      Groovy example:
      return learningUtil.list().collect { it.code() }

    • get

      public static com.ssgllc.fish.service.learning.LearningLibraryService.LearningPackageInfo get(String idOrCode)
      A package by its id or code, or null when there is none.

      Groovy example:
      def pkg = learningUtil.get("VACCINE_STORAGE")

    • attemptSummary

      public static Map<String,Object> attemptSummary(String login, String packageId)
      A learner's result in the default attempt at a package, or null when they have none: completed (Boolean), completionStatus and successStatus (codes), and score (percent or null). The module reports the result from the learner's browser, so it is the course's record, not proof.

      For a package of several items (SCOs) the result rolls up the items: completed only when every item is completed; successStatus PASSED when it is completed and every scored item passed, FAILED when an item failed; score the mean of the items' scores; plus totalSeconds (the items' time summed) and items, a list of maps with each item's identifier, title and summary (null for an item not started).

      Parameters:
      login - The learner's login.
      packageId - The package's id or code.

      Groovy example:
      def result = learningUtil.attemptSummary(learner, "VACCINE_STORAGE")
      return result?.completed

    • attemptSummary

      public static Map<String,Object> attemptSummary(String login, String packageId, String attemptKey)
      A learner's result in one attempt at a package (for example one attempt per enrollment), or null when they have none. A package of several items answers with the roll-up described at attemptSummary(String, String).
      Parameters:
      login - The learner's login.
      packageId - The package's id or code.
      attemptKey - The attempt, as the learning-player field names it; null is the default attempt.

      Groovy example:
      def result = learningUtil.attemptSummary(learner, "VACCINE_STORAGE", enrollmentId)
      def unfinished = result?.items?.findAll { !it.summary?.completed }*.title

    • interactions

      public static List<Map<String,Object>> interactions(String login, String packageId, String attemptKey)
      The interactions (question responses) a learner's module saved in one attempt at a package, for an application that copies them into its own records when it scores the course. Each is a map with interactionId, interactionType, learnerResponse, correctResponse (the first correct pattern), result (correct, incorrect, unanticipated, neutral, or a number as text), latencySeconds, recordedAt (an Instant; null for SCORM 1.2, which records no date), objectiveIds (a list) and itemIdentifier (the item, for a package of several items; else null). A package of several items lists every item's interactions in manifest order. Entries the module saved malformed are left out. The module reports them from the learner's browser, so they are the course's record, not proof.
      Parameters:
      login - The learner's login.
      packageId - The package's id or code.
      attemptKey - The attempt, as the learning-player field names it; null is the default attempt.
      Returns:
      The interactions, or an empty list when there is no attempt or nothing was saved.

      Groovy example:
      learningUtil.interactions(learner, "VACCINE_STORAGE", enrollmentId).each { row ->
          entityUtil.createEntity("QuizAnswer", [question: row.interactionId, answer: row.learnerResponse, result: row.result])
      }

    • interactions

      public static List<Map<String,Object>> interactions(String login, String packageId, String attemptKey, String itemIdentifier)
      The interactions a learner's module saved for one item of a package of several items. See interactions(String, String, String) for the keys.
      Parameters:
      login - The learner's login.
      packageId - The package's id or code.
      attemptKey - The attempt; null is the default attempt.
      itemIdentifier - The item, as attemptSummary(...).items names it; null reads every item.
      Throws:
      IllegalArgumentException - When the package has no such item.

      Groovy example:
      def finalQuiz = learningUtil.interactions(learner, "VACCINE_STORAGE", enrollmentId, "final_quiz")

    • objectives

      public static List<Map<String,Object>> objectives(String login, String packageId, String attemptKey)
      The objectives a learner's module saved in one attempt at a package. Each is a map with objectiveId, completionStatus and successStatus (the same codes as an attempt summary), scorePercent, scoreRaw, description (SCORM 2004 only) and itemIdentifier. Read like interactions(String, String, String).
      Parameters:
      login - The learner's login.
      packageId - The package's id or code.
      attemptKey - The attempt; null is the default attempt.
      Returns:
      The objectives, or an empty list when there is no attempt or nothing was saved.

      Groovy example:
      def missed = learningUtil.objectives(learner, "VACCINE_STORAGE", enrollmentId).findAll { it.successStatus == "FAILED" }

    • objectives

      public static List<Map<String,Object>> objectives(String login, String packageId, String attemptKey, String itemIdentifier)
      The objectives a learner's module saved for one item of a package of several items. See objectives(String, String, String) for the keys.
      Parameters:
      login - The learner's login.
      packageId - The package's id or code.
      attemptKey - The attempt; null is the default attempt.
      itemIdentifier - The item; null reads every item.
      Throws:
      IllegalArgumentException - When the package has no such item.

      Groovy example:
      def objectives = learningUtil.objectives(learner, "VACCINE_STORAGE", null, "final_quiz")

    • tourCompletedAt

      public static Instant tourCompletedAt(String login, String tourKey, Integer minVersion, Instant since)
      When the learner last completed a guided tour, for a "try it" lesson that counts only a recorded walkthrough. The completion is what the browser sent at the tour's last step: it shows the learner reached the end, not that each step was done.
      Parameters:
      login - The learner's login.
      tourKey - The guidance tour key.
      minVersion - The lowest tour version that counts, or null for any version.
      since - Only completions after this time count, for example the enrollment's start; null for any time.
      Returns:
      The time of the latest matching completion, or null when there is none.

      Groovy example:
      def done = learningUtil.tourCompletedAt(learner, "IIS_Inventory_TryIt", 2, enrollment.startedDate) != null

    • videoWatchedAt

      public static Instant videoWatchedAt(String login, String videoKey, Instant since)
      When the learner last watched a lesson video to its end, as recorded by the video-watched field.
      Parameters:
      login - The learner's login.
      videoKey - The video's key, as the video-watched field names it.
      since - Only events after this time count; null for any time.
      Returns:
      The time of the latest matching event, or null when there is none.

      Groovy example:
      def watched = learningUtil.videoWatchedAt(learner, "VFC_STORAGE_2027_L1", enrollment.startedDate) != null