Skip to main content

Step Handles

A step handle represents an interface to a specific step in a workflow. Steps can have many different types. There is a small amount of common functionality always available on a step handle. You can also ask a step handle for a type specific context to interact with type specific functionality as well.

There are several approaches for you to obtain a step handle. Below are three common ways. In situations where a step may not be found, expect an undefined value instead.

// This will return the step handle for the step in the workflow with this configured name.
const stepByName = workflowExperience.getStepByName("Choose a color");

// This will return the step handle for the step in the workflow with this unique identifier.
const stepByIdentifier = workflowExperience.getStepById("1234-5678-9012-3456");

const steps = workflowExperience.getSteps();

Common Functionality​

There are a number of functions available on all step handles. These are useful for obtaining information about the step and interacting with it. Each step also has type specific functionality

getId(): string​

Returns a unique identifier for the step. This is unique for the step within the workflow and may be used as a reference to obtain the step later elsewhere in your code.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const id = step.getId();
console.log(id);

getName(): string​

Returns the name configured for this step in the workflow. This can also be used to obtain the step handle via getStepByName, this practice is not recommended though as the name is not uniue. The first step will always be returned.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const name = step.getName();
console.log(name);

getHelpText(): string​

Returns a message that can accompany the step name in UI components. Used to describe the purpose of the step in more detail.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const helpText = step.getHelpText();
console.log(helpText);

getType(): string​

Returns the type of the step. Useful for determining what type specific functionality would be required for the UI rendering this step.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
// DigitalContent, Frame, Illustration, Material, Model, Picture, Question, Shape, SilentIllustration, Text
const type = step.getType();
console.log(type);

getCurrentVariant(): Promise<Variant | undefined>​

Returns thhe currently selected variant for this step. Remember that a step may not have a variant selected. In this case, the function will return undefined. The call needs to be awaited to ensure the variant resolves.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const currentVariant = await step.getCurrentVariant();

getAvailableVariants(): Promise<Variant[]>​

Returns a list of variants that are available on this step. These can be used to render UI for the user to select a variant. The call needs to be awaited to ensure the variants resolve. Any variants that have been marked as disabled will not be returned in this list.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const variants = await step.getAvailableVariants();

getAllVariants(): Promise<Variant[]>​

Returns a list of variants that are available on this step, including ones that have been disabled. The call needs to be awaited to ensure the variants resolve. Use this function instead of getAvailableVariants() if you wish to display disabled variants as "out of stock", "unavailable", etc.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const variants = await step.getAllVariants();

selectVariant(v: Variant): Promise<void>​

Marks the supplied variant as the variant selected for that step. This function is implemented across all step handles via their interface. The behavior of this function is explained in more details within each of the step specific sections. The call should be awaited to ensure the variant is selected before continuing.

const step = workflowExperience.getStepById("1234-5678-9012-3456");
const variants = await step.getAvailableVariants();
step.selectVariant(variants[0]);

getTags(): string[]​

Returns the list of tags attached to this step.

hasTag(tag: string): boolean​

Returns whether the given tag is attached to this step.