Configure Learn steps

This runbook is for Program Managers wiring a Learn step to a NextStreet course on a Goal that's already been added to a Program. By the end you'll have a Learn step a supplier can launch and complete on their action plan.

Prerequisites

Before you start, confirm:

• The Program and Goal already exist (visible under the Goals and Programs nav in /admin)
• The course you want to attach exists in the NextStreet API and you have its UUID handy. The Learn step's externalCourseId must be a real NextStreet course UUID — synthetic IDs (used in scenario test seeds, e.g. scenario-course-…) render a stub on the supplier side and SCORM playback won't work against them.
• You're logged into AdminJS at /admin with role admin or programManager

Concept map

The supplier sees the course only when both the LearnStep.externalCourseId (or its program-specific override) AND a matching ProgramCourse row exist. Missing the ProgramCourse license blocks the course-fetch authorization gate.

Walkthrough

1. Create the Learn GoalStep

In AdminJS, navigate to Goals → Goal Steps → New and fill in:

• Goal — pick the goal you're configuring
• Type — LEARN
• Title and Description — supplier-facing copy
• estimatedTime — text shown next to the Clock icon (e.g. "20 min")
• displayOrder — controls render order on the supplier's learning path; pick a value that fits the goal's existing sequence
• isActive — true (publish)

Saving creates the GoalStep and an empty LearnStep extension row linked to it.

2. Attach the NextStreet course

Open Goals → Learn Steps, find the row whose goalStep matches the step you just created, and edit:

• externalCourseId — paste the NextStreet course UUID (use the Course Select picker, which validates against the NextStreet API)
• resourceSegment — optional grouping; set if you want this step bucketed in a particular Resource Hub category

Save. The form will surface a validation error if you try to create more than one Learn step record for the same Goal Step.

3. License the course to the program

Each course must be explicitly licensed to a program before suppliers in that program can fetch it. Navigate to Program Relations → Program Courses → New and fill in:

• Program — the program the supplier is enrolled in
• externalCourseId — the same UUID you set on the Learn step
• Status — ACTIVE

Save. Re-saving the same (Program, externalCourseId) pair surfaces a validation error rather than creating a duplicate. Skipping this step blocks the supplier from launching the course — they'll see an authorization error.

4. (Optional) Override the course per program

If a specific program needs a different course than the Learn step's default, create a ProgramLearnStepCourseOverride record:

• LearnStep — the step
• Program — the program that should see a different course
• externalCourseId — the override UUID

The supplier's resolver picks the override when a row exists for (learnStepId, programId); otherwise it falls back to LearnStep.externalCourseId. Don't forget to also create a matching ProgramCourse row for the override course in the same program.

5. (Optional) Wire pre/post questionnaires

Same flow as Coach steps. Create a Questionnaire record under Goals → Questionnaires, then edit the GoalStep from step 1 and set preQuestionnaireId / postQuestionnaireId to the questionnaire's id. The pre-questionnaire blocks course launch until completed; the post-questionnaire blocks step completion until completed after the course.

6. Sanity check as a supplier

Log in as a supplier in the program, navigate to the goal's learning path, and open the Learn step. The course thumbnail, title, description, and duration should render via the Course details drawer. The "Start Course" CTA should launch the SCORM player without error.

If the course details fail to load:

• Re-check the externalCourseId is a valid NextStreet UUID (not a synthetic test ID)
• Re-check the ProgramCourse row exists and is ACTIVE
• Verify the supplier's SupplierOrganization.programId matches the program you licensed against

Common pitfalls

• Synthetic course IDs — placeholder course IDs (e.g., scenario-course-… used in test seeds) are not real NextStreet UUIDs. The drawer will render with placeholder data, but SCORM playback fails because the placeholder is missing the actual course content. Always use real NextStreet UUIDs in production / dev orgs you'll actually click through.
• Missing ProgramCourse row — supplier sees an authorization error when launching the course. Always pair "create LearnStep" with "create ProgramCourse for the program(s) that should see it".
• Forgetting the override's license row — when you set ProgramLearnStepCourseOverride.externalCourseId = X, you ALSO need a ProgramCourse row for that override course id, or the override resolver will silently fall back to "no licensed course" and hide the step.
• Goal step displayOrder collisions — two steps with the same displayOrder produce non-deterministic ordering on the supplier's learning path, which can cascade into unexpected "locked" states.
• Questionnaire FK fields are hidden in the AdminJS GoalStep edit form — relations show in the detail/show view, but to attach you have to set preQuestionnaireId / postQuestionnaireId on the GoalStep record directly.

Quick reference

• Related runbooks: Configure Do steps, Configure Coach steps