CoursePlan Import
There are two ways to get a fully-structured course into ZəkaHouse: describe it to the AI Course Creator and refine what comes back, or hand ZəkaHouse a finished plan as a JSON file and skip the AI step entirely. This page covers the second path — CoursePlan Import.
The AI-assisted path, for contrast
Normally, creating a course with AI is a conversation: an admin or teacher describes what they want in the AI Course Creator, gets back a streamed, AI-drafted plan — chapters, activities, assignments — refines it back and forth in chat, and only then finalizes it into a real course. Every draft passes through a model, and every finalize call turns whatever the conversation ended with into the course, chapters, and activities that get created.
The CoursePlan Import path
CoursePlan Import takes the same underlying course structure — name, description, chapters containing activities, activities containing assignments and tasks — but supplies it directly as a .json file instead of drafting it through chat. No AI call happens anywhere in this path:
Because there is no model in the loop, there is nothing for a model to truncate, paraphrase, or quietly alter. Whatever is in the file is exactly what gets created.
How it works
- From Courses → Import, choose Structured Plan (as opposed to ZəkaHouse Courses, the other option there — that one re-imports a
.zippackage previously exported from ZəkaHouse, a separate mechanism from this one). - Upload one or more
.jsonfiles matching the CoursePlan structure. Each file is parsed and checked immediately: valid files show their chapter and activity counts; anything that isn’t a CoursePlan at all (missingnameorchapters) is flagged and excluded up front. - On the review screen, each file gets its own row with a checkbox, its chapter/activity counts, and a warning if its course name collides with a course that already exists in the organization — collisions are unchecked by default so you don’t create an accidental duplicate, but you can check the box to import it anyway. If the plans name images or audio, you can pick those files here too.
- Click import. The selected files are uploaded to the server, one request per file, and the import is handed to a server-side job. Keep the window open only for this upload; a dropped connection retries the file that was in flight, not the whole batch. The server checks each file again as it arrives, and refuses one whose course, chapters, or activities lack a
name(atitlekey is not read as one). The refusal says which, for exampleChapters with no name: 1, 2., and the other files go ahead. - From then on the server builds the courses. You can close the dialog, the tab or the browser, put the laptop to sleep, or lose your connection: the import carries on.
Following an import
Every import has its own page under Courses → Imports (/dash/courses/imports), listing each plan with its outcome: created (with a link to the course), waiting, or failed with the reason. While an import runs:
- the Studio header shows its progress on every dashboard page, and a short message appears when it finishes;
- the Courses page shows it above the course list, and new courses appear there as they are built;
- if it ran for more than a minute, the person who started it gets an email when it is done.
Org admins and maintainers see every import in their organization. Anyone else who can import sees the imports they started.
Steering an import
Controls act between courses, never in the middle of one, so a course is always either fully built or not started:
- Pause / Resume — stop after the course being built, and pick up later from the next one.
- Cancel — stop after the course being built; every course already created stays created, and the rest are skipped.
- Retry — after an import ends, run it again for every plan it did not create. Courses already created are left alone.
If a CoursePlan’s assignment tasks reference media files by name (an audio prompt, a reference image, the course cover), the import matches them by file name, ignoring case. Files you add on the review screen are uploaded with the plans. Anything still missing is listed on the import’s page with an Add files button: courses already built get the file at once, courses not built yet get it when their turn comes. Uploaded files are kept for 7 days after an import ends; after that it can no longer be retried.
One import holds one file per name. If two plans each ship their own cover.jpg or listening_01.mp3, every course in that import gets the same file, so give different files different names (for example aslan_cover.jpg, toplu9_listening_01.mp3). The review screen warns when you pick a different file under a name already picked. A cover must be a JPG, PNG, WebP, or GIF: SVG files are refused, and a refused file is listed with its reason when the upload ends.
When something goes wrong on the server
The import does not depend on any one server process. If the process running it stops — a deploy, a restart, a crash — another one picks the import up where it stopped. A course that was half-built when that happened is removed and built again from its plan, so a plan never ends up as two courses. A plan the server refuses (no permission, a plan limit reached) fails at once, with the reason; one that fails for a reason that may pass is tried up to three times. Either way the import moves on to the next plan.
What can change during import
The course always finishes building. When ZəkaHouse cannot build something exactly as your file describes it, it builds the closest thing it can and tells you on the import’s page, under each course, grouped by reason, with the activity names. It never fails halfway and leaves a half-built course.
| What the dialog says | What happened | What to do |
|---|---|---|
| Questions were not imported because no answer option is marked correct | A quiz question that has text and options but marks no option correct is skipped on purpose: it would mark every answer right. This is by far the commonest cause when a book is converted to a plan, because the answer key often sits in a separate section. | Put the correct answers into the plan file (is_correct: true on the right option) and import again, or add those questions by hand. |
| Assignments were cut to the first N tasks | An assignment is built from at most N tasks; later ones were not created. N is set by the operator with LEARNHOUSE_IMPORT_MAX_TASKS_PER_ASSIGNMENT (default 500, never above 5,000). | Raise the setting, or split a long exam into several assignments in your file. |
| Assignments became content pages because the assignment limit was reached | The API refused to create the assignment with a 403, which is how a plan limit on assignments is reported (not every deployment enforces one). The activity exists as a content page and its tasks were not created. | If you have an assignment limit, free up assignments and import again; otherwise check your role’s permissions. |
| Assignments could not be created | The assignment was refused or failed to save. It is a content page. | Check the activity in the editor and re-add it. |
| Assignments were created with no usable tasks, or some tasks could not be read or saved | A task could not be read or failed to save. | Open the assignment and add or fix the tasks. |
Quiz, form, short-answer and number-answer tasks that your file gives without content are not an error: they are planned as shapes and filled in later, from the Content tab.
When to reach for this instead of the AI Course Creator
CoursePlan Import is for anywhere exact, reproducible output matters more than a conversational draft:
- Migrating a known curriculum you’ve already got structured elsewhere.
- Scripted or bulk content generation — generate CoursePlan JSON with your own tooling (or your own call to a model, if you want AI involved on your terms) and import the result deterministically.
- Re-importing a course plan you exported, generated, or hand-authored previously, and want recreated exactly as written.
If you’d rather describe a course in plain language and iterate on an AI-drafted outline, use the AI Course Creator instead — see AI for Teachers.
Who can do this
Starting a CoursePlan import requires the same course-creation permission the AI Course Creator’s finalize step requires — Instructors, Maintainers, and Admins by default, or any custom role granted courses create access. The import runs as the person who started it, and their permission is checked again for every course: if they lose it while the import runs, the import stops.