Workflow stage renderers

Workflow stage renderers determine how a workflow displays stages in a workflow field.

There are multiple renderers available.
Note: Most workflows should use the workflow-driven renderer. This renderer is used by default for all workflows. Use a different stage renderer only after careful consideration and to satisfy specific requirements for how the stages appear.

Workflow-driven

Use the workflow-driven renderer as much as possible. This renderer displays icons for stages using the stage state controlled by the workflow. Icons are displayed in a way that is meaningful for many situations. This renderer can display stages from a main workflow and subflows. The order of the icons is determined by the expected path of the executing workflow. As the workflow progresses, stages on paths that the workflow did not take are removed from the display. Stages from paths other than the expected path are not included unless the workflow follows that path.

The Stage order field on the Stages tab has two options:
  • Computed uses the actual workflow path in order
  • User-specified uses the order specified in the Order column on the Workflow Stages record

Main flow

The main flow renderer displays icons for stages defined in the main workflow only. Use this renderer when you do not want to expose the details of the subflows. For example, a single main workflow may run several subflows to handle implementation details. The stages in these subflows do not provide useful information for the user who starts the workflow, but are useful when editing the subflow. In this scenario, using the main flow renderer leads to the best user experience. The stage field displays the high-level process of the workflow without exposing unnecessary details.
The Stage order field on the Stages tab has two options:
  • Computed uses the actual workflow path in order
  • User-specified uses the order specified in the Order column on the Workflow Stages record

Linear

Linear rendering displays all stage icons from the main workflow and all subflows within a single workflow field on a list or form. It displays icons in a linear sequence regardless of the paths the workflow follows as it executes. This renderer uses stages defined in both the main workflow and any subflows that the main flow launches. The icons appear in the user-specified order. Skipped stages do not appear.

Use this renderer when the workflow stages must display in a consistent order and the actual details of how the workflow runs are less important. For example, a workflow may revisit or revert to previous stages based on one or more Condition workflow activities. Displaying these loops in the stage field does not provide useful information to the user. In this scenario, using the linear renderer leads to the best user experience. The stage field displays the predefined process, including stages from subflows, in a consistent order.

For example, you can create a service catalog workflow that uses a subflow to complete delivery of the requested item. The following images illustrate the main flow and subflow for ordering corporate-branded supplies.
Figure 1. Linear main flow
Figure 2. Linear subflow

The linear renderer displays all these stages in one workflow field. The parent workflow specifies the Waiting for approval, Fulfillment, and Completed stages. The subflow specifies the Delivery and Waiting for Task, and Delivery OK stages.

Progress bar

The progress bar renderer displays a single progress bar instead of a sequence of stage icons. This renderer is particularly useful when you want to display the general progress of the workflow as a percent. Each stage in the workflow controls an equal percentage of the progress bar. For example, if a workflow has 10 stages, reaching each stage causes the workflow field to display an additional 10% of the progress bar. Stage names do not appear in the progress bar.

The progress bar renderer provides a way to display the status of a workflow that has a large number of stages. Other rendering options may provide a better user experience when rendering fewer than four stages in a single workflow.

The Stage order field on the Stages tab has two options:
  • Computed uses the actual workflow path in order
  • User-specified uses the order specified in the Order column on the Workflow Stages record
Figure 3. Workflow field progress bar

Legacy

The legacy renderer displays stages in the same way as releases prior to Dublin. When an instance is upgraded from a release prior to Dublin, all existing workflows are set to use the legacy renderer. Whenever possible, use a different stage renderer instead. If you want your workflow to maintain pre-Dublin behavior, use the Legacy option. The legacy renderer sometimes assigns incorrect data to and/or reports incorrect data from the workflow stage field. If possible, we recommend all workflows use the Workflow-driven renderer.

With the legacy renderer, you can create and reference a custom workflow field icon set by setting the icons attribute to a new script include. For example, to use the WorkflowIconsSCR script include to define which icons to use, add the attribute icons=WorkflowIconsSCR to the Attributes field of the dictionary entry for the workflow field. To use the default icon display behavior, use the attribute icons=WorkflowIconsStages.

The legacy renderer works with all tables except the Requested item [sc_req_item] table. In this case, use the requested item renderer instead.

Requested item

The requested item renderer functions the same way as the legacy renderer, but is for use with the Requested item [sc_req_item] table.