We're proud to provide services to our friends in Government.

The Commonwealth of Massachusetts maintains several APIs used by a variety of internal and external teams.

The APIs are built leveraging AWS API Gateway, which allows each granted user to be assigned an API key with various functionality such as rate limiting and access one or more of the state’s APIs. This system is great to work with, but requires a user who is managing the applications to be very familiar with AWS and API gateway in order to add or modify a user’s access to each API.

The application requires OAuth2 authentication through GitHub in order to access the tool, and has a ReactJS frontend that allows authenticated users to easily administer the keys.

Discovery

The success of Mass.gov hinges on getting the right feedback from constituents to site authors. Our first step in overhauling the way Mass.gov collects feedback was to define what we needed to know about each page in order to improve it, so we could design the feedback component around that. It consisted of the following:

• Whether or not users found what they were looking for, and what that was.
• Contextualize the above by knowing how satisfied users are with the page, and what they came to the site to do.
• Very detailed feedback that could only be provided through their user panel, a list of nearly 500 constituents who have volunteered to test new features for the site.

With our broad goals defined, we wanted to make sure the feedback component was working on a more granular level as well. We conducted a series of interviews with site authors asking how to best reach their users, and gained some valuable insight. Here’s what they told us:

• Too much information in the feedback form would scare users away.
• Feedback was being submitted with the expectation of a response, and organizations wanted to be able to respond.
• But, not all organizations would be able to respond, so a variety of contact options needed to be available to them.

Strategy

We combined what we learned above with our best practices to make a set of requirements that we used to define a strategy. It was immediately obvious that this feedback component needed to do a lot! And like site authors told us, if we showed that to users all at once, we might scare them away.

So to maximize the amount of responses we’d get, we decided to lower the effort for submission by presenting these options one at a time, starting with the step that takes the least amount of commitment, and increasing with each step. So users can submit a little bit of feedback, and then opt into submitting a little more, and then keep going.

Designing the feedback form

With a clear strategy in place, we designed the following component.

On first load, the component is very simple — it’s only asking users if they found what they were looking for.

Once users have made a selection, the component expands with fields asking them what they were looking for.

Site authors have the option of including an alert here that tells users this form is not for urgent assistance, and directs them to a better place where they can do that.

In the above example, the organization who is responsible for this page is able to respond directly to feedback. So if users say they would like a response, a form opens up for them to enter their contact information. If the organization was not able to respond directly to feedback, a brief explanation of why would appear there instead.

 After submitting, users are thanked for their feedback. 

Seen above, organizations are given the option to link to their contact page. This is commonly used if the organization is unable to respond directly to feedback.

Users are then given the option to take a short survey, where they can provide more detailed feedback.

After submitting the survey, users are given the opportunity to join the Mass.gov user panel. This is the largest commitment available for providing feedback, so it’s at the very end!

So that’s how feedback is collected on the site. But what happens to it after that?

Displaying feedback to site authors

Feedback submitted through the site can be viewed per node, i.e. a site author can go to a specific page through the backend of the site and view all the feedback submitted for that page. But a lot of feedback can be submitted for a single page, and on top of that, site authors are often responsible for multiple or even many pages. Combing through all that feedback can be a prohibitively daunting task, or simply not possible.

To help with this, we designed the “Content that needs attention” panel for site authors.

The “Content that needs attention” panel appears on the welcome page on the backend of the site, making it one of the first things site authors see after logging in. It displays the page titles of their 10 pages with the lowest scores from users, sorted by page views. By showing site authors their content that’s seen by the most people first, we’re helping them prioritize what to work on next.

We’re giving site authors additional information about the content right in the component, helping them make decisions at a glance. In addition to the aforementioned page titles, scores, and page views, we’re showing them the content type (since some titles can be very similar on this site), the date they last revised it (in case that helps them know how badly this content needs attention), and something a little surprising… a “Snooze” button!

We put a snooze button in because once site authors make an improvement to content, it’s no longer helpful for them to see it here. So, the way it works is that they make an improvement to content, then hit “Snooze,” and it’ll disappear from this list for one month. At the end of that month, one of two things will have happened: 1) the content will have improved enough to no longer appear on this list, or 2) the content needs more improvement, and will appear back on this list.

LCM worked with the Commonwealth to build an extract-transform-load tool (ETL) that runs whenever an updated data set is provided by GIS. The ETL takes millions of records from the FGDB dataset, normalizes them, and imports them into an AWS RDS database. The state had a proof-of-concept process for this that took hours to run. By leveraging AWS Fargate and the open-source GDAL library the required time was brought to under 10 minutes.

After the ETL, we built an API endpoint using Serverless.js (AWS) that takes in addresses in a typical mailing address format (which allows for many potential variations). We leverage libpostal to separate the address into distinct address components, and then perform a query against the RDS database to see if any matches are returned.

The serverless architecture of both the ETL and the API endpoints are highly scalable and secure, and the state is only charged while they are actually being used. This allowed us to create a flexible address matching system that took advantage of their internal dataset of unique addresses, and allowed user input in a wide variety of formats, for a very small cost.

Our first step in initiating the migration was to investigate what we were dealing with. At the time, mass.gov had around 600,000 revisions with a moderation state that needed to be migrated from Workbench Moderation to Content Moderation. We started off by digging into Content Moderation’s code to fully understand the complexities and layers of the switch. We found the systems to be very different and with no pre-designed migration path, we deduced that we needed to create a handmade migration path from scratch, outside of a standard Drupal 8 migration. Once the initial configuration of this path was set up, the process was just to keep building the migration through trial and error and figuring out the fastest plan of action.

We knew that switching from Workbench Moderation to the new core module, Content Moderation meant the mass.gov site and its authors would benefit. For a government site, security is always a concern and therefore a top priority. When working with a core module, it is actively supported for security and for any updates that core has as opposed to still running on a contributed module. 

After we felt sound on the coding portion of the switch, we wanted to make sure we were in alignment about expected workflows, transitions, non-transitions, and revision states. We started with around 20 transitions in Workbench Moderation that we were able to consolidate to 5 transitions in Content Moderation for a more optimized workflow. 

We also worked on rebuilding some views such as the “all content view” and mass.gov’s specific dashboard called, “MyContent Block”, which contains all the content the logged in author is watching. 

After a successful switch, mass.gov users are leveraging Content Moderation to moderate content. We are implementing a patch to Content Moderation for the view for “filter by moderation state”. This filter was missing some indices that would cause MySQL to incorrectly do a full table scan instead of an indexed scan of content that caused a lot of performance issues. We ended up writing a patch to include the missing indices that would bring down the query load time on the “MyContent Block” view from 15,000 milliseconds to 200 milliseconds. We plan for this patch to be made available for other sites experiencing the same issue with a lot of content like Mass.gov does.