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

• User Manual to set up and manage your programs and applications

• IT Manual to deploy CiviForm on your technical infrastructure

• Governance & Management Documentation 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.

CiviForm is written in Java using the Play Framework backed by a PostgreSQL database. The application is containerized for development and deployment using Docker, 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.

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.

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

​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 Admin—Government staff that administer the tool. They set up CiviForm, create and manage questions, build program forms, and manage permissions for Trusted Intermediaries and Program Admins.

• Enumerator screen—Screens that contain an enumerator question type. Repeated screens can be created from enumerator screens to ask questions for each entity enumerated by the applicant.

• Enumerator question—A question type that allows applicants to create a list of one type of entity. For example, household members, vehicles, jobs, etc.

• Personally identifiable information (PII)—Any data that could potentially identify a person, a corporation or other entity, or a browser or device by either (1) inspecting the data directly, or (2) joining the data with another widely available dataset.

• Program Admin—Government staff that administer a benefit program and handles applications for that program.

• Question bank—New questions added by a CiviForm Admin are saved in the global question bank. The CiviForm Admin can reuse the question in any program forms they build.

• Repeated screen—A program screen created from an enumerator screen that contains repeated questions.

• Repeated question—A question associated with an enumerator question. A repeated question is asked for each entity enumerated by the applicant when they answer the enumerator question. A repeated question can be of any type, including an enumerator question. This can create nested enumerator questions and later nested repeated questions. For example, an enumerator question for household members could have a repeated dependent question for employment that’s also an enumerator. This allows for creating additional repeated questions about each employment role for each household member.

• Screen—A screen holds one or more questions. A program is made up of one or more screens. One screen is displayed at a time so screens can loosely be thought of as a single page within the form. Some screens can be repeated. Each program has one default screen.

• Trusted Intermediary Group—Community-Based Organization (CBOs) who help applicants apply for benefit programs.

• Trusted Intermediary—Staff members of CBOs who interact with applicants.

Last updated: June 2021

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.

The 4 users of CiviForm

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

• Applicants are residents seeking public services.

• Trusted Intermediaries are third-parties who help residents navigate the application process and access public services (for example, community-based organizations)

• CiviForm Admin are government employees who create and manage forms for programs.

• Program Admin are government employees who review and make decisions about applications.

Read on to learn about the features for each user type.

A note on data management & security:

All data is managed by the civic entity and thus their own security and privacy policies apply. For security, CiviForm is built to defend against cross-site scripting (XSS), SQL injection, cross-site request forgery (CSRF), and other common hacking tactics.

Applicant Experience

Expand each heading below to learn more about features for applicants.

Trusted Intermediary Experience

Residents often turn to local community-based organizations (CBOs) or other third parties to help navigate public benefits programs. These trusted intermediaries are juggling various databases, managing hundreds of applications, and working with several families per day. With CiviForm’s one-stop-shop for your community’s benefits applications, trusted intermediaries have their own accounts to manage their workload from a simple interface.

Expand each heading below to learn more about features for trusted intermediaries.

CiviForm Admin Experience

CiviForm Admin are the government employees who create and update applications. These users manage CiviForm for their civic entity, build custom applications, and can maintain the tool without ever needing to go into the code. They may be provisioned access to aggregated and anonymized data for analytics purposes.

Expand each heading below to learn more about features for CiviForm admin.

Program Admin Experience

Program Admin are government employees who review and make determinations about applications for public benefits. Using CiviForm, they can improve existing workflows and gain insights about utilization of programs.

Expand the heading below to learn more about features for Program Admin.

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

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 show or hide and click Edit visibility condition.

5. On the Visibility Condition page, under New visibility condition, select the questions you would like to use for your condition and then click Add condition.

6. In the Configure Visiblity Conditions page select if the screen should be either hidden if or shown if.

7. For each question in your condition:

   1. Set the Field data type.

   2. Set the Operator value.

   3. Enter the Value.

   4. Click Submit.

8. The visibility condition is displayed on both the Visibility Condition page and the screen. For example, “Screen 3 is hidden 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 Visiblity Conditions page and fill in the additional values.

Edit a visibility 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 show or hide and click Edit visibility condition.

5. Click Edit existing visibility condition.

6. Follow steps in "Add a visibility condition" for configuring the condition.

Remove a visibility 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 a visibility condition and click Edit visibility condition.

4. Click Remove condition visibility condition.

5. Click Return to edit screen #.

6. The visibility condition is removed from both the Visibility Condition page and to the screen. The default statement “This screen is always shown" is displayed on the page.

Rules for visibility conditions

The following rules apply when trying to understand visibility conditions:

• There can only be one visibility condition per screen.

• You can only add a visibility condition for questions used in previous screens. For example, adding a date question to Screen 2 means it’s available for selection in Screen 3. Questions in Screen 3 are not available for selection.

• 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 visibility condition fires if the answer to the question is blue or green or purple.

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.

   4. Click Save condition.

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 Edit eligibility condition.

5. Click Edit existing eligibility condition.

6. Follow steps in "Add an eligibility condition" for configuring the condition.

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 Remove existing eligibility condition.

5. Click Return to edit screen #.

6. The eligibility condition is removed from both the Eligibility Condition page and to the screen.

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.

4. Click on the dropdown menu corresponding to the draft program.

5. Click Settings.

6. Click on the toggle to set eligibility to the desired behavior.

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.

5. Click Save. The new program appears in the list of programs.

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 Manage versions for programs & questions.

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 Add screen. The screen appears within the program.

5. (Optional) To modify a screen’s name and description, click Edit name and description.

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

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

1. Sign in to CiviForm as a CiviForm Admin.

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

3. Click Edit.

4. Modify the program information fields.

5. Click Save.

Learn how to edit screens, questions, and visibility conditions.

Add a question to 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. Add a question to a screen by selecting it from the question bank. The question appears within the screen.

Note: Enumerator or file upload questions must be the only questions on a screen. These question types cannot coexist with others. For example, if you add one of these questions to an empty screen, you can't add any other question types. If you have a screen that already has a question, you can't add an enumerator or file upload question to the screen.

Remove a question from 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. Find the question within a screen you want to remove and click Delete. The question is removed from the screen and it returns to the question bank.

Reorder screens

If you have more than one screen in your program, you can organize the screens within the screen tree.

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. To reorder the list, select the screen you want to move and click the up or down arrow.

Remove 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. Find the screen you want to remove within a program and click Delete screen. The screen is removed from the program and the questions return to the question bank.

Note: You cannot delete all screens from a program as a program must have at least one screen. Only once your program has more than one screen can you delete the default screen.

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:

To use this feature, you will need to have your IT manager configure the GIS service.

Once the address correction feature is enabled, an admin user may enable address correction for an address. Only one address question per block can have address correction enabled at a time.

How to enable service area validation

To enable service area validation for an address question, an admin user must first enable address correction for an address question. Once that is done, an admin user may add service area validation by following these steps:

• Click the "edit eligibility condition" button:
• Find the address question in the list of questions, check the checkbox and click the "add condition" button:
• Configure the eligibility condition by adding values and saving the condition:

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.

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

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 checkbox.

5. Add questions to the pre-screener as normal.

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.

5. Check the Set program as pre-screener checkbox.

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

• COMMON_INTAKE_MORE_RESOURCES_LINK_TEXT

• COMMON_INTAKE_MORE_RESOURCES_LINK_HREF

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.

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

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 Manage versions for programs & questions.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Click Publish all drafts. Any new or versioned program is now available.

Publish a single draft program

Instead of publishing all programs and questions at the same time, you can also publish just a single draft program.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Locate the draft program you'd like to publish.

4. Click Publish on that program's row.

If the program has any draft questions, those questions will be published along with the program. However, if the draft questions are also referenced by other programs, the program cannot be published on its own. You can only publish it by publishing all programs as described above under Publish all draft programs.

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.

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

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.

5. Click Update.

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

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.

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.

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

If a CiviForm Admin attempts to publish a program that does not contain all universal questions, a warning will be shown, but the program may be published anyway.

Primary Applicant Information questions

Primary Applicant Information (PAI) questions are a subset of Universal questions that allow the system to take actions based on answers to those questions given by a logged in or guest user. There are currently four types of questions that may be marked as PAI questions:

• Name questions

• Email questions

• Phone number questions

• Date questions (should only be used for date of birth questions)

[!NOTE] A question MUST be marked as a Universal question before it can be marked as a PAI question. Only one instance of a question type may be marked as the PAI question for that question type at a time.

When an applicant answers a question marked as a PAI question, specific actions may be taken using their answer. The current available system actions are:

• Searching applications by name, email, and phone number

• Emailing guest users status updates about their applications

• Pre-populating applications with information entered when a Trusted Intermediary (TI) creates a client

• Updating TI client information based on answers to application questions

For questions that may be marked as PAI questions, you will see an additional section appear when you toggle the "Set as a universal question" toggle. The "Primary application information" section that appears will describe what system actions apply for this question type, and will allow you to set the question as the PAI question for this question type.

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, edit the program and save a version of the program in the draft (unpublished) state.

2. Click the three dots button on the right-hand side.
3. Click Manage translations in the dropdown menu.
6. Click Save.

7. To go back to program list page, click Back button.

Add or edit question translations

1. Sign in to CiviForm as a CiviForm Admin.

6. Click Save. To go back to Question list page, click Back button.

CiviForm contains the enumerator question type that offers CiviForm Admins a specialized way of structuring their data. Repeated questions can be created for enumerator questions, which allows admins to ask the same question for each repeated entity the applicant lists for the enumerator question.

An enumerator screen allows you to create repeated screens with repeated questions in them. In an enumerator screen, the applicant provides a list of repeated entities (for example, household members). Applicants can view each repeated screen for each repeated entity declared in the enumerator screen.

For example, if a program needs to gather name and date of birth information for each of an applicant's children. You can create an enumerator screen with an enumerator question to list the applicant's children, and a repeated screen with the repeated questions for the name and date of birth. You can choose to put both the name and date of birth repeated questions in the same repeated screen, or create two repeated screens with one question in each screen.

Enumerators do not store question data. Instead, each repeated question of the enumerator stores the data. An Applicant's answers to enumerator questions are only used to help Applicants track their answers within the repeated questions.

A screen can only contain an enumerator when it’s the only question on the screen. Repeated screens are created from enumerator screens. An enumerator screen can be a repeated screen of another enumerator. An enumerator screen's repeated screen appears below the enumerator screen and is indented in the tree. Repeated screens display a label showing the screen they were copied from. When adding repeated screens, the enumerator question in the enumerator screen isn’t copied to the repeated screens.

Create an enumerator question

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar.

3. Click Create new question and select Enumerator.

4. Enter the information for the question. See table below for the enumerator question fields, along with the expected data input:
5. Click Create. The new question appears in the list of questions.

Create a repeated question

Any question type can be a repeated question, including the enumerator type.

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Questions on the navigation bar.

3. Click Create new question and select the question type you want to use.

4. Enter the information for the question. See table below for the repeated question fields, along with the expected data input:
5. Click Create. The new repeated question appears in the list of questions.

Add an enumerator question to an enumerator 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. Select an existing screen with no other questions (since a screen can only contain an enumerator when it’s the only question in the screen) or click Add screen.

5. Add an enumerator question to the screen by selecting it from the question bank. The question appears within the screen and the “Create repeated screen” button is visible.

6. (Optional) To modify a screen’s name and description, click Edit name and description.

Add a repeated question to a repeated 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. Locate an enumerator screen.

5. Click Create repeated screen. The screen appears at the bottom of the repeated screens list for the enumerator screen.

6. Add a repeated question to the screen by selecting it from the question bank. The question bank shows only the questions you can add to a screen, so if there are no questions available that means you need to create repeated questions. The question then appears within the screen.

7. (Optional) To modify a screen’s name and description, click Edit name and description.

Remove an enumerator from 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. Find the enumerator question within a screen you want to remove and select it. The question is removed from the screen and it returns to the question bank. The “Create repeated screen” button is also removed.

Remove a repeated 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. Find the repeated screen you want to remove and click Delete screen. The screen is removed from the program.

Example: Use Enumerator Question to Collect Household Information

Suppose you have a section on a program application form where applicants need to provide information about their household members.

List of Household Members

Example valid values: Relationship: "Head of Household", "Spouse", "Child", "Parent" Employment Status: "Employed", "Unemployed", "Retired", "Student"

Steps to Collect Household Information

Step 1: Create an Enumerator Question

1. Go to the Questions tab and click "Create new question".

2. Select "Enumerator" as the question type.

3. Fill in the details:

1. Click Create.

Step 2: Create Repeated Questions

Now, create the repeated questions for each piece of information you want to collect about each entity (in this case, household member). For this example, we'll create repeated questions for:

Name:

1. Create a new question of type "Name".

2. Fill in the details:

   • Question text: What is $this's full legal name?. (The $this token refers to the household member listed by the applicant.)

   • Administrative identifier: household_member_name

   • Question enumerator: household_members (This is the Administrative identifier of the Enumerator Question created in the previous step.)

3. Click Create.

Birth Date:

1. Create a new question of type "Date".

2. Fill in the details:

   • Question text: What is $this's date of birth?

   • Administrative identifier: household_member_birthdate

   • Question enumerator: household_members

3. Click Create.

   Tip: By asking for the date of birth and not age directly, we can calculate the age, and the benefit is that the value of age is only valid at a specific point of time and becomes stale as time goes on, whereas a person's date of birth stays valid. This also makes for a slightly shorter application for the applicants as opposed to asking both questions.

Relationship:

1. Create a new question of type "Dropdown".

2. Fill in the details:

   • Question text: What is $this's relationship to the applicant?

   • Administrative identifier: household_member_relationship

   • Dropdown options: "Head of Household", "Spouse", "Child", "Parent"

   • Question enumerator: household_members

3. Click Create.

Employment Status:

1. Create a new question of type "Radio Button".

2. Fill in the details:

   • Question text: What is $this's employment status?

   • Administrative identifier: household_member_employment_status

   • Radio button options: "Employed", "Unemployed", "Retired", "Student"

   • Question enumerator: household_members

3. Click Create.

Step 3: Add Enumerator and Repeated Questions to Screens

1. Go to the Programs tab and select the program you're working on.

2. Click Edit.

3. Create a new screen or select an existing screen with no other questions.

   • A screen can only have an enumerator question if it is the only question on the screen.

4. Add the enumerator question (List all members of your household) to this screen from the question bank.

5. Click Create repeated screen to create a repeated screen associated with the enumerator screen.

   • Screen name: Household member details

   • Screen description: "Please add each household member's name, birth date, relationship, and employment status."

6. Click "Add question" to the repeated questions for name, age, relationship, and employment status to the repeated screen.

Step 4: Configure and Publish

1. Modify screen names and descriptions as needed.

2. Save your changes.

3. Publish your draft program to make it available to applicants.

Now, when applicants fill out this program:

1. They will first be asked to list all household members.

2. For each member listed, they will be presented with repeated questions to provide:

   • Name

   • Date of birth

   • Relationship

   • Employment status

This allows you to collect comprehensive household information in a structured manner.

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.

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.

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.

Update program version

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar.

3. Locate the program you'd like to update.

4. Click on the three dots to open the dropdown menu for that program.

5. Click Edit to create a draft version of the program.

6. Modify the program information fields, edit questions, etc. Note: You can’t edit the internal Program Name field.

Update question version

1. Sign in to CiviForm as a CiviForm Admin.

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

3. Click Edit to create a draft version of the question.

4. Modify the question information fields.

5. Click Update.

Rules for versioning

The following rules apply when trying to understand versioning:

• Individual configuration objects (for example, programs) cannot be versioned independently of the complete version set.

• There can only be one unpublished version in the system at a time.

• Once a version is published, it’s locked and cannot be modified.

• New versions are initialized with a complete copy of the current published version.

• Applicants are pinned to the version they began their first program application with. They remain on that program version until it’s been submitted.

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.

To Create a Status

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar and select the program for which you would like to add statuses.

3. Click the three dots on the right side of a draft program.

4. Click Manage Statuses.

5. Click Create a New Status.

6. Enter your status name and (optional) any email text you would like the applicant to receive upon the status change.

7. Repeat steps 5-6 for all statuses you would like to create.

8. For any status you wish to set as default, check the "Set as default status" checkbox when creating or editing the status.

Tip: Don’t see Manage Statuses as an option when you click the three dot icon? This is because you must add statuses to a Draft program, not an Active program. To create a Draft version of your program:

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar and find the program you are interested in.

3. Click Edit on the right side of the program.

4. Click Programs on the navigation bar to return to the programs page, where you will now see a Draft version of your program.

To edit or delete a status:

1. Sign in to CiviForm as a CiviForm Admin.

2. Click Programs on the navigation bar and select the program for which you would like to modify a status.

3. Click the three dots on the right side of the program.

4. Click Manage Statuses.

5. Click Edit or Delete.

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 Integration.

API key security

API key expiration

When an admin creates an API key they must specify an expiration for it. This is to ensure that API keys are rotated so that in the event a key is compromised it does not grant indefinite API access to the attacker. Requests made using credentials for an expired API key receive an HTTP 401 status code.

API key allowed subnet

When an admin creates an API key they must specify an allowed subnet for it. Requests made from IP addresses outside of the allowed subnet receive an HTTP 401 status code.

API key permission grants

When an admin creates an API key they must specify what CiviForm resources the key provides access to. It is highly recommended that API keys be given narrow scopes of access e.g. access to one program per key, and that keys not be shared between multiple programs or backend processing systems. Requests made using credentials for API keys that don't have access to the requested resource receive an HTTP 401 status code.

API key retiring

Admins may retire API keys using the admin UI. Retiring is a distinct concept from expiration and provides admins with a way to revoke an API key's access. Requests made using credentials for a retired API key receive an HTTP 401 status code.

Creating a new API key

The CiviForm admin creates API keys in the admin UI. To create a new key:

1. Login as a CiviForm admin

2. Click 'API keys' in the top nav

3. Click 'New API key'

4. Follow the on-page instructions for creating a key

5. Click 'Create'

6. Copy the API credentials string and store it somewhere secure

API key credentials are presented only once in the CiviForm UI: on the page shown immediately after the key is created. The credentials are not stored in the database or anywhere else in the system. After navigating the browser page away from that page it is impossible to recover an API key's credentials from CiviForm.

This is so that a malicious user with temporary access to a CiviForm admin account cannot simply copy the credentials of an existing API key to gain long term access to the system in a way that would be difficult to detect.

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

Program admins have access only to applications of programs they were assigned to. Assignments controlled by CiviForm admins on per-program basis. If Alice (alice@mycity.gov) 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 alice@mycity.gov as admin.

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

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.

5. Click Add. The new staff member appears in the list of groups.

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. The Trusted Intermediary is removed from the list of members for the group.

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

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

• Regular question text (Note: For regular question text, please limit formatting to bold, italics and text links only. Changing font size or making other edits that alter the flow of text can make question text hard to read)

• Question help text

• Question options (Note: Markdown only works for checkbox and radio type question options, not for dropdown options. Line breaks and lists do not work for question options at this time)

The formatting options currently supported by CiviForm are outlined in the table below along with how to use them. If you would like a formatting option that we do not currently support, let us know!

Notes and Caveats about working with Markdown in CiviForm

Font Size

Header syntax can be used to change font size. We currently support three font sizes - large, regular, and small. Starting a line with # or ## will create an "h2" size header, which is the largest text possible. Using 3 (###) or 4 (####) hashes will result in regular sized text. Using 5 (#####) or 6 hashes (######) will result in the smallest text.

Accessibility Note: Generally, more hashes indicates less important text. Folks who are visually impaired often rely on the header tag to let them know the relative importance of text on the page since they might not be able to see differences in font size.

URLs

Urls that start with http:// or https:// will be automatically detected as links and have the appropriate formatting applied. Urls that do NOT start with http:// or https:// will not be detected as links. All links are set to automatically link out to a new page.

Urls used within text links must also include http:// or https:// to link out correctly. Examples: Correct: [This link will work!](https://www.example.com) Incorrect: [This link will not work](www.example.com)

Email Addresses

Email addresses (Eg. test@example.com) are automatically detected as links and formatted accordingly. Clicking on an email address will open the local email program (Eg. Outlook) and create a new email to that address.

You can also use email addresses in text links by adding mailto: and the email address in the parentheses after the text. Example: [Send email](mailto:test@example.com)

Overview

Program migration is a feature to allow programs and their associated questions to be moved between CiviForm environments.

Handling question collisions

If a program you are migrating shares questions with an existing program in your import environment, you can decide whether you want to create a new duplicate question or use the existing question. Here are our recommendations for when to choose which flow:

1. Create a duplicate question (Default flow)

   • Use this when you want to import a program into an environment that already has existing programs. Programs imported using the default flow will not affect any programs in the import environment.

   • Using the default flow will create duplicate questions if there are questions in the import environment that match questions being imported (match is determined by the question admin name). We suggest you replace the duplicate questions with existing ones after importing your program, so your applicants benefit from CiviForm’s shared question model.

   • You can find questions that were duplicated, since their admin names will have -a or another letter attached to it. Once you replace duplicate questions in new imported programs, you can archive the duplicate questions that were created.

2. Use the existing question

   • To use this flow, turn on the NO_DUPLICATE_QUESTIONS_FOR_MIGRATION_ENABLED feature flag

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

   • If there are existing programs or questions in the import environment, they must be published before importing a new program.

   • Importing a program with this flag enabled will put all programs into draft mode.

   • Importing a program with this flag enabled will update any questions that already exist in the import environment, which means updating any programs that contain those questions. This is why we do not recommend using this flow if there are already programs in the import environment, especially if you are importing into a production environment.

Exporting a 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

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

• Primary Applicant Info settings applied to questions

• "pre-screener" setting on a 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.

  • You can resolve this by editing the program admin name in the json, but please be careful when doing so and only use lowercase letters with dashes between words. Using invalid characters in a program admin name will result in another error.

• Exporting a program from an environment that is on a different CiviForm version than the import environment.

  • Please try to make sure environments are on the same CiviForm version before migrating programs between them. If they are on different versions, you might see an error about an expected field or translation missing.

• Attempting to import a program with program visibility set to “Visible to selected trusted intermediaries only” (shows up as “SELECT_TI” in the program json)

  • Since we don’t migrate ti groups with the program, you must select a different visibility for the program before migrating.

• Programs are in draft mode.

  • With the NO_DUPLICATE_QUESTIONS_FOR_MIGRATION_ENABLED flag enabled, you must make sure all programs and questions are published before attempting to import a new program.

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:

• Apply to a program on behalf of a resident

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.

  • Organization assessment

  • Program assessment

• Implement: Work with program administrators to create a better experience for applicants and staff.

  • Getting started with service design

  • Journey mapping

  • Discovery, eligibility, and intake

  • Consolidating questions across programs

  • Working with existing tools and processes

  • Working across jurisdictions

  • Data reporting and other integrations

  • Security and privacy considerations

• Pilot: Test applications and processes to refine your approach.

  • Piloting with staff

  • Piloting with CBOs

  • Piloting with residents

• Launch: Put your new applications out into the world.

• Grow: Leverage CiviForm to continue to expand access to programs.

  • Onboarding new programs

  • Resources for community outreach

• Sustain: Ensure that this work can continue over time.

  • Staffing overview

  • Impact measurement and reporting

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.

2. At the top of the Programs & services page, it should say “Trusted intermediary dashboard (applying as: your name)”

3. Click Trusted intermediary dashboard.

4. Under Add client, fill in the Applicant information fields and click Add. The new client appears in the list of clients.

Apply to a program for a client

1. Sign in to CiviForm as a Trusted Intermediary.

2. At the top of the Programs & services page, click Trusted intermediary dashboard.

3. Under Clients, click Applicant dashboard beside the name you want to start an application for.

4. On the Programs & services page, it should now say (applying as: client name)”.

5. Find the program you want to apply to and click Apply.

6. Enter information on each page of the application, clicking Next to advance through the program.

7. When finished, click Submit.

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.

What key programs are administered by your jurisdiction (city, county, state)?

What other programs might residents of your jurisdiction still want to access, even if they are administered by another entity (city, county, state, federal)?

For example, if you are a city, residents may still want to find and access county or state programs.

What are the most common ways residents access programs in your jurisdiction?

What is your organization's existing approach to facilitating benefits access across programs?

Is each program discovered and administered on its own, or can residents access many services at once? Do you manage a central website or tool that lists all programs? Do you have a shared data referral or intake process across programs?

What role do community organizations or nonprofits play in connecting residents to programs or administering programs?

What outcomes is your organization aiming to achieve by expanding benefits access?

For example: Is there a specific focus on reducing burdens for residents, expanding access to specific programs, or supporting specific populations?

What role does IT play in supporting programs that administer benefits?

For example: Do you manage a central website or tool that lists programs? Does each program manage their own application process and tooling, or does a central IT team help provide support?

What is your organization's technical capacity?

For example, do you run applications on cloud or on-premises infrastructure? Do you have staff who are comfortable with systems administration or application development?

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.

4. Click Applications. Note: The number following the Applications link indicates the number of applications present under that version.

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

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.

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

5. Program staff calls applicant to verify information D (X minutes)

6. Applicant must bring document D into office (X days waiting)

7. Program staff verifies document D against database Y (X minutes)

8. Application is approved. Status is shared with applicant through system Y (X days)

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?

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 "Working with existing tools and processes".

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

• Exporting applications from CiviForm as PDFs and emailing them to programs if they accept email submissions.

• Submitting applications directly through existing program websites via a headless browser. This can only be done if the existing website allows submissions without creating an account, and it may still require permission from the program.

These approaches are likely to provide a worse experience than direct integrations, so they should only be pursued if more direct approaches fail.

Incremental steps: Discovery, eligibility screening, and intake

If it seems infeasible to support submitting applications to programs in other jurisdictions, consider surfacing programs in other ways. As described in "Discovery, Eligiblity Screening, and Intake", it may still be valuable to surface programs from other jursdictions to help someone discover them if they are relevant to their needs. Additionally, providing screening functionality for that program can still help someone know whether or not it may be worth applying to with minimal marginal effort as they are screened for other programs within CiviForm. Finally, leveraging CiviForm for intake or referral to programs in other jurisdictions can directly connect someone to the right person for continued support.

Security and privacy considerations

It is essential that applicants understand how their information is being used when submitting an application from within CiviForm. If you plan to share information beyond your jurisdiction, clearly and plainly communicate where that information will be sent and how it will be used so that applicants can make informed decisions about whether or not they'd like to apply. See the "Security and privacy considerations" section for more information.

Data sharing agreements

Sharing information across jurisdictions may require a data sharing agreement. For more information, see the guide "Data Sharing to Build Effective and Efficient Benefits Systems" (PDF) by Benefits Data Trust.

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:

• NYC Civic Service Design Tools + Tactics: 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.

• Preparing for Human-Centered Redesign

  • Starting Small with Human-Centered Redesign (PDF)

  • Going Big with Human-Centered Redesign (PDF)

• 18F Human-Centered Design Methods

• The Good Services Scale

• Mapping the applicant experience of benefit enrollment

• Civilla Practica

  • Foundations

  • Design Principles

  • Qualitiative User Research

  • Applications

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.

Discovery

CiviForm can serve as a directory of programs available to a resident, even if programs don't accept applications through CiviForm directly. Including programs in CiviForm for discovery allows applicants to find programs relevant to their needs in one place rather than having to search across multiple resources or simply never learning that a program exists. This can be especially useful for programs that offer services rather than benefits, which may involve going to a physical location or calling a phone number, and may not require an application at all.

While not an ideal experience for the applicant, it is also possible to list programs and their details within CiviForm specifically to direct applicants to submit an application through a website or form outside of CiviForm. This will require them to re-enter all of their information into the new system, which is a poor experience for the applicant. Whenever possible, programs should allow applicants to submit their applications directly through CiviForm and enable them to leverage the information they've already entered for other programs. See "Working with existing processes" for more information on how CiviForm can be used by programs that have established tools and processes in place.

Eligibility Screening

CiviForm can also give applicants a quick sense of which programs they may or may not be eligible for, even if they can't apply through CiviForm. Programs and their eligibility rules can be included directly in CiviForm, and programs can then link out to an external application tool or other channel for accessing the program or service. It is still helpful for applicants to get a sense of their likely eligibility across programs, even if they need to take additional steps outside of CiviForm to access the program.

Intake

For some programs, CiviForm can serve as a channel for intake, where preliminary information is submitted through CiviForm then exported for program staff to follow up with an applicant through other channels. This can be useful if you already have tools that manage business rules and processes for program outreach and eligibility determination, but would like another entry point for residents to be brought into these programs. While intake can be a great way to reach people regardless of which programs you've brought on to CiviForm, allowing residents to submit full applications directly via CiviForm allows them to avoid having to re-enter information in other systems when necessary.

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

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?

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 demography export UI or through CiviForm's API. 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.

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.

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.

Technical staff

Broadly speaking there are two options for technical staffing. One option, "keep the lights on", describes a minimum level of skill and staffing to keep a CiviForm deployment usable at a basic level. The other option, "custom code and incident response self-sufficiency", describes a minimum level of skill to take advantage of the opportunities for data integration that CiviForm presents.

Keep the lights on

Two part-time IT professionals minimum

Note: this estimate is for a CiviForm deployment to a major public cloud provider. On-prem deployments require additional resources and an assessment of the civic entity's IT capabilities for an accurate estimate of an on-prem CiviForm deployment's IT staffing needs.

We recommend at least two part-time technical staff for supporting CiviForm at a minimum viable level of service. Two is the minimum level of redundancy necessary to ensure incident response availability. The equivalent of one FTE is the anticipated minimum for maintenance and operations efforts.

At this level of staffing we expect the CiviForm deployment to stay up to date with the latest security and feature patches from the mainline project. At this level of IT staffing incident response involves contacting the mainline open source team and waiting for their availbility for resolution.

Skills needed:

• familiarity with web services and basic web application architecture

• familiarity with command line interfaces

• basic familiarity with web security (e.g. provisioning SSL certificates)

• some knowledge of computer networking – IP addresses, DNS, ports, etc

• experience maintaining web servers in a cloud environment

Custom code and incident response self-sufficiency

Two full time software developers minimum

Staffing two full time software developers or more would allow for code-level customizations and a readier incident response posture. At this level of staffing, the civic entity is able to investigate and resolve production incidents independently without relying on the mainline open source developers.

The majority of those developers' time however could be spent on feature work which could include generic features and enhancements to the core system desired by the civic entity and/or custom features such as integration with external systems for administering programs (e.g. populating entries in a vehicle licensing database with applications submitted through CiviForm).

Additional skills needed:

• proficiency in Java or another statically typed language (e.g. C#, Go, or TypeScript)

• familiarity with relational databases

• understanding of web application security best practices

• comfortable working in open-source software ecosystems

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 Program Assessment 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.

Understanding what's possible

Once you have a journey map of what exists, you can better understand what improvements are possible across the resident journey. Whether it involves simplyifying application forms, consolidating many applications into one, or just making a paper application accessible digitally, work with your stakeholders to craft a new journey map that represents a better experience for program staff and residents.

Information specific to CiviForm Terraform deploy scripts for AWS.

For general information, see Terraform deploy system.

Infrastructure

Created for CiviForm app:

• VPC

• Load balancer

• Internet Gateway

• NAT Gateway

• Fargate ECS cluster

• RDS with Postgres

• S3 bucket

Connected services

• SES

• Secrets Manager

Supporting Infrastructure:

• S3 bucket for Terraform backend state

• Cloudwatch export for logs

Code and examples (AWS)

The code that manages deployment can be found here.

Our staging environment is at staging-aws.civiform.dev.

Config for the staging environment is here.

Troubleshooting

After running the setup or deploy script, you can login to the AWS ECS console to check the status of CiviForm. Make sure to select correct region in the top right corner.

You should see Cluster with app_preffix-civiform name. Click on it and go to Tasks tab. If everything is going well you should see a task in the Running state.

Inspecting task config

You can see the task configuration by clicking on the Task definition tab, finding the latest revision, and opening the JSON tab.

Inspecting logs

You can see the logs on the task page by clicking into the specific task and selecting Logs.

Logs are also available in Cloudwatch. Search for app_prefix-civiformlogs group.

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:

• Azure and GCP support will be added upon request.

Overview

This section describes the tasks necessary to deploy CiviForm new infrastructure. Many tasks can and should be done in parallel. Tasks may vary depending on the specifics of each organizations's needs, but the high-level components remain relevant.

Information you will need

The following details are necessary for the initial deployment. A staging environment can be brought up without most of these values, but you will need all of them for a complete production deployment. Deciding on some of them might require coordination across different departments, so it is helpful to start tackling them early.

• The infrastructure you wish to deploy on (e.g. a specific cloud provider or on-premises infrastructure).

  • If using a cloud provider, the region you wish to deploy in.

• An authentication provider for administrators (including client_id, client_secret, and discovery_uri details).

• An authentication provider for applicants (including client_id, client_secret, and discovery_uri details).

• Two domain names for your deployment (one for a staging environment, and one for the production environment).

• Government logo images for branding

• A support email address to display on the site

• SSL certificates for domain names and/or load balancers.

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.

Sources for reporting

Here are key sources for accessing reporting information in CiviForm.

CiviForm reporting dashboard

CiviForm has a built-in dashboard that administrators can use to see core program metrics such as the number of applications and the distribution of application completion time. More metrics are being added over time to provide administrators with insights into their programs out-of-the-box.

Application analytics

CiviForm supports integration with common web analytics tools. Such tools can provide page-level analytics on how applicants are progressing through applications, which can indicate which questions may need to be removed, adjusted, or improved to simplify the application process.

Exports for external reporting

Information in CiviForm can be exported to integrate with existing reporting tools, analyses, or workflows. This is helpful for combining information from CiviForm with other sources to give an even broader view of the applicant experience. It can also help make insights about programs available to broader stakeholders (for example, program administrators, policymakers, or the public) through publications or other reporting channels.

Combining information with other sources

Some analyses may require combining information from CiviForm with data from other sources. For example, CiviForm has information on how long it takes for someone to complete an application, but in order to know how long start-to-finish service delivery takes, data must be incorporated from downstream systems that manage later steps in the process of delivering services. Similarly, a complete assessment of responsiveness and access for a given program requires integrating metrics from non-CiviForm channels, such as phone calls or office visits.

Collecting feedback from residents

In addition to these passively measured proxies for residents' experiences with specific programs, CiviForm can also serve as a channel for the direct and active collection of feedback from programs. For example, a feedback or satisfaction survey can optionally be added to the end of program applications when they are configured in CiviForm, or throughout the site via third-party tools.

Terraform is an infrastructure-as-code tool that allows you to define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. CiviForm provides Terraform configuration files that allow you to deploy CiviForm on AWS. Knowledge of Terraform is not required to run them, but reading the high-level Terraform overview may be useful.

More detailed information on our deploy system can be found in our developer docs.

Setup

Outside configuration

You will need some values that are configured outside of CiviForm before you start the setup. Some of the steps are optional, meaning that you can bring up a staging environment and get the app working without them, but they will need to be completed for production setup.

• (Optional) Admin auth client_id, client_secret, and discovery_uri. See setting up Azure AD for an example

• (Optional) Applicant auth client_id, client_secret, and discovery_uri. See setting up the Authentication Providers

• Domain name for your deployment. For example civiform.mycity.gov

• (AWS) ARN of an SSL certificate for load balancer. See requesting AWS certificate

• (AWS) Decision around where deployments will live. See AWS deployment setup options

Steps to run

1. Fork the civiform-deploy repo to your organization via the GitHub webpage.

2. Clone the repo onto the machine you are deploying from. Ideally, this would be a shared instance that multiple people can log onto.

3. Find the version that you want to deploy on Github.

4. Copy the civiform_config.example.sh into civiform_config.sh and fill out the missing values. You can get a sense of required values depending on your cloud provider by looking at staging-aws configs.

5. Run bin/doctor and install the dependencies.

6. Run bin/setup. What to expect:

   • Takes up to 20 minutes to run. Make sure you have time to allow the script to run to completion to avoid errors.

   • Terraform brings up resources in the cloud (database, network, server, etc).

   • Asks confirmation a few times before creating resources, listing everything that will be created.

   • Safe to re-run the script if it fails (re-runs will take longer because resources must be destroyed before being re-created).

   • The configuration values in civiform_config.sh represent the desired state of your CiviForm deployment. The bin/setup and bin/deploy commands work to make your cloud environment match the desired state. If a command fails, your cloud environment may not match the desired state. These commands are safe to retry if they fail. If a command is persistently failing, you can work with our on-call engineer to resolve the issue. Our on-call engineer responds to new issues in the CiviForm issue tracker.

Note: If you are running bin/doctor or another command for a config file other than civiform_config.sh, you can specify that with the config flag (i.e. bin/doctor --config=civiform_staging_config.sh)

Deploy

1. Find the version that you want to deploy on Github.

2. Update the CIVIFORM_VERSION value in civiform_config.sh.

3. Run bin/deploy.

Rotating the application secret

The Play Framework used by CiviForm utilizes an application secret key. This key is used for signing session cookies and CSRF tokens, among other things. While this secret is secured storely by the deployment system, it's a good idea to rotate it periodically in order to mitigate the risk of a leaked secret.

IMPORTANT: When the secret is rotated, all user sessions will be invalidated. This means that any guest users in the middle of an application that have not submitted it yet will lose that application, and any logged in users or admins will get logged out. It is recommended that this rotation happen at a low traffic time of day. You may also want to give users a warning before it happens.

To rotate the secret, run bin/run, and enter the rotate_app_secret command. This will redeploy CiviForm, changing the secret key to a new, random value.

Additionally, you should add export RANDOM_PASSWORD_LENGTH=64 to your civiform_config.sh file. The secret length was originally only 16 characters, and when CiviForm moves to using version 2.9 or later of the Play Framework, 32 will be the minimum.

Troubleshooting

Terraform fails with error "Provider produced inconsistent final plan"

This error can happen when running bin/setup for the first time. If you see it, re-run bin/setup. This is a known Terraform bug.

Terraform fails with other errors

The deploy command is idempotent, so if it fails, try running it again. The setup command can also be re-run, but it may fail to destroy resources if the resources Terraform uses to track created resources are corrupted. If the script is failing to destroy resources, try running bin/run destroy on its own. If this fails, you may need to manually delete resources in your cloud provider's console. Once all resources are cleaned up, run bin/run destroy_backend_state_resources to cleanup up the corrupted backend state resources and then try running bin/setup again.

If changes were made upstream, you can change the code in the checkout env, but will need to commit PRs to fix in the main repo.

No such file or directory

If you see error like "no such file or directory"

./db-connection: line 2: cloud/aws/bin/lib.sh: No such file or directory
./db-connection: line 21: out::error: command not found

The scripts expect you to be in specific directories. You probably need to cd into the checkout directory or the top level directory. If you are running setup/deploy/revert, you will need to be in the top level directory. If you are running a script like db-connection, you need to be in the checkout directory.

Terraform fails with Error acquiring the state lock

This situation can happen when exiting deployment scripts using "Ctrl-C". Terraform acquires a lock every time you run ./bin/deploy or ./bin/setup, and releases the lock at the end of the script. This helps to prevent concurrent infrastructure changes. If the deploy process exited outside of Terraform, the lock remains and needs to be force removed in order to run deploy again. The end of the error message will contain the LOCK_ID. To unlock, re-run either bin/deploy or bin/setup with FORCE_UNLOCK_ID set like this:

FORCE_UNLOCK_ID="$LOCK_ID" ./bin/deploy

Alternatively, it can be done by manually calling terraform like this:

terraform -chdir=checkout/cloud/aws/templates/aws_oidc force-unlock $LOCK_ID

(AWS) Notes on using CloudShell for deployment

It is an option to use CloudShell for doing deployments, but you should be aware that installations aren't persisted (see (FAQs)[https://aws.amazon.com/cloudshell/faqs/]), so it may be easier to use the AWS CLI.

If you do choose to use CloudShell, you likely will need to install Java and Terraform.

Java can be installed with sudo yum install java and terraform can be installed by following the installation commands under Linux / Amazon Linux.

Helpful resources

Requesting AWS certificate

Follow official documentation. After your certificate is ready and validated, copy the ARN from your console and put it into the SSL_CERTIFICATE_ARN variable in your civiform_config.sh

ARN has format of arn:aws:acm::<user_id>:certificate/<identifier>

AWS deployment setup options

Before going through the AWS deployment, it is helpful to understand how you plan to manage various deployments, if you plan to create multiple instances of CiviForm (i.e. staging, prod, etc.).

By default, each deployment will have its own prefix, which allows you to distinguish the different ones from each other, but AWS Organizations is a way of keeping deployments more separate from each other.

Some benefits of using AWS environments are:

• There is more separation between environments, which makes it easier to remove resources without worrying about causing any issues to another deployment environment

• It is easier to see cost breakdowns by deployment

A drawback to be aware of is that you'll have to create profiles in the AWS CLI and switch between the different profiles when doing deployments or, if using CloudShell, you'll have to do this in separate CloudShell for each environment.

Setting up Azure AD

The setup script prompts you to set up Azure AD. There are a few additional steps.

In Azure Portal:

• Go to Azure Active Directory -> App registrations

• Click the tab for "All applications"

Use the menu on the left:

• Authentication: setup the Redirect URI to be what the app expects: https://<custom_hostname>/callback/AdClient.

• You will also need an admin group which creates CiviForm admins

• Token configuration: To allow for CiviForm admins, you need to have Azure AD return the groups claim. Add the security groups claim (you can verify the groups claim is being returned by decoding the base64 token from the token you get back from Azure AD on the website-- if you preserve the log in the Chrome Dev Tool window it should be from https://<custom_hostname>/callback/AdClient)

Access the database for emergency repair

The CiviForm deployment system provides a mechanism for temporary and secure direct access to the production database via the pgadmin

For details on how to access the database with pgadmin visit the Production Database Access page.

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.

2. "Admin readable" variables should be set in your deployment config file. The values for these variables can be seen in the admin settings panel, but not changed there.

3. "Server setting" variables should be set in your deployment config file and are not visible in the admin settings panel.

4. "Managed secret" variables should be set in your cloud provider's secrets manager. These are not visible in the admin settings panel.

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

• Description of new features

• Database schema changes

• Other stateful changes (such as stored file key name schema)

• API version changes and deprecation notices

• New configuration values

• Infrastructure changes

• Dependency changes (for the server only) including new, removed, and version updates

Version numbers

Version numbers take the form v<major>.<minor>.<patch>. Generally, we will always increment the minor version with each release and set the patch version to 0. If we do an unscheduled release in order to fix a bug, we'll increment the patch version. The major version will only increment if the release includes changes that require great care when deploying or includes signficant changes to the way CiviForm works.

Major version

A new major version indicates major feature or functionality changes that could be disruptive to users or administrators of the system without preparation (i.e. a chance for staff to read documentation or get an overview of new UI).

A new major version must be created if there are any changes that cannot be deployed by simply updating the server image, but also require manual technical staff effort from downstream deployments to incorporate. Examples of this kind of effort include altering deployment infrastructure, moving to a new major PostgreSQL version, etc. In general, the CiviForm core team seeks to minimize effort needed by downstream maintainers to perform version upgrades. A new major version may also be created when there are signficant changes to CiviForm functionality or appearance.

Admins should ensure they have database backups before applying a new major change.

Minor version

A new minor version indicates feature or functionality changes that enable new capabilities in the system or fix existing ones, but are unlikely to be disruptive and do not require signficant preparation. Examples of such changes include new features, new APIs or API versions, new configuration parameters, and new resources in the system.

A new minor version may also indicate changes in the database schema, file key naming schema, or other stateful parts of the application. New minor versions should be deployable by simply updating the server image (the Play Framework evolutions system should update the database schema automatically).

Admins should ensure they have database backups before applying a new minor change.

Patch version

A new patch version indicates a bug fix to the previous release that was serious enough to require an unscheduled release. Patch versions should generally be taken up as soon as possible, but if the bug fixed does not apply to your environment, waiting until the next release may be viable.

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

Applicant authentication setup

Branding

Configuration options for CiviForm branding.

WHITELABEL_SMALL_LOGO_URL

Small logo for the civic entity used on the login page.

• Type: string

WHITELABEL_LOGO_WITH_NAME_URL

Logo with civic entity name used on the applicant-facing program index page.

• Type: string

WHITELABEL_CIVIC_ENTITY_SHORT_NAME

The short display name of the civic entity, will use 'TestCity' if not set.

• Type: string

WHITELABEL_CIVIC_ENTITY_FULL_NAME

The full display name of the civic entity, will use 'City of TestCity' if not set.

• Type: string

FAVICON_URL

• Type: string

External service dependencies

Configures connections to external services the CiviForm server relies on.

Applicant Identity Provider

CIVIFORM_APPLICANT_IDP

What identity provider to use for applicants.

• Type: string

• Allowed values:

  • idcs

  • login-radius

  • generic-oidc

  • login-gov

  • auth0

  • disabled

APPLICANT_REGISTER_URI

URI to create a new account in the applicant identity provider.

• Type: string

Oracle Identity Cloud Service

IDCS_CLIENT_ID

An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with IDCS. A Civiform instance is always the client.

• Type: string

IDCS_SECRET

A secret known only to the client (Civiform) and authorization server, specifically for IDCS OIDC systems. This secret essentially acts as the client’s “password” for accessing data from the auth server.

• Type: string

IDCS_DISCOVERY_URI

A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider.

• Type: string

Login Radius

LOGIN_RADIUS_API_KEY

The API key used to interact with LoginRadius.

• Type: string

LOGIN_RADIUS_METADATA_URI

The base URL to construct SAML endpoints, based on the SAML2 spec.

• Type: string

LOGIN_RADIUS_SAML_APP_NAME

The name for the app, based on the SAML2 spec.

• Type: string

LOGIN_RADIUS_KEYSTORE_NAME

Name of the SAML2 keystore, used to store digital certificates and private keys for SAML auth.

• Type: string

LOGIN_RADIUS_KEYSTORE_PASS

The password used the protect the integrity of the SAML keystore file.

• Type: string

LOGIN_RADIUS_PRIVATE_KEY_PASS

The password used to protect the private key of the SAML digital certificate.

• Type: string

OpenID Connect

APPLICANT_OIDC_PROVIDER_LOGOUT

• Type: bool

APPLICANT_OIDC_OVERRIDE_LOGOUT_URL

By default the 'end_session_endpoint' from the auth provider discovery metadata file is used as the logout endpoint. However for some integrations that standard flow might not work and we need to override logout URL.

• Type: string

APPLICANT_OIDC_POST_LOGOUT_REDIRECT_PARAM

URL param used to pass the post logout redirect url in the logout request to the auth provider. It defaults to 'post_logout_redirect_uri' if this variable is unset. If this variable is set to the empty string, the post logout redirect url is not passed at all and instead it needs to be hardcoded on the the auth provider (otherwise the user won't be redirected back to civiform after logout).

• Type: string

APPLICANT_OIDC_PROVIDER_NAME

The name of the OIDC (OpenID Connect) auth provider (server), such as “Auth0” or “LoginRadius”.

• Type: string

APPLICANT_OIDC_CLIENT_ID

An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers. A Civiform instance is always the client.

• Type: string

APPLICANT_OIDC_CLIENT_SECRET

A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server.

• Type: string

APPLICANT_OIDC_DISCOVERY_URI

A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider.

• Type: string

APPLICANT_OIDC_RESPONSE_MODE

Informs the auth server of the desired auth processing flow, based on the OpenID Connect spec.

• Type: string

APPLICANT_OIDC_RESPONSE_TYPE

Informs the auth server of the mechanism to be used for returning response params from the auth endpoint, based on the OpenID Connect spec.

• Type: string

APPLICANT_OIDC_ADDITIONAL_SCOPES

Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides.

• Type: string

APPLICANT_OIDC_LOCALE_ATTRIBUTE

The locale of the user, such as “en-US”.

• Type: string

APPLICANT_OIDC_EMAIL_ATTRIBUTE

The OIDC attribute name for the user’s email address.

• Type: string

APPLICANT_OIDC_FIRST_NAME_ATTRIBUTE

The OIDC attribute name for the user’s first name.

• Type: string

APPLICANT_OIDC_MIDDLE_NAME_ATTRIBUTE

The OIDC attribute name for the user’s middle name.

• Type: string

APPLICANT_OIDC_LAST_NAME_ATTRIBUTE

The OIDC attribute name for the user’s last name.

• Type: string

Login.gov

LOGIN_GOV_CLIENT_ID

An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with Login.gov. A Civiform instance is always the client.

• Type: string

LOGIN_GOV_DISCOVERY_URI

A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with a given auth provider, specifically for Login.gov.

• Type: string

LOGIN_GOV_ADDITIONAL_SCOPES

Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space.

• Type: string

LOGIN_GOV_ACR_VALUE

• Type: string

• Allowed values:

  • http://idmanagement.gov/ns/assurance/ial/1

  • http://idmanagement.gov/ns/assurance/ial/2

Administrator Identity Provider

ADFS_CLIENT_ID

An opaque public identifier for apps that use OIDC (OpenID Connect) to request data from authorization servers, specifically communicating with ADFS. A Civiform instance is always the client.

• Type: string

ADFS_SECRET

A secret known only to the client (Civiform) and authorization server. This secret essentially acts as the client’s “password” for accessing data from the auth server.

• Type: string

ADFS_DISCOVERY_URI

A URL that returns a JSON listing of OIDC (OpenID Connect) data associated with the IDCS auth provider.

• Type: string

ADFS_GLOBAL_ADMIN_GROUP

The name of the admin group in Active Directory, typically used to tell if a user is a global admin.

• Type: string

ADFS_ADDITIONAL_SCOPES

Scopes the client (CiviForm) is requesting in addition to the standard scopes the OpenID Connect spec provides. Scopes should be separated by a space.

• Type: string

AD_GROUPS_ATTRIBUTE_NAME

The attribute name for looking up the groups associated with a particular user.

• Type: string

Database

Configures the connection to the PostgreSQL database.

DATABASE_APPLY_DESTRUCTIVE_CHANGES

• Type: bool

DATABASE_CONNECTION_POOL_SIZE

Sets how many connections to the database are maintained.

• Type: int

DB_JDBC_STRING

The database URL.

• Type: string

DB_USERNAME

The username used to connect to the database.

• Type: string

DB_PASSWORD

The password used to connect to the database.

• Type: string

AWS_REGION

Region where the AWS SES service exists. If STORAGE_SERVICE_NAME is set to 'aws', it is also the region where the AWS s3 service exists.

• Type: string

AWS_SES_SENDER

The email address used for the 'from' email header for emails sent by CiviForm.

• Type: string

Application File Upload Storage

Configuration options for the application file upload storage provider

STORAGE_SERVICE_NAME

What static file storage provider to use.

• Type: string

• Allowed values:

  • s3

  • azure-blob

AWS_S3_BUCKET_NAME

s3 bucket to store files in.

• Type: string

AWS_S3_FILE_LIMIT_MB

The max size (in Mb) of files uploaded to s3.

• Type: string

AZURE_STORAGE_ACCOUNT_NAME

The azure account name where the blob storage service exists.

• Type: string

AZURE_STORAGE_ACCOUNT_CONTAINER

Azure blob storage container name to store files in.

• Type: string

AZURE_LOCAL_CONNECTION_STRING

• Type: string

ESRI Address Validation

Configuration options for the ESRI GIS client and address validation/correction feature.

ESRI_ADDRESS_CORRECTION_ENABLED

Enables the feature that allows address correction for address questions.

• Type: bool

ESRI_FIND_ADDRESS_CANDIDATES_URL

• Type: string

ESRI_ADDRESS_SERVICE_AREA_VALIDATION_ENABLED

Enables the feature that allows for service area validation of a corrected address. ESRI_ADDRESS_CORRECTION_ENABLED needs to be enabled.

• Type: bool

ESRI_ADDRESS_SERVICE_AREA_VALIDATION_LABELS

Human readable labels used to present the service area validation options in CiviForm’s admin UI.

• Type: index-list

ESRI_ADDRESS_SERVICE_AREA_VALIDATION_IDS

The value CiviForm uses to validate if an address is in a service area.

• Type: index-list

ESRI_ADDRESS_SERVICE_AREA_VALIDATION_URLS

• Type: index-list

ESRI_ADDRESS_SERVICE_AREA_VALIDATION_ATTRIBUTES

The attribute CiviForm checks from the service area validation response to get the service area validation ID.

• Type: index-list

ESRI_EXTERNAL_CALL_TRIES

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

• Type: int

Email addresses

SUPPORT_EMAIL_ADDRESS

This email address is listed in the footer for applicants to contact support.

• Type: string

IT_EMAIL_ADDRESS

This email address receives error notifications from CiviForm when things break.

• Type: string

STAGING_ADMIN_LIST

If this is a staging deployment, the application notification email is sent to this email address instead of the program administrator's email address.

• Type: string

STAGING_TI_LIST

If this is a staging deployment, the application notification email is sent to this email address instead of the trusted intermediary's email address.

• Type: string

STAGING_APPLICANT_LIST

If this is a staging deployment, the application notification email is sent to this email address instead of the applicant's email address.

• Type: string

SECRET_KEY

• Type: string

BASE_URL

The URL of the CiviForm deployment. Must start with 'https://' or 'http://'.

• Type: string

• Validation regular expression: ^(http://|https://)

• Regular expression examples:

  • http://my-civiform.org should match.

  • https://my-civiform.org should match.

  • my-civiform.org should not match.

STAGING_HOSTNAME

DNS name of the staging deployment. Must not start with 'https://' or 'http://'.

• Type: string