This is CiviForm's documentation. Visit the main website here.

CiviForm is a free, open source tool that makes it easier to access and administer public assistance programs. Residents and community organizations can find and apply to multiple programs in one place, and governments can streamline services and reach communities in need.

In the docs, you will find:

• Overview of CiviForm with a high-level summary on how the tool works for different users

• Onboarding Guide to understand how CiviForm can support your organization's service delivery

• to set up and manage your programs and applications

• to deploy CiviForm on your technical infrastructure

• with information on how CiviForm is being collaboratively managed and developed

Getting Started

Below are good docs to start learning about CiviForm:

CiviForm is free, open-source software that was built with support from Google.org Fellows and is managed by Exygy as a product steward. CiviForm is deployed and maintained by civic entities themselves.

The Problem

Signing up for critical government services often requires reentering the same information on each application. Our research shows that the need to repeatedly navigate complex requirements and re-enter sensitive personal information can feel dehumanizing. Moreover, people seeking to help residents apply for programs, such as local administrators or community-based organizations, must spend valuable time and resources to work through duplicative data.

In times of crisis, these problems can be particularly acute (e.g. during a public health emergency like COVID-19).

Our Solution

CiviForm supports a more human-centered approach to public benefits applications. When someone applies to a program, their data is stored in a centralized program database so that they see questions and programs that are most relevant to their needs. Applicants can then choose to re-use that data for other applications as they see fit.

For applicants and their trusted intermediaries, this means that once you enter personal information for one program, you won’t need to re-enter it for future assistance. For government program administrators and local staff, this means less time collecting and sorting through redundant data across programs.

Technical Platform and Security

All data is managed by the civic entity and thus their own security and privacy policies apply. Neither Google nor Exygy have access to applicant data in CiviForm. It was built as a low-code solution for government employees to respond to the needs of their community without needing technical expertise.

CiviForm is written in Java using the backed by a database. The application is containerized for development and deployment using , and deployed using container management systems that work with all major cloud providers. For authentication, CiviForm uses OIDC and SAML to integrate with existing single-sign-on services such as Microsoft ADFS, Oracle IDCS, and LoginRadius, allowing program administrators and residents alike to authenticate with existing accounts. For security, CiviForm is built to defend against cross-site scripting (XSS), SQL injection, cross-site request forgery (CSRF), and other common hacking tactics.

Watch the video or follow the step-by-step guide below to download the demography export for all applications for all programs into a CSV file:

1. Navigate to the programs page by clicking Programs in the navigation bar.

2. Click the Download Demographic Data (CSV) button.

3. Select a date range for the data you'd like to export. If you select a large date range or leave it blank, the data could be slow to export.

4. Click the Download Demographic Data (CSV) to begin the export.

5. You will see the CSV file downloaded onto your computer.

​You can use the CiviForm glossary to learn more about frequently used terms or concepts. To find terms on this page press Ctrl + F on PC or Command + F on Mac.

• Applicant—Resident seeking to apply for government benefit programs.

• Block—Can be used interchangeably with screen.

CiviForm admins can label a program with one or more categories. These categories serve as filters on the applicant home page, helping residents to find the types of programs they are looking for. Here are some of the available categories:

• Education

• Childcare

• Food

Trusted intermediaries are third-parties that residents turn to when applying for programs (e.g. community-based organizations).

In this Guide, you will learn how-to:

Program admins have access only to applications of programs they were assigned to. Assignments controlled by CiviForm admins on per-program basis. If Alice ([email protected]) needs access to applications of program "Solar program":

1. CiviForm Admin need to go to Programs list and click "Manage Program Admins" on "Solar program". Then add [email protected] as admin.

2. Alice needs to log in to CiviForm using "Admin login" flow. Logging in using applicant flow won't work.

When a CiviForm Admin creates a question, they must choose an export setting. The export setting controls whether data will be exported in the demography CSV, which is the CiviForm Admin's exported data. The export setting does not affect the Program Admin's exported data. The CiviForm Admin selects one of the following data export options:

Don't include in demographic export - the answer won't appear in any way in the exported data.

Include in demographic export - the raw answer as provided by the applicant will appear in the exported data.

Obfuscate and include in demographic export - the raw answer as provided by the applicant will not appear in the exported data, and instead, an "obfuscated" answer will appear. Obfuscated means that the applicant's answer to the question is cryptographically obscured, exporting text that is unique to the applicant's answer but does not reveal what the original text was. It is impossible to derive the applicant's original input from the resulting exported value. Only other questions with the exact same answer will have the same exported value.

For example, in a social security number question, the following inputs would result in the corresponding outputs:

Input: 123-45-6789 Example obfuscated output: d158596dd5a6cae6fcb282832885631553ecc8c8b0bf07f84c4aa691953cd0da

Input: 123-45-6780 Example obfuscated output: 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b

Welcome! Kick off your training by watching the video below about CiviForm, the CiviForm Admin role, and the other users of the tool.

https://drive.google.com/file/d/1gWzGgvugZzSMLISKHv5bLuIv_bWYAWvb/view?usp=sharing

By default, CiviForm sends Program Admins an email every time an application is submitted to a program they manage.

To change this:

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Click Edit for the program you would like to edit notification settings for.

4. Under Email Notifications, select or unselect Send Program Admins an email notification every time an application is submitted.

5. Save and publish the program.

You can find links to existing deployments of CiviForm (staging and production) in the doc below. The doc is access controlled. If you work on CiviForm but don't have access to the doc - ask on someone on slack to give you access.

Google doc.

Create a program

A CiviForm program is a benefits program built by CiviForm Admins. It’s essentially a vehicle to ask questions of program applicants and to collect completed applications. Once you create a program, you’ll need to publish it to make it available.

Watch the video to learn how to create a program in CiviForm. You can also follow the step-by-step guide below.

How to add program information

Tip: To retrieve a list of all programs, click Download Exported Data (CSV) at the bottom of the Programs page.

Create a program

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Click Create new program.

4. Enter information for the program, including the external link for additional program information.

Note: The internal Program Name field ensures each program is distinct. Once the field is set, it cannot be edited.

Add or remove questions & screens in a program

How to add screens and questions

CiviForm programs are made up of one or more questions housed in screens. Each program has a default screen.

A program can hold multiple screens and each screen should contain a logically themed set of questions (for example, all employment-related questions). Each screen equates to a new page when applying to a program.

You edit both unpublished and published programs. To edit published programs, you need a new version. For more details on versioning, go to .

Add a screen

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar and select a program.

3. Click Edit > Manage questions.

4. Click

A Program Admin can review completed applications using CiviForm. Program Admins only have access to applications for the programs they are assigned to manage. For more details, go to CiviForm data management & security.

Tip: To retrieve a list of all applications, click Download All (CSV).

Review current program applications

1. Sign in to CiviForm as a Program Admin.

2. Click Applications for the program you want to review. You’re presented with a paginated list of applications.

3. Locate the form you want to analyze and click View.

Review previous program applications

1. Sign in to CiviForm as a Program Admin.

2. Click Applications for the program you want to review. You’re presented with a paginated list of applications.

3. Under Applications for other versions, locate the version number you want to examine.

Change the status of an application

As a Program Admin, you have the ability to change the status of a given application in CiviForm. When an application is set to a status with associated email content, applicants receive an email. The applicant will also see the status of their submitted application(s) when they log into their CiviForm account.

1. Sign in to CiviForm as a Program Admin.

2. Click Applications for the program you want to review. You’re presented with a paginated list of applications.

3. Locate the form you want and click View.

4. At the top of the application, select the status you would like from the dropdown menu of options next to Status.

Note: A CiviForm Admin must create and publish statuses for your program. To create or modify status options for your program, contact your CiviForm Admin.

Watch the video below or follow the step-by-step guide to learn how to manage Program Admins in CiviForm.

1. Navigate to the programs page by clicking Programs in the nav bar.

2. Locate the program you'd like to manage Program Admins for in the list of programs.

3. Click on the three dots on righthand side. If the program has both a draft and active version, make sure to click on the three dots that are in line with the draft version.

4. Click Manage Program Admins.

5. To add a new Program Admin, type in their email address and click Add. Note that the Program Admin must create their own account before you're able to add them in here. Use the email address that they used to create their account when adding them as a Program Admin.

6. You can also remove someone as a Program Admin from this screen by clicking on the Delete button.

Get oriented and learn how to navigate CiviForm as a CiviForm Admin.

At the top of the screen, there is a navigation bar. You can navigate to:

• Programs: View, create, edit and publish programs. This is the page you see when you log in.

• Questions: View all the questions you can add to your programs and create new questions.

• Intermediaries: Create or view Trusted Intermediaries.

• API keys: Manage API keys, which enable accessing CiviForm programmatically from other software products.

• Reporting: The data dashboard where you can view core program metrics.

Program Admin are the government employees who handle applications for programs. With CiviForm, they can integrate the tool into or improve existing worklows.

In this Guide, you will find how-to:

• How to become a Program Admin

• Review completed applications

Watch the video to learn how to edit programs. You can also follow the step-by-step guide below.

Learn how to edit admin and applicant information.

Edit a program

CiviForm can be a helpful tool even in cases where a program does not require applications, or does not want to use CiviForm to accept applications. As you map the needs of various programs, consider whether CiviForm could play a role in program discovery, eligibility screening, or intake across programs.

Questions can be shared between programs. If the wording for a question changes, it does so for all programs that use it. However, programs can be set up to show or hide specific questions based on previously answered questions. These dependencies can be different for the same questions across different applications.

To account for this use case, CiviForm allows versioning of programs and questions when making changes instead of overwriting the existing version. This means when Applicants begin an application, they remain on that version even if the program or questions are updated.

When you publish all drafts, all changes to programs and questions are published together. The versioning and change publishing system bundles the entire set of configuration objects together in a versioned configuration set using a version number. A given version includes its own question set and program definition set including the program application and data export configuration. This means a version can only reference questions in the same versioned configuration set.

Read more about the .

As a CiviForm Admin, you have the ability to set custom statuses (e.g. Approved, Waitlisted) and email content for each program. Once you create and publish statuses for a given program, the Program Admin will be able to set statuses for each application submitted to their program.

For statuses with associated email content, a status change will trigger an email to applicants that used a CiviForm account to submit their application. The applicant will also see the status of their submitted application(s) when they log into their CiviForm account.

Additionally, you can choose one of the statuses to be a default status. All new applications will automatically be set to this status, and the associated email for that status will be sent to the applicant.

Note: in order to use status tracking, your IT Admin must have enabled the feature. To enable the feature, have your IT Admin set the CIVIFORM_APPLICATION_STATUS_TRACKING_ENABLED environment variable to true.

Watch the video or follow the step-by-step guide below.

Publish all draft programs

Once a program is created or a new version is launched, the program remains in draft until published. When published, it’s available to both Trusted Intermediaries and Applicants.

There can only be one unpublished version in the system at a time and once a version is published, it’s locked and cannot be modified. For more details on versioning, go to

This document describes long-term CiviForm staffing needs for a deploying civic entity. Those needs include a non-technical administrative role, and technical roles to support the functioning of the software system.

CiviForm administrator

The CiviForm Admin user role has the ability to define questions, designate data anonymization settings, define program applications, perform anonymized bulk applicant data exports, designate program administrators, and designate trusted intermediaries.

For programs to reuse applicant data, they must have harmonized data requirements, which requires someone to coordinate those data needs across programs. This is a natural fit for the CiviForm admin.

The role requires someone who is comfortable working with computers but it is not a technical role – all tasks can be completed using the CiviForm UI. Most importantly, the role requires someone who is able to interface with a large number of program staff to understand their data needs and design user-friendly application questionnaires with the CiviForm tool.

How to enable address correction for an address question

When an admin adds an address question to a program, they will see a toggle button to enable address correction, with a tooltip that reads:

Enabling address correction will check the resident's address to ensure it is accurate.

If the address correction feature has not been enabled, the tool tip provides additional information to an admin user:

Markdown is a simple formatting tool that allows you to create text links and lists as well as apply bold, italics, font sizes, and other formatting edits to text. CiviForm Admin can use Markdown to format text in six key places within CiviForm:

• Program descriptions

• Custom confirmation screen messages

• Static question text

CiviForm supports integration with external systems via its HTTP JSON API. The API authenticates requests using API keys managed by the CiviForm admin. For more details on how API keys are used and list of APIs supported, refer to .

API key security

API key expiration

One strategy for understanding the needs of applicants and program staff in more detail is journey mapping. Journey mapping is a way of documenting and understanding the end-to-end experience of applicants and program staff as they engage with the program. A journey map can give a high-level overview of key interactions, challenges, and opportunities for improvement for different stakeholders throughout their experience with the program.

Mapping what exists

The first step to improving residents' experience with programs is understanding their current experience in detail. Working with each program to answer the questions in can help give a clear picture of each program's user journey across different phases, including discovery, eligibility screening, application submission and processing, determination, delivery, and renewal. A detailed journey map will include touchpoints between residents and staff, tools, processes, timelines, and pain points. In addition to working closely with program staff, conducting reserach with residents is a key part of understanding existing challenges and opportunities for improvement.

This guide is for Systems Administrators, IT managers, SREs, or DevOps folks. It explains how to do an initial deployment of CiviForm into your production cloud environment. CiviForm has the following deployment options:

• Can be deployed into AWS using .

• Can be custom deployed using in cloud or on prem using directly. Requires more configuration and maintainance.

Universal questions

Universal questions are questions that are intended to be used by all programs. When a question is marked as universal, it appears at the top in a separate section in the questions tab and in the questions list sidebar when creating a program. Any question may be set as a universal question.

When creating or editing a question, select the following toggle to make the question universal.

It then shows up in the questions tab, as well as the questions list sidebar.

On the programs tab, each program notes how many of the universal questions are used in the program.

What is your organization's approach to service delivery? Understanding how residents engage with the government as a whole and with different agencies in particular can help inform where CiviForm can fit into your work. Understanding which programs may be administered by other organizations or jurisdictions can also help consolidate access to those programs for your residents. In addition, understanding technical and operational capacity across programs can help ensure that CiviForm integrates well into your existing workflows.

What challenges does your organization face in administering programs or services? What opportunities do you see?

Any details are fine, the challenges do not need to be technology-related.

The CiviForm server is configurable through environment variables. All availabile variables are documented in a file in the civiform/civiform repository.

When a CiviForm server version is released, the env-var-docs.json file corresponding to the release is used to generate markdown documentation of the variables. The generated markdown files are added to this directoy. Use the left sidebar to see the available configuration variables for the CiviForm version you are deploying.

Variables can have four different modes which determine where they are set and displayed:

1. "Admin writeable" variables should be set in the admin settings panel which is accessible in CiviForm when logged in as an admin. These variables should NOT be set in your deployment config and setting them there will result in a deployment error. If you need to set custom values for Admin writeable variables during an intial deploy, it is possible to override this error by setting export ALLOW_ADMIN_WRITEABLE=true in your deploy config. This should only be used for the initial deploy and should be removed from the config immediately afterwards.

CiviForm provides administrators with metadata about programs and applications, enabling actionable insights that can improve residents' experience in accessing programs.

Leveraging data to improve program operations

Because CiviForm includes metadata from across programs, administrators can have visibility into applicants' experience across programs in CiviForm. This includes key metrics such as how long it takes to complete an application, which questions applicants might be struggling with, and which programs people tend to cross-apply to. Such metrics can inform changes that lead to direct improvements in a specific program's application experience. Additionally, administrators can analyze metadata to assess which communities are or aren't being reached by a given program, which can in turn inform targeted outreach or other local efforts to expand access.

CiviForm supports integration with external systems via its HTTP JSON API. The API authenticates requests using API keys managed by the CiviForm admin. API clients can expect indicating the result of their request.

Please see the articles in this section for more detail:

Welcome to the CiviForm Admin Training Guide!

If you are a government employee who creates, publishes, and manages application forms for programs, then you are a CiviForm Admin. With CiviForm, you can manage and create program application forms using a repository of reusable questions.

Navigate through this guide to learn the ropes as a CiviForm Admin.

CiviForm enables applicants to re-use previously submitted information when completing applications to new programs. It accomplishes this by unifying question definitions across programs. This is not a technical problem -- it is first and foremost an administrative problem. CiviForm makes it easier to implement information re-use across programs once the administrative work of consolidating question definitions is complete. Here are some best practices for consolidating questions and applications across programs.

Work with key stakeholders across programs

This work involves understanding administrative and policy requirements for different programs, so you must work closely with individuals responsible for administering those programs to understand what they need out of their application forms (and why). In particular, seek out people who have the organizational context to understand why questions must exist, as well as the agency to make decisions about whether or not questions can or should be changed.

Start with a few programs

Begin by mapping questions across one or two key programs to understand where there are similarities and differences in the questions they ask (and how they ask those questions). Starting with a few programs makes the task of mapping questions easier to approach, and provides a solid foundation for adding additional programs incrementally once enough questions have been mapped.

Understand key shared questions

Understand key questions such as name, date of birth, address, contact information, income, household size, assets, and other characteristics such as whether or not someone is a student or has a disability. These questions may seem similar across programs, but there may be subtle differences in what they are actually asking for. For example, questions around income may have different definitions (e.g. in what is considered income, or over what time period). For demographic questions such as race, ethnicity, and gender, understand whether these questions are being asked through free-text fields or categorical fields. If they are categorical, identify similarities or differences in which categories are used across programs.

Understand the purpose and meaning of each question

In order to consolidate and simplify questions across programs, it is essential to understand each question's purpose and meaning. If the meaning of questions can be made consistent across programs, then combining and re-using questions is straightforward. However, if questions seem similar but actually serve different purposes or ask for different information, they may need to exist separately in the question bank to meet different programs' requirements.

Is it necessary?

While auditing questions, understand whether or not a question or requirement is actually necessary. It may be the case that some legacy questions are no longer necessary to administer a program and can be removed entirely. In order to judge with certainty, you must work closely with program administrators to understand a question's origin and purpose.

Why is it necessary?

Different questions may be necessary for different reasons. For example, some questions such as income are simply necessary to determine someone's eligibility for a given program. Other questions such as demographic questions may be necessary (or optional) for mandated reporting purposes. Some questions may be "necessary" simply because some underlying software system or process was poorly designed to require them. Other questions such as past enrollment in other programs might be valuable to help with program operations, but may not be truly required for the administration of the program. Understanding which questions are actually necessary and why they are necessary can help indicate which questions can be consolidated or removed, and which must remain.

What information is actually necessary?

While some questions may seem similar, their underlying meaning may differ subtly, or the actual information required may be a subset of what is asked for. For example, rather than asking for individual information about each household member, it may be sufficient to just ask for the total number of household members. In other cases, it may be necessary to know the age of each household member, in which case asking for that detailed information is justified. Similarly, if only each household member's age is necessary, there is no need to ask for each person's date of birth.

Encode information so that it can be easily re-used

Information can be re-used if each piece of information is represented as a single question in CiviForm. As an example, if you'd like to understand characteristics about someone such as whether or not they are a student or have a disability, asking these questions individually makes them reusable in other applications, whereas asking them all in a single question using a checklist of multiple options requires that another program use the same checklist of options to re-use that information. In this sense, questions should be broken down into their simplest form to enable re-use. However, if such formatting affects the usability of a form -- for example, asking a dozen one-off questions rather than having a single checklist with a dozen options -- it may be best to have separate questions that serve each use case, even if it means that information can't be directly re-used. Alternatively, data can be exported and processed outside of CiviForm to re-encode information to a usable form, even if it wasn't asked as such originally (for example, turning a series of yes/no questions into a checklist or vice-versa).

Promote accepted best-practices when possible

For demographic questions such as race and gender, make a decision to standardize on accepted best-practices when possible. For example, some jurisdictions enable individuals to self-report these fields or have their own set of options which may differ from other standards. While there may be federal reporting requirements that mandate specific language in questions, some jurisdictions or programs may have more flexibility in how they ask these questions and can promote best practices within their organization.

Residents seeking public assistance are often required to submit personal information to government programs without a clear sense of why that information is being submitted or how it is being used. Such a vulnerable interaction can be especially burdensome on someone in a time of need. As temporary stewards of residents' information, government programs have a responsibility to establish and maintain trust in how they manage residents' information and experiences. Here are some considerations to take into account when managing application information in CiviForm.

Informing residents

Programs should clearly explain to residents how their information is being used when submitted through CiviForm, both across programs and for individual programs. For example, communicating the full application process for a given program in its description can help residents understand what happens after they submit their application, including follow-ups or any other information that may need to be provided. Additionally, explaining why certain pieces of information are required and who will be reviewing them can help give residents confidence and trust in the application process.

How information is managed in CiviForm

When an applicant submits information via CiviForm, that information is submitted to a specific program. Administrators of that program can view any application submitted to that program, but they cannot view information the applicant has submitted to other programs. That is, from each program's perspective, the only information a program administrator can see is the information that the applicant has explicitly submitted to that program.

Once an application is submitted, the applicant's submitted information is stored in a database to be re-used when the applicant chooses to apply to another program, but it is not otherwise accessible outside of an application that has been submitted to a specific program.

When an applicant begins an application to another program, their previously-submitted information in CiviForm is used to pre-populate the new form with any questions they may have answered from other programs. Their information is not visible to the new program until the new application to that program is submitted, at which point only the information in that new program's application is visible to the new program administrators.

Who can export information

Information in CiviForm can be exported by CiviForm Administrators, either via the or through . When API access is configured, each API key must be explicitly assigned a list programs that it has permission to access (i.e. an API key can be configured to allow access to only one program, or to multiple programs). CiviForm Administrators do not have inherent ability to view application information, but CiviForm can be configured to grant CiviForm Administrators that permission.

Program administrators can only view and export information for programs to which they are assigned. Importantly, program administrators can view and export any application that has been submitted to their program.

Managing information across programs

If certain application information will be deliberately shared across programs by the organization administering CiviForm (for example, through a common intake form that is then sent to other programs as a referral), it is essential to communicate this process to residents and ask for their approval on which programs their information should or shouldn't be shared with. Providing a clear explanation for how common intake information might be used (e.g. for proactive outreach from programs) can help residents understand whether or not they see value in having their information shared with other programs.

Working with trusted intermediaries

Trusted intermediaries can submit and modify applications on behalf of residents. When a trusted intermediary submits an application, any other staff member assigned to that trusted intermediary group can also view and modify each application submitted through that trusted intermediary.

You can mark one program as the pre-screener (aka intake form). The pre-screener is pinned to the top of the programs page for applicants in a special Find services section. After the applicant submits the pre-screener, programs they may be eligible for are displayed to them based on their answers. For that reason, you may want to use the pre-screener feature in combination with specifying eligibility conditions on non-pre-screener programs.

Using eligibility conditions in combination with the pre-screener

When the applicant fills out the pre-screener, programs they may be eligible for are displayed to them based on their answers. To make the most use out of this feature, set eligibility conditions on the programs using questions that appear on both the pre-screener and the target program.

For example, you may create a pre-screener with a question asking applicants for their date of birth. You may have program A that requires applicants to be at least 18 years old and program B that requires candidates to be under 18. Set an eligibility condition for program A specifying that the applicant is eligible if 18 or over. Set the eligibility condition for program B to under 18. Then when the applicant fills out the pre-screener, either program A or B will be recommended to them based on their answer to the date of birth question.

Creating a program and marking it as the pre-screener

1. Sign in to CiviForm as a CiviForm admin.

2. Click Programs on the navigation bar.

3. Click Create a new program.

4. Fill out all of the program details and check the Set program as pre-screener

Marking an existing program as the pre-screener

1. Sign in to CiviForm as a CiviForm admin.

2. Click Programs on the navigation bar.

3. Click Edit for the program you would like to set as the pre-screener.

4. Click Edit program details

Note that eligibility conditions cannot be set for the pre-screener, so if you had already created eligibility conditions for this program, they will be removed.

Viewing which program is the pre-screener

1. Sign in to CiviForm as a CiviForm admin or Program admin.

2. Click Programs on the navigation bar.

3. The pre-screener will be labeled. If no program has the pre-screener label, there is no pre-screener currently set.

Setting a redirect URL for when no eligible programs are found

If the applicant fills out the pre-screener and no programs they may be eligible for are found, we display a message to them that contains a link to the civic entity's website where they can find more benefit programs. The message says:

The pre-screener could not find programs you may qualify for at this time. However, you may apply for benefits at any time, by clicking 'Apply to programs'. Or to view additional benefit programs you can visit CIVIC_ENTITY_WEBSITE

To set the text and URL that are used for CIVIC_ENTITY_WEBSITE, you need to set the following in your deployment script:

• COMMON_INTAKE_MORE_RESOURCES_LINK_TEXT

• COMMON_INTAKE_MORE_RESOURCES_LINK_HREF

Trusted Intermediaries can help residents apply to services or they can alert individual Applicants that programs are open to applications. They can also create profiles for their clients when applying. If the Applicant has applied to programs using CiviForm in the past, and they elected to save their information, CiviForm can reuse the Applicant’s stored information for future applications.

CiviForm also allows Trusted Intermediaries to manage multiple clients through the application process. Trusted Intermediary Groups can also view the Applicant data their staff have entered.

Note: Before a Trusted Intermediary can sign in, they must be added to a Trusted Intermediary Group by the CiviForm Admin. For more details, go to Manage Trusted Intermediaries.

Add clients

1. Sign in to CiviForm as a Trusted Intermediary. This will take you to your dashboard.

2. Click the button on the right side of the page that says Add new client.

3. Fill in the new client form and click Save.

4. Now you can either click Start an application or Back to client list.

Apply to a program for a client

1. Sign in to CiviForm as a Trusted Intermediary. This will take you to your dashboard.

2. Here you will see a list of all your clients. You can search for your client by name or date of birth.

3. When you find your client, click View applications to start an application for them. It should now say "You are applying for client name” on the Programs and services page.

4. Find the program you want to apply to and click

CiviForm Admins are responsible for setting up and managing Trusted Intermediaries. A Trusted Intermediary Group is a Community-Based Organization (CBO) that helps people apply for benefit programs. A Trusted Intermediary is a CBO staff member who interacts with Applicants.

Watch the video or follow the step-by-step guide below.

Create a Trusted Intermediary Group

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Intermediaries on the navigation bar.

3. Enter information for the group (Note: The group name should be unique).

4. Click Create. The new group appears in the list of groups.

Note: Once the Trusted Intermediary Group field is set, it cannot be edited.

Add a Trusted Intermediary to a Trusted Intermediary Group

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Intermediaries on the navigation bar and select a Trusted Intermediary Group.

3. Click Edit.

4. Enter the work email address of the staff member you wish to add.

Delete a Trusted Intermediary Group

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Intermediaries on the navigation bar.

3. Select a Trusted Intermediary Group and click Delete. The group and its associated members are removed from the list of groups.

Note: Deleting a group also deletes the group members. However, program applications submitted by the deleted group remain in the system.

Delete a Trusted Intermediary Group member

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Intermediaries on the navigation bar.

3. Select a Trusted Intermediary Group and click Edit.

4. Select a Trusted Intermediary and click Delete

Note: Deleting a Trusted Intermediary doesn’t remove the program applications submitted by the group member.

CiviForm supports two different flows for authentication:

• Applicant authentication - how residents and trusted intermediaries or community based organizations will log into CiviForm

  • Accessed by the "Log in" or "Create account" buttons at the top right of any page or in the middle of the home page

  • Examples providers include: Login.gov, Oracle IDCS, LoginRadius, Generic OIDC (i.e. Auth0 or Google Identity)

• Admin authentication - how CiviForm administrators and program administrators log into CiviForm

  • Accessed by the "Are you an administrator? Admin login" prompt at the bottom of the home page

  • Example providers include: Okta and Azure AD

Choosing an authentication provider involves various considerations, including price, existing login providers used by other sites managed by the city, and ease of use for both the city staff and the people logging in.

Once an authentication provider is chosen, it is not recommended that it is changed, since data associating an applicant to their applications would be lost.

Authentication setup

At a high level, most authentication setups will involve:

1. Some setup through the authentication provider's website

2. Adding configuration values into the config.sh file of the deployment

3. Updating AWS Secrets Manager with the client ID and secret values

Admin authentication setup

• Okta and generic OIDC: follow steps

• Azure AD and ADFS : follow steps

Applicant authentication setup

• Generic OIDC: follow steps

  • Auth0: follow steps

  • Google Identity: follow steps

• Login.gov: follow steps

At the heart of delivering effective government services is the practice of civic service design. Service design strategies aim to understand the needs of residents and craft policies, processes, and services that are tailored to meet those needs. This can include how people find or apply to services, how they interact with programs through in-person staff or digital tools, what programs require from residents throughout the application process, and operational practices such as providing applicant support and reporting on program outcomes.

CiviForm is designed to make it easy to implement key best practices in civic service design, such as making program information and applications accessible to residents, supporting workflows for community organizations, notifying applicants of their progress, enabling operational insights through data reporting, and integrating with existing administrative systems and processes. As you work to improve service delivery in your community, service design can help guide how you implement CiviForm to support your specific programs.

Service design is grounded in understanding the resident experience as it currently is, and identifying improvements to better meet the needs of residents and better fulfill the mission of each program. The remainder of this guide will focus on how CiviForm can best enable such efforts through the lens of civic service design.

Here are excellent resources on service design to read and reference as you work:

• : A comprehensive overview of civic service design practices, including understanding resident needs, mapping processes, and ideating on solutions. Each section includes useful templates and resources for different research and engagement practices.

• • Starting Small with Human-Centered Redesign ()

  • Going Big with Human-Centered Redesign ()

We support on-demand deployment of the pgadmin web UI to temporarily access the CiviForm database. We require explicit IP allow-listing via a list of CIDR blocks. Only these IPs will be able to access pgadmin. The public IP of the host running the web browser used to access the pgadmin web UI (like your work laptop/desktop) must be covered by a block in the list. This can be useful when investigating and/or remediating production incidents.

When accessing the database in this way, it is strongly recommended to do so on a trusted network and device. Furthermore, do not interrupt the script while it is running (ctrl-c) as this may prevent it from revoking the temporary security settings allowing connections from the public internet.

How it works

To provide access to the production database, the access script creates a temporary node running pgadmin along with a random username and password in the CiviForm VPC and temporary network security settings allowing it to connect to the production database. It also adds network security settings allowing connections from an IP-allowlist from the public internet. With the access script running, you must make requests from an allow-listed IP and enter the username and password to access the database.

Access the database for emergency repair

AWS

To detect the public IP of a host running a web browser, visit https://checkip.amazonaws.com.

1. Run ./bin/run

2. When prompted for a command to run, enter pgadmin

3. The deploy tool will auto-detect the public IP of the host it is running on and ask if you would like to add the IP to the allow-list. If you want the deploy tool to wait until pgadmin is available to print out connection information, enter 'y'.

Saving files within pgadmin

WARNING: The pgadmin tool has the ability to save queries. Do NOT save files within the tool. When pgadmin is shutdown it will permanently remove the files. If you need to save a query, copy and paste it into a file on your computer.

Updating data in pgadmin

We cache program and question data on the server for active and obsolete versions, so if you're making changes to this data, you may not see updates reflected until you:

• Dev / staging instance: clear the cache by going to Dev Tools -> Additional tools -> Clear cache

• Prod instance (in which data shouldn't be maniputlated or should be done with extreme caution): re-start the the application containers to clear the cache

CiviForm admins can add programs hosted outside of CiviForm to reduce the burden on residents of navigating multiple websites to search for relevant programs and information. External programs will be presented to applicants along with other programs, but with a clear indicator that the program opens in a link outside of CiviForm.

Enable external programs feature

External programs are currently under a feature flag. The feature must be turned on to allow external programs be added by admins and be visible to applicants. To enable external programs feature:

1. Sign in to CiviForm as a CiviForm admin.

2. Select Settings on the navgiation bar.

3. Enable EXTERNAL_PROGRAM_CARDS_ENABLED.

Create an external program

1. Sign in to CiviForm as a CiviForm admin.

2. Click Programs on the navigation bar.

3. Click Create a new program.

4. Select External program as the program type.

Notes:

• An external program cannot change its type after creation.

• There can be multiple external programs in a CiviForm instance.

View external programs

1. Sign in to CiviForm as a CiviForm admin.

2. Click Programs on the navigation bar.

3. External programs will be clearly labeled in the program list.

Notes:

• External programs are not visible to Program admins since external programs have no settings they can manage.

How external programs appear to applicants

When applicants view available programs, external programs are displayed alongside regular CiviForm programs. When an applicant clicks on an external program card, a modal dialog appears that informs the user that the program will be opened outside of CiviForm. The applicant must accept this modal to proceed, which then opens the external program's website in a new window or tab.

External programs are only visible to applicants when North Star is enabled.

https://github.com/user-attachments/assets/229bc9b7-bf20-4924-be33-4299931a576c

Information specific to CiviForm Terraform deploy scripts for AWS.

For general information, see .

Infrastructure

Created for CiviForm app:

When creating programs, some application questions might not need to be displayed when based on the answers to previous questions. For example, if an Applicant’s date of birth is earlier than the qualifying year, a screen displaying a discount code for older adults is unnecessary.

Using a visibility condition, CiviForm Admins can easily show or hide a screen based on the answer to any question within the program.

Important: If you create a visibility condition based on a question that’s potentially hidden behind a different visibility condition, unexpected behaviors might occur.

Add a visibility condition

This section outlines strategies on how to adopt and implement CiviForm to meet your organization's needs.

• Plan: Map the needs of your organization and programs in detail to understand where CiviForm can help.

The CiviForm core team every other week on Tuesdays or Wednesdays. We strongly recommend deployments stay up to date with the latest version to benefit from security patches, bug fixes, and new features.

Each release is published using with a corresponding server Docker image uploaded to and tagged with the release number.

Be sure to review the release notes on GitHub for each new release before deploying it.

Release notes include:

• Description of fixed bugs and security vulnerabilities

While your program may be administered by and for your jurisdiction, there are likely other programs administered by federal, state, or local agencies that are also relevant to the residents of your jurisdiction. They may not know or care that certain programs are administered by the city, county, state -- they just need help. Surfacing programs from other jurisdictions can be a powerful way to connect residents with the services they need, regardless of where those programs are administered.

Integrating with other application systems

It's likely that programs operated by other jurisdictions already have existing tools and processes for accepting applications and delivering services. In this case, one possible approach is to work directly with those programs to establish data integrations with their existing systems as described in "".

If direct integrations are seen as too challenging, other approaches may include:

CiviForm uses email to send notifications to program administrators, applicants, and for a few other functionalities. Email addresses are provided via the deployment configuration file or the Admin Settings Panel. Below is the list of different email addresses that are required and some recommendations on how to organize them.

Email addresses

Support email address Applicants see this email address in the footer of each page as a mailto link. This value should be set via the Admin Settings Panel SUPPORT_EMAIL_ADDRESS.

Sender email address This email address is used as a sender for all notifications sent by the CiviForm. For example, notifications sent on new applications (sent to program admins) and program status changes (sent to applicants). Config variable is SENDER_EMAIL_ADDRESS.

Notifications recipients in staging. These email addresses are used only in staging. Instead of sending email notifications to program admins, they are sent to the provided email addresses. Config variables: STAGING_PROGRAM_ADMIN_NOTIFICATION_MAILING_LIST, STAGING_TI_NOTIFICATION_MAILING_LIST, STAGING_APPLICANT_NOTIFICATION_MAILING_LIST.

Emails in staging

For simplicity, we recommend having a single email address for staging and use it in all the variables listed above.

Emails in prod

If your organization already contains a tech support email address, use it. Otherwise, you can create something like [email protected]. For simplicity, you can use the same email as sender. That way, admins and applicants can reply to the email if they are having difficulties or questions about the notification they received. Remember that that someone needs to regularly check the inbox for the email addresses used in CiviForm.

AWS SES

CiviForm uses the AWS Simple Email Service (SES) to send emails. To send emails from a certain address, a verified identity must be created for the address. There are two kinds of verified identities: email-verified and domain-verified.

In a new deployment, SES starts in sandbox mode. While SES is in sandbox mode, it can only send emails to verified identities. SES must be taken out of sandbox mode for prod deployment, otherwise it will not be able to send emails to applicants, program admins, and TIs. Follow to take SES out of sandbox mode.

We create email-verified identities for each unique email specified by the server environment variables SENDER_EMAIL_ADDRESS, STAGING_PROGRAM_ADMIN_NOTIFICATION_MAILING_LIST, STAGING_TI_NOTIFICATION_MAILING_LIST, and STAGING_APPLICANT_NOTIFICATION_MAILING_LIST. After the initial deployment, AWS will send 'Email Address Verification Request' emails to each created identity. You must click the verification link in the email for the identity to be verified. This allows you to test email sending in staging deployments without taking SES out of sandbox mode.

Using a no-reply email address for SENDER_EMAIL_ADDRESS

If you wish to use a no-reply address with no ability to receive emails, there are two options:

1. Configure the no-reply address so that it can receive emails before the first deployment, deploy CiviForm, click the verification link in the 'Email Address Verification Request' email sent to the no-reply address, then configure the no-reply address to not receive any emails.

2. Create a domain-verified SES identity. For example, to use '[email protected]', you must create a domain-verified identity for 'mystate.gov'.

   Follow the steps in the 'Creating a domain identity' section of . To verify the domain, you will need to add CNAME records in your domain registrar.

Testing emails

After deploying CiviForm to staging or prod it's important to test that email integration works correctly. Here is the list of things to try:

1. Open the CiviForm site as an applicant and send email to the technical support email address provided in the footer.

2. Create a program with a status that has email content.

3. Apply as an applicant.

4. Program Admin and applicant (and TI if present) should receive the email.

Troubleshooting SES email issues

1. Go to Simple Email Service in the AWS console

   • On the "Get Set Up" page, ensure production mode is enabled. Without production mode enabled, emails can only be sent from verified domains and there is a limit to the number of emails that can be sent

   • On the "Identities" page, ensure the identities are verified. You can use a specific email identity or a domain.

2. Check the ECS logs

CiviForm Admins can translate text for both programs and questions using the CiviForm interface. When an Applicant chooses a language, the entered text is displayed in the application.

English is the default language for CiviForm. If CiviForm doesn’t include translations for a requested language, the default language is displayed instead. A warning also appears stating the form is not fully translated into the requested language.

Note: There’s no user interface for the CiviForm Admin to add or remove translation languages from programs or questions. The list of languages CiviForm can support is set up within the code.

You can edit both unpublished and published programs. To edit published programs, you need to click New Version. For more details on versioning, go to Manage versions for programs & questions.

Watch the video or follow the step-by-step instructions below.

Add or edit program translations

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

1. Find a draft (unpublished) program.

   • To add or edit translations for a published program, and save a version of the program in the draft (unpublished) state.

2. Click the three dots button on the right-hand side.

Add or edit question translations

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar and select an unpublished question.

3. Click Manage draft translations.

CiviForm's production database is backed up daily, with snapshot names prefixed with the value set by POSTGRES_RESTORE_SNAPSHOT_IDENTIFIER. By default they are retained for 7 days, which can be configured byPOSTGRES_BACKUP_RETENTION_DAYS.

Making a full backup and restore of the database

As part of your backup strategy, you may want to dump the contents of the database outside of AWS in case something happens to your AWS account. There are a couple ways to do this.

Option 1: Use the pgadmin UI

Backup

1. Follow the instructions to .

2. Right click the postgres database and choose Backup.

1. Pick any file name. All of the options can be left as default. If you'd like to only download some of the data, you can select which tables to download in the Objects tab. Note that this saves the file locally inside the pgadmin container.

1. When complete, in the top menu bar, click Tools -> Storage Manager.

1. Choose the file you just created, then click the download button.

1. Save this file in a secure location.

Restore

1. If your backup file is larger than 50MB, go to File -> Preferences -> Storage -> Options and change the maximum file upload size appropriately.

1. In the top menu bar, click Tools -> Storage Manager.

1. Click the Options button and choose Upload, then upload your backup file.

1. Right click the postgres database and choose Restore.

1. Under Filename, choose the file you just uploaded. In the Query Options tab, select Clean before restore. Then click Restore.

1. Inspect the tables under postgres -> Schemas -> Tables to verify the data was restored properly.

Option 2: Use the dumpdb and restoredb commands

This option utilizes the CiviForm Terraform-based deployment system. It will create a temporary EC2 host with access to the database, install the PostgreSQL client, run pg_dump or pg_restore, and then clean up the resources. These commands require the ssh, ssh-keygen, and scp binaries to be available on your system.

Backup

1. From your clone of the civiform-deploy repo, run bin/run.

2. Enter the dumpdb command and follow the prompts.

Restore

1. From your clone of the civiform-deploy repo, run bin/run.

2. Enter the restoredb command and follow the prompts.

Answering these questions will make it easier to understand how CiviForm and other tools should adapt to the needs of applicants and program staff. Answering these questions can help form a journey map of applicants and program staff experiences to inform where and how changes might be implemented.

What department or organization administers this program?

What challenges do you face in administering or managing this program?

Any details are fine, the challenges do not need to be technology-related.

How do residents typically find out about the program?

Include websites, community organizations, or other channels.

Where or how do residents typically submit applications to the program?

Include websites, electronic forms, paper forms, community organizations, program offices, or other channels.

Do residents typically apply on their own, or do they receive assistance in applying?

For example, from program staff, call centers, community organizations, social workers, or others.

How many applications do you process each (day, week, month, year)?

What information is necessary to apply to the program?

Share a link to the form or application, or share the questions directly here.

How long do applications typically take to be completed (from start to submission)?

Once submitted, how long do applications take to be processed (from submission to approval)?

What steps are involved in the life cycle of applying to the program, processing an application, and delivering benefits?

Include the end-to-end life cycle from discovery to the delivery of benefits in as much detail as you can manage, including typical timelines, individuals or roles involved, and steps from both the applicant side and the program/administrative side (and any other stakeholders involved).

For example:

Discovery and application (X minutes total):

1. Resident discovers program through local community group

2. Resident fills out application X via website at www.example.com with help from local staff member (30 minutes)

3. Resident comes into program office to drop off paper form (30 minutes)

4. Paper form is prepared for processing by program staff in X group (once daily)

Processing (X days total):

1. Program staff is assigned an application to process (once daily)

2. Program staff begins processing application within X days after submission

3. Program staff from group A enters information into computer system Y

4. Program staff cross-references data in systems Y and Z

Delivery (X days total):

1. Approved application is marked for delivery in system A (once per application manually, 10 minutes)

2. Data is exported from system A to system B for fulfillment (once daily for all applications automatically)

3. Benefits are delivered through mail (X days)

(feel free to adjust these section categories or use your own)

Discovery and application (X minutes total):

1. ...

2. ...

3. ...

Processing (X days total):

1. ...

2. ...

3. ...

Delivery (X days total):

1. ...

2. ...

3. ...

What applications, systems, websites, tools, or other resources are used to process information or applications for this program?

Include tools used at all steps, including for application intake, record-keeping, benefits processing and delivery, status notification, data aggregation, reporting, or any other tools.

Do you cross-check eligibility information or other details with any other programs or data sources?

Do you report your program data to any organizations or stakeholders? What do you report and how is it reported?

There are programs that may have strict criteria for eligibility. For example, if an Applicant’s date of birth is earlier than the qualifying year, they are ineligible for the program.

Using eligibility conditions, CiviForm Admins can screen applicants who don't meet the minimum requirements for a program early in the application process, as well as show applicants cases when there is a program they may qualify for, based on their previous answers.

Add an eligibility condition

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Click Edit for the program you would like to add a condition for.

4. Select a screen you wish to add an eligibility condition for and click Edit eligibility condition.

5. On the Eligibility Condition page, under New eligibility condition, select the question(s) you would like to use for your condition and then click Add condition.

6. For each question in your condition:

   1. Set the Field data type.

   2. Set the Operator value.

   3. Enter the Value.

7. The eligibility condition is displayed on both the Eligibility Condition page and the screen. For example, “Screen 3 is eligible if household size question name Number is less than 2."

Multiple allowable values can be specified for a given set of questions in a condition. For example, if a condition uses two questions, household size (number) and household income (currency), multiple combinations of household size and income pairings can be specified that meet the condition. To add additional value groups, click +Add values on the Configure Eligibility Conditions page and fill in the additional values.

Edit an eligibility condition

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Click Edit for the program you would like to edit a condition for.

4. Select a screen you wish to edit an eligibility condition for and click

Remove an eligibility condition

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar and select a program.

3. Select a screen with an eligibility condition and click Edit eligibility condition.

4. Click

Rules for eligibility conditions

The following rules apply when trying to understand eligibility conditions:

• There can only be one eligibility condition per screen (but can be across multiple questions).

• When using a text field, the value should not be in quotes.

• When using the operators "is one of" or "is not one of" on text values, the text should be in a comma-separated list. For example, blue,green,purple. The eligibility condition fires if the answer to the question is blue or green or purple.

Allowing applicants to submit ineligible applications

By default, eligibility conditions block application submission for ineligible candidates. If you'd like to allow ineligible applicants to submit applications, you can change this in the program settings page. The applicant will not be blocked from submitting an application, but the program admin will still be able to see that the application is ineligible during review.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. If the program is not already a draft, you must create a draft of it by clicking Edit. Return to the Programs page after doing so.

Overview

This guide will walk you through performing a full restoration of your CiviForm environment in the event you need to recover a broken installation. This process will allow you to specify a database snapshot and will build out a full, brand new environment.

We do not recommend trying to restore over an existing environment for two reasons. The first is that keeping the old one allows for future investigation on the cause of a failure at a later date when there is no pressure to restore services.

The second is that by building out a brand new environment there is no chance of introducing incorrect settings with system components that may be in an unknown working state.

Prerequisites

This guide assumes there has already been an initial setup of the system as outlined in the .

Prepare config file

• Find the existing config file for the environment needing restoration. The default name is often civiform_config.sh.

• Make a copy of the original config file that was used for the last successful deployment.

Edit the new config file

Make a few edits to the new configuration file.

• Change APP_PREFIX to a new value.

• Set POSTGRESQL_VERSION to the version of the existing database.

  • To find the postgres version go to the AWS console and navigate to RDS.

  • Click on the database you will be restoring to get the details page

  • Click on the "Configuration" tab

• Set POSTGRES_RESTORE_SNAPSHOT_IDENTIFIER to the snapshot to restore.

  • To find the snapshot identifier go to the AWS console and navigate to RDS > Snapshots.

  • Use the snapshot identifier (not the name, the identifier begins with rds:) for the value for POSTGRES_RESTORE_SNAPSHOT_IDENTIFIER.

Do NOT change any other settings.

Initialize the deployment

Verify that deployment tool is correctly setup by running run bin/doctor --config=NEWCONFIGFILE

Restore into new environment

• To begin the restoration run bin/setup --config=NEWCONFIGFILE.

• Wait as setup runs

• When prompted enter the values for all the requested secrets.

• When prompted for Postgres snapshot restore follow all prompts. You will be asked for the app prefix of the old environment. This is the value from APP_PREFIX

When complete, make note of the endpoint url listed at the end of the deployment. It will be the one that has the APP_PREFIX from your new config file and ends with "elb.amazonaws.com".

At this point the new environment is setup and should be online at the above endpoint url if no errors occurred during this process.

Verify the new site is working

Test that the site responds by using the endpoint url from the previous section.

• Paste the endpoint url into your browser, you will see an invalid SSL certificate error and may not be able to proceed depending on your browser settings. If you can temporarily accept the invalid certificate you should see the CiviForm program page load.

• Alternatively, you can run curl --insecure --location PUT_ENDPOINT_URL_HERE. The results should be HTML.

Change DNS settings to point to new site

• Go to AWS Route53

• Go to Hosted zones

• Click the Hosted zone name link for the site you just restored

• Select the A

Testing

• Verify you can log in as an admin and an applicant

• Check Cloudwatch for errors

Post restoration

• Remove the POSTGRES_RESTORE_SNAPSHOT_IDENTIFIER from the config file.

Going forward with new deployments you will continue to use this new file.

Overview

Program import is a feature to allow programs and their associated questions to be imported into a CiviForm environment. Imported programs may be migrated from one CiviForm environment to another or imported from another source.

Handling question collisions

If a program you are importing shares questions with an existing program in your import environment, you can decide whether you want to create a new duplicate question, use the existing question, or overwrite the existing defintion in your question bank. "Shared questions" are determined by the question admin name. Here are our recommendations for when to choose which option:

1. Reuse the existing question (Default)

   • Use this option when you want to import a program into an environment that already has existing programs and you want to reuse the questions in the import environment.

   • Use this option when you want to import many programs with overlapping questions into a fresh environment.

   • The newly imported program will benefit from CiviForm's shared question model.

Exporting a Program

1. Each program on the program dashboard page has a menu item that says “Export program”.

2. Click this to be taken to the program export page for that program.

3. From there you will have the option to download or copy a json representation of the program.

4. Program export works for programs that are in draft or active mode. Either way they will be imported as drafts into the new environment.

Importing a program

1. Look for the “Import existing program” link on the program dashboard page.

2. Click this link to be taken to the program import page and follow the instructions there to import a program.

Program Settings That Are Not Migrated

There are a few program and question settings that are not yet being migrated over. You will have to manually set these in your import environment after importing a new program:

• Program images

• Program statuses (and their associated translations)

• Any categories assigned to the program

• TI groups associated with the program

Potential Errors

Situations in which you might get an error include:

• Attempting to import a program that is larger than 512,000 characters.

  • We do not currently support importing programs that are larger than 512,000 characters. If you need to import a program that is larger than this limit, contact the engineering team and we can look into raising the size limit.

• Attempting to import a program with an admin name that matches the admin name of an existing program.

The 4 users of CiviForm

Through the Google.org Fellowship, user researchers identified 4 key users of CiviForm:

• are residents seeking public services.

In order for CiviForm to be implemented sucessfully, it must be easy for your program staff to continue administering their programs without significantly disturbing their existing workflows and processes. Integrating CiviForm with existing tools and processes allows staff to take advantage of CiviForm's benefits without introducing a substantial learning curve.

This approach assumes there are three phases of end-to-end service delivery: (1) Accepting applications, (2) reviewing applications, and (3) delivering benefits/services. Existing tools may serve all or none of these purposes, whereas CiviForm can serve to (1) accept applications, and optionally (2) review applications, depending on the needs and existing approach of each program.

Here are a few examples of how CiviForm can integrate with existing tools and processes.

Accepting applications from CiviForm to process with existing tools

Certain programs may already have back-office tools that work well for program staff. In such cases, CiviForm can integrate with those tools as a channel to acccept applications without significant additional effort necessary on the part of program staff.

CiviForm as the primary channel for accepting applications

If a program doesn't have a significant existing online application (e.g. primarily paper, phone, or walk-in applications), but does have existing back-office tools for application review and processing, then CiviForm can serve as the primary resident-facing channel through which the program accepts applications online. When residents submit applications through CiviForm, the data can be exported using the API and ingested into the existing tool for program staff to review and process as they normally do.

CiviForm as a secondary channel for accepting applications

If a program already has an online form for accepting applications that the program wishes to keep, CiviForm can be used as a secondary channel for accepting applications. Similar to the option above, application revview and processing takes place in existing tools -- CiviForm just acts as another source of applications.

Keeping tools in sync

In the examples above, program staff do not need to interact with CiviForm at all, since it is simply being used as another channel for accepting applications into existing back-office tools. However, depending on the remainder of the process, it may be important to keep specific information in sync across existing tools and CiviForm.

For example, if you wish to communicate program status updates via email to applicants using CiviForm, that information must be updated in CiviForm, either via the interface or through the API (API re-design in progress as of Q2 2023). However, if status updates are communicated through existing tools, then no such integration back into CiviForm is necessary and CiviForm's status update feature can be disabled for that program.

Similarly, if additional information needs to be collected from an applicant, if that information is collected through a tool other than CiviForm, it will not be apparent to the applicant that their information has been updated. In this case, asking the applicant to submit the additional information from within CiviForm directly, or having a mechanism to feed the new information back into CiviForm via the interface or API (API re-design in progress as of Q2 2023) may be necessary to ensure a good applicant experience with consistent information across tools.

Additionally, if information requirements change in existing forms or online applications, mechanisms must be put in place to update CiviForm's forms to match those changes and ensure consistency across different channels.

Linking data with existing accounts

CiviForm for discovery or eligibility screening

Even if CiviForm is not used to accept applications for a given program, it may be valuable as a tool for discovery or eligibily screening that then directs applicants to an existing application form. See "" for more information.

Accepting and reviewing applications within CiviForm

If a program doesn't already have a back-office application review tool or is looking to replace an existing tool, program staff can directly use CiviForm to review applications. For simple programs, this enables staff to take advantage of CiviForm's built-in features such as status tracking, status notifications, and note-keeping. For more complex programs, additional steps may be required for the delivery of benefits/services after applications are approved within CiviForm (for example, exporting data to a payment processor or another system to disburse funds, or referring someone to a service provider for next steps).

CiviForm as the primary tool for reviewing applications

If a program wishes to use CiviForm as the primary interface through which applications are reviewed, CiviForm can perform this functionality out of the box. Program administrators can review applications, keep internal notes, update an application's status, and send notifications to applicants when their application status changes.

This approach can be taken regardless of whether or not there are existing channels for application intake; however, administration may be simpler if a program chooses to standardize on using CiviForm for application intake (for example, encouraging individuals to apply through CiviForm, or having program or CBO staff submit walk-in or phone applications through CiviForm on behalf of residents). Otherwise, there will be separate review processes for different application channels.

CiviForm as a secondary tool for reviewing applications

If there is already a tool used for reviewing applications that a program wishes to keep, CiviForm can be used alongside that tool, albeit at the cost of having two different review processes. This may be useful in a state of transition as a program consolidates to use one tool (whether CiviForm or the existing tool), or if there is a way to consolidate the remainder of the delivery process after applications are reviewed across tools. Understanding the primary channels for accepting applications and the downstream processes after applications are review can help make a decision about how to best integrate CiviForm within a program's workflow.

Other considerations

Consider these other factors when integrating CiviForm with existing tools.

• Can the program's existing tool ingest data from external sources via an API?

• What is your IT team's preferred approach to running data import/export pipleines?

• What is an acceptable frequency for applications to be exported from CiviForm and imported into other systems?

• What processes must be implemented to ensure breaking changes to forms or APIs are accounted for across systems?

Outage, site is down

DNS

Symptoms

• "This site can’t be reached" in Chrome

• Requests timing out

Diagnose

On a unix command line, run dig <your CiviForm domain>. (Note: Remove the protocol -- http or https -- from the front of your domain before running the command.) There should be a CNAME entry that points to an AWS load balancer e.g. seattle-civiform-lb-2038295446.us-west-1.elb.amazonaws.com.

Confirm that the CNAME record matches the public domain for your AWS application load balancer by visiting the AWS console EC2 > Load Balancing > Load Balancers and finding the load balancer for your prod deployment.

Resolution

If the CNAME entry is missing or does not match the DNS name you find in AWS, add or update a CNAME entry in your domain registrar with the application load balancer's DNS name.

Server can't start

Symptoms

• "This site can’t be reached" in Chrome

• Requests timing out

Diagnose

View the ECS cluster for your prod deployment in AWS by going to ECS > Clusters and clicking the cluster for your production deployment. There should be at least one healthy task. If all tasks are unhealthy or unknown the server is unable to start.

If no tasks are healthy, view the server logs (see Server errors below). Look for stack traces and error messages.

Resolution

If you have just deployed, revert your CiviForm version number to the previous version you deployed and .

Contact the CiviForm maintainers and include any errors you found in the server logs.

Server errors

Symptoms

Server returns 400 or 500 level errors or pages with short, plaintext messages stating an error message.

Resolution

If you have deployed recently, consider reverting your CiviForm version number to the previous version you deployed and .

Investigate the server logs. Report any errors you find along with complete stack traces to the CiviForm maintainers. To view the server logs in the AWS console go to CloudWatch > Logs > Log groups, select the log group for your production deployment and view the combined log stream.

Symptoms

Server returns 504 Gateway Timeout error, especially when doing admin actions such as application exports.

Resolution

If the CiviForm server takes too long to respond to a request, the load balancer will time out. This can be configured by setting export LB_IDLE_TIMEOUT=<integer> to a value larger than the default 120 seconds in your config file and redeploying.

Authentication errors

Symptoms

Users are unable to log in.

Resolution

Check with maintainers of the admin and applicant auth systems if there have been recent changes. Check the for your CiviForm version to see if it mentions auth changes. If errors are occuring after the user successfully authenticates with the identity backend and redirects back to CiviForm there is likely a server error involved. Check server logs for errors.

Contact CiviForm maintainers with details of the investigation.

Errors related to Authority ID

If a user has created an account as an applicant and then is added as an admin with the same email, they may see an error when logging in. When checking the logs, it'll show Profile already contains an authority ID: Optional[iss:xxx] - which is different from the new authority ID: Optional[iss:yyy]. To fix this error, the account admin will need to and update the particular account to use the new authority ID. First, you can find the existing account by runnning SELECT * FROM accounts where authority_id = 'iss:xxx' (with the original authority_id). Once you confirm there is one account listed and it is the correct account (see note below), you then can run UPDATE accounts SET authority_id = 'iss:yyy' WHERE authority_id = 'iss:xxx';

NOTE: It should be strongly verified that the user/account is correct. Changing this without care is a security issue as now the "new" account has access to the system.

This document describes the infrastructure required to deploy CiviForm into a new jurisdiction.

CiviForm is a classic web-based client-server architecture which stores applicant information in a database. The application server typically runs in a Docker container, a type of virtualized environment which contains most of the pieces described below.

The Subsystems

Basic architecture

Note that there usually is not direct traffic between the CiviForm server and identity providers (dotted lines). Rather, users authenticate by visiting CiviForm, which redirects their browser to an identity provider, which in turn redirects them back to CiviForm.

Map questions allow applicants to view and select locations on an interactive map. This section covers the detailed setup and configuration options for map questions.

Setup requirements

1. A publicly accessible HTTP endpoint that provides location data in the GeoJson format

2. Valid data containing Features with:

   • Unique identifiers (the Feature ID)

   • Point geometry only (longitude and latitude coordinates)

   • Properties must include fields for:

     • Display name of the location

   When setting up the GeoJSON, you may use any name for the individual fields. Later, when configuring the map question, CiviForm Admins will be able to specify which GeoJSON property fields contain the required information.

Sample GeoJSON

Configuration options

When creating a map question, admins must configure:

1. GeoJSON Endpoint URL

2. GeoJSON Key Mappings:

   • Name key: Specify which GeoJSON property contains the location's name (e.g., "facility_name", "location_title")

   • Address key: Specify which property contains the location's address (e.g., "street_address", "location")

Admins can also configure:

• Maximum selections: Limit how many locations an applicant can choose

• Filters: based on specific GeoJSON property keys to help applicants find relevant locations

• Tag: that displays on locations with specific property values

For example, if you were using the

You would:

1. Select facility_name as the name key field

2. Select location as the address key field

3. Select more_info_link as the view more details URL field

Adding a filter

Filters help applicants narrow down location options based on specific criteria. When you add a filter, applicants will see a dropdown or checkbox interface to filter locations by the values in a specific GeoJSON property. Up to six filters can be added to each map question.

To add a filter:

1. Click Add filter when configuring the map question

2. Select the Key that contains the filter values (e.g., "wheelchair_accessible", "service_type", "language_support")

3. Enter a Display name for the filter

How filters work for applicants:

• CiviForm automatically detects all possible values for the specified property across all locations in the GeoJSON data

• Applicants see these values as filter options in the interface

Best practices:

• Use property keys with a limited number of distinct values (e.g., boolean values, categories)

• Avoid using properties with unique values for each location (e.g., phone numbers, specific addresses)

• Ensure the property exists on all or most locations in your GeoJSON data

Adding a tag

A tag displays on locations with a specific property value. Optionally, an alert for that tag displays to applicants when they select a location with that specific property value. This is useful for notifying applicants about special conditions, requirements, or limitations.

To add a tag:

1. Click Add tag when configuring the map question

2. Select the Key for CiviForm to monitor (e.g., "capacity", "status", "requires_appointment")

3. Enter the Value that triggers the tag (e.g., "limited", "closed", "true")

4. Enter a Display name that displays as the tag on a location

How tags work for applicants:

• When an applicant selects a location on the map, CiviForm checks if the tag condition is met

• If the selected location has a property that matches the configured key-value pair, the alert message is displayed

• The tag is informational and does not prevent applicants from selecting the location

Best practices:

• Keep alert messages clear and concise

• Consider what actions you want applicants to take after seeing the alert

• Test the alert with your actual GeoJSON data to ensure it triggers correctly

Data storage and refresh settings

CiviForm stores all the data provided by the GeoJSON endpoint (see ). When an applicant makes a selection, CiviForm stores:

• The unique identifier of the selected location provided as the Feature ID in the GeoJSON data

• The value of the configured name field at the time of selection

Note: It is the admin's responsibility to maintain a record of which location corresponds to each Feature ID, as CiviForm only returns these two pieces of information.

By default, the stored data won't be automatically updated. To enable automatic data refresh:

1. Set durable_jobs.map_refresh=true in your application configuration

2. Once enabled, CiviForm will ping the GeoJSON endpoint every 10 minutes to refresh the data. If the endpoint fails at any point, the data will not be updated and CiviForm will continue to use data from a previous successful call until it is able to successfully refresh the data.

This automatic refresh is useful for locations with frequently changing properties (e.g., availability, capacity, or service hours).

Validation options

The map question supports:

• Required vs optional selection

• Maximum number of selections

Accessibility considerations

To ensure map questions are accessible to all users:

• Ensure location names are clear

• Include several filters so that applicants can narrow down the list of locations

Troubleshooting

GeoJSON endpoint failing

Problem: CiviForm cannot fetch data from the GeoJSON endpoint.

Possible causes and solutions:

• Invalid GeoJSON format: Verify your GeoJSON data is valid using a validator like

• Missing Feature IDs: Ensure every Feature in your GeoJSON has a unique id field

• Incorrect geometry type: Map questions only support Point geometry. LineString, Polygon, and other geometry types will not display

Key mapping not working

Problem: Location names, addresses, or URLs not displaying correctly.

Possible causes and solutions:

• Incorrect key selection: Verify you've selected the correct property keys during map question configuration

• Missing properties: Ensure all Features in your GeoJSON have the name, address, and URL properties

• Null or empty values: Check that the properties contain actual values, not null or empty strings

Filters not showing expected options

Problem: Filter dropdowns are empty or missing expected values.

Possible causes and solutions:

• Incorrect key selection: Verify you've selected the correct property keys during map question configuration

• Inconsistent property names: Ensure the property exists across locations in your GeoJSON data

• Data refresh needed: If you recently updated your GeoJSON, wait for the next refresh cycle (every 10 minutes if automatic refresh is enabled)

Tags not appearing on locations

Problem: Configured tags don't display on locations.

Possible causes and solutions:

• Value mismatch: Verify the tag value exactly matches the property value in your GeoJSON (case-sensitive)

Data not refreshing

Problem: Updates to GeoJSON data don't appear in CiviForm.

Possible causes and solutions:

• Automatic refresh disabled: Verify durable_jobs.map_refresh=true is set in your application configuration

• Endpoint failures: Check your endpoint logs for any errors during CiviForm's refresh attempts

Selection data missing in exports

Problem: Application exports don't show expected map question data.

Explanation: CiviForm only stores the Feature ID and the name field value at the time of selection. To get complete location information, you'll need to:

• Maintain a separate mapping of Feature IDs to full location details

• Cross-reference the Feature IDs from exports with your GeoJSON data source

You may have some programs that need to collect an applicant's address to offer services. Those programs may also want to verify that the address exists and matches a standard format, and may also want to verify that the address is in the area that's eligible for the program. For example, a program may only be for applicants living in a certain county. CiviForm uses the external Esri service for both these use cases. CiviForm is not currently compatible with other geolocation services. If you'd like to use another geolocation service, please reach out to the engineering team.

Address Correction

Programs may want to have an applicant's address corrected so that they can verify the address exists and have all addresses in a standard format. This needs to be configured both at the deployment level and at a question level.

If you want to see what results address correction might provide, you can experiment with ArcGIS's world endpoint. Here's a sample query for 700 5th Ave, Seattle WA 98101. For your official deployment, you could choose to use this endpoint instead of defining your own, but you would still need to purchase an Esri subscription and create an Esri API token.

Deployment-level configuration

Before any specific program can use address correction, it must be enabled for your deployment as a whole.

1. Set to true.

2. Set to one or more URLs that CiviForm will use to call Esri’s . The service should have a GeocodeServer type. Example URL value: "https://gisdata.seattle.gov/cosgis/rest/services/locators/AddressPoints/GeocodeServer/findAddressCandidates"

1. Optional, but recommended. Set which forces the service calls to return spatial references using the specified wellknown id value for their coordinate system.

Expected findAddressCandidates response format

Civiform expects a response with the following fields:

Notes on parsing:

• If there the response does not include a value in SubAddr, CiviForm keeps the value the user entered.

• If the value in RegionAbbr is not two characters, CiviForm checks the Region field for the two character state code. If it's also not two characters, CiviForm keeps the state code the user provided.

Overriding the default wellKnownId

The Esri API has the ability to return spatial reference data using different coordinate systems via a wellKnownId (a.k.a wkid). Details of that along with links to the long list of possible coordinate systems can be found on the .

The default wellKnownId is 4326 - GPS which are traditional latitude and longitude value most often thought around of around coordinate systems. Custom hosted installations may set a different value as their default. For example, Seattle defaults to using wellKnownId 2926 - NAD_1983_HARN_StatePlane_Washington_North_FIPS_4601_Feet .

This works fine as long as calls to correct an address and calls to mapping layers for service area validation are all defaulting to the same wellKnownId. Such as calling both endpoints on the same hosted instance.

Where it becomes a problem is if you want to start mixing calls to different installations.

Example

1. Call arcgis.com to correct address, returns coordinates using wellKnownId 4326

2. Call Seattle's hosted instance for map query endpoints for service area validation using values from arcgis.com would result in not being eligible because the coordinates systems don't match

By setting the ESRI_WELLKNOWN_ID_OVERRIDE we force both systems to use the same coordinate system.

Existing data

After we get the corrected address we save the x, y, and wkid as part of the address. Calls to map query endpoints already use the stored wkid to specify what the input spatial reference should be. Existing records will still work as is.

Applying to questions

Once those configuration variables are set up, address correction can be enabled or disabled on any address question using a toggle:

When a user fills out an address question with address correction, CiviForm will use the Esri endpoint to fetch address suggestions. If a suggestion perfectly matches what the user inputted, the suggestion will automatically be used and the user will proceed with the application. Otherwise, the user will be presented with a screen asking them to choose the correct suggested address:

Note that for each block in an application, there can only be one address question with address correction enabled. This is because it's complicated to chain multiple address correction pages together (both from a technical standpoint and from the perspective of an applicant). If multiple address questions need address correction, they can be on different blocks.

Service Area Validation

Service area validation checks whether an address is within a specific area. This can be used for visibility or eligibility conditions. For example, a user may only be eligible for a program if they live in a specific neighborhood.

Service area validation requires that address correction must also be enabled for the question. CiviForm needs the address's latitude and longitude values from Esri to determine if the address is within a certain area, and we only get the latitude and longitude values from Esri's address correction information.

Deployment-level configuration

Step 1: Enable feature flag

Set to true. Note that ESRI_ADDRESS_CORRECTION_ENABLED must also be set to true.

Step 2: Configure service area map values

Set the four ESRI_ADDRESS_SERVICE_AREA_VALIDATION_* configuration variables to contain the necessary information:

• is the list of URL(s) that CiviForm will use to call Esri’s to determine if the address is within the area specified by the map query service. The map should be a MapService type.

  • Type: String[]

  • Example value: ["https://gisdata.yourcity.gov/server/rest/services/City_Limits/MapServer/1/query"]

The configuration allows you to set up multiple service areas so that different questions can have different eligibility requirements. For example, maybe one program allows anyone in the county to apply while a different program only allows people in a certain zip code to apply. You can set up two service areas:

One program can set their eligibility condition to use "Arkansas" and the other program can set their eligibility condition to use "Example Neighborhood".

The arrays in each of these four variables should all be the same length. The values at index i should all correlate with each other. In the example above, all values at index 0 are for checking the county service area, and all values at index 1 are for checking the neighborhood service area.

Put another way:

• When checking that an address is in the service area labeled "Arkansas" in the admin UI, CiviForm will query arkansas-url and check the response for a field called STATE with a value of "AR".

• When checking that an address is in the service area labeled "Example Neighborhood" in the admin UI, CiviForm will query neighborhood-url and check the response for a field called ZIPCODE with a value of "01234".

Applying to questions

Once those configuration variables are set up, service area validation can be enabled or disabled on any address question using eligibility or visibility conditions:

Address correction must be enabled on the question before the eligibility or visibility conditions based on the service area can be set up.

Other configuration

- Integer

The number of tries CiviForm will attempt requests to external Esri services.

Questions form the structure of a CiviForm program. When a CiviForm Admin creates a question for one of their forms, the question is saved in the global question bank. When programs reuse the same question, all Applicant data related to the question gets autofilled. This reduces duplicate data entry and ensures accuracy by using previously vetted information.

Create a question

Watch the video or follow the step-by-step guide below.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar.

3. Click Create new question and select a question type. For more details on question types, go to .

4. Enter the information for the question.

5. Click Create. The new question appears in the list of questions.

Tip: You might want to develop a naming convention for your questions. For example, address-residence, address-work, etc.

Edit a question

You can edit both unpublished and published questions. To edit published questions, you need a new version. For more details on versioning, go to

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar and select a question.

3. Click Edit draft.

4. Modify the question information fields.

Archive a question

If a question is no longer in use by any program, you can archive a question.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar and select a question.

3. Click Archive.

Restore an archived question

When you restore an archived question, you can use it in your programs. You can restore an archived question up until the next version is published. For more details on versioning, go to

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar and select an archived question.

3. Click Restore archived.

Question type requirements

All question types have the following configuration options:

• Title (text shown to the user)

• Description or help text (this is raw text, but if we detect a URL, we can format it as a hyperlink.)

• Required or optional

Each question may have zero, one, or more validation criteria.

• For simplicity, if there are two or more criteria, it's assumed that they're joined with "AND" (all criteria must be met for the answer to be accepted)

• The list of supported validation criteria are given under each question type's heading.

Each validation criterion may be paired with an error message in case that criterion isn't met.

Question types

You can customize your program to include multiple different question types. The table below shows the supported question types, along with the expected data input.

CiviForm supports server monitoring via metrics visualized in . These metrics are related to server status, things like latency and error rates, and do not contain sensitive data, such as who is applying to what programs.

Enabling metrics export

Exporting metrics from the server is optional, and must be enabled by setting the CIVIFORM_SERVER_METRICS_ENABLED environment variable to true. When enabled, the server exports metrics from the