This document is written from a post-V2-launch perspective. As of Sep 2023, not all of it is implemented.

The Library Content Component will be implemented by enhancing the existing Randomized Content Module, which is implement by the library_content XBlock. The changes to the library_content XBlock are described in this ADR:

PR: https://github.com/openedx/edx-platform/pull/33231
Rendered ADR (will work after PR merges): https://github.com/openedx/edx-platform/blob/master/xmodule/docs/decisions/0003-library-content-block-schema.rst

The Library Content Component

Briefly, the Library Content course component includes components from content libraries into courses, and then selects some or all of those components and shows them to learners.

1 The Library Content Component
- 1.1 Inclusion (Studio)
- 1.2 Selection (LMS)
- 1.3 Modes
- 1.4 Data flow diagram
- 1.5 User stories

Inclusion (Studio)

Each Library Content component can be pointed to a single Source Library, from which components will be included. Once a Source Library is chosen, components are included from the library, and saved as the Children of the Library Content component. The way components are included (e.g., include all, include a filtered set, author manually picks which to included) depends on the component’s Mode, described later.

The included Children are visible in Studio. They can individually be customized.

In the background, the Source Library is pinned to a particular Version. When a new version of the Source Library is published, the course author will be presented with the option of updating to it.

When the Source Library, its Version, or the Mode changes, the Children may need to be re-included into the Library Content component. This will erase any content customizations the course author has made to the individual Children, but will preserve any settings overrides they have made to them.

As a rule of thumb, neither the set of included Children, nor their content nor settings, should ever change without the course author’s intervention! This shields instructors from accidental loss of live library content and student state due to changes in the Source Library.

Once the course is published, the Children are pushed into the LMS instance of the Library Content component, where component selection occurs (next section).

Selection (LMS)

Given a particular Library Content component and a particular learner, the Selection defines the Children which the learner will actually see. The Selection could be equal to the Children; it could be the same components but in a different order; or it could be a subset of the Children. It may or may not vary from learner to learner. All of this behavior is determined by the Mode that the Library Content component is using.

The Selection is first built for a learner whenever the LMS needs to know it. That might be whenever the learner loads the unit containing the Library Content component, or it might be earlier on; for example, the LMS may need to know what a learner’s Selection contains in order to determine time estimates on their course outline.

Regardless, once a learner’s Selection is built, it remains stable, unless the course is published with a change such that:

the list of the included Children changes, or
the Mode or its parameters change.

If this either of those do happen, LMS will try to keep as many of the same components in the Selection as possible, and keep them in the same order. However, it may need to add or remove components in order to satisfy the selection criteria. (For example, if we are in Randomized mode, and the Count is reduced by one then LMS will keep all components in each learner’s existing selection except for one). The LMS aims for Selection stability, because any changes to it will impact course progress and grading.

Modes

The component can be configured to include and select blocks two different ways:

Randomized Mode (available with V1 content libraries): The entire source library is included into Studio, optionally filtered by a Problem Type. The author optionally specifies a Count. From the included components, LMS selects a randomized subset of size Count for each learner. If Count is not specified, all included components are shown in a random order to each learner.
Static Mode (new with the V2 content library launch): The author manually includes zero or more components from the source library. All components are shown in the original order

On the backend, the Library Content component has been built to allow for flexibility in defining new modes in the future, such as:

Statically-Included-Randomly-Selected Mode (needs a better name): The author manually includes zero or more components from the source library. The author optionally specifies a Count. From the included components, LMS selects a randomized subset of size Count for each learner. If Count is not specified, all included components are shown in a random order to each learner. (This really is just a generalization of Randomized and Static mode, combining the capabilities of both. It could be presented to the authors as an enhanced version of Random or Static mode).
Recommendation Mode (not fleshed out): Components are are smartly included from the source library based on tags or other metadata. TBD: How would components be selected for each learner?

Data flow diagram

(This is how components flow from the library to the learner, for a particular Library Content component instance. This isn’t a user flow diagram)

Source: https://lucid.app/lucidchart/4cfbb5d6-86f3-4cd6-98cf-c85c123a8cb7/edit?invitationId=inv_7c5dea04-a713-4f45-b73e-e06e20fcfa9d&page=TcjvDJoIqz14#

User stories

Colors are just to group related cells together; they are not significant.

User stories Start here, and then read the cells left-to-right: As a course author using a Library Content component in their course…					Works in…
					V1?	V2?
…if no Source Library is chosen…	…then I will see a prompt telling them to choose a library, and clicking it will bring me to the block’s settings editor.
…if I choose a Source Library…	…then I will no longer see a prompt telling me to choose a library.
	…then I be able to choose the library’s Mode.
	…then Children will be included (see below).
…if I change the Source Library…	…then the Children will be re-included (see below).
…if a new Version of the Source Library is available…	…then my library_content block will give me the option of updating to the latest library version.
…if I select to update to the latest Source Library Version….	…then it will will silence the update prompt until the next Source Library Version is available.
	…then Children will be re-included (see below).
…if I import OLX into the course…	…then for each imported Library Content component…	…the component’s Children should contain the exact set of blocks specified in the OLX and should use the the block content defined by the OLX, regardless of whether: the Children of this Library Content component were added to, removed from, or edited in the destination course before import; this Library Content component existed at all in the destination course before import; components were added to, removed from, or edited in the Source Library at any version; the Source Library exists at all on the destination instance.
		…if the OLX contains a library default settings document for this Source Library… (Later feature; not applicable to the initial V2 launch!)	…then for each Child component, it should… get its default settings from the document, and get its setting overrides from OLX of the Library Content component.
		..if the OLX does not contain a library default settings document for the Source Library… (Test this one--it will be the case for all OLX imports in the initial V2 launch.)	…then if the Source Library exists on the instance…	…then for each Child component, it should… get its default settings from the Source Library, and get its setting overrides from OLX of the Library Content component.
			…then if the Source Library is missing from the instance…	…then for each Child component, it should… get its default settings from the platform-defined XBlock defaults (which will likely confuse me), and get its setting overrides from OLX of the Library Content component.
		…if the Source Library exists on the destination instance, and its latest version is the same as the Version specified in the Library Content component…	…then I will neither see a warning about missing library nor a prompt to update my Source Library Version.
		…if the Source Library exists on the destination instance, and its latest version is older than the Version specified in the Library Content component…
		…if the Source Library exists on the destination instance, and its latest version is newer than the Version specified in the Library Content component…	…then I will not see a warning about missing library.
			…then I will be prompted to update my source Source Library Version.
		…if the Source Library does not exist on the destination instance…	…then I will be warned of this via an alert within the Library Content component editor.
			…then I will not be prompted to update to a later library version.
			…then I will still be able to configure the Library Content component, and edit its children, and publish.
			…then if I import the correct Source Library into the instance…	…then the messaging will change (per other user stories) based on whether the imported library’s version matches, is older, or is newer than the configured Source Library Version.
…when the Children are re-included…	…then the updated Children will be visible in the Library Content component detail page, by clicking “View”.
	…then the unit editor containing the Library Content component will indicate that the block has unpublished changes.
	…then no learner’s Selection will be changed until the unit containing the Library Content component is published.
	…and if I have edited the content of any of the existing Children…	…then my content edits will be overwritten.
	…and if I have overridden the settings of any of the existing Children…	…then my setting overrides will be preserved.
	…and if any of the existing Children no longer exist in the current Version of the Source Library…	…then they will be removed.
	…and if any of the existing Children no longer meet the criteria to be included (e.g., they no longer meet the Problem Type filter)…	…then they will be removed.
	…and if this version of the Source Library contains new components…	…and if I am using Randomized Mode…	…then the new components will be included as Children.
		…and if I am using using Static Mode…	…then the new blocks will not be included as Children, but they will be visible the next time the component picker is opened.
…if I am using Static mode…	…then I cannot see the Problem Type or Count fields.
…if I am using Static mode…	…and I change the Mode to Randomized…	…then the Children will be re-included, such that the entire library (filtered by Problem Type) is included.
…if I am using Randomized mode…	…and I change the Problem Type…	…then the Children will be re-included, such that the entire library (filtered by Problem Type) is included.
	…and I change the Count…	…then the Children will not be re-included, as it is unecessary.
	…and I change the Mode to Static…	…then the the library component picker dialog will be shown, starting with the entire library included…	…and, based on the what the author picks, the the Children will be re-included.
	…and I make any of the above changes (Problem Type, Count, or Mode)…	…then the unit will not indicate that it has unpublished changes.
		…then the changes will not impact learners until published.
…if I change the Mode or Count settings…	…then the set of included Children will not be affected.
	…then the unit editor containing the Library Content component will indicate that the block has unpublished changes.
	…then no learner’s Selection will be changed until the block is published.
…if I publish a Library Content component in Static mode after either of the following have changed: Mode The list of included children (not included their contents or settings)…	...then the unit editor will no longer indicate that the unit has unpublished changes.
	…then for each learner, next time they load the Library Content component…	…the learner’s Selection will equal the Children, both in content and ordering.
…if I publish a Library Content component in Static mode after either of the following have changed: Mode Count The list of included children (not included their contents or settings)…	...then the unit editor will no longer indicate that the unit has unpublished changes.
	…then for each learner, next time they load the Library Content component…	…if Count equals -1…	…then the learner’s Selection will equal the set of included Children, but in a random order.
		…if Count is greater than the number of included Children…
		…if Count is greater than zero and less than the number of included Children…	…then the learner’s Selection be will a subset of the included Children of size Count, in a random order.
			…and if the learner has an existing Selection containing components which still exist in the included Children…	…then those previously-selected components should remain in the Selection, unless it would make the Selection larger than Count, in which case the appropriate number of them should be randomly removed.

Open edX Community

Library Content Component User Stories