Make it easier to update form data from outside sources

[short000]

User story

As a VFS developer, I need the forms library to allow me to seed or update form data from outside sources so that I don't have to implement workarounds to avoid data sync and clobbering issues.

Additional details/notes/links

Paraphrasing @Mottie: for forms 526 (get discharge date from intro page wizard) and 996 (get contestable issues from a separate API endpoint), we obtain data before the form's first page (need to seed or initialize the form); however, it doesn't appear that updating initialData value (dynamically) works. The only method I've found is to use setData (platform/forms-system/src/js/actions) from within the form.

For example, with the 526 wizard, the wizard is run before the form is built. So the value is saved in session storage. I tried to pass in that value into initialData but it appears to get overridden by the save-in-progress update. I tried to use setData on the same page as where it was needed, but apparently redux would update, but the date string didn't update the form's 3 separate elements. So I opted to move the setData to the first page of the form. I'm not sure if this is a pure documentation requirement... I mean in my case, I needed to update a data within an object, inside an array.

@micahchiang has a different scenario for using setData, but I don't know how much trouble he had with it.

Acceptance criteria

What must be true in order for this to be complete?

Point(s) of contact

@Mottie @micahchiang

What type of issue is this?

• [ ] Bug
• [ ] Request new feature
• [x] Request update to existing feature
• [ ] Documentation change
• [ ] Other (please describe)

How to configure this issue

• [ ] When ticket is opened, assign to Epic #12765 Forms library user feedback and requests to be triaged
• [ ] FE Tools team will triage and add to Design System Governance Process Project Board as applicable

[short000]

Impact if not done:

@jbalboni: "The difficulty in updating form or schema data based on async or outside data is one reason why VAOS doesn’t use the form config and opts to use lower level form system component directly"

@Mottie: "Here is what I ended up doing: [workaround]": https://github.com/department-of-veterans-affairs/vets-website/pull/13963/files#diff-167692f4e3fc3a7112e3721652f402f4

[cvalarida]

What might this look like in the form config? What's the ideal usage?

[cvalarida]

Discussion

After a conversation in Slack, what I'm understanding is we'd need a couple different ways to update formData from outside sources: 1) A pattern in which we plug data into the form only once when the form is first started.

• This is the wizard on the intro page pattern 2) A pattern where we make a request for "volatile" data whenever the form is started (including loading a saved form). The pre-requisites here are:
• The data requested can change in an upstream system
• The data requested cannot change by the user input (I think)
• ...I could have sworn I had more... :grimacing:

Proposal

I feel like we can accomplish both patterns with a single post-load hook. An example hook might look like this:

const formConfig = {
  postLoadHook: async firstLoad => {
    const additionalFormData = {};
    if (firstLoad) {
      // This is the first time the user has started the form
      _.merge(additionalFormData, getWizardData());
    }

    // Always get this data from the API when starting the form
    _.merge(additionalFormData, await getExtraDataFromApi());

    // Dispatch Redux action to update the form data
    setFormData(additionalFormData);
  },
};

Work breakdown

To accomplish this, VSP would provide:

• The form config postLoadHook (or whatever we name it)
• The setData function (this already exists in actions.js)

App teams would provide:

• The functionality to set the wizard data in a shared space
  • The redux store probably makes the most sense
• The functionality to retrieve the wizard data from the shared space
• The functionality to query data from the API

Notes

• setWizardData and getWizardData sound like good candidates for shared code, but they're outside the scope of the forms library
• Not captured in the example nor the work breakdown is ensuring that the data gotten from the API cannot be changed by user input
  • I think this would be hard to enforce in our current loose data-to-schema coupling (well, "loose" is maybe not the right word...)
  • There may also be scenarios where we do want to allow the data to be changed—like bank account information (showing the masked old data, but allowing the user to enter new data)

---

@short000 @Mottie @micahchiang Does the above sound like it would solve the problems you've been running into?

[cvalarida]

Talked with @Mottie in Slack; it sounds like we can either update the onFormLoaded hook to run after the pre-fill / SiP response or remove it in favor of the postLoadHook (or again, whatever we call it).