Configure Do steps

This runbook is for Program Managers configuring a Do step on a Goal that's already been added to a Program. Do steps come in two flavours — internal (in-platform SurveyJS form) and external (outbound link to a third-party resource). The wiring differs slightly between the two.

Prerequisites

Before you start, confirm:

• The Program and Goal already exist (visible under the Goals and Programs nav in /admin)
• For internal Do steps: you have the SurveyJS schema ready (or are going to build it inside AdminJS)
• For external Do steps: you have the outbound URL and a friendly source/provider label
• You're logged into AdminJS at /admin with role admin or programManager

Concept map

The supplier sees the Do step only when both the Tool is attached AND a matching ProgramTool row exists for the program. Missing the ProgramTool license blocks the supplier's view of the step.

Walkthrough — Internal Do step

An internal Do step renders an in-platform SurveyJS form the supplier fills out without leaving the app. Their answers are stored in ToolResponse.

1. Create or pick a Tool

Navigate to Resources → Tools → New (or pick an existing one). The custom Tool form shows different fields depending on type:

• name, description, estimatedTime (minutes), tags — apply to both types
• type — set to INTERNAL
• surveySchema — opens the SurveyJS editor; build the form here. Required for internal tools.

Save. Re-saving on edit creates a NEW Tool rather than mutating the existing one (you'll see a confirmation modal). This is intentional — it preserves response history against the original Tool.

2. License the Tool to the program

Navigate to Program Relations → Program Tools → New:

• Tool — the one from step 1
• Program — the program the supplier is enrolled in
• Status — ACTIVE

Save. Unique on (toolId, programId).

3. Create the Do GoalStep

Navigate to Goals → Goal Steps → New and fill in:

• Goal — pick the goal
• Type — DO
• Title and Description — supplier-facing copy
• estimatedTime — text shown next to the Clock icon (e.g. "15 min")
• displayOrder — render order on the supplier's learning path
• isActive — true

Saving creates the GoalStep and an empty DoStep extension row.

4. Link the Tool to the GoalStep

Open Goals → Do Steps, find the row whose goalStep matches step 3, edit it, and set:

• Tool — pick the Tool from step 1

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

5. (Optional) Wire pre/post questionnaires

Same as Learn / Coach. Create a Questionnaire, then set preQuestionnaireId / postQuestionnaireId on the GoalStep record from step 3.

6. Sanity check

Log in as a supplier in the program. The Do step should expand on the action plan with a "Start" button that opens the SurveyJS form. After submit, the step transitions to IN_PROGRESS, the supplier can edit their response, and finally mark complete (or complete the post-questionnaire if configured).

Walkthrough — External Do step

An external Do step is just a vetted outbound link — clicking the CTA opens a third-party site in a new tab. Used for "go read this article" / "register for this webinar"-style assignments.

1. Create or pick a Tool

Navigate to Resources → Tools → New:

• name, description, estimatedTime, tags — same as internal
• type — set to EXTERNAL (the form switches to show external-only fields)
• externalUrl — the outbound URL the supplier will be sent to
• source — provider label, rendered as "Source: <source>" in the supplier's Resource details drawer (e.g. "U.S. Small Business Administration")
• isLicensed — see the Third-party disclaimer section below

Save.

2. License the Tool to the program

Same as internal — navigate to Program Relations → Program Tools → New and create a (toolId, programId) row with status = ACTIVE.

3. Create the GoalStep + DoStep

Same as internal (steps 3–4 above), but the supplier-facing surface differs:

• The action plan card surfaces a View Details button that opens the Resource details drawer with the description and source.
• The Visit Resource CTA opens the outbound URL in a new tab.

4. Sanity check

Log in as a supplier and click both View Details and Visit Resource. Confirm:

• Drawer shows the right title, source, and description
• Clicking Visit Resource opens the URL in a new tab
• If isLicensed = false, the third-party disclaimer modal appears before the URL opens (see next section)

Third-party disclaimer: the isLicensed flag

For legal reasons, suppliers see a disclaimer modal ("Before you continue…") before navigating to a third-party site that NextStreet has not licensed. The Tool.isLicensed flag controls this:

Set isLicensed = true only for resources that NextStreet has a contract / license / partnership with. When in doubt, leave it as false — the modal is the safe default.

The same flag exists on Event.isLicensed for outbound event registration links (configured in Resources → Events).

Common pitfalls

• Missing ProgramTool row — supplier doesn't see the step at all. Always pair "create Tool" with "create ProgramTool for the program(s) that should see it".
• Wrong tool type — saving an EXTERNAL tool with a surveySchema (or vice versa) won't break, but the irrelevant fields are ignored on the supplier side and confuse later editors. The Tool form already hides the irrelevant fields once type is set; don't fight it.
• isLicensed defaults to false — that's correct, but easy to forget when wiring a known-licensed partner resource. The supplier will see an unnecessary disclaimer if you don't flip it.
• Editing an internal Tool clones it — by design, but don't expect the existing Do steps to pick up the new schema unless you re-link them in step 4 of the internal flow.
• Goal step displayOrder collisions — two steps with the same displayOrder produce non-deterministic ordering and 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 Learn steps, Configure Coach steps