What editWizard is, and the rule that decides whether to use it

editWizard is a widget that groups several independent edit pages behind one navigation pane, with an optional review page and an optional confirmation page. Nothing is saved until the user clicks OK at the end. At that point the wizard submits the outbound endpoints of every step together.

Workday's documentation sets the deciding rule: you can't pass data from one step to another. A step can't use what an earlier step will create, or data an earlier step loaded. If step 3 depends on what the user picked in step 1, editWizard is the wrong tool and a flow is the right one (see below).

How to build one

The wizard is the only tag in the presentation body of a view page. Each entry in editTasks points at an edit page by its taskId from the AMD:

{
  "id": "equipmentRequestWizard",
  "presentation": {
    "pageType": "view",
    "body": {
      "type": "editWizard",
      "id": "equipmentWizard",
      "title": "Equipment Request",
      "subtitle": "<% worker.descriptor %>",
      "summarySettings": { "enabled": true, "label": "Review and Submit" },
      "conclusion": {
        "task": { "taskId": "equipmentRequestDone", "parameters": { "workerId": "<% queryParams.workerId %>" } }
      },
      "editTasks": [
        { "label": "Device", "task": { "taskId": "equipmentDevice", "parameters": { "workerId": "<% queryParams.workerId %>" } } },
        { "label": "Accessories", "task": { "taskId": "equipmentAccessories" } },
        { "label": "Remote work details", "render": "<% queryParams.isRemote ?: false %>", "task": { "taskId": "equipmentRemote" } },
        { "label": "Delivery", "task": { "taskId": "equipmentDelivery" } }
      ]
    }
  }
}

The documented constraints:

  • Every editTasks entry must be an edit page. Each renders embedded in the wizard.
  • At most 10 tasks can be active. You can list more, as long as no more than 10 render at run time, which lets render switch steps on and off per user.
  • Each step can use any widget except editButtonBar.
  • You can't use flows inside an editWizard, and you can't use an editWizard inside a flow.
  • An app can have at most 15 editWizard widgets and flow definitions combined (Reference: Limits on Presentation Components).
  • Don't make an editWizard page a navigation task in a hub. Workday allows it only as an additional link.

Getting data into each step

Steps can't read each other, but each step can receive the same starting context. parameters on a task are PMD script values that arrive in that step as queryParams. Pass anything every step needs, such as the worker ID, the record being edited or a mode flag, through parameters from the wizard page's own queryParams or endpoints. Each step then loads what it needs from its own inbound endpoints.

This is also why conditional steps use render rather than branching logic. The condition must be known when the wizard page loads, from query parameters or the wizard page's endpoints, not from an answer the user gives in a step.

The wizard draws title and subtitle at the top of a collapsible navigation pane listing each task's label. On smaller displays the list renders as a dropdown. Users move with the next and previous buttons or by clicking a task. Moving between steps caches the entered data on the server without submitting it. If the user leaves the wizard without clicking OK, Workday discards the data, unless saving is on (next section).

Workday warns about performance here. Because everything submits at the end, many widgets and outbound endpoints per step slow the wizard down, and you should keep it to no more than two or three grids across all steps, so the cache doesn't grow large. If a step's grid needs per-row checks, grid validation in Extend covers them.

Save for Later and autosave

Set enableSaving to true to turn on both a Save for Later button and automatic saving of the current step. You can't have one without the other. Each step page must use section as its top-level container. Workday then stores the draft for 30 days, which isn't configurable.

The details that matter in production:

  • The draft is tied to the user's session, not to a worker or an inbox task, and only one draft exists per session. A wizard meant for processing several employees in turn can't hold a draft for each.
  • A saved draft overrides defaults and values filled in from endpoints. A user who returns sees their draft, not refreshed data.
  • Drafts are keyed by the id of the wizard page, each step page and every widget on each step. Every tag needs a unique id, and a tag without one causes a validation warning. Changing any of those IDs after deployment loses users' drafts.

The review page

summarySettings.enabled defaults to true, so a wizard shows a review page unless you turn it off. Its sidebar label defaults to Review and Submit. The review page shows every field from every step as a view page would. Widgets with no view-page form are converted to a close counterpart; Workday's example is a checkBoxList rendering as a list of text values. Check the review page with real data for each widget type you use, because what a user approves there is the converted view.

The confirmation page after OK

conclusion names a view page the wizard redirects to after the user clicks OK, typically a message that the request was submitted, with parameters to tell it what was saved. Without conclusion, or with its render set to false, the wizard returns to the last viewed page.

App Preview doesn't redirect to the conclusion page. The redirect happens only in the tenant. A conclusion page that "doesn't work" in App Preview is behaving as documented, so test it in the tenant.

Workday documents parameters as the only way to pass data to the conclusion page, and says nothing about handing it the IDs of records the submit created. Design it to look the result up, for example by worker and most recent request, or to show a message that doesn't need the new ID.

Validation inside the wizard

Use errors, not warnings. Workday states that editWizard doesn't support warnings: a setWarning call shows up as an error when the wizard submits. The rest of the validation model is the same as on any edit page, so clear every error from an onChange handler or the user can get stuck. Extend onSubmit and onChange validation has the pattern.

Because all steps submit together, a rejection from one step's outbound endpoint lands after the user has finished every step. Validate on each step whatever can be checked there, so the final OK rarely fails.

When to use a flow or multiStepLayout instead

Choose by the dependency between steps:

  • Steps that depend on each other need a flow. A flow is defined in flowDefinitions in the AMD. Each step's edit page can pass values forward with an outboundVariable whose variableScope is flow, and later steps read them as flowVariables. Transitions are ordered conditions, so a flow can branch on what the user entered. Each step submits its own outbound endpoints when the user clicks OK on it, and a flow can end on a view page as its confirmation.
  • Independent steps that should be reviewed and saved as one transaction are what editWizard is for.
  • One form that's too long for a single screen fits multiStepLayout. It splits a single page into up to 10 numbered steps of layoutSections, works on view and edit pages, and submits as one page. All widgets are on the same page, so later steps can reference earlier ones.

Testing the wizard in the tenant

Test in the tenant, not only in App Preview, because App Preview skips the conclusion redirect.

  1. Fill every step, go back to step 1, and confirm your entries are still there. Then leave the wizard without OK and confirm in the app's data that nothing was created. With enableSaving, confirm instead that reopening restores the draft.
  2. Submit, and confirm the conclusion page appears with the right parameters.
  3. Read back each record the steps were meant to create or update, one per outbound endpoint. One missing record means that step's endpoint was excluded or failed. The page error and Analytics > Logs on the Workday Developer Site show which one; Workday Extend page errors explains how to read them.
  4. If any step uses render, repeat as a user for whom it's hidden and confirm the wizard neither shows nor submits that step.

Sources checked