Generalized wizard state restore / resumption

[mahmoud]

Hey there! Getting more into XSW, I find myself wondering if there's a pattern for restoring the state of a wizard, e.g., if someone gets logged out mid-fill. Maybe not for the current field, but for past states, for instance. Any thoughts/examples appreciated!

[youmustfight]

There is @mahmoud ! You can see the TWizardSession type for details here. The XState machine's context has a specific schema TCreateMachineContext for tracking internal changes as the person goes through the form. This is what gets modified overtime, what you'll have access to in the methods below so you can persist to a db, and then what you can load back in. Under the hood it's being passed in the plain old XState createMachine method.

There are 2 vars and 3 methods on the <WizardRunner /> top level component you'll want to use in combination with backend endpoints to persist to a session (aka machine context with a schema) to the database:

• sessionEnabled: true/false for whether we run the commands below
• sessionRequestCheck: Async callback that should return either null or the session you want to load in. The two values provided to the callback are the machine "key" (aka machine id/label) and version, which you can include in your query to your backend (along with things like user id which you can pull from other stores/component props outside the callback's function scope.
• sessionRequestStart: Async callback that runs if there was no session returned by the check callback. This is how you can initialize a new "session" record in your database for the user.
• sessionRequestProgress: Takes a callback where on each state change you get access the machine context/JSON that you can either persist to an external database or even just local storage. Very important note here, this progress callback is not triggered when there is state progression in a spawned machine. This is the single most important thing I'd like to improve in this lib. This is not a blocking call. A user will progress and this will keep firing off in the background on each step. This also has access to progressPercentage which is a 0 to 1 value you can save and utilize in analytics.
• sessionForceNew: boolean for skipping sessionRequestCheck. This is helpful if answers may change frequently and you want to ensure prior answers are cleared, but you still want to keep records/state info for analytics purposes perhaps.

Here's a quick snippet of code for how I've done this in the past (chopping out lines of code for readability and focusing on the session callbacks). Also, before calling things "wizards" I was calling them interviews. I'd like to be consistent by just calling everything a wizard:

export const WizardRunner = (props) => {
  const { data: user } = useLoggedInUser();
  
  return (
    <WizardRunner
      configExitTo={props.configExitTo ?? "/journey"}
      debugConfig={{
        logging: true,
        skipSaves: user.isAdmin,
      }}
      models={upsolveWizardModelsMap}
      spellMap={preparedSpellMap}
      sessionEnabled={props.sessionEnabled ?? false}
      sessionForceNew={
        // hack: for webdriver tests, we ensure we're getting a fresh session
        props.sessionForceNew || window?.___FORCE_NEW_WIZARD_SESSION___
      }
      sessionRequestCheck={async ({ key, version }) => {
        const wizardSession = await axios
          .get("/v1/wizardSession/check", {
            params: {
              machineId: key,
              machineVersion: version,
              userId: user.id,
            },
          })
          .then((res) => res.data?.wizardSession);
        return wizardSession?.id ? wizardSession : null;
      }}
      sessionRequestStart={async ({ key, version }) => {
        const wizardSession = await axios
          .post("/v1/wizardSession/start", {
            wizardSession: {
              machineId: key,
              machineVersion: version,
              userId: user.id,
            },
          })
          .then((res) => res.data?.wizardSession);
        return wizardSession;
      }}
      sessionRequestProgress={async ({ wizardSessionId, machine, progressPercentage }) => {
        await axios.put(`/v1/wizardSession/progress`, {
          wizardSession: {
            machineContext: machine.context,
            machineState: machine.value, // cancel/save states should still be saved. we won't init from sessions w/ these machineStates
            id: wizardSessionId,
            endedAt: machine.done ? new Date() : undefined,
            progressAt: new Date(),
          },
          progressPercentage,
        });
      }}
    />
  );
};

One key detail about the backend is how you want to handle your session check. I use the SAVE_STATE and CANCEL_STATE constants as a way to know that we hit a done state and save a done timestamp in the database. So when you do a session check, you'll likely want to have a WHERE clause that filters out done states in addition to selecting for a session that relates to your user.

Thought I had this an example, but definitely can add one! Will call it react-wizards-session and have it call to localStorage so you can see that async funcs at play, and then will try to add a simple local storage viewer to see how the data changes over time.

[mahmoud]

Awesome. I stumbled upon the session type and figured it was related. Tangentially, right now I'm starting to use it to pre-set default values onto the context.

I half-expected TContentDefinition to have a default value field for inputs that write to the context, but sessions are the closest affordance I've found for that. Let me know if I'm way off base! 😅

[mahmoud]

Oh also, skipSaves needs to be false for session loading to work (not just saving).

[youmustfight]

Ohh, that's interesting. The way I've done default values is within the JSON schema that's associated with a spell. Though what you're doing is much more straight forward/cleaner than a schema object. I intended if we had a schema obj, we can do checks on inputs or something fancy but that's never really come about. So maybe an improvement for the future is to ditch the schema idea and just take default values at the top level sort of like what you're doing.

[mahmoud]

Haha, I actually do have the schema integrated, but the defaults weren't showing up for the context? I was actually thinking maybe this would work better if I switched to a wrapper model!

One of my concerns with using the context directly is that the top level of the context has a few keys that I don't want to conflict with, e.g., resources.