18F's projects result in tangible outcomes, like redesigned websites and more efficient government services, as well as outcomes that are less easy to measure — like training or coaching agency staff in running essential technology product work.

To measure the output of these less tangible outcomes, we use tried and true techniques — drawing from tech, management, and other industries — to make our work visible and demonstrate how we're serving the American people.

Training product owner skills

During one recent 18F project, our goal was to enable agency partner staff members in being first-time product owners. None of the agency staff had ever done product work, but they were tasked with managing a complex digital services project. It was important to the agency that we teach them well.

How would we know we were successful in turning agency staff into successful product owners?

Adding a measurable framework

There's an adage that "You can't change what you can't measure." We needed a way to measure the impact we were having, so we could know how well our coaching was working.

We decided to measure all the product owner trainees' progression in a set of important product owner skills. We brainstormed all of the product owner skills we could think of, then de-duplicated the list. Next, we voted on the skills using n/3 voting — that is, each person got one-third as many votes as there were stickies. For example, if there were 30 stickies, each person would get 10 votes.

In the end, we decided to measure product owners' progression in a set of 10 key skills, including Product discovery, Setting goals and a roadmap, and Managing vendors.

The next problem to solve was, how would we measure the development of these skills?

We decided to use a skill development approach called EDGE, which stands for Explain, Demonstrate, Guide, Enable. This is a decades-old, tried-and-true methodology how to teach a skill.

First the teacher Explains what they're going to teach, then they Demonstrate it by showing the skill. Next, the learner starts trying it on their own, but the teacher is there to Guide the learner, correcting or refining the skill as they practice it. Then, the teacher Enables the learner to take ownership of the skill — the learner starts doing it on their own, intervening only when the learner requests help.

We decided to assess product owner skills by asking each apprentice product owner to do a self-assessment of their skills every few months, using a survey based on EDGE.

We created a table with the EDGE stages across the columns and the product skills down the rows. At regular intervals throughout the project, we asked the apprentice product owners to assess themselves on each of the 10 product ownership skills. Were they unfamiliar with the skill and needed explanations or demonstrations? Were they doing the skill, but still in need of guidance? Or did they think they were enabled to fully own the skill?

Our goal was to get all the product owners to "Enabled" in all 10 skills. When we ran self-evaluations, we would look at what skills were more to the left of where we expected, and focus more on supporting the product owners in learning those skills.

We produced a new chart for each self-evaluation, so we could look back and see changes over time. As the product owners developed in skills, we could see movement to the right, toward the "Enabled" column.

By using this method, we were able to see that we effectively coached these product owner skills, and left the agency in good shape to manage their technology modernization project.

Using multiple types of assessments

In this project, we only used the trainees' self-assessments. Next time, in addition to self-assessments, we'll ask the 18F leads to also assess the apprentices' skills, using the same EDGE chart. Then, we'll compare the self-assessment to the coach assessment and talk about the similarities we see, and the differences we see.

With both assessments, we can have two data points instead of one, which we expect will give a clearer picture of the skill development.

In conclusion

You can't improve what you can't measure. When a digital services project includes less tangible outcomes such as skill development and coaching, make them visible by finding metrics to measure, and measuring them over time.

By measuring product owner skills over time, we were able to see that we were effectively training our agency partner's staff, and that we were delivering value by supporting our partner agency in sustainably managing their technology modernization effort.

In this post, we want to share five templates we have adopted as defaults across our projects.

• Project README: helps new teammates and leadership quickly gain context on a project
• Internal kickoff agenda: allows teams to connect and absorb background information at the start of a project
• Team charter: helps teams document roles, practices, and norms
• Weekly ship: ensures stakeholders know about a project’s status, blockers, and progress towards outcomes, so they aren’t taken by surprise
• Risk tracker: helps teams track risks and discuss mitigation plans throughout the project

18F receives inquiries from digital services teams from around the U.S. and across the world asking about how we work. If your team works on digital services projects, we hope these templates will be useful.

Want to work with us? Reach out at Inquiries18F@gsa.gov.

Reference to any non-federal entity does not constitute or imply its endorsement, recommendation, or favoring by GSA.

Are you afraid of spreadsheet formulas? You're not alone. Many people consider spreadsheets to be anxiety-producing messes of formula code that spit out cryptic #N/As at the most minor of changes.

The problem is, we suspect that most government code runs in spreadsheets. Various unverifiable estimates floating around the internet suggest that between one and three billion people use spreadsheets, and that at least 500 million people write spreadsheet formulas. This would mean that spreadsheets are the most commonly-used programming systems in the world. That would also mean spreadsheets are where most government code lives — spreadsheet formulas are code, after all.

If spreadsheet formulas are the most prolific government code, and if people fear their spreadsheet formulas — well, that combination can't be good for government, or for the public servants who develop, use, and maintain those spreadsheets.

The good news is, it doesn't have to be this way. We can make spreadsheet code easier to read by making it clearer and simpler. And when code is easier to read, it's easier to understand. If you understand your code, you can change it without fear.

To create clear spreadsheets, we can use simple, well-tested programming practices to write spreadsheet formulas.

Below, we'll work through an example problem, first using conventional spreadsheet formula-writing practice commonly used over the past 40 years or so. Then, we'll solve it again using simple, tried-and-true programming techniques that are now possible in modern spreadsheet programs.

The result? Truly delightful spreadsheet formulas. Feeling suspicious? That's understandable.

Let's get started.

Our scenario

Let's imagine we work for the National Park Service, in the fictional Igorville National Park. At the end of each day, we get a report of how many people visited the park that day. Our supervisor has asked us to create a cell in our spreadsheet that shows the average number of daily visitors to Igorville Park since the start of the fiscal quarter.

The general solution is to:

Divide the total number of visitors this quarter by the number of days elapsed in the quarter.Round up that number to the nearest integer.Then, add text at the beginning so it looks something like this:

sql
visitors per day: 171

Writing conventional formulas

Let's assume that the total visitors this quarter are in cell B2. The number of days elapsed this quarter are in cell C2.

To get the rounded visitor rate, we'll divide the total park visitors by the number of days in the quarter, then round.

sql
=ROUND(B2 / C2)

Next, we'll add the presentation logic. We'll convert the number to text, even though that's not always necessary. Then we'll add lead-in text that says visitors per day: .

sql
=CONCATENATE("visitors per day: ", TEXT(ROUND(B2 / C2)))

There's a hidden divide-by-zero (#DIV/0!) error waiting to happen here. Do you see it?

On the first day of each quarter, zero days have elapsed, so C2 will be zero. This means we'll get a divide-by-zero error the first day of each quarter. (This is also probably the day our supervisors will look at last quarter's numbers, so we don't want to show them a spreadsheet with ugly errors.)

Instead, let's catch the error, and output a message that the data is still pending for this quarter. We could try wrapping the whole formula in an IFERROR to catch the error, and report that "Data is pending."

diff
+=IFERROR(
  CONCATENATE("visitors per day: ", TEXT(ROUND(B2 / C2))), "Data is pending"
+)

But when we step back and read this code, the headaches begin.

The IFERROR is far away from the divide operation, so readers might not understand that we're trying to catch a divide-by-zero error. In a week or two, we're likely to forget what this IFERROR is doing.

Plus, we want to prevent only the divide-by-zero error, but the way this is written will catch all errors. We won't know if there's another type of error happening here that we should be aware of.

Let's make the connection between the potential error and the error-handling code more clear. To do this, we could rearrange the error and the error-handling to be closer together, like this.

sql
=CONCATENATE("visitors per day: ", TEXT(ROUND(IFERROR(B2 / C2, "Data is pending"))))

This won't work either. On the first day of each quarter, the formula would evaluate to ROUND("Data is pending"). Since you can't round text, this would give us a #VALUE! error.

Instead of handing the error like this, we can prevent the error from happening. We know that the error occurs under one specific condition — the first day of the quarter, when zero days have elapsed. So, let's add a pre-condition that prevents the error. This is known as a "guard clause."

(If you're copying and pasting this code, remember to delete the comment denoted by /* */. These are my way to annotate the code, but the spreadsheet formula language will raise an error.)

sql
=IF(C2 = 0, /* guard clause */
  "Data is pending.",
  CONCATENATE("visitors per day: ", TEXT(ROUND(B2 / C2)))
)

(You can make your formula span multiple lines by using Option + Return on Mac, or Control + Enter on PC.)

With the guard clause in place, the divide-by-zero can never happen! And with that, our formula is all set.

This formula is pretty clear when read aloud. In plain language, it reads something like: "if there are zero days in the quarter, data is pending, otherwise, show the rounded daily visitor rate."

We could stop writing our formula here, and it would be fine — so long as this formula stayed about this simple. If we needed to make bigger changes, with more potential for errors, this could get overly complex very quickly.

Four steps your code should follow

Let's pause a moment and think about the "story" this code is telling.

In his talk Confident Code, developer Avdi Grimm explains that code has to do four things:

• Collect input
• Perform work
• Deliver results
• Handle failure

When we read code, we should ideally see these four steps in order, telling a clear story.

Try reading the code in the last example out loud. Here's how I'd read the story of this code:

The story of this code puts the more important parts last. This formula calculates and reports the error rate, but not until the very end of the code. The "perform work" step comes last, instead of in second place like in Avdi's list. This is like reading a news article where the crucial information is introduced in the last paragraph.

But writing formulas this way probably feels familiar. That makes sense, because it's the way formula programming language has encouraged us all to write for the last 40 years. And while the conventional way we've written this formula works for this simple example, it isn't sustainable for more complex problems.

Three techniques for writing better formulas

Let's approach this same problem using tried-and-true software design principles using three techniques. First, we'll tell a clear story that's easy to read and write. Then, we'll add comments to clarify what we've written. Last, we'll organize our code so readers can more easily understand our formula.

To do this, we'll use the functions LET and LAMBDA. These might be unfamiliar, since spreadsheet programs introduced these only in the last few years.

Technique 1: Use LET to tell a clear story

Introducing LET

Let's say we have a formula we want to put into our spreadsheet:

sql
x + y

In conventional spreadsheet practice, we would replace these variables x and y with either literal values, such as 1 and 2, or cell references, such as A2 and C2.

sql
=1 + 2

sql
=A2 + C2

With LET, we can assign values to variables. In this example, we'll set x and y to 1 and 2 respectively, while leaving the formula as-is.

sql
=LET(
  x, 1,  /* set x to 1 */
  y, 2,  /* set y to 2 */
  x + y  /* evaluates to `1 + 2`, which returns `3` */
)

The first line assigns the value 1 to the variable x, and sets y to 2. The last line is the formula, where everything previously assigned is evaluated.

LET can assign any other formula or expression to a variable, like this:

sql
=LET(
  x, 1 + 2 + 3, /* set x to 6 */
  y, x * 2,     /* set y to 12, using the already-set value for x */
  x + y         /* returns `18` */
)

How does naming values like this help make our formulas better? Well, we can use this to tell the story of our formula in clear steps.

Writing the story of our code

First, let's write the story of our code, following the order of Avdi's steps.

Gather input: Get the number of visitors in the quarter and the number of days in the quarterPerform work: Divide the number of visitors by the number of days to get the rate, then round the rateHandle failure: Handle when there are zero days elapsed at the start of a quarterDeliver results: Format and present the rate

Let's translate these steps, in this order, into formula code.

sql
=LET(
  /* 1. Gather input */
  visitors_in_quarter, B2,
  days_in_quarter, C2,
  /* 2. Perform work */
  daily_visitor_rate, ROUND(visitors_in_quarter/days_in_quarter),
  IF(
     /* 3. Handle failure */
  days_in_quarter <= 0,
  "Data is pending.",
     /* 4. Deliver results */
     "visitors per day: " & daily_visitor_rate
  )
)

This tells a much clearer story than the previous conventional formula. The inputs are named, so we know we're working with visitors and days in the quarter. The visitor rate is named, so when we present it with the "visitors per day: " text, it's clear what we're presenting. Even a first-time reader would have a pretty good idea of what's happening here.

In conclusion, LET helps you name the inputs and steps in your formula code, and these names clarify your story.

Technique 2: Use comments to clarify readable code

What are comments?

When software developers write code, they can leave comments in the code. Comments are narrative descriptions of the code, which other developers can read to better understand the code.

If comments are being used instead of writing clear code, the code and developers suffer. You may hear anti-comment sentiments from some developers, but my understanding is that disdain for comments is a reaction to the negative experience when comments are used as a substitute for clear code.

If comments are being used to supplement writing clear code, they can be quite helpful. Comments can provide context, explain assumptions, warn about common mistakes, and more. Comments can also summarize the formula, so that readers don't have to read all the code to understand what's going on.

But spreadsheet programs don't let you leave comments — or do they?

Writing our first comment

In other languages, a special identifier like a hash (#), double-slash (//), or other syntax (/* */) will indicate a comment. Spreadsheet language doesn't let you do quite that, which you may already know if you tried to copy and paste some of the prior code examples into a spreadsheet.

But believe it or not, you can use LET to leave a comment!

sql
=LET(
  comment, "
     Calculates the daily visitor rate for the current quarter.
     On the first day of the quarter (0 days elapsed), it will say that data is pending.
  ",
  visitors_in_quarter, B2,
  days_in_quarter, C2,
  daily_visitor_rate, ROUND(visitors_in_quarter/days_in_quarter),
  IF(
  days_in_quarter <= 0,
  "Data is pending.",
     "visitors per day: " & daily_visitor_rate
  )
)

If your spreadsheets are large and complex, or built by a team of people, you can make a team decision to use a standard comment format. If you use a standard, your team won't have to waste time developing its own commenting conventions. As a Ruby developer, I've repurposed the Ruby comment standard YARD for use in my more complex sheets.

In conclusion, commenting summarizes and clarifies your formulas, and helps your team members and yourself remember important things about your code.

Technique 3: Use LAMBDA to organize your code

Let's return to our scenario, calculating the daily visitor rate. Here's where we left off using LET:

sql
=LET(
  visitors_in_quarter, B2,
  days_in_quarter, C2,
  daily_visitor_rate, ROUND(visitors_in_quarter/days_in_quarter),
  IF(
  days_in_quarter <= 0,
  "Data is pending.",
     "visitors per day: " & daily_visitor_rate
  )
)

Let's say our fictional supervisor has discovered that the system that sends our spreadsheet the visitor numbers has a bug. Every day, that system over-counts by 10 visitors per day. Here's a table with a few examples.

Our supervisor has asked us to display the corrected number, but to also report the un-adjusted numbers so the executives understand what's going on, since they also look at the old system.

So, on day 3 in the above table, we'd expect to see:

visitors per day: 161 (adjusted from 171)

What a nightmare! Or is it? Can we turn this nightmare into a delight?

When writing formulas, simpler is better. So if you have a complex problem to solve, it's helpful to break it into simpler problems. The practice of solving complex problems by breaking them into smaller and simpler problems is called "decomposition." Each piece will be easier to think about and solve, and then you can compose all the pieces together into the solution.

Let's add the adjusted numbers and rates into our formula.

diff
=LET(
  visitors_in_quarter, B2,
  days_in_quarter, C2,
+ adjusted_visitors_in_quarter, visitors_in_quarter - (10 * days_in_quarter),
  daily_visitor_rate, ROUND(visitors_in_quarter/days_in_quarter),
+ adjusted_daily_visitor_rate, ROUND(adjusted_visitors_in_quarter/days_in_quarter),
  IF(
    days_in_quarter <= 0,
    "Data is pending.",
    "visitors per day: " & adjusted_daily_visitor_rate & "(adjusted from " & daily_visitor_rate & ")"
  )
)

Notice how we do the same rate calculation twice, but with different numbers — we're dividing, then rounding.

It's common practice in software development to try to reduce the amount of duplication. We call it DRY, which stands for Don't Repeat Yourself. We can reduce duplication with LAMBDA, a relatively new feature in spreadsheet programs.

In the next code example, we'll add a lambda, then reduce duplicated code by using the lambda instead.

diff
=LET(
  visitors_in_quarter, B2,
  days_in_quarter, C2,
+ visitor_rate, LAMBDA(visitor_count, ROUND(visitor_count/days_in_quarter)),
  adjusted_visitors_in_quarter, visitors_in_quarter - (10 * days_in_quarter),
+ daily_rate, visitor_rate(visitors_in_quarter),
+ adjusted_daily_rate, visitor_rate(adjusted_visitors_in_quarter),
  IF(
    days_in_quarter <= 0,
    "Data is pending.",
    "visitors per day: " & adjusted_daily_rate & "(adjusted from " & daily_rate & ")"
  )
)

We've just created our first lambda! Lambdas are mini-formulas you can use and reuse within a main formula. We've created a lambda named visitor_rate that takes any visitor count and divides it by the number of days elapsed. We then use that lambda twice, giving it different numbers to use to calculate the rounded rate.

Let's make one more change, and move the details of how we format or present the rate into its own LAMBDA. Moving complexity out of the main body of the formula can help clarify the code. We can trust the body of the code to be the most important part, and then we can go back and read the lambdas if we need to get into the details of how they work.

diff
=LET(
  visitor_rate, LAMBDA(visitor_count, ROUND(visitor_count/days_in_quarter)),
+ format, LAMBDA(adjusted, original, IF(
+     days_in_quarter <= 0,
+     "Data is pending.",
+     "visitors per day: " & adjusted & "(adjusted from " & original & ")"
+   )
+ ),
  visitors_in_quarter, B2,
  days_in_quarter, C2,
  adjusted_visitors_in_quarter, visitors_in_quarter - (10 * days_in_quarter),
  daily_rate, visitor_rate(visitors_in_quarter),
  adjusted_daily_rate, visitor_rate(adjusted_visitors_in_quarter),
+ format(adjusted_daily_rate, daily_rate)
)

Let's annotate this code again using Avdi's story steps. We'll omit some of the code (indicated by "...") for brevity.

sql
=LET(
  visitor_rate, ...,
  format, ...,
  /* 1. Gather input */
  visitors_in_quarter, B2,
  days_in_quarter, C2,
  /* 2. Perform work */
  adjusted_visitors_in_quarter, visitors_in_quarter - (10 * days_in_quarter),
  daily_rate, visitor_rate(visitors_in_quarter),
  adjusted_daily_rate, visitor_rate(adjusted_visitors_in_quarter),
  /* 3. Handle failure - not relevant */
  /* 4. Deliver results */
  format(adjusted_daily_rate, daily_rate)
)

Reading this, we understand that there's a visitor rate step and a format step — but we don't necessarily need to know all the details of them for now.

In conclusion, LAMBDA helps you organize and reuse your code, especially in response to changing needs. This helps keep the readers' focus on what's important, and they can always dig into details as needed.

Bonus technique: Use custom functions to name formulas

Even with our readable code, one problem remains. Every time someone looks at this formula, they have to read 16 lines of code to understand it.

In this case, the easiest-to-read solution would be to name the formula. How about something like, "daily visitor rate"?

With the custom formula creator available in major spreadsheet programs, we can do exactly that.

In Google Sheets:

• Right-click on the cell containing the formula
• Click "View more cell actions", then "Define named function"
• Give the function a name like DAILY_VISITOR_RATE.
• In "Argument placeholders," add visitors_in_quarter and days_elapsed_in_quarter.
• In the formula definition, delete the two lines that set those variables. Those variables will now be added directly to the formula, so we don't need the cell references.

sql
  visitors_in_quarter, B2,
  days_elapsed_in_quarter, C2,

Then, save the function.

Now you can replace the formula with the named function:

sql
=DAILY_VISITOR_RATE(B2, C2)

Before, anyone would have to read all the code or comments to understand what was happening. Now, it's probably clear from just the name. And if they need to understand the inner workings of this formula, they can look it up in the list of custom formulas.

Summary

We started with this:

sql
=IF(C2 = 0,
  "Data is pending.",
  CONCATENATE("visitors per day: ", TEXT(ROUND(B2 / C2)))
)

We're ending with this:

sql
=DAILY_VISITOR_RATE(B2, C2)

And behind that named function is a formula with clear variable names using LET, separated components using LAMBDA, and comments to clarify the code. This approach is a relatively new option available to us.

Using software design principles and practices, our formula is much easier to read, understand, and change. Future readers will thank us — including ourselves, because we're future readers too!

Code that is easier to read is easier to understand. And code that is easier to understand is easier to change without fear and maintain over time. Go forth and write fearless formulas!

Previously, we used Pablo Stanley’s Avataaarslibrary to represent people.

While able to depict a range of skin tones and ages, the bust portraitsultimately proved limiting when trying to represent the vast collective ofhuman experiences.

Our new image style is based on Pablo Stanley’s open-source library Open Peeps. We call our version, whichreflects the brand’s signature blue tones and flat forms, 18F Folks.

Now our graphics look like:

With 18F Folks, we’re able to construct vignettes of people interacting witheach other and their environments. This helps us narrate stories about theworld we want to build.

As a government agency, we use branding to inform and engage the public.Relationships emerge from the content we share. For instance, governmentagencies have reached out after reading this blog, asking how to emulatesoftware systems and service processes. Something as basic as our illustrationstyle impacts how our audience perceives us.

Consider this simple presentation slide.

While the content presents a matter-of-fact list, the shrugging Peep conveysthe body language equivalent of “I’m with you. This is confusing.” We optedfor an illustration style that can cue understanding and trust—emotions morecomplex than the previous style would allow.

Some organizations may delegate branding directives to a marketing team. At18F, we leverage the combined strength of our multifaceted design team tobring ideas like 18F Folks to life. Our content designer took inspiration from18F’s written tone to inform our selection criteria, emphasizing qualitieslike “welcoming” and “conversational.” Service designers conducted research todetermine ideal use cases for illustrations.

The team then created a scorecard and conducted a comparative analysis ofseveral illustration libraries. Open Peeps was selected as the basis of the18F Folks style because it balances professional with approachable.

Product managers compiled a list of additional characteristics to make the 18FFolks library even more inclusive. Considerations included diverse religiousdress, physical abilities, and body types.

On the surface, these depictions are simply bubbly cartoon characters. But weintentionally adopted an illustration style where more people can findthemselves reflected in the content we share. When people can see themselvesin media, they feel seen. That’s why it is so important for us to representthe diverse American public. We want every person to believe that they matterto us–that we are a government by the people, for the people. After all, goodbranding is the public celebration of a group's shared values.

Disclaimer of endorsement

The GSA.gov website includes hypertext links, or pointers, to informationcreated and maintained by other public and/or private organizations. Weprovide these links and pointers only for your information and convenience.When you select a link to an outside website, you are leaving the GSA.gov siteand are subject to the privacy and security policies of the owners/sponsors ofthe outside website.

• We do not control nor guarantee the accuracy, relevance, timeliness, orcompleteness of information contained on a linked website.
• We do not endorse the organizations sponsoring linked websites and we do notendorse the views they express or the products/services they offer.
• The content of external, non-Federal websites is not subject to Federalinformation quality, privacy, security, and related guidelines.
• We cannot authorize the use of copyrighted materials contained in linkedwebsites. Users must request such authorization from the sponsor of the linkedwebsite.
• We are not responsible for transmissions users receive from linked websites.
• We do not guarantee that outside websites comply with Section 508(accessibility requirements) of the Rehabilitation Act.

Here are six launches that 18F has supported this year.

🚀 IRS Direct File Pilot launch with the Internal Revenue Service and the U.S. Digital Service

What

Taxpayers in 12 states used the Direct File pilot to file their taxes quickly, easily, and for free directly with the IRS.

When

Public testing began in February 2024. The website opened for eligible taxpayers in pilot states in March 2024.

Impact

Over the course of the pilot, more than 3.3 million taxpayers started the Eligibility Checker to see if they could use Direct File.

423,450 taxpayers logged into Direct File, and 140,803 taxpayers submitted accepted returns.

Direct File issued more than $90 million in tax refunds and collected $35 million in tax balances due.

More than 15,000 Direct File users participated in a Touchpoints survey, which found that:

• 90% of respondents ranked their experience as Excellent or Above Average.
• When asked what they particularly liked, respondents most commonly cited Direct File’s ease of use, trustworthiness, and that it was free.
• 86% of respondents said that their experience with Direct File increased their trust in the IRS.

🚀 get.gov launch with the Cybersecurity and Infrastructure Security Agency (CISA)

What

.Gov domains help the public identify official, trusted information.

Government organizations at all levels in the United States are eligible for .gov domains — this includes cities, towns, counties, election offices, states, tribal governments, courts, federal agencies, and more. Overall, more than 11,000 government organizations use .gov domains.

CISA worked with 18F to launch a new website for requesting .gov domains.

When

The new get.gov website launched in January 2024.

Impact

The old domain request process required a signature, typically from a senior elected or high-ranking official. For many organizations, these requirements led to unnecessary bureaucracy that caused delays.

The new request process is fully digital, doesn’t require a physical signature, and can usually be approved by someone with significant executive responsibility in the organization, reducing delays.

The new process has also empowered CISA to adjudicate more new domains than .gov has ever done in a single year — and the year isn't finished yet.

🚀 ClimateCorps.gov launch with AmeriCorps and the U.S. Digital Service

What

AmeriCorps, 18F, and the U.S. Digital Service partnered to build a new website for the American Climate Corps.

The website’s goal is to make it easy for any American to find work tackling the climate crisis, while gaining the skills necessary for the clean energy and climate resilience workforce of the future.

When

ClimateCorps.gov launched on Earth Day, April 22, 2024.

Impact

The public can use ClimateCorps.gov to find jobs advancing clean energy, conservation, and climate resilience.

ClimateCorps.gov organized information on nearly 2,000 Climate Corps positions located across 36 states, the District of Columbia, and Puerto Rico. These positions are hosted by hundreds of organizations advancing clean energy, conservation and climate resilience.

🚀 National Accuracy Clearinghouse launch with U.S. Department of Agriculture

What

The National Accuracy Clearinghouse (NAC) is a data matching system designed to ensure individuals are not receiving Supplemental Nutrition Assistance Program (SNAP) in more than one state at the same time.

The National Accuracy Clearinghouse was established as a result of the 2018 Farm Bill.

The goals of the NAC are to:

• enhance SNAP program integrity
• reduce improper payments
• improve the customer experience for participants who move from one state to another by ensuring timely, fair, and accurate benefit decisions

When

The National Accuracy Clearinghouse launched with its first two participating states in February 2024.

Impact

The NAC is improving program access and customer experience by facilitating state-to-state communication to help state agencies promptly and accurately process SNAP recipient moves from one state to another.

Since February, a total of five states have implemented the NAC, with all SNAP state agencies working toward nationwide implementation.

🚀 Notify.gov launch with GSA Public Benefits Studio

What

Notify.gov is a new text messaging service from GSA’s Public Benefits Studio. Notify.gov helps government agencies meet people where they are, by lowering barriers to texting and enabling agencies to easily send customized, bulk text messages to the people they serve. 18F worked with the Public Benefits Studio on the development of Notify.gov by providing research, design, and engineering support.

When

In the summer of 2023, Notify.gov launched its first pilot partnerships with state and local agencies administering SNAP and Medicaid.

In November 2023, the first messages were sent to the public with Notify.gov by the Department of Human Services in Norfolk, Virginia.

Impact

Texting is a proven way to improve the public’s experience of government, deliver better program outcomes, and reduce administrative costs — and Notify.gov is a trustworthy and easy-to-use onramp to help government agencies get started texting.

To date, state, local, and federal pilot partners have sent over 60,000 messages using Notify.gov. These messages have helped people:

• keep their health care coverage, by informing Medicaid recipients that they need to renew their coverage
• protect their benefits, by alerting them that their EBT may have been compromised
• avoid passport processing delays, by informing applicants that they need to submit a new photo.

Notify.gov is growing rapidly, and has received interest from more than 100 programs in at least 30 states, 10 counties, 12 cities, and 18 federal agencies. To learn more and get started with Notify.gov, contact the team at tts-notify@gsa.gov.

🚀 Federal Audit Clearinghouse launch with the Office of Regulatory and Oversight Systems, Presidential Innovation Fellows, and 10x

What

All entities that spend $750,000 or more in federal grant funds in a fiscal year must submit an audit to the federal government.The Office of Regulatory and Oversight Systems (OROS) within the General Services Administration created a new Federal Audit Clearinghouse for grantees, with the goals of:

• delivering a maintainable new system
• seamlessly transitioning users from the old system to the new one
• making audit data more transparent

Who

The new site was built and launched by the Office of Regulatory and Oversight Systems with support from many parts of government, including Presidential Innovation Fellows, 10x, and 18F.

When

The new Federal Audit Clearinghouse site launched in October 2023.

Impact

The modernized Federal Audit Clearinghouse serves hundreds of thousands of users who interact with hundreds of billions of dollars in federal grant funding each year.

Launching the new site allowed Census to successfully retire its legacy system. Customer satisfaction with the new website helpdesk is trending over 95%.

Work with us

Work in government? Want to see your agency launch software products like these? Reach out at Inquiries18F@gsa.gov.

Links

IRS Direct File

• Eligible taxpayers in 12 states can file for free with IRS Direct File
• IRS Direct File Pilot Program Filing Season 2024 After Action Report
• IRS Direct File pilot news

get.gov

• Getting a .gov just got easier
• Benefits of .gov domains
• dotgov-data on GitHub

ClimateCorps.gov

• AmeriCorps Newsroom
• Whitehouse.gov Fact Sheet

National Accuracy Clearinghouse

• SNAP National Accuracy Clearinghouse (NAC)

Notify.gov

• GSA launches pilot partnerships to help people get benefits through text messaging
• Collaborate with the TTS Public Benefits Studio – Digital.gov

Federal Audit Clearinghouse

• Welcome to the FAC
• 10x FY22 Impact Report, 10x
• FAC Product Vision on GitHub

Government technology projects face challenges to successful delivery from budgeting through post-award. To lower risk of failure at any stage, the guide offers methods, models, and examples that reflect:

• Best practices in modern software development
• 18F’s experience working with federal and state partners
• Input from state employees

Topics covered include:

• The differences and trade-offs between commercial and custom software
• Key principles for effective custom software development
• How (and why) to buy custom software development services using performance-based services contracting
• How to work with a vendor development team to deliver human-centered software quickly

These changes respond to current government agency needs. As part of the Office of Management and Budget’s Facing a Financial Shock initiative, an 18F team talked with state employees about challenges to procuring and developing state benefits technology systems and possible improvements. Staff expressed a strong desire for federally authored resources about managing technology projects and enabling successful vendor performance. The revised guide is a resource for both.

The changes also reflect the core 18F value to iterate. The guide's original authors hoped it would be revised over time. As we're able, we'll continue to do so.

Check out the new guide online and in PDF. You can also read the GSA.gov press release about the new guide. Share it around. Suggestions, questions, and feedback are welcome! Please reach out through the 18F Guides GitHub repo.

[Bashful]* is the lead Security Engineer on the TTS DevTools program, an internal shared service focused on providing key secure software development tools and building blocks in order to reduce the time and cost of starting and maintaining public digital services. [Bashful]* synthesizes his extensive development skills, applied technical security expertise, and his battle-tested ATO experience to bake it all into everything DevTools provides in order to allow dedicated civic technologists to focus on solving problems for the public instead of meeting ever-growing compliance requirements.

In a Hyder Award first, [Bashful]* was nominated by two different people for his work on the IRS Direct File project. From his nominations:

In 2023 and 2024, the IRS partnered with the U.S. Digital Service and 18F to form a blended team of federal employees and contractors to design, build, and implement the IRS Direct File pilot. Direct File gave taxpayers the option to file their federal tax return directly with the IRS for free.

[Bashful]* joined the effort as a lead engineer during the summer of 2023 and the project was successful, in part, because of [Bashful]*'s involvement, experience, and working approach. Throughout the process [Bashful]* collaborated with colleagues at the IRS and USDS to advocate for the end users and to implement agile, iterative development practices.

Although the approaches and preferences of each group were different, [Bashful]* was able to find common ground between them to push forward a high stakes, stressful project that was ultimately one of the most successful government tech stories of the past decade.

[Bashful]* led Direct File’s work to achieve Authority to Operate (ATO) and One Solution Delivery Life Cycle Guidance (OneSDLC). Both were secured on a remarkably fast 9-month timeline, enabling Direct File to be released to the public for tax filing season.

Simultaneously, with three months until a launch deadline, he flagged critical opportunities to strengthen the production environment, setting Direct File up for success. [Bashful]* then organized and led a vital Path-to-Production sprint across organizations within IRS ahead of the pilot launch. [Bashful]*’s unwavering commitment to get the pilot into users' hands for the tax filing season made it possible for many people to file taxes with less confusion and anxiety.

[Bashful]*’s leadership and unwavering commitment to iterative and secure development also allowed the team to practice agile and user-centered design and development while still meeting governance and compliance requirements. This directly resulted in a secure, safe, and stable Direct File pilot that protected the privacy of taxpayers.

Not only did [Bashful]* bring these ideals to the IRS, he also openly shared what he learned from the Direct File experience with TTS colleagues to better prepare them for future, similar engagements. His current work building internal compliance tools at TTS enables teams to more quickly and reliably build secure software for partners across the government.

“I am proud of what we were able to accomplish this filing season. I’m proud of the success of the Direct File pilot. I also acknowledge that there’s a lot more work to do and as I look across the IRS, there are areas where we can learn from the success of the Direct File and our own technology operations and our own management success. I’m going to learn from it as well.” – IRS Commissioner Danny Werfel.

[Bashful]* lives in Baltimore with his wife and their two school-age daughters. He describes his hobbies as “pretty varied, which inevitably leads me to not spending as much time on any one of them as I’d like”. Those hobbies include bicycling, hiking, camping, woodworking, cooking, baking, and yoga.

His career aspirations include being part of a build-to-buy team writing software that is released to production for real end-users. He’d also really like to have an impact on the ATO process by working directly with an OCIO shop to improve their workflows, instead of just working within the confines of a single application.

The Andrew Hyder Government Service Improvement Award commemorates the life and work of Andrew Hyder, a dedicated public servant and community organizer who brought together activists, technologists, community members, and others to improve the way that governments delivered services to those in need. It is presented annually to one or more federal employees who demonstrate both excellence in their work and a commitment to improving the public’s experience with government.

Introduction

During a recent 18F project, we built an open-source prototype with a twist: all of the data for our project was locked in a closed-source Oracle database, with no way to export it to an open format.

After days of cobbling together research from across the internet, we managed to set up an Oracle database and connect it to an open-source web application. This is the post we wish we had when we started.

If you need an Oracle database in your open-source project, quickly and for free, then welcome to our step-by-step technical tutorial. Fun fact: this is 18F's first technical tutorial blog post since 2016!

Before you begin

In writing this tutorial, we assume you're already familiar with using the command line, and with the basics of setting up and connecting to Docker containers. We use Macs at 18F, but if you use Windows, nearly everything except file path formats should be the same.

By the end of this tutorial, we expect that you'll have a working Oracle database running in Docker. We will provide guidance on importing data, but we can't guarantee you'll have everything fully imported — it depends largely on the nature of your data.

Our challenge

During a recent project, we were developing an open-source prototype that was all about the data — everything we prototyped had something to do with the data model, how data was stored, and what needed to happen to get the data ready to transform.

So, we needing realistic data, and we received approval to use data from a non-production database.

The only data we could access, however, was a database export file from a no-longer-supported Oracle 12c database.

We hoped we could simply convert the data to something usable in our default database, Postgres. However, it’s not trivial to convert data between database platforms, and tools that offer conversion between Oracle and Postgres are either costly, not secure, or excessively challenging to understand and use.

We considered asking the database administrator re-export to CSV, but we needed the full dataset of several hundred thousand rows with all their relationships preserved. CSV export would only be appropriate if we needed just a handful of tables, or could live without those relationships.

We decided we needed the full database to accomplish the prototype’s objectives. Procuring an Oracle database wasn’t an option on our timeline.

So — what to do?

Discovering Oracle’s free databases

Fortunately, we discovered that Oracle provides two free versions of their database — Oracle Free and Oracle Express Edition (XE).

Both databases provide a single database instance that can hold up to 12 GB. We couldn't discern any meaningful differences between these databases — as far as we can tell, the primary difference is the name. The only other difference we spotted was that, when we imported data into Free, we noticed about 3% fewer data import errors than when we imported into Express.

Both databases are available on Oracle's container registry, container-registry.oracle.com. You don’t need an Oracle account to access the free databases, but you do have to get them from Oracle’s registry — neither database image is available on Docker Hub.

If your database is larger than 12 GB, you may need to export a smaller subset of your data. In our case, the tabular data itself was almost 12 GB in size. We were able to load all of the tabular data, but other objects like indices and constraints were dropped during import because they didn’t fit inside that 12 GB. Fortunately, we didn’t need those additional objects, and the database continued working well enough.

We arbitrarily chose Express to start with, so this tutorial will cover Express. If you choose to use Free, make sure to change the image URL and the database name in the examples below.

Ok, let’s start the tutorial!

Tutorial

This tutorial uses curly braces {{ }} to indicate when you should replace something with your own information. For example, if your Oracle database password is `"my-secure-password" (don't use this), and you see a block like

ORACLE_PASSWORD={{ your secure password }}

your version should look like

ORACLE_PASSWORD=my-secure-password

Part 1: Running an Oracle database using Docker

We’ll use Docker Compose to install and run an Oracle database. Once we have an empty database running, we'll start importing data in Part 2 below.

Setting up the container

Let's think through the setup before we run any code.

First, we know want any data we import into the Oracle database to persist (stick around) even if the container stops or crashes. To make sure that the data in the database persists, we’ll create a volume that links to the Oracle data directory. The details of how Docker volumes work are outside the scope of this tutorial, but you can always go to Docker to read up.

Second, we want to make sure the Oracle database can see the data file we’re going to import into the database. (This tutorial assumes you have a data file exported from another Oracle database.) So, we’ll create a second volume that connects the folder containing our data import file to a folder in the container. That way, when we tell the database to import the file, it can find it.

Let’s run the container for the first time, with our two volumes and a few more features we’ll explain in a moment!

First, set up a docker-compose.yml file with the following content:

docker-compose.yml

yaml
version: '3'
services:
  oracledb:
    image: container-registry.oracle.com/database/express:21.3.0-xe
    volumes:
      - ${FOLDER_WITH_IMPORT_FILE}:/db/data
      - oracle_data_volume:/opt/oracle/
    ports:
      - 1521:1521
    environment:
      - ORACLE_PWD=${ORACLE_PASSWORD}
volumes:
  oracle_data_volume:

Next, let’s set up an environment file (.env) that contains the Oracle username, the Oracle password, and information about the file we want to import. We’ll keep this separate from docker-compose.yml so that secrets that could make hacking easier — username, password, info about your filesystem — aren’t published. Make sure that .env cannot be checked into your version control system, so add it to your global .gitignore.

Generate a random password for your database by running a command like openssl rand -base64 24. Make sure the only special characters in the password are _, $, and #, since Oracle has a hard time with special characters other than these. Then set this value as the ORACLE_PASSWORD in the .env file.

.env

sh
ORACLE_USER=system
ORACLE_PASSWORD={{ your secure password }}
IMPORT_FILE={{ name of the file to import, e.g. export.dmp }}
FOLDER_WITH_IMPORT_FILE={{ folder containing the import file as a path relative to the Docker Compose file, e.g. ./db/data }}

Let’s explain what’s going on here.

On line 5 of docker-compose.yml, we specify oracledb as the name of the container. Line 6 sets the link to the image, which we get from the Oracle container registry page.

On line 8, we link our computer’s ./db/data folder (or the folder specified in .env) to the container’s /db/data. Note the period-slash (./) in the host path ./db/data — that dot indicates that we’re specifying a relative path starting from our current directory.

On line 9, we create a persistent volume that links the container’s /opt/oracle/ to a Docker-managed folder on our host computer. This is the volume that holds all the Oracle database data, so if the container goes down or gets deleted, it knows where to look for the data we will have imported by the end of this tutorial. Since we're not using the format host_path:container_path, this line is just specifying the container path, so Docker chooses a location on the host that we don't really need to know about. This is fine when we’re just persisting data, but it’ll take a little more digging if we ever want to look at the data just using our host computer.

The port mapping on lines 10 and 11 connects our host port 1521 to Oracle’s default port 1521 on the container. This lets us connect to the database on our host computer, meaning that we don’t have to be inside the container to get to the database. We won’t be doing anything with that in this post, since all the commands connect to the database from inside the container, but it’ll be important in the next post when we connect a Rails app running on our host computer to the database in the container.

Lastly, the environment-setting block on lines 12 and 13 set a default password for the default database users, which we are storing securely in a .env file that we don’t check into version control. Setting this in the container environment gives us a known password to use when logging in later on.

The block at the end starting with volumes just names the volumes to create. We need that block for the reference to oracle_data_volume in the oracledb service to work.

Checking that the database works

Let’s start the database!

First, run docker compose config.

If you get an error, you missed including a template value like ${ORACLE_PASSWORD}. Otherwise, you don’t have to read the output of this command — it’s a lot!

Next, run docker compose up. This should start the container

Let’s make sure that the container started correctly, with all the volumes correctly linked. Try listing the files in the ./db/data folder both on the host machine and in the container — if we set everything up right, you’ll see the same files listed.

sh
$ ls -l ./db/data
# ... list of files ...
$ docker compose exec -it oracledb ls -l /db/data
# ... hopefully the same list of files ...

If you don’t see the same files listed, something went wrong in the above steps.

If all is well, let’s start a connection to the database and run some SQL commands. Previously we specified a user named system, but this time, we’ll connect as user sys, for reasons we’ll explain later.

sh
$ docker compose exec -it oracledb sqlplus sys/{{ your secure password }}@XEPDB1 as sysdba

Let’s take a moment to understand this command.

• docker exec -it oracledb tells the command to run inside the oracledb container, and to do so as an interactive terminal.
• sqlplus is the database client that comes built-in with the container.
• sys/{{your secure password}}@XEPDB1 as sysdba is for authentication.
• We’re logging in as the user sys, because we found we couldn’t quite get the right privileges with system, even logging in as sysdba.
• We’re logging into the database XEPDB1. This stands for eXpress Edition Pluggable DataBase #1. Pluggable databases are an Oracle concept that is outside the scope of this article, but you can read documentation on PDBs.
• We’re logging in with the sysdba system privilege, which lets us do what Oracle calls “high-level administrative tasks — see documentation on sysdba privileges.

Now that we’re logged in, let’s run a quick SQL command. This will return the size in megabytes of the physical storage space taken up by the current database. It will probably be a relatively small number, since we haven’t added any data yet — we got 735 MB.

sql
SELECT SUM(bytes)/1024/1024 size_in_mb FROM dba_data_files;

This may admittedly seem anticlimactic, just showing a number of megabytes, but it’s actually reason to celebrate — you’ve just set up an Oracle database using Docker! Congratulations!

Take a breath and get a glass of water. Once you’re ready, we’ll start importing data.

Part 2: Importing data into your Oracle database

Preparing to import data

Now that we have a database and we’re able to log in, it’s almost time to start adding data!

First, let’s ensure that the database can see our data import file. By default, the database doesn’t know much about the filesystem, and it doesn’t know anything about where our import file lives.

In order to let the database know about our file, we have to create a named directory, a special type of object in Oracle that gives us access to the filesystem.

sql
CREATE DIRECTORY db_data AS '/db/data';
GRANT read ON DIRECTORY db_data TO system;

Let’s take a moment to understand this command.

The first line creates a directory object in the system called db_data, which we’ve chosen as the name since it mirrors the name of the container folder where our import file lives, /db/data.

The second line grants read permissions on this object to the user system. That way, when we log in as system, we’ll be able to access the contents of /db/data through the object db_data.

Exit the terminal by typing Control+D.

Importing data, iteratively

Okay, now we're ready to start importing data, in iterations. Don't expect this to work the first time. We'll try to import, see what kinds of errors we get, and attempt to fix them one step — one iteration — at a time.

Frankly, we expect a number of data import problems to occur, and this tutorial may not be able to help you solve all of them. That said, we’ll explain what problems we figured out solutions to, so you can learn how to fix some problems and how you might approach any unique problems you encounter.

Let's add a command to our Docker Compose file, to make it easier to repeatedly re-run the import process. Edit docker-compose.yml as follows. Make sure this block is nested under (further right into) the services block.

docker-compose.yml

diff
version: "3"
services:
+  oracledb: &oracledb
    image: container-registry.oracle.com/database/express:21.3.0-xe
    volumes:
      - ${FOLDER_WITH_IMPORT_FILE}:/db/data
      - oracle_data_volume:/opt/oracle/
    ports:
      - 1521:1521
+    expose:
+      - 1521
    environment:
      - ORACLE_PWD=${ORACLE_PASSWORD}
+  import:
+    <<: *oracledb
+    profiles: ["utilities"]
+    command: impdp ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1 directory=db_data dumpfile=${FILE_TO_IMPORT}
volumes:
  oracle_data_volume:

This is called a "profiled command". (See the profiles: key there?) Profiled commands are a Docker feature we learned from 18F member Andrew Dunkman. This allows us to run the one-off command docker compose run import. But, because we’ve given the command a profile, it doesn’t run by default when we run docker compose up. So we are in control of when this runs.

Let’s look at the command itself.

• impdp is the import data command for Oracle — it stands for “import data pump”.
• system/{{your secure password}}@XEPDB1 is for authentication. Note that this time, we’re not logging in as sys with sysdba administrative privileges. Why? Because we used the sys account to grant read access to system. We would have granted it to sys and kept things simple with one user, but we were told firmly in an error message that a user is not allowed to grant privileges to themselves.
• directory=db_data tells the database what directory to look for the file in. In the previous section, we created this db_data directory object, which allows the database to read from (and in our case, write to) the container’s /db/data directory.
• dumpfile=${FILE_TO_IMPORT} tells the import command which file in /db/data/ to use. The filename should be in your .env file.

We also want to point out the addition of the YAML anchor. On line 5, we add an anchor &oracledb to the service name. This is a feature of YAML that lets us reference the oracledb service’s configuration without having to type it all out again. We’ll need this because these commands use the sqlplus client program that comes with the database image.

Lastly, we expose port 1521 internally — that allows the command to find the database.

Now we're ready to import! Go ahead and run:

$ docker compose run import

If your import ran, even if you got thousands of import errors — congratulations! You’re on your way to a working containerized Oracle database!

Fixing common errors

Fixing missing users

Scan through the log messages that happened while you were importing. What kinds of errors are you noticing? Maybe write them down somewhere so you can troubleshoot later.

We’ll walk through the two main issues that we ran into: missing users and missing tablespaces.

The primary source of errors in our import was caused by missing users or roles. That is, many other errors occurred because privileges couldn’t be granted to users who didn’t exist in the database.

It’s possible this could be solved by adjusting the export to include users. In our case, however, we didn’t have this option, so we fixed it ourselves.

For every user the error log said was missing, we ran this block before re-trying the import.

sql
create user {{ username }} identified by {{ a secure password }};
grant CREATE SESSION, ALTER SESSION, CREATE DATABASE LINK, CREATE MATERIALIZED VIEW, CREATE PROCEDURE, CREATE PUBLIC SYNONYM, CREATE ROLE, CREATE SEQUENCE, CREATE SYNONYM, CREATE TABLE, CREATE TRIGGER, CREATE TYPE, CREATE VIEW, UNLIMITED TABLESPACE to {{ username }};

Let’s break this down.

The first line creates the user and sets their password. The second grants a handful of permissions.

It took a few iterations to identify all of the missing users in the logs, but we eventually solved all the related errors by adding users, watching the logs for missing users, creating the missing users, and repeating.

Fixing missing tablespaces

The next set of errors related to missing tablespaces, the specific files on the filesystem where the data in the database is stored.

After some research and trial-and-error, we landed on an approach of manually creating “bigfile” tablespaces that started at 7 MB, estimated to be the minimum size.

sql
CREATE BIGFILE TABLESPACE {{ tablespace name }} DATAFILE '{{ tablespace name }}.dbf' SIZE 7M AUTOEXTEND ON;

There may be a benefit to creating larger tablespaces up front, but we’re not sure this kind of optimization will be meaningful on databases this small.

Running fixes as a SQL file

After each iteration, we ended up putting all of the SQL commands we ran into a setup.sql file. That way, we wouldn’t have to re-encounter and re-solve all these problems when, say, a new contributor came onto the team and needed to set up a database copy.

Let’s also set up a one-off Docker Compose command to run the setup script. Add the below block to your docker-compose file, nested in two spaces so it's under services. The command will run a file ./db/data/setup.sql on the Oracle database.

docker-compose.yml

diff
version: "3"
services:
  oracledb: &oracledb
    image: container-registry.oracle.com/database/express:21.3.0-xe
    volumes:
      - ${FOLDER_WITH_IMPORT_FILE}:/db/data
      - oracle_data_volume:/opt/oracle/
    ports:
      - 1521:1521
    expose:
      - 1521
    environment:
      - ORACLE_PWD=${ORACLE_PASSWORD}
  import:
    <<: *oracledb
    profiles: ["utilities"]
    command: impdp ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1 directory=db_data dumpfile=${FILE_TO_IMPORT}
+  setup:
+    <<: *oracledb
+    profiles: ["utilities"]
+    command: bash -c 'cat /db/data/setup.sql | sqlplus ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1'
volumes:
  oracle_data_volume:

Clearing and re-running the import

If you’re not satisfied with an import and want to re-run it, we’ll have to get to a blank slate before trying it again. We run docker compose down and then use Docker Dashboard, the GUI application, to delete the volume.

To re-run the import, run docker compose up to start the database.

Then, in another terminal window, run docker compose run setup to run the fixes and preparatory steps in setup.sql.

After that finishes, run docker compose run import to import the data.

Confirming the import is complete

Once you’re satisfied that you’re not getting any critical errors when you import (though there may still be warnings), you can run a database console session to make sure the data looks good.

(At the end of our import process, we still had 1727 errors, mostly conversion errors and errors with setting up database constraints. Fortunately, we could ignore these, and were able to work with the data regardless.)

To log in and use the database console, run:

sh
docker exec -it oracledb sqlplus system/{{ your secure password }}@XEPDB1

From here, you can start running SQL queries to determine whether the data you expect is in the database.

Note that this SQL client program doesn’t support common functions like tab-completion, history, and even navigating a line using left and right arrows. If you’re used to modern software development tools, this can be mildly frustrating to work with, so you may want to find another program to connect with and use as your query editor.

Conclusion and summary instructions

Well done! You've set up an Oracle database and imported your data!

Here’s the final set of files and commands. Save .env and docker-compose.yml into the root of your project, then save setup.sql and any data exports you might have inside your data directory, which in our case was {project root}/db/data/. Fill out the values in {{ }} to match your setup.

.env

sh
ORACLE_USER=system
ORACLE_PASSWORD={{ your secure password }}
IMPORT_FILE={{ name of the file to import, for example export.dmp }}
FOLDER_WITH_IMPORT_FILE={{ relative path to the folder containing the import file, for example ./db/data }}

docker-compose.yml

yaml
version: '3'
services:
  oracledb: &oracledb
    image: container-registry.oracle.com/database/express:21.3.0-xe
    volumes:
      - ${FOLDER_WITH_IMPORT_FILE}:/db/data
      - oracle_data_volume:/opt/oracle/
    ports:
      - 1521:1521
    expose:
      - 1521
    environment:
      - ORACLE_PWD=${ORACLE_PASSWORD}
  setup:
    <<: *oracledb
    profiles: ['utilities']
    command: bash -c 'cat /db/data/setup.sql | sqlplus ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1'
  import:
    <<: *oracledb
    profiles: ['utilities']
    command: impdp ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1 directory=db_data dumpfile=${FILE_TO_IMPORT}
volumes:
  oracle_data_volume:

db/data/setup.sql

sql
-- Set up permissions to access the dumpfile
CREATE directory db_data as '/db/data';
GRANT read on directory db_data to system;
-- Create users and roles
-- TODO: Fill in this template if you see errors about missing users during import. Otherwise, delete this section.
CREATE USER {{ username }}
  identified by {{ secure password }};
GRANT CREATE SESSION, ALTER SESSION, CREATE DATABASE LINK,
  CREATE MATERIALIZED VIEW, CREATE PROCEDURE, CREATE PUBLIC SYNONYM,
  CREATE ROLE, CREATE SEQUENCE, CREATE SYNONYM, CREATE TABLE,
  CREATE TRIGGER, CREATE TYPE, CREATE VIEW, UNLIMITED TABLESPACE
  to {{ username }};
CREATE USER {{ username 2 }}
  identified by {{ secure password 2 }};
GRANT CREATE SESSION, ALTER SESSION, CREATE DATABASE LINK,
  CREATE MATERIALIZED VIEW, CREATE PROCEDURE, CREATE PUBLIC SYNONYM,
  CREATE ROLE, CREATE SEQUENCE, CREATE SYNONYM, CREATE TABLE,
  CREATE TRIGGER, CREATE TYPE, CREATE VIEW, UNLIMITED TABLESPACE
  to {{ username 2 }};
-- Create tablespaces
-- TODO: Fill in this template if you see errors about missing tablespaces during import. Otherwise, delete this section.
CREATE BIGFILE TABLESPACE {{ tablespace name }}
  DATAFILE '{{ tablespace name }}.dbf'
  SIZE 7M AUTOEXTEND ON;
CREATE BIGFILE TABLESPACE {{ tablespace name 2 }}
  DATAFILE '{{ tablespace name 2 }}.dbf'
  SIZE 7M AUTOEXTEND ON;

Instructions:

• Set up the above files.
• Open a terminal window and run docker compose up.
• Open another terminal window, run docker compose run setup, then run docker compose run import.

Special thanks

Special thanks to [Cooperative Earthworm]* for working through database issues together, to [Clever Gopher]* for doing a technical review of this post, to [Stupendous Nightingale]* for doing the plain-language review of this post, and to [Vivacious Herring]* for his constant encouragement.

18F has grown and matured as an organization over time. We recently celebrated our 10th anniversary delivering better government services to the public. As we have grown, so has our care and feeding of our own tools, processes, and best practices. To support continual investment in our practices, we are renewing our commitment to regularly publishing what we learn, and creating a new engineering leadership role at 18F.

Renewing our commitment to sharing our work

Every quarter, we will choose a theme. We will base the selection on problems that our engineers are seeing as they work on delivering technology in government. During the quarter, we will run activities, create resources, and then share what we learn.

Here is what you can expect:

• Updates and additions to 18F's Engineering Guide
• Public tech talks on improving government service delivery
• Public blog posts (like this one) about what we learn

If these sound like familiar activities, that is because 18F engineers have been doing this sort of work for a long time. You may know us from previous hits such as:

• An Introduction to ATOs
• Our open-source Engineering Hiring Guide
• Why simplicity? Choosing a web architecture

Based on recent project experiences, next quarter we will be focusing on the theme of launching software projects. We look forward to creating and sharing brand new resources within 18F and the broader community.

Introducing principal engineers

Another investment we are making is the creation of a principal consulting engineer role. This new role is a career role in the competitive service, meaning we now have engineers in the chapter without term limits. We hired principal consulting engineers with a mandate to:

• Help our partner agencies deliver better digital services to the public
• Help other 18F engineers develop skills necessary to build and deploy software in government
• Guide 18F's efforts to improve how engineers learn, share, and iterate on our best practices.

18F brings engineers from the private sector into government. We need to help them ramp up quickly on how to be effective in a government context. Hiring permanent principal consulting engineers will help us do this more effectively.

For more than 10 years, 18F has published guides and methods that have been widely referenced and cited across government technology. Principal consulting engineers will help us grow and improve the guidance we offer the community, and provide continued institutional knowledge for 18F.

We know that many engineering organizations are experimenting with non-supervisory leadership roles like principal engineers and staff engineers. Principal consulting engineers are our version of those roles. We look forward to sharing both the outcomes from this new role, and what we learn along the way.

If these topics sound interesting to your engineering organization, talk to us: 18F@gsa.gov.

Defining AI

"AI" refers to software that can do human-like tasks. For example, solving problems or "recognizing" the contents of a photograph. The phrase "artificial intelligence" can sound very futuristic and even alarming. In reality, the word "intelligence" is somewhat of a misnomer and we’ve been using forms of AI in our day-to-day work and lives for many years. A simple type of AI is a spelling or grammar checker. Big advancements in recent years have certainly created powerful new tools, but the underlying technology is familiar.

While there are many forms of AI, some of the more common ones include:

• Machine learning (ML) — the application of AI that allows computers to learn and improve on tasks without being explicitly programmed to do so
• Natural language processing (NLP) — a type of machine learning model that allows computer systems to understand digital text and spoken human language, like voice assistants or smart speakers (e.g., Siri, Alexa)
• Large-language models (LLM) — a type of machine learning model that is pre-trained on large amounts of data to predict and generate language, like the “auto-complete” feature in emails or text messages

Like with any new technological advancements, the use of AI has pros and cons. AI can automate rote tasks, reduce human error, or perform complex analysis in seconds. At the same time, AI can perpetuate biases based on the data it ingests, not recognize edge cases, be used to cheat, and contribute to disinformation (e.g., deep fakes). Like most technology, AI is neither good nor bad in and of itself — it’s all about the application and use cases.

AI in government

In fall 2023, the Biden Administration released an AI Executive Order, encouraging agencies to harness the potential of AI to solve urgent challenges, but stressing the importance of doing so responsibly and safely. That mandate has begun to be operationalized through OMB’s first government-wide policy on AI, which outlines expectations for agencies to use it in smart, ethical, and equitable ways. To further support these goals, a national AI talent surge is underway.

In the meantime, AI is already in use across the government. Many applications focus on increasing the government’s ability to serve the public, accelerating data analysis and synthesis, or saving time for public servants by accomplishing rote or tedious tasks.

Some specific examples of AI in action today:

• Powering chatbots. Multiple agencies are using natural language processing to power chatbots that can help the public navigate their websites and services more efficiently. For example, the Department of Education’s “Aidan Chat-bot” answers common financial aid questions and helps students get information about their federal aid on StudentAid.gov. In just over two years, Aidan has interacted with over 2.6 million unique customers.
• Cleaning data. Agencies are applying machine learning and natural language processing techniques to clean and normalize a variety of data. For instance, the Department of Homeland Security uses artificial intelligence to verify, validate, correct, and normalize addresses and identification information to help correct data entry errors, connect information about a person across datasets, and save time on investigations.
• Taking a first pass. An application at the Department of Justice scans documents and looks for attorney/client privileged information based on keywords. At the National Archives and Records Administration, a tool is planned to automatically redact personal information from records being prepared for release through the Freedom Of Information Act. At the General Services Administration, USAGov and USAGov en Español use AI to group data from survey comments, web searches, and more into topics to help identify opportunities for updates and enhancements. In each of these cases, AI is accelerating a process with human support and oversight.

You can find many other examples of AI in use at https://ai.gov/ai-use-cases/.

How 18F is navigating AI

Leaning on what we know

While AI may seem daunting and overwhelmingly technical, the good news is that many of our current design practices are still relevant in navigating AI.

Here are some of our practices and ways of thinking that we’ll be relying on as we explore AI alongside our partners.

Examining who is involved in projects. In real-world use, technology is not neutral — it produces what humans design it to do. Having a clear understanding of who is designing the application directly impacts what is being designed. One of the first steps to mitigating harm is to name the visible and invisible ways that power dynamics exist in our work. At 18F, we use a few different methods to examine our own positionality and the power dynamics that brings.

• Use tools that help identify power dynamics on your project - such as those relating to race, gender, age, ability status, language, class, etc., and how those can lead to potential biases in what is being designed.
• Stakeholder mapping is a way to visualize who holds influence in a project and uncover invisible or visible power dynamics that can introduce bias.

Identifying/minimizing bias. Any technology — including AI — can replicate human biases, assumptions, or preconceived notions. One of the particular risks of AI is the ability to automate or replicate these biases at very large and fast scales. At 18F, we strive to be aware of and reflective of our own biases and create avenues of accountability.

• Learn more about how 18F identifies and minimizes bias in our UX guide.

Surfacing potential harms to groups. Carefully thinking through potential harms to different groups of people is a critical part of engaging with AI ethically. Because of the potential scale and impact of harm through the usage of AI, it is more important than ever to be thoughtful and cognizant of unintended harmful consequences.

• Learn more about how 18F considers ethics in our UX guide.

Incorporating new techniques

As we continue to navigate our evolving landscape, 18F is exploring the following considerations and practices to help us more effectively and responsibly harness the powers of new technologies.

Designing to actively protect human vulnerabilities. Human tendencies have helped us to evolve and survive over generations — whether it's choosing sweet, fatty foods for readily available energy or following popular opinions of those around us to build stronger communities with others. Technology can easily exploit these human vulnerabilities or biases for harm, whether intentionally or unintentionally. As government practitioners, we must intentionally design solutions that protect human vulnerabilities.

The Center of Humane Technology’s humane design guide is an activity to assess a product or feature across six categories of human vulnerabilities and to identify actions to protect or support your users.

Thinking beyond the current context. We often design products thinking about its use in the current context, but what we design will likely outlive that timeframe. Designing for an ever-changing world requires us to consider the potential futures in which our solution will exist.

Identifying externalities, with tools like a Futures Wheel, before designing products, services, or features creates space to discuss any downstream consequences of our designs, whether positive or negative, intention or unintentional, or short or long term, across multiple factors.

Going beyond the happy path. It’s common to create and test solutions for and with people who plan to use the solution as intended. But how often do we consider and protect against adversarial actors? How might they use our design for harm?

Anti-personas are archetypes of user groups that misuse a solution, potentially creating harm for your intended audience or your organization (e.g., people who hack into a system to steal and misuse data). You can create anti-personas the same way you create personas — the key difference is exploring how adversarial actors might use your solution for harm and defining ways to mitigate.

You can test your anti-personas through situational testing practices, like red teaming, where a predefined bad actor (e.g., your anti-persona) gains access to your product, feature, or service in a simulated environment and attempts to misuse it. The internal team can respond to the bad actor, practicing their internal defensive procedures. Red-teaming can also be in the form of a simple discussion of different scenarios of how anti-personas might exploit your solution before you start prototyping it. In any case, scenario-based practices are meant to surface potential risks and vulnerabilities, evaluate your team’s response in those situations, and reduce harm to your users and your organization.

Looking ahead

While we upskill and build capacity in AI, we’re regrounding ourselves in many of our established practices while we explore newer ones. Just like us, you probably have a lot of tools you can use as you learn about and bring AI into your work — don’t disregard them!

If you’re in government, join the AI community of practice, a space for government employees to learn and share about how the government can foster thoughtful and responsible use of AI. If you’re an AI professional, consider bringing your talents to bear in the federal government.

As technologists, there are 18Fers with dexterity to advise on how you might leverage the power of AI. Reach out to 18F if you’re interested in exploring what this might look like for your agency.