This solution covers how to programmatically import content into Learnosity's Item bank from an existing Item bank or product.
This solution is ideal for:
- Any client who has content created outside of Learnosity
- Have Item content stored in a way that can be exported
- Have a team of developers with the ability to convert the Items into Learnosity JSON
- Wish to take advantage of the Learnosity APIs without having to manually recreate all of their content
Example company & solution
A company, Dunder Mifflin, has an online assessment platform. The platform has already been built, and they have their own assessment tool which they've created themselves. Teachers can log on to create new content, and students can then take the created assessments. But Dunder Mifflin also has content created by their own in-house assessment experts.
Dunder Mifflin is looking to use the Learnosity APIs, to give their teachers and professional authors more options when it comes to Question types, and so they do not have to store all of the assessment information themselves. While they have confirmed the Learnosity APIs will meet their needs, their biggest concern is the conversion of their old content to their Learnosity Item bank. In total they have half a million Items, and don’t want to force their professional authors to re-author the content using Learnosity, nor do they want their teachers to be forced to stay on their old assessment tool, which they no longer want to support.
While almost all of Learnosity’s APIs are used for rendering an environment on the front-end, the Data API is Learnosity’s only API used as a back-end service. This allows Dunder Mifflin the ability not only to get all the information that Learnosity stores for them in its raw format, it allows a great deal of it to be written as well.
The process of converting Questions into Learnosity essentially comes in two steps: first, the content has to be converted into Learnosity format. Second, we can use the Data API to write all the Items to the Learnosity Item bank. Though this may be done in multiple steps, overall, here is the workflow:
For the sake of explanation, we’ll take each step of conversion individually.
At the moment, all of our Items exist in Dunder Mifflin's database. There are essentially three different “levels” of content that Dunder Mifflin would like to convert. The first is the actual Question -- taking that base level Question in its current form and converting it to Learnosity JSON.
While Learnosity provides a QTI conversion engine, the Questions are built in Dunder Mifflin’s own unique format, and so they’ve decided to write their own conversion script.
Examples and details of exactly how each Question is built in Learnosity is available within the Questions API documentation. Dunder Mifflin will start with their most common Question type: the multiple choice question (MCQ).
They write a conversion script in whatever language they’d like -- this pulls all the relevant Question data from their databases, removes all irrelevant information, and changes it to JSON in the format defined within the Questions API docs.
Now that it’s completed, we can write these formatted Questions to the Learnosity Database. We find the appropriate endpoint- in this case, the one for setting Questions. Dunder Mifflin, knowing that Learnosity SDKs allow for easy recursive calls to the Data API, find an SDK from the Learnosity GitHub repository to use. In this process, Dunder Mifflin will set a reference for each of these Items. They’ll save these references for later.
Once this set is complete, all of the multiple choice Questions we’ve imported exist on Learnosity’s Item bank exactly as if they were authored by someone using our tools. Dunder Mifflin now repeats this process, expanding their conversion script to work with all the different Question types and features that they used on their old assessment system. But they cannot be rendered yet, because they only exist as Questions on Learnosity’s side -- and all of Learnosity’s high level APIs render Items, rather than individual Questions.
Items are containers that can contain multiple Questions or Features- for some of Dunder Mifflin’s multipart Questions, they may have more than one Question to an Item. There also may be some Items with Features, like video players and passages, that can go into Items as well. So Items could look like any of these:
Once the Questions have finished being imported, it’s time to put them inside of Items so they can be rendered and tested. This time, they use the Set Items endpoint. They’ll look up the Item definition documentation to make sure they’re placing it into each correctly. While most of Dunder Mifflin’s Questions will be put into their own Items, some of their Questions are multipart Questions, so they can combine them into one Item within this step. They’ll use the references set in the Questions import process that they saved.
With this process completed, each Item can be rendered exactly as if it were authored within Learnosity’s Author API. Dunder Mifflin’s content experts can check on some Items, making sure that the Questions are rendering as expected and are displayed correctly within their Items. It may be at this point that Dunder Mifflin needs to update their conversion script with changes, should any information be missing or misaligned.
But from this point on, the Items can be referenced like any other Item:
This may be the end of the import process for some companies who simply want to recreate their Items into Learnosity’s Item bank. But Dunder Mifflin has one more step, as they also want to combine their Items into Activity templates. Activity templates are sets of Items that can be rendered as one individual test, allowing them to be referenced by one Activity template ID, rather than an array of Item references.
So, they have one more call to make -- using the references of the Items set in the previous process, they use the Set Activities endpoint:
With this final process completed, they can check their work- using either the Author API in Activity builder mode, or by signing on to Learnosity’s prebuilt Author Site.
Return to the index of technical solutions.