Best Practices

Best Practice #1 – Use of Objectives

(Since Objectives usage outside of course structure is not defined.)

Objectives are defined for the course structure, but there is no language in the specification concerning their usage in statements. If an AU is using Objectives in statements, the best practice is to add the objective (with the same objective id provided in the course structure) to the context activities “parent” property as an activity type of from the ADL vocabulary.

Best Practice #2 – LMS should always implement the “returnURL”

LMS should always implement the “returnURL”

LMS should not spawn a new window to launch AU (i.e. “popup”). Depending on the settings it could take the following actions to launch an AU:

Best Practice #3 – Fetch URLs

Best Practice #4 – AU Mastery Score

If the LMS issues a Mastery Score, the AU should respond in the following ways:

Best Practice #5 – LMS Mastery Score

LMS should use caution when adding Mastery Scores to AU course structure entries if they are not present in the original course structure. (As the AU may not be designed to handle scores). It is recommended that such changes be tested prior to enrolling learners.

Best Practice #6 – Always specify a moveOn criterion in the course structure for each AU

When creating a course structure, always specify a moveOn criteria for each AU. Failing to do so will result in a default of “Not Applicable”. This can have the following unintended consequences:

Best Practice #7 – Launching apps on mobile devices

One of the following options should be used to launch AU’s that are apps on mobile devices:

Option 1: Use an app protocol in the launch URL.

Option 2: Use and HTML wrapper to launch the app AU is an HTML page (wrapper) that directs from the mobile browser to the app.

Best Practice #8 – In the absence of returnURL, the AU should close browser window to exit.

If the AU is not a mobile app and the LMS does not provide a “returnURL”, the best practice to exit the AU is to close the Window (window.close()) or direct the learner to manually close the browser window.

Best Practice #9 - LMS error handling of non-conforming cmi5 statements.

If an AU sends a statement that doesn’t conform to cmi5, the LMS should reject it (see section 6.3 of cmi5 specification) and return an HTTP error 403.

Best Practice #10 - LMS Administrators should use caution when changing the moveOn property.

The AU may not have the capability of sending statements required by any moveOn value that was not in the original course structure. It is recommended that all changes to course structures after import be tested prior to learner assignment.

Best Practice #11 – Use “progressed” verb for indicating progress during a session.

For recording progress during a session, it is recommend to use a cmi5 allowed statement with the progressed verb ( and a progress extension in the result (see section of specification). Progress statements should not be sent for progress value of 100% as that indicates completion. Once the learner reaches 100% it is recommended that a cmi5 defined “completed” statement be issued instead.

Best Practice #12 – Provide registration id in all statements.

It is strongly recommend to include the registration id provided by the LMS at launch time in the context of all statements issued by the LMS and AU.

Best Practice #13 – LMS create “satisfied” statements for AU’s.

It is recommended that the LMS create a cmi5 “allowed” statement (with a satisfied verb) when an AU has met its moveOn criteria. The statement should also include the same AU activityId used in cmi5 defined statements.

Best Practice #14 – Use of Objectives (in LMS/Course Structure)

Objectives are defined for the course structure so that the LMS can associate learning objectives to AU and Blocks in the course structure. If an LMS has features for managing or reporting on objectives it should use the objectives defined in the course structure (to make the association of objectives to the AUs & Blocks).

Best Practice #15 – LMS should use the Session ID and authorization token to validate actor

When the LMS receives a Statement, it should verify that the Actor in the statement matches the actor provided on the launch URL and that the authorization token provided was the same one issued for that specific launch session. If the Session ID, authorization token, actor in statement, and actor do not match, then the LMS/LRS should reject the Statement with a HTTP 403 (Forbidden) Error.

Best Practice #16 – AU should use a derived activity ID for “cmi.interaction” statements

When the AU issues statements with an activity type of “cmi.interaction” it should use an activity ID derived from the AU’s activity ID by appending the following convention:


Where :


Best Practice #17 – Persist AU Session State

There are certain situations, such as browser window refresh, that may inadvertently cause cmi5 errors related to operations that must occur only once in a session. To prevent such issues, AU’s should be designed to use non-volatile storage (local to AU) to preserve the state of following operations that have been performed during the session: