View sample UI application code

As a part of the Claimant Experience Pilot, we collaboratively developed code for a sample UI application from the ground up that has all of the modern best practices baked in. New Jersey adapted language and design elements from this sample to work into their own UI forms, and Arkansas adapted the login.gov part of the pilot to integrate online identity verification into their UI flow. For others who might also want to explore the sample in its entirety, we have made the Claimant Experience Pilot application code completely open source.

The application code includes the following functionality:

• User flow and integration of identity proofing with login.gov at Identity Assurance Level (IAL) 2
• Initial Unemployment Insurance (UI) claim intake

We recommend that engineers pull the code down to their local computers, follow the setup instructions (colocated with the code), and explore the running application. You can also explore the code, as it uses many best practices from which your engineers can pick and choose to implement. These examples can both improve the UI claimant experience and make it possible to change your code faster.

Some of the best practices included in the open-sourced code are:

• Using feature flagging to enable faster, easier, and more reliable code releases
• Using internationalization libraries for translations
• Expressing and storing complex data relationships

Use feature flagging to enable faster, easier, and more reliable code releases

One blocker for rapid code deployments is not being able to release new features or fixes because of other separate changes that are still in-process. This can be mitigated by using feature flagging: a technique used to toggle functionality on or off in an application. The Claimant Experience Pilot application uses a feature flag software-as-a-service product to gate content that isn't ready to be exposed to users in production. This allows us to keep shipping code to production even if features are partially completed.

The following code snippet shows an example of a feature flag used in the Claimant Experience Pilot application Python code. This flag currently prevents the use of a future 1099G upload feature that hasn't been released yet.

def v1_act_on_claimant_1099G(request, claimant_id):
    # Get flag value from our flag service
    ld_flag_set = ld_client.variation(
        "allow-1099g-upload", {"key": "anonymous-user"}, False
    )
    # Return a 404 "Not Found" error if the flag is off
    if not ld_flag_set:
        logger.debug("allow-1099g-upload off")
        return JsonResponse({"status": "error", "error": "route not found"}, status=404)

    # Handle the request if the flag is on
    return v1_POST_1099G(request, claimant_id)

Use internationalization libraries for translations

The Claimant Experience Pilot application uses internationalization libraries (e.g., react-i18next) that can be used to display text in multiple languages. These libraries use user-provided translation strings rather than automatic text translation. States and territories are required to provide forms in languages other than English (see UIPL 02-16), and automated translation services may not provide accurate translations, which can further confuse claimants.

Express and store complex data relationships

Claims data is complex. There are many potential shapes that claim data might have depending on how a claimant answers questions. Because of this, the Claimant Experience Pilot team elected to store claims data as semi-structured JSON files. The JSON data is validated using JSON Schema, which offers a way to codify complex data relationships.

The following example shows how union membership can be expressed with JSON schema. By default, only the is_union_member field needs to be completed. However, if is_union_member is true, then union_name, union_local_number, and required_to_seek_work_through_hiring_hall all become required fields.

{
  "union_membership": {
    "$id": "/definitions/union_membership",
    "$schema": https://json-schema.org/draft/2020-12/schema,
    "type": "object",
    "properties": { "is_union_member": { "type": "boolean" } },
    "required": ["is_union_member"],
    "if": {
      "properties": {
        "is_union_member": { "type": "boolean", "const": true }
      }
    },
    "then": {
      "properties": {
        "union_name": { "type": "string", "maxLength": 32 },
        "union_local_number": { "type": "string", "maxLength": 16 },
        "required_to_seek_work_through_hiring_hall": {
          "type": "boolean"
        }
      },
      "required": [
        "union_name",
        "union_local_number",
        "required_to_seek_work_through_hiring_hall"
      ]
    }
  }
}

Using JSON Schema, the Claimant Experience Pilot development team was able to express the entire claim form in a single JSON file against which any claim object could be validated.

An additional benefit of storing claims as semi-structured data was that the application could save in-progress claims: the data did not need to conform to more rigid database specifications but simply had to be saved to an object store. This results in a better experience as claimants do not have to finish the form in one session.