update-course-content

Files (2)

• SKILL.md
• update-course-content.js

SKILL.md (first lines)

# Update Course Content

This is an **Action** skill — a single, unambiguous API call. It is deterministic and narrowly scoped.

## Endpoint

`PUT /incoming/v2/content/course/update`

## When to use

- Updating the body of existing topics (e.g., after rewriting a lesson).
- Changing titles, positions, or metadata of sections/lessons/topics.
- Adding new child nodes (omit `id` to create under an existing parent).
- **Retiring test/junk content** — TI has **no delete endpoint**, so set a **course (session)** to `status: "archived"` here (this does not remove the parent course group). See [Removing content](#removing-content).

> **Updating pre-existing content is fully supported** — it is not limited to content you created in the same session. The only prerequisite is the correct topic/section/lesson **UUID**. Do **not** fall back to "edit it manually in the TI admin UI" just because the content already existed. The supported end-to-end flow for existing content is:
>
> 1. **`resolve-content`** — turn a course/lesson/topic title or admin URL into UUIDs.
> 2. **`get-full-content`** — read the current topic `body` (this is the only read endpoint that returns body; `get-topic`/`get-topics-by-lesson` do not).
> 3. **`update-course-content`** — PUT the changed topic(s) by `id`. This is a verified round-trip.
>
> The manual-in-TI fallback is only appropriate for the genuine limits below — never as a substitute for a supported update.

## Agent instructions

This endpoint does double duty:

- **Update** an existing entity → include its `id` (UUID). Only the fields you pass change. Use read actions first to obtain IDs.
- **Create** a new child under an existing course → **omit `id`** and instead supply the **parent link** (and, for topics, a `type`):

  | Creating a… | Omit `id`, then supply | Also required |
  |-------------|------------------------|---------------|
  | course (under a group) | `courseGroupId` | — |
  | section | `courseId` | — |
  | lesson | `sectionId` | — |
  | topic | `lessonId` | `type` (e.g. `text`) |

  Do **not** invent field names like `parentId` — the API only recognises the parent keys above. This is the correct way to "attach a section/lesson/topic" to a course that already exists.

  **New topic `type` must be lesson-safe.** Use `"text"` for HTML body content. Do **not** use `"article"` (or other standalone-only types) for a topic attached to a lesson — the API accepts it but the learner view 404s and the editor cannot open it, and there is no delete action to recover. The script blocks this locally.

1. Run `update-course-content.js --dry-run --file=update.json` first to validate — the script now fails locally with a precise message if a create is missing its parent link or a new topic is missing `type`, or if a video's source is in the wrong field.
2. Then run without `--dry-run`.
3. Confirm `restartProgress` semantics with the user if replacing SCORM on an existing topic.
4. To set/replace a **video**, target the topic by `id` with `videoAsset`/`videoUrl` — never an embed in `body`. See [Video content](#video-content).

## Limits

- The update payload is an **object** (not an array like create). It contains optional arrays: `courseGroups`, `courses`, `sections`, `lessons`, `topics`.
- Up to **100 items** total across all arrays combined.

### One payload, multiple arrays

You can mix `courseGroups`, `courses`, `sections`, `lessons`, and `topics` in a single payload, and mix different fields per item (e.g. one topic changing `title`, another changing `body`). The script always sends this as **one request**.

Historically, some server versions applied each entity array as **one SQL statement built from the union of all fields in that array**, which failed with an opaque `HTTP 400 — "A processing error occurred. Please refresh the page and try again."` whenever the update items in a single array didn't all carry the **same set of fields**. (This was a server bug, not entity-type mixing — two topics in one array, one with only `title` and one with only `body`, reproduced it on its own. It is fixed server-side.)

To stay compatible with instances that haven't picked up the server fix yet, `update-course-content.js` uses a **fallback**: it sends the combined request first (atomic, and the only request needed on a fixed server); only if the server rejects it with that specific legacy processing error does it retry by splitting the payload into the minimum number of sequential requests (parent→child order), grouping update items so each request's arrays are field-uniform. Use `--dry-run` to preview the combined request and, if relevant, the fallback split.

On a fixed server the update is a single atomic request. On the fallback path, updates are re-sent per group and are idempotent, but are **not atomic**; if a fallback request fails, the error names which entity arrays and ids were involved and how many earlier fallback requests already applied.

### Genuine limits (when manual TI editing IS the right answer)

These are the only cases where "do it in the TI admin UI" is legitimate — plain text/HTML `body` edits are **not** among them:

- **Publishing.** This action never releases content; a human publishes drafts in TI (see hard gate).
- **Quiz/assessment questions & answers.** `body` is HTML page content; it does not edit structured quiz questions, options, or scoring.
- **SCORM / media file uploads.** Binary uploads use the separate content-upload flow, not a JSON `body`. Confirm `restartProgress` semantics with the user before replacing SCORM on an existing topic.

When you hit one of these, name the specific part that must be done in TI and still apply everything the API *does* support (e.g. the text body) rather than deferring the whole task to manual editing.

## Run the script

```bash
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/update-course-content/}update-course-content.js" --dry-run --file=update.json
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/update-course-content/}update-course-content.js" --file=update.json
```

## Payload shape

```json
{
  "topics": [
    { "id": "TOPIC_UUID", "body": "<p>Updated content here</p>" }
  ]
}
```

Or with explicit wrapper:
```json
{
  "courseAttributes": {
    "topics": [
      { "id": "TOPIC_UUID", "title": "New Title", "body": "<p>...</p>" }
    ]
  }
}
```

Attaching a new section → lesson → topic to an existing course (each level created bottom-up needs its parent's UUID; create the section first to get its `id`, then the lesson, then the topic — or add each level in separate calls):
```json
{
  "sections": [
    { "courseId": "COURSE_UUID", "title": "New Section", "displayOrder": 3 }
  ]
}
```
```json
{
  "lessons": [
    { "sectionId": "SECTION_UUID", "title": "New Lesson", "openType": "studentsOnly" }
  ]
}
```
```json
{
  "topics": [
    { "lessonId": "LESSON_UUID", "title": "New Topic", "type": "text", "body": "<p>...</p>" }
  ]

From thoughtindustries/ti-admin-plugin, MIT.

More from thoughtindustries/ti-admin-plugin