Import
- Dave Ormsbee (Axim)
This concept of Import is being implemented for the new Libraries experience, and is not consistent with how this feature works in Courses.
This kind of documentation is something that we’re experimenting with, following Essence of Software notion of concepts. See the tutorials for more info on what each of these sections means.
Related Concepts
Course, Library, Export
Purpose
Allow content to be rapidly added and updated from external sources, such as other courses, libraries, GitHub repositories, and other authoring systems.
Operational Principles
After an import is created, authors can adjust various parameters (e.g. types of content to import, what collections to add the imported content to) and preview the expected effect that it will have on the destination library.
After an import has completed, authors can review a summary of what the import changed, as well as any unexpected errors that happened during the import.
After an import has completed, an author may revert the effects of an import and restore the library to its pre-import state.
State
destination
source
configuration
import filters
destination collections
auto-publish (auto-publish if no errors?)
owner
status
created
manifest extracted
staged
running
complete
reverted
summary
errors
Actions
Notes
Error Handling
Unrecognized Content
Different sites may be customized to support different content types. If we receive such content, our approach is to add the raw OLX data and assets, but to display a generic error message when trying to work with that content later in the library.
Malformed Content
Question: What do we do with content that we know is broken, e.g. a ProblemBlock defined with broken XML? Import it in its broken state, but flag it as an error? Refuse to import the broken item, but allow the rest of the import to succeed? Fail the import as a whole to keep the import operation atomic? If we do decide to skip the broken item but allow the rest of the import to succeed, do we also skip everything that referenced the broken item, e.g. all containers it was in?
Imports are Add/Update for Libraries (NOT Replace)
Course imports currently work by completely replacing the course with the contents of the import. The import tar file for courses includes both the draft and published versions of all course content.
When importing into a library, the content is treated as an add/update operation, creating new versions of that content in the library as necessary. No content is deleted from the library as a result of an import. Content that is imported into a library also does not encode multiple versions of itself–they are treated as add/updates to the draft versions, and optionally published after import.
Supplementary Purposes of Course Import
The course import feature in Open edX currently also serves other purposes, partly to get around feature shortcomings. I include them here to note that they exist, but I don’t believe they are the primary purpose of this feature. These represent distinct problems that can be solved in other ways:
Efficient Bulk Editing
There is currently no good on-platform method of doing something like a bulk search-and-replace across an entire course or library. Users have found it easier to create an export, run replace-all in their text editor, and re-import to make those changes.
Backup/Restore (Same Site)
Imports can be used as a way to back up courses and legacy libraries, and restore them in the case of a disastrous user error. This shouldn’t be necessary with better undo/revert capabilities.
Cross-site Syndication
Sometimes a course or library is needed across multiple instances of Open edX, because similar content is being used by multiple groups of people to teach different audiences. These courses are periodically re-exported from the source site and re-imported on destination sites, as the content is updated.
Advanced OLX-only Features
Historically, some advanced features cannot be accessed through the normal Studio editors, and would require manual editing of the OLX XML format of our content files, followed by an import.
Open Questions