Program Steps API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Create an article step

Use an article step when you want to add written content to a section.

To create an article step:

1. Create or identify the target program and section.
2. Call Create Step, specifying the section ID in step.sectionId and ARTICLE in step.stepType.
3. Specify the title in step.description.title and, optionally, rich text content in step.description.details.
4. Save the returned step ID for later update, move, or delete calls.

Add an image to a step

Step content is a Ricos rich content document stored as a JSON string in description.details. Images that should appear with the step belong inside that document. Images set anywhere else on the step aren't displayed.

To add an image to a step:

1. Upload the image to the site's Media Manager, or pick an existing file, and note its file ID, width, and height.
2. Retrieve the step with Get Step and parse the current description.details JSON.
3. Append a node with type set to IMAGE, a unique id, and an imageData object. In imageData, set image.src.id to the file ID, image.width and image.height to the file's dimensions, and altText to a description of the image. Set containerData.width.size to CONTENT and containerData.alignment to CENTER for the default layout.
4. Call Update Step with the step's current revision and the serialized document in description.details.
5. Use the returned step object to confirm the new revision and content.

Create a quiz step

Use a quiz step when you want the step to point to a separately managed quiz.

To create a quiz step:

1. Create or clone a quiz with the Quiz API.
2. Save the returned quiz ID.
3. Call Create Step, specifying the section ID in step.sectionId and QUIZ in step.stepType.
4. Specify the saved quiz ID in step.quizOptions.id.
5. Optionally specify the passing threshold in step.quizOptions.passingGrade.
6. Retrieve the created step with Get Step to confirm that it references the quiz.

Reorder steps in a section

Use move operations to change the sequence of steps. You can move a step within its current section or to another section.

To reorder a step:

1. Retrieve the target section's steps with Query Steps, filtering by sectionId and sorting by ordering.
2. Identify the step to move and the step that should come immediately before it.
3. Call Move Step, specifying the step ID, target section ID, and afterStepId.
4. To make the moved step the first step in the section, omit afterStepId.
5. Use the returned step object to confirm the new section and ordering values.

Update multiple steps in one request

Use a bulk update when you need to modify several steps together. Each update is processed separately and has its own result.

To update multiple steps:

1. Retrieve the current steps with Query Steps and save each step's latest revision.
2. Build a Bulk Update Steps request with one entry per step.
3. For each entry, include the step ID, latest revision, and the fields to update in a partial step object.
4. Set returnEntity to true if you need each updated step in the response.
5. Submit the bulk request and check the per-item results and bulk metadata in the response.