VxSuite can tabulate a wide variety of ballot designs as long as they conform to the following requirements:

1. Ballot size must be one of the available system options

2. Ballot must include correctly formatted timing mark borders

3. Ballot must include an appropriately positioned metadata QR code

4. Ballot must use a specific bubble shape

5. Ballot must adhere to system limits

Ballot Size

There are six valid ballot sizes. All are 8.5 inches in width, but vary in height:

These lengths correspond to the length specified in the Ballot Layout within the election definition.

Timing Mark Borders

Every ballot must have timing mark borders on both front and back. The timing marks and page margins are strictly defined:

As for number of timing marks, there are always 34 in the top and bottom borders. The number of marks in the left and right borders varies based on the length of the ballot, and should be calculated by the formula (# inches * 4) - 3. For example, a letter-sized ballot (11 inches) should have 41 left and right timing marks whereas a legal-sized ballot (14 inches) should have 53 left and right timing marks.

The timing marks must be aligned to the margins of the page and evenly spaced.

QR Code Metadata

The ballot must include a QR code which contains key metadata about the ballot.

QR Code Content

The QR code includes ballot metadata:

• Precinct Index - corresponds to a precinct in the election definition

• Ballot Style Index - corresponds to a ballot style in the election definition

• Page Number - page number within the ballot style

• Test Ballot Flag - indicates whether the ballot is a test ballot or an official ballot

• Ballot Type (Precinct, Absentee, or Provisional)

In addition, the QR code includes the ballot hash. The ballot hash ensures that the ballot was generated from the same election definition that will be used to interpret the ballot.

For full specifications on how to generate readable QR codes, view the ballot encoder documentation.

Metadata QR Code Placement

The interpreter looks for ballots in the bottom-left corner of the ballot. The detection area is a square whose sides are 1/4 of the ballot width.

Bubble Format

In order to be interpreted correctly, bubbles must meet the following dimensions:

Grid Coordinates

The timing mark borders define an abstract grid that VxSuite uses to assign coordinates to positions on the ballot. In the election definition, bubble positions and other ballot regions are specified using these grid coordinates. The ballot grid is an XY grid with the origin in the top-left corner. For example, the coordinate (5, 3) would correspond to the following position on the ballot:

Notes:

• Coordinates correspond to the center of each timing mark

• Coordinates specify the center of each bubble

• Fractional coordinates are allowed

Complete Example

Below is a complete ballot that, when paired with the appropriate election definition, could be interpreted within VxSuite:

The election package contains all of the information that defines an election. VxAdmin is configured by inserting a USB drive and selecting an election package from the drive.

After VxAdmin is configured, the election package can then be digitally signed and exported onto a USB drive in order to configure VxScan, VxCentralScan, and VxMark. The verifies that the election package is legitimate. The other devices require that the signature is present. As a result, an election package from outside the system cannot be used to directly configure VxScan, VxCentralScan, or VxMark.

Election Package Contents

The election package is a zip archive (a .zip file). The zip archive contains 6 files:

• Election Definition (election.json)

• App Strings (appStrings.json)

• Audio IDs (audioIds.json)

• Audio Clips (audioClips.jsonl)

• System Settings (systemSettings.json)

• Metadata (metadata.json)

Election Definition

The election definition file includes the information that defines the election and ballots, including but not limited to definitions for contests, ballot styles, precincts, parties, multi-lingual ballot translations, and ballot layouts. The system accepts two formats - the format or the . When using the Ballot Definition CDF, some features are not available.

The election definition file is required to be present in the election package.

App Strings

The app strings file contains all voter-facing strings in the user interface and their translations. For example, at the beginning of the voter flow in VxMark there is a button labelled, by default, "Start Voting." If the voter has set VxMark to another language, however, the button will display the translation for that language specified in the app strings file. Additionally, the default English text can be overridden by specifying a different English value in the app strings file.

In the case of specifying a Spanish translation and overriding the English translation for "Start Voting", which has an internal key of buttonStartVoting, the following values and overall structure would appear in the app strings file:

Notes:

• Voter-facing strings that appear on ballots (contest names, candidate names, the name of the jurisdiction, etc.) are not included in the app strings file because they are already included in the election definition.

The app strings file is optional. If not provided, default English strings will be used.

Audio IDs & Audio Clips

The audio IDs file is a JSON file structured identically to the app strings file except that instead of containing text values for each voter string, it contains audio IDs for each voter string. Each audio ID corresponds to an entry in the audio clips file.

Each row of the audio clips file contains one audio clip with relevant metadata. The audio itself appears as an MP3 file encoded in base 64. For example, a row representing an audio clip for the "Start Voting" button would appear as:

Together, the two files allow specifying audio playback for any text read to a voter in audio mode, including both non-English translations and English overrides.

The audio IDs and audio clips files are optional. If they are not provided, audio playback will be disabled.

System Settings

The system settings file contains settings which are not specific to an election definition but do impact machine behavior.

• Authentication Settings

  • arePollWorkerCardPinsEnabled - When set to true, poll worker cards are created with PINs which are then required when authenticating.

  • inactiveSessionTimeLimitMinutes- Sets the number of minutes after which machines automatically lock due to inactivity.

  • numIncorrectPinAttemptsAllowedBeforeCardLockout- Sets the number of times that a PIN can be entered incorrectly before the user has to wait extra time to retry.

  • overallSessionTimeLimitHours- Sets the maximum number of hours for any session, regardless of activity.

  • startingCardLockoutDurationSeconds - Sets the number of seconds that the user is locked out from retrying a PIN after the number of failed attempts specified by numIncorrectPinAttemptsAllowedBeforeCardLockout. Each subsequent failed attempt triggers a lockout double the length of the previous lockout.

• Scanning Thresholds

  • definite - Specifies the percentage of a bubble that needs to be filled in for the tabulators to consider it a mark.

  • writeInTextArea - Specifies the percentage of the write-in area that needs to be filled in for the tabulators to consider it a write-in. This is only relevant for jurisdictions that allow unmarked write-ins i.e write-ins without an accompanying mark.

• Adjudication Reasons

  • precinctScanAdjudicationReasons - Specifies the reasons that a ballot scanned at VxScan should be flagged for adjudication. Supported reasons are overvotes, undervotes, blank ballots, or unmarked write-ins.

  • centralScanAdjudicationReasons - Specifies the reasons that a ballot scanned at VxCentralScan should be flagged for adjudication. Supported reasons are overvotes, undervotes, blank ballots, or unmarked write-ins.

  • disallowCastingOvervotes - When set to true, scanners will always reject overvoted ballots. When set to false, VxScan will allow a voter to choose whether to reject or cast an overvoted ballot, and VxCentralScan will allow an election manager to choose whether to reject or tabulate an overvoted ballot.

  • allowOfficialBallotsInTestMode - When set to true, official ballots will not be rejected in test mode. The setting is for jurisdictions where testing must take place on official ballots.

• Other

  • precinctScanEnableShoeshineMode - When set to true, VxScan will run in "shoeshine mode," which will scan the same ballot repeatedly. Instead of ejecting the ballot after scanning it, VxScan will move it back to the input tray and scan it again. This mode is used only for internal testing and certification testing.

  • castVoteRecordsIncludeOriginalSnapshots - When set to true, scanners will include "original" snapshots in the CVR export for each ballot. This includes extra information about the marks on the ballot before contest rules are applied as specified in the CVR CDF. This extra information increases the size of the CVR export, degrading performance.

  • castVoteRecordsIncludeRedundantMetadata - When set to true, scanners will include election and system metadata in each ballot's CVR as specified in the CVR CDF, rather than just including it once for the entire export. This extra information increases the size of the CVR export, degrading performance.

  • disableVerticalStreakDetection - Disables the warning when streaks are detected when scanning ballots (which indicates that the scanner needs to be cleaned). Used as a failsafe in case of erroneous warnings.

The system settings file is optional. If not provided, the following default settings will be used:

Metadata

The metadata file is a JSON file that contains a single key, version. In the current software version, the value will only ever be "latest". In other words, the metadata file is a JSON file with the contents:

In future software versions, the "version" value will be used to differentiate versions of the election package that correspond to different software versions. For example, if a user flow is updated, a new app string may be added and the "version" value will indicate which app strings to expect.

Ballot Hash and Election Package Hash

There are two hashes for each election which are both critical to operation and security of each election.

The ballot hash is the SHA256 hash of the election definition file and represents a snapshot of all election-specific data which determines the ballot, including contest definitions and ballot layout. Ballots must include a machine-readable version of the ballot hash (e.g. a QR code or a pattern of timing marks). When a ballot is scanned, the scanner checks to make sure the ballot has the expected ballot hash. The ballot hash from the ballot must match the ballot hash from the scanner's configured election definition.

If any election content changes, the ballot hash will change, meaning the system will consider it to be a new election definition, and any ballots with a different ballot hash will not scan. The system's strict checking of the ballot hash prevents situations where a change to the election definition leads to ballots being miscounted (for example, if the order of two candidates is swapped). As a result, any changes to the election definition require reprinting all ballots.

The election package hash is the SHA256 hash of the entire election package, which includes both the election definition and all other files. The election package hash is displayed on screen to election managers and system administrators. It allows the user to ascertain which election package was used to configure a machine. The election package hash is not used during ballot scanning.

For example, imagine that an election administrator wants to change the audio clip for candidate's name. The audio clip is not a part of the election definition but it is a part of the election package, so the ballot hash remains the same while the election package hash changes. The election administrator can reconfigure VxMark with an updated election package but does not have to reprint ballots.

The election ID shown on screen and included in printed reports contains a shortened version of both the ballot hash and the election hash in the format: {ballot hash}-{election hash}. For example, with ballot hash 083e2e0afbb19191a4d2850562ddef050ff860b0d61acee15d3bb26954932941 and election hash db5c379b71accbf991e42ab23d26202f88b2539b6c69b814a0d3c8dc9f4072dc, the election ID would be: 083e2e0-db5c379. This enables identification of both the specific election package and election definition that a machine is configured with.

The election definition within the election package can be a JSON Ballot Definition CDF Version 1.0 file. The full specification is defined by NIST and can be .

VxSuite CDF Implementation

VxSuite accepts the Ballot Definition CDF Version 1.0 as defined by NIST without any data extensions. VxSuite requirements differ from the NIST CDF schema only in the following respects:

• Some fields not required in the NIST CDF are required in VxSuite

• Some enumeration values are more restricted in VxSuite than in the NIST CDF

• Some classes and attributes are ignored in VxSuite

The exact VxSuite schema is defined as a which is derived from the . The differences between the two are documented in the below tables.

Required Class Attributes

Restricted Enums

Ignored Classes and Enums

Ignored Class Attributes

VxSuite CDF Conversion

Attribute Mappings

Translations

Geographies

The Ballot Definition defines all geographies as GpUnits, whereas the VxSuite Election Definition defines various geographies.

VxSuite CDF Limitations

• Contest term descriptions (e.g. “2 years”) will always show up in English because there is no field in the CDF for internationalized term descriptions

• The full party name will be displayed for each candidate on VxMark (e.g. “Democratic Party” instead of “Democrat”) because the CDF only has one attribute for party name. In contrast, the VxSuite format supports two separate fields, one for the full name and one for showing on the ballot.

• When adjudicating write-ins, the highlighted contest option area will be set to a default because there is no field in the CDF for this parameter.

• Seal images are not supported in the CDF, so no seal will be shown in association with the election.

After a voter is done making vote selections with VxMark, the machine will print a ballot representing the selections. The voter reviews the ballot, after which it is deposited into the attached ballot box. Eventually, those ballots are scanned at VxScan or VxCentralScan.

Ballot Layout

The ballot displays information about the election, metadata about the ballot, and the voter's selections. The selections are both displayed and encoded in the QR code.

The blank space at the top of the ballot is included so that all of the ballot content is visible when VxMark presents the ballot for the voter to review (since the top part of the ballot is held in the machine).

Multi-Lingual Ballots

QR Code

VxAdmin supports a variety of results exports.

Tally reports contain contest results for the full election or a specific subset of ballots. They can be printed directly from VxAdmin, exported as PDFs, or exported in CSV format. In addition, full election results can be exported as an Election Results Reporting CDF JSON file.

Ballot count reports include only ballot counts, without contest results. They can also be printed directly from VxAdmin, exported as PDFs, or exported in CSV format.

The write-in adjudication report acts as a summary of all write-in adjudication activity or as a "scatter report." The tally reports consolidates write-in candidates whose vote totals are too small to affect the contest outcomes. The counts for those write-in candidates are available in the write-in adjudication report. The write-in adjudication report may be printed directly from VxAdmin or exported as a PDF.

For all VxAdmin reports, the report is either "Official" or "Unofficial." If the report is exported before the results are marked as official in the application, the results are "Unofficial." If the report is exported after the results are marked as official in the application, the results are "Official." All visual reports have "Official" or "Unofficial" included in the title and all exported files will have "official" or "unofficial" included in the filename.

Polls Opened and Closed Reports

When polls open or close on VxScan, a tally report is printed. The tally report contains the tally results (pre-adjudication) of all ballots scanned at the scanner.

The tally report header contains the following information:

• Title - Includes the type of the polls report and the name of the precinct, or "All Precincts" if VxScan is configured to accept ballots from all precincts

• Subtitle - For primary elections, includes the full party name or "Nonpartisan Contests"

• Election Info - The title, date, and location of the election

• Timestamps - The first timestamp indicates when the poll status changed and the second indicates when the report was printed. In most cases these times are the same, but in some cases the report may be printed later.

• Election ID - The election ID on the report is a concatenation of the ballot hash and election package hash and specifies exactly which election definition and election settings that the report corresponds to

• Certification Signatures - The space is provided for poll workers or election officials to sign the report in accordance with local statute.

The ballot counts table provides the count of hand marked vs. machine marked ballots. For elections with multi-sheet ballots, it provides counts per sheet.

Each candidate or contest option appears in a row below the contest header. Because results at VxScan are not yet adjudicated, all write-ins are grouped under the "Write-In" bucket (except unmarked write-ins, which are reported as undervotes until adjudicated at VxAdmin).

As a rule, the sum of the number of votes for all candidates, the number of undervotes, and the number of overvotes will equal the number of total possible votes for the contest, which is the number of ballots times the number of selections allowed.

candidate votes + undervotes + overvotes = ballots * votes allowed

Polls Paused and Resumed Reports

When voting is paused or resumed, VxScan prints a report containing the ballot count. Tally results are never included. The header is structured in the same way as the polls opened and closed reports.

The VotingWorks voting system (a.k.a. VxSuite) consists of four primary components:

• VxAdmin: election setup and election results manager

• VxMark: ballot-marking device (BMD)

• VxScan: precinct scanner

• VxCentralScan: batch scanner

Using VxSuite for an election begins with generating an election package and hand marked ballots using an external system.

VxAdmin

VxAdmin is where the election administrator performs election setup tasks and manages election results. At the beginning of an election, the user configures VxAdmin with an election package. Once configured, VxAdmin is used for two key election setup tasks:

• Exporting a copy of the election package to USB drives with a digital signature. The election package is used to configure VxMark, VxScan, and VxCentralScan, and it must be digitally signed by VxAdmin.

• Programming role-based smart cards that will be used to authenticate on all machines. While the "System Administrator" role is election-agnostic, the "Election Manager" and "Poll Worker" roles are election-specific and cards must be programmed for every election.

VxAdmin is later used to load, store, and tabulate cast vote records from the scanners. The results are available for review or export in several results formats. Once tabulation is complete, election administrators can mark results as official, after which no new results can be added.

• VxAdmin Function

• VxAdmin & VxCentralScan Hardware

VxMark

VxMark is the system's ballot-marking device (BMD) that provides an accessible voting experience. At the beginning of an election, it is configured with an election package from VxAdmin. Once configured, a voter can make vote selections in various interaction modes according to their needs.

The following input modes are supported:

• Touch, using the touchscreen

• Tactile, using the accessible controller

• Limited Dexterity, using a sip-and-puff device or other dual-switch input

The following output modes are supported:

• Visual, with options to change color contrast and text size

• Audio, with navigation instructions and contest details read to the user over headphones

The voter can also adjust the language based on translations included in the election package.

After the voter finishes their vote selections, VxMark prints a machine marked ballot and presents it to the voter. The ballot is scanned (but not cast) so the interpreted results can be presented to the voter on-screen. After reviewing the ballot and confirming their selections, the ballot is cast and ejected into the attached ballot box. At a later time, depending on election procedures, the ballot will be removed from the ballot box and tabulated at one of the system's scanners.

• VxMark Function

• VxMark Hardware

VxScan

VxScan is the system's precinct scanner. At the beginning of an election, it is configured with an election package from VxAdmin. The election package specifies the ballot layouts. The polls are opened by a poll worker after which casting ballots is allowed. Opening polls prints a tally report which is empty because no ballots have been scanned, a.k.a. the zero report.

Voters cast ballots by inserting their ballots into the scanner in any orientation. After interpreting the scanned ballot, the scanner will drop the ballot into the ballot box and inform the voter that their ballot was successfully cast. During voting, VxScan continuously exports cast vote records to an attached USB drive.

If the election is configured to support second-chance voting and the ballot triggers a configured adjudication reason (e.g. it has an overvote), the scanner will hold the ballot while the voter is notified of the issues on their ballot. The voter then chooses whether to cast their ballot or return it to update or spoil.

When polls are closed, the CVR export is completed and a polls closed report prints. The polls closed report includes the vote tallies of all ballots cast at the scanner while polls were open. Unlike the vote tallies eventually exported from VxAdmin, the vote tallies at VxScan do not contain any post-voting adjudication information such as write-in adjudication. The CVR export on the USB drive is then taken to VxAdmin for adjudication, aggregation, and reporting.

• VxScan Function

• VxScan Hardware

VxCentralScan

VxCentralScan is the system's batch scanner, often used to scan absentee or provisional ballots. At the beginning of an election, it is configured with an election package from VxAdmin. The election package specifies the ballot layouts.

Ballots are inserted in the batch scanner's hopper and a batch scan is triggered from VxCentralScan. The ballots are scanned and interpreted in succession until the hopper is empty. If a ballot triggers a configured adjudication reason (e.g. it has an overvote), scanning will pause and the ballot will be displayed on screen, at which point the user can choose to tabulate the ballot anyway or remove it, untabulated.

After scanning is complete, the user can export the cast vote records to a USB drive and take the USB drive to VxAdmin for adjudication, aggregation, and reporting.

• VxCentralScan Function

• VxAdmin & VxCentralScan Hardware

The VxSuite Election Definition is a data format for defining an election that is specific to VxSuite. It is a JSON file which defines the essential features of an election - metadata, contests, parties, precincts, districts, ballot styles, candidates, and more. In addition to defining that basic structure of the election, the format contains translations for any text which may appear on the ballots and ballot layouts to map the bubbles on each ballot to contest options.

Core Election Attributes and Relationships

Election

The Election entity is the top-level entity that contains all other entities.

Ballot Layout

The ballot layout entity includes basic information about the physical ballots used for the election.

The paperSize attribute accepts the following valid options:

letter, legal, custom-8.5x17, custom-8.5x18, custom-8.5x21, custom-8.5x22

The metadataEncoding attribute must be "qr-code".

Ballot Style

Each ballot style corresponds to a single- or multi-sheet ballot. The contests on a ballot style are determined by its associated districts - every contest belonging to an associated district is considered a part of the ballot style. A ballot style may be used in multiple precincts, one ballot style might correspond to multiple ballot PDFs that have identical contest layouts but different precinct labels.

Contest

There are two types of contests - candidate contests and yes-no contests. Both types share core attributes:

Candidate Contest

In a candidate contest, the voter makes a selection between pre-defined candidates or write-in options. The following attributes extend the shared Contest attributes:

Candidate

Yes-No Contest

In a yes-no contest, also known as a ballot measure, the voter makes a selection between two options. The following attributes extend the shared Contest attributes:

Yes-No Contest Option

County

One and only one county is associated with each election.

District

Districts are used to define levels at which a contest takes place. For example, an election may have districts defined for the state, county, town, and ward levels. Different contests can be associated with each of those levels.

Party

Parties are used in the data model either to associate candidates with a party, associate ballot styles with a party for a primary, associate contests with a party for a primary

Precinct

Ballot Strings

The ballotStrings object contains the translations for any text which may appear on the ballot. The text falls into one of two categories: instructional text or election-specific text.

Instructional Text

Examples of instructional ballot text include:

• "To vote, completely fill in the oval next to your choice."

• "Vote for up to 3",

• "Official Absentee Ballot"

Although the system does not use the hand marked ballot instructional text for any purpose, it must be included in the election definition for security purposes. When included, it becomes a part of the ballot hash and cannot be changed without invalidating older ballots.

Election-Specific Text

The core data model already includes names and labels. For example, the Precinct entity already has a name attribute. The names within the data model are used by default in the system in reports and administrative menus. The translations for all of these names are within the ballotStrings and are important for two main reasons:

1. The language-specific strings are used to accommodate multi-lingual voting on VxMark

2. Including the translations in the election definition means they are included in the ballot hash and cannot be changed without invalidating older ballots.

The election-specific ballotStrings recognized by the system are the following:

Example

{
  "ballotStrings": {
    "en": {
       ...
      "candidateNames": {
         "john-doe": "John Doe",
         "jane-doe": "Jane Doe".
         ...
      },
      "electionTitle": "General Election",
      "hmpbOfficialBallot": "Official Ballot",
      ...
    }
    "es-US": {
      ...
      "candidateNames": {
         "john-doe": "John Doe",
         "jane-doe": "Jane Doe".
         ...
      },
      "electionTitle": "Elecciones generales",
      "hmpbOfficialBallot": "Boleta oficial",
      ...
    }
  },
  ...
}

The language codes used are the IETF language tags for supported VxSuite languages: English, Spanish, Simplified Chinese, and Traditional Chinese.

Grid Layouts

Grid layouts describe where the bubbles and write-in areas exist on each ballot style. They must correspond exactly to the ballots used for the election in order for interpretation to succeed. For more information on the acceptable ballot format and its relationship to grid coordinates, see Hand Marked Ballots.

gridLayouts is an array which contains entities with the following attributes:

Outset

The optionBoundsFromTargetMark field specifies an Outset entity. The purpose is to give the distance from the bubble to edges of the entire contest option e.g. the area that includes the bubble, the corresponding candidate's name, and some padding. The system uses this area during write-in-adjudication to highlight specific contest options for review.

Grid Position

Grid positions are defined positions on the ballot corresponding to bubbles that can be marked by a voter. The row and column coordinates of each grid position denote where the bubble is printed within the abstract "grid" created by the timing marks on the outer edges of the ballot. There are two types of positions - a standard option position corresponding to a candidate or option in the election definition or a write-in position corresponding to a write-in bubble and area on the ballot.

Option Grid Position

Write-In Grid Position

In some jurisdictions, a write-in can only be counted if the associated bubble is filled in as for any other option. In other jurisdictions, a write-in must be counted even if the bubble is not filled. In order to detect these write-ins, a writeInArea is defined for each write-in grid position. The Rectangle specifies the area.

Rectangle

Examples

Election definition examples are located in the vxsuite repository, such as here.

The full election tally reports can be exported as JSON Election Results Reporting CDF results. The feature is only available for the full election results and not grouped or filtered results. The export follows the CDF specification without extensions. The CDF fields are used as follows:

The write-in adjudication report includes the results of all write-in adjudication organized by contest:

The values in the contest table above are as follows:

Relationship to Tally Reports

Before adjudication, write-ins are treated as votes for a generic write-in candidate and will appear in tally reports as "Unadjudicated Write-In." After adjudication, the new value will be reflected on tally reports:

• When adjudicated for an official candidate, the write-in will be added to the official candidate count just as a regular vote for the candidate would be

• When adjudicated for a write-in candidate, either:

  • The write-in will appear in the adjudicated write-in bucket if it is not relevant to the results

• When invalid, the write-in becomes an undervote

Unmarked Write-Ins

Unmarked write-ins behave differently in relationship to the tally results because they cannot be considered a valid vote before adjudication. As a result, they are considered undervotes before adjudication. If an unmarked write-in is adjudicated as invalid, then tally results will not change. If an unmarked write-in is adjudicated for a candidate, the unmarked write-in is no longer an undervote and is added to the vote total for that candidate.

Also note that, because the write-in adjudication report includes unmarked write-ins, the "Unadjudicated Write-In" count on tally reports may be less than the "Not Adjudicated" count on the write-in adjudication report. The initial difference is the count of unmarked write-ins.

Both tally reports and ballot count reports can be exported in comma-separated values (CSV) format.

Tally Report CSV Structure

In the CSV tally report, the vote total for each candidate or contest option is listed in a single row. In addition, there are rows for overvote and undervote totals for a contest.

For example, here is an excerpt of a tally report including the results for one contest:

If manual results were entered, two additional columns will be added - "Scanned Votes" and "Manual Votes." These columns denote which votes for each selection came from the scanners vs manual entry.

The results of write-in adjudication are always included in the CSV exports. All write-in candidates will appear with their adjudicated name and a UUID assigned by VxAdmin. Unadjudicated write-in candidates will appear as "Unadjudicated Write-In" with the ID "write-in". Unlike in the printed reports, write-in candidates are never consolidated.

Ballot Count Report CSV Structure

Shared Metadata Structure

Any filters or groupings which apply to each row will be indicated in the row itself by metadata columns. For example, in the example export above, the "Precinct" column lists which precinct group each row represents.

If a row is filtered by a single attribute value (e.g. represents one precinct rather than multiple precincts) then the following basic metadata fields are used:

If a row is filtered by multiple attribute values, the following columns may be used:

In cases as above, where a row value includes comma-separated values, those values will be wrapped in quotation marks per typical CSV formatting in order to allow consumers to properly differentiate columns.

Basic Structure

The basic structure of the tally reports printed from VxAdmin is similar to the printed from VxScan.

Filtered and Grouped Reports

In addition to the full election report, VxAdmin exports reports filtered or grouped by the following dimensions:

• Ballot Style

• Precinct

• Voting Method

• Scanner

• Batch

• District (filtering only)

When a report is grouped, the report is broken up into multiple sections each with their own filter. For example, if you were to group by "Voting Method," the resulting report would have a section filtered for precinct ballots only and a section filtered for absentee ballots only:

The filter for a given report section is indicated in the title of the report. If the report has more than one filter applied to it, the full details of the filter will be specified in a box below the title:

Note that filters and groups can be combined.

Manual Results

If manual results have been added, they will be included in the tally report alongside the scanned results. For each contest, there will be three results columns: "scanned", "manual", and "total".

Write-In Candidate Aggregation

In order to prevent a long list of write-in candidates from making contest results difficult to read, VxAdmin tally reports consolidate write-in candidates if they're not relevant to the contest outcome. Relevant write-ins are included as "<Name> (Write-In)". Irrelevant write-ins are consolidated as "Write-In" or, if there are relevant write-ins in the list, "Other Write-In". Unadjudicated write-ins are always consolidated as "Unadjudicated Write-In."

A write-in is deemed relevant if it must be listed for the reader to determine the winner(s) of the contest. In the middle example below, the single adjudicated write-in is consolidated because Natalie Portman is the winner regardless of the identities of the write-ins. In the last example, however, there are 31 adjudicated write-ins so it's possible that a write-in got more votes than Natalie Portman. The report then enumerates the write-ins with the highest vote totals until the "Other Write-In" count is smaller than the counts for all winners.

Overview

Laptop

VxAdmin and VxCentralScan are both laptops that connect to peripherals as needed. The laptop is a .

The relevant hardware interfaces are:

• Smart Card Reader - Enables reading and writing to smart cards, which is the basis for authentication in VxSuite

• USB Ports - Allows connecting to the peripherals for scanning or printing

While not strictly necessary, VxAdmin and VxCentralScan are bundled with a mouse and a USB hub for ease of use. A USB A-B cable is included to connect to the peripherals.

VxAdmin

VxAdmin connects to a printer for the purposes of printing reports. The printer includes an RJ45 (ethernet) port which is blocked by a port blocker because network connectivity is not required by the system.

VxCentralScan

VxCentralScan connects to a batch scanner for batch scanning. The scanner is either the smaller Ricoh fi-8170 or the larger Ricoh fi-7600. Ballots are loaded into the hopper and then, after a scan is triggered from the application, the scanner processes the ballots one-by-one, sending images to the application for interpretation.

Both batch scanners can be used with Ricoh imprinters (not pictured) which allow printing an identifier on each ballot as it's exiting the scanner, which can be useful for certain types of post-election audits.

The batch scanner is powered through an Anker Solix C300 LFS (Lithium Ferrite System) UPS (Uninterruptible Power Supply) to ensure that the scanner can operate in variable power environments.

The fi-8170 includes an RJ45 (ethernet) port which is blocked by a port blocker because network connectivity is not required by the system.

Bill of Materials

Shared Components (Laptop & Accessories)

VxAdmin Components (Printer)

VxCentralScan Components (Scanner)

VxCentralScan can be used with either the Ricoh fi-8170 or the Ricoh fi-7600, but does not need both. Each scanner can be paired with one of the two imprinters listed below.

Laptop Specification

The laptop is a custom configuration of the widely available HP Elitebook 840 14" G11 laptop. B43P6UP#ABA is the HP SKU of the VotingWorks configuration, which includes the following:

Discussion of Critical Components

As listed in the bill of materials above, the high criticality components are as follows:

• HP Elitebook 840 11" G11 - As the processor and data store for ballot data and other tallies, the laptops are one of the most critical components in the entire system. HP is the only manufacturer. VotingWorks is an official OEM partner of HP in order to work closely together to ensure the quality and configuration of the laptops.

• Ricoh fi-7600 & fi-8170 - As the source of ballot images for VxCentralScan, the Ricoh scanners are highly sensitive and critical components.

The medium criticality components and the reasons for their classification are as follows:

• Tripp Lite Ultra Slim USB Hub - Manages flow of data between laptop and peripherals.

• Logitech B100 Mouse - Does not directly handle election data but does plug into a USB port, thus it could still pose a USB attack vector.

• Monoprice USB A-B Cable - Manages flow of data between laptop and peripherals.

• HP LaserJet Pro 4001dn - The VxAdmin printer is responsible for printing reports from VxAdmin and therefore handles highly sensitive election information. All reports from VxAdmin can be exported as PDFs and printed elsewhere, so it is not strictly necessary for the operation of the system and thus is not the highest criticality.

• Ricoh fi-760PRB & fi-819PRB - The imprinters that pair with the Ricoh scanners are not involved in generating ballot data, so they cannot influence the interpretation of ballots when used according to instructions. The imprinted identifiers are important for post-election audits, however, so the imprinters are security-sensitive components.

VxSuite has four authenticated user roles. Authentication is performed with JCOP4 Java Cards, a security-oriented type of smart card. Each card is programmed with a single role and, in most cases, a PIN for two-factor authentication. Details of the authentication system can be found here: .

Poll Worker Role

The poll worker role is the lowest privilege role for election day tasks at the precinct.

The poll worker role allows a user to manage the polls on the precinct equipment, VxScan and VxMark. On both devices, the poll worker card is used to open and close polls on election day. On VxMark, the poll worker card is used to enable voter sessions. There are a few other actions enabled by the poll worker card - reprinting reports, powering down the machine, or checking the software hash - but overall the role is quite limited.

All poll worker cards are programmed at VxAdmin and are programmed for a specific election. They must be reprogrammed for every election. Poll worker cards may or may not require PINs depending on the value of arePollWorkerCardPinsEnabled flag in the file within the election package.

The poll worker role has no purpose on the central equipment, VxAdmin and VxCentralScan, and poll worker cards will be ignored on those devices.

Election Manager Role

The election manager role is a broad role for election officials to setup and operate the election.

On the precinct equipment, an election manager card is used to configure the machines at the beginning of each election. This includes loading the election package, selecting a precinct for the device, and checking on consumables such as thermal paper for VxScan. At the end of an election, the election manager card can be used to unconfigure machines, re-export results, and export logs. In addition, system functions like setting date and time, turning on and off certain features, and accessing system diagnostics are available to election managers. The election manager card is not usually required at the precinct on election day, however, where the poll worker card should be sufficient for all election day tasks.

On the central equipment, an election manager card is used to access core election management features. On VxAdmin, it is used to load, adjudicate, review, and export results. On VxCentralScan, it is used to operate the scanner and export results.

All election manager cards are programmed at VxAdmin and are programmed for a specific election. They must be reprogrammed for every election. They alway have PINs, which change after reprogramming the cards for a new election.

System Administrator Role

The system administrator role is a powerful role for initial election setup and machine management. Unlike the poll worker and election manager roles, they are not tied to specific elections.

On VxAdmin, a system administrator card is necessary to initially load an election package from an external system. System administrators can then program poll worker cards and election manager cards for a specific election. In that sense, the system administrator role is the gatekeeper for loading elections and creating users, and is strictly necessary for every election.

On all devices, the system administrator role allows accessing a menu with powerful system actions. Many actions are shared with election managers - unconfiguring a machine or setting the date and time. Others are unique to the system administrator. For example, on precinct devices a system administrator can reset polls from a "closed" state to a "paused" state in case a poll worker accidentally closes polls prematurely.

Additional system administrator cards can be programmed by a system administrator at VxAdmin. System administrator cards always have PINs. Because a system administrator card is necessary to program cards or set up elections to begin with, at least one pre-programmed card is initially provided with the voting system to bootstrap the jurisdiction's authentication.

Vendor Role

The vendor role is a role that only VotingWorks itself has access to. It allows booting into an administrative menu with options to update various system configuration files.

Voter Mode

While the authentication model only includes the four aforementioned roles, one can conceptually describe a "voter mode" on the precinct devices. On VxMark, a poll worker must authenticate in order to initiate a voting session. Once initiated, the voter is able to make selections, navigate menus, and print their ballot. Once done voting, the machine leaves voter mode and once again requires authentication to start a voting session. On VxScan, voter mode is any time the polls are open and no other role is authenticated, during which a ballot can be inserted for tabulation.

VotingWorks software is open-source, which means that the code is free and publicly available. All code written by VotingWorks and almost all dependencies are open-source, with the notable exception of third-party firmware for various hardware components.

All system components - VxAdmin, VxCentralScan, VxMark, VxScan - run different application code but have fundamentally the same software architecture. The rest of this document applies to all system components unless otherwise noted.

Operating System

The system uses 12 as the base operating system. Debian is a free and open source Linux distribution developed by the Debian Project. The operating system is first installed with the minimally required dependencies and then any additional packages required by the system are installed during build time.

Due to the extensive security measures, users are limited to using the application software and will not have access to Debian's typical set of features.

Application Architecture

All machines are completely disconnected from any network and have network capabilities disabled, but the frameworks and architecture employed are borrowed from web-based development. The user interacts with a restricted browser which communicates with a server that provides the web-content and another server that provides application data and hardware status.

kiosk-browser

Application Frontend Server

Application Backend Server

Application Data Management

Peripheral Management

The hardware peripherals are polled and managed through the application backends. For example when detecting the status of the card reader, the browser polls the backend server which in turn polls the hardware itself and returns a status to the browser. In order to manage changing states of more complex hardware such as scanners, the backends use state machines.

The exact layer between the application backend and the hardware varies by hardware. Some run in-process whereas others run as a separate process with which the backend communicates. For the accessibility peripherals - the accessible controller and the sip-and-puff interface - the backend starts and manages a daemon which surfaces user input directly to the browser as keyboard commands.

In many cases VotingWorks has written custom drivers that interface directly with the USB device. In other cases, VotingWorks leverages open-source middleware layers installed as Debian packages:

Firmware for embedded devices such as screens and speakers is bundled with the operating system.

Software Independence

On hand marked paper ballots, voters fill in bubbles next to their selections. Because voter indications are made and reviewed directly by the voter, they are inherently voter-verified. The software interprets the image of the ballot for tabulation but, of course, the paper ballot persists after scanning.

For machine marked paper ballots, voters make selections on screen at VxMark. After the voter has made all their selections, the ballot is printed and presented to the voter. The ballot displays a textual representation of the selections and a QR code with the selections encoded. The voter reviews the ballot and, once accepted, the voter-verified ballot is ejected into the attached ballot box. VxMark's machine marked ballots are not actually tabulated until they are scanned at a scanner.

Ballots are never modified by the system after voter verification in any way that could affect voter selections or the ability to perform an audit. The only modification to ballots is the possible use of an imprinter on VxCentralScan, which prints only an identifier along the outside margin of the ballot.

Because all voter selections are recorded on paper, voter-verified, and unmodified, the election results can always be re-tabulated or audited.

Key VotingWorks Repositories

There are four code repositories relevant to the voting system:

Key Dependency Chart

Traceability of Procured Software

Software Best Practices

The VotingWorks codebase is written in TypeScript and Rust, two widely used languages with well established coding conventions. We make use of automatic code linters to enforce these conventions. Details about our best practices and tooling used to enforce those best practices can be found here:

Failure Recovery

Common Software Functions

Subsequent articles will describe the particular software design of each application, but some software patterns are common across all applications and described here.

USB Management

All VxSuite components require a USB drive at some point in their operation for configuration or for the import or export of results. The application is polling for attached USB drives multiple times per second. If a USB drive with a FAT32 partition is detected, the application will attempt to mount the USB drive to a known mount point. Once mounted, the USB drive will be available for use by the application.

The USB drive should be ejected before removing it. Most critical operations also make sure to sync the data to the USB drive before allowing the user to continue, however, so removing the USB drive without ejecting will normally not result in problems.

Only one USB drive can be used at a time and additional USB drives inserted after the first USB drive will be ignored.

Document Creation

All VxSuite components must generate documents for printing or export. VxAdmin and VxScan must generate tally and ballot count reports. All components must generate diagnostic readiness reports.

In order to do so, the applications have a headless browser (specifically Chromium) launched by the backend. Exported documents are all defined in terms of HTML (using React), so the headless browser is able to load the documents and render them as PDFs. The PDFs can then be sent to printer or saved to a USB drive.

Date & Time Management

The date and time is set on the machine in during initial configuration before the machine is sent to a customer. There is some amount of "clock drift" over time for all computers, however, so eventually the clocks may be wrong. This may cause problems with authentication due to mismatched timestamps and will cause reports to have incorrect timestamps.

All machines allow system administrators and election managers to edit the date, time, and time zone in order to address clock drift or, in rare cases, to set up machines for use in a part of the jurisdiction with different time settings.

Other Shared Software Patterns

Ballot count reports contain ballot and ballot sheet counts, not contest results.

The ballot counts are broken down by ballot type - "HMPB" (for hand marked ballots), "BMD" (for machine marked ballots), and "manual" (for manually entered results, if applicable).

If there are multi-sheet ballots, the hand marked ballot counts may have sheet counts specified. The ballot count is determined by counting the first sheet of each ballot style.

When grouping is applied in a ballot count report, each group corresponds to a row in the table. In the following example, the ballot counts are grouped by both precinct and voting method:

The following metadata columns may appear in a ballot count report table in order to specify groupings:

Filters apply to the entire report. Simple filters are shown in the title, while complex filters are listed in a box below the title.

VxCentralScan is the system's batch scanner which enable election managers to efficiently scan large batches of ballots.

Configuration

VxCentralScan is configured with a signed exported from VxAdmin. The election definition includes the ballot layouts necessary for interpreting ballots and the system settings which indicate what type of ballot issues (e.g. overvotes) require adjudication. After the election package is loaded by an authenticated election manager, no further configuration is required.

Ballot Mode

After initial configuration, VxCentralScan is in test ballot mode. The election manager can toggle between test ballot mode and official ballot mode. In official ballot mode, only official ballots can be scanned and exported CVRs will be official ballot CVRs. In test ballot mode, only test ballots can be scanned and exported CVRs will be test ballot CVRs. If allowOfficialBallotsInTestMode is set in the , official ballots will be allowed in test mode but exported CVRs will still be test CVRs.

Switching between ballot modes clears all scanned ballot data. The election manager can switch from test ballot mode to official ballot mode at any time. When in official ballot mode after ballots have been scanned, the election manager can only switch back to test ballot mode if the scanned ballot data has been backed up.

Unconfiguring

VxCentralScan can be unconfigured by an election manager or system administrator. If ballots have been scanned in official ballot mode, an election manager can only unconfigure the machine after scanned ballot data has been backed up. System administrators can unconfigure the machine at any time.

Batch Scanning

Scanner Management

VxCentralScan is compatible with the Ricoh fi-8170 and Ricoh fi-7600 production scanners. Once either scanner is detected, the user may begin scanning batches. The scanners are controlled via commands provided by the Debian sane package ("Scanner Access Now Easy") which creates a uniform API for most commercial scanners. As a result, no scanner-specific drivers are required.

Batch Management

The start time, end time, size, and index of all batches is tracked and displayed to the election manager. If a mistake was made in organizing batches or adjudicating a ballot, election managers can delete any individual batch or delete all batches.

Imprinting

Both Ricoh scanners can be used with an optional imprinter - the fi-819PRB for the fi-8170 and the fi-760PRB for the fi-7600. As the ballot exits the scanner, the imprinter prints an identifier on the side margin of the ballot. The identifier is the batch's UUID suffixed with the index of the sheet in the batch e.g. 378f6a69-62d3-4184-a1a7-3a5d90083e21_0000 for the first sheet in a batch. The identifier will appear in the CVR as the BallotAuditId. Imprinting allows later reconciling CVRs to ballots such as in ballot comparison audits.

Batch UUIDs

The v4 UUID (universally unique identifier) for each batch is generated when the batch is first created. It is generated with the node package uuid which uses the system's underlying FIPS-complaint OpenSSL implementation to generated random bytes.

Ballot Issues & Adjudication

Batch scanning pauses whenever a ballot is not counted for any reason. Sometimes the ballot was not interpreted or cannot be accepted, in which case the ballot must be removed:

• Vertical Streaks Detected - the scanner may require cleaning

• Wrong Ballot Mode - test ballots in official ballot mode or official ballots in test ballot mode

• Wrong Election - the hash on the ballot does not match the currently configured election

• Unreadable - the ballot image could not be successfully interpreted, possibly because it is not a valid ballot or because the image skew was too great

• Overvote - at least one contest is overvoted

• Undervote - at least one contest is undervoted

• Blank - all contests are blank

In these cases, the affected contests will be highlighted on screen to the election manager and they will have the option to remove or tabulate the ballot.

Exporting CVRs

CVRs must be exported onto a USB drive and taken to VxAdmin for aggregation and reporting. The election managers has options to either save CVRs or save a backup. When saving CVRs, ballot images are only included for ballots with write-ins and rejected ballots are not included. A backup is simply a CVR export with images for all ballots and images for rejected ballots.

After ballots are interpreted, their images are saved to disk and their interpretation is stored in VxCentralScan's data store. On export, all CVRs are pulled from the data store, converted to the CVR CDF, and written to the USB drive.

A cast vote record is a record of voter selections based on the system's interpretation of a scanned ballot. Each cast vote record corresponds to a single scanned ballot sheet. Multi-sheet ballots produce multiple cast vote records.

Cast vote records are exported from VxScan and VxCentralScan onto USB drives and then imported into VxAdmin. Each cast vote record export is created with a digital signature. VxAdmin verifies this signature when importing cast vote records to ensure that the export has not been tampered with.

Directory Structure

In order to export cast vote records efficiently and without compromising voter privacy, every cast vote record is generated individually. The structure of a cast vote record directory is as follows:

The cast vote record export contains a directory for each cast vote record, labelled with its UUID. Each specific cast vote record directory contains:

• Cast Vote Record Report - Contains information about the election and the ballot interpretation in the Common Data Format. The information in the report is used as the basis for tabulation by VxAdmin.

• Images - Ballot images to be used in write-in adjudication or auditing

• Interpreted Ballot Layouts - Metadata for the position of ballot features such as contests, contest options, and bubbles in the ballot image. The interpreted layout data is used to properly crop and highlight ballot images for write-in adjudication.

In addition, there is a metadata file that applies to the entire export at the root of the directory, metadata.json.

CVR UUIDs

The v4 UUID (universally unique identifier) for each cast vote record is generated when the ballot information is first stored in the database in VxScan or VxCentralScan. It is generated with the node package uuid which uses the system's underlying FIPS-complaint OpenSSL implementation to generated random bytes.

Including Ballot Images

In VxScan, ballot images and layouts are always included. In VxCentralScan, ballot images and layouts are only included in the cast vote record export if the ballot has write-ins that may require adjudication. When exporting a backup from VxCentralScan, however, ballot images and layouts are included for all ballots.

Layouts are not included for machine marked ballots.

Including Rejected Ballots

In VxScan, images of rejected ballots are always included. In VxCentralScan, images of rejected ballots are not included in the cast vote record export but are included in the backup. There are no layout files or cast vote record report for rejected ballots because they are often uninterpretable. When rejected ballots are included, they will appear in the directory with the prefix rejected-, as in the following example:

Cast Vote Record Report

CDF Implementation

Because VxAdmin requires a VxSuite digital signature on all imported cast vote records, it's not possible to import a cast vote record from outside of VxSuite. The goal of using CDF is to help external systems consume VxSuite cast vote records for audit or analysis.

VxSuite Required Fields

Report Metadata

CastVoteRecordReport

CastVoteRecordReport.ReportingDevices

Only one ReportingDevice is ever listed:

CastVoteRecordReport.Party

CastVoteRecordReport.GpUnit

CastVoteRecordReport.Election

Cast Vote Record Attributes

Each cast vote record includes a set of ballot metadata attributes:

Ballot Images

The CVR.BallotImage attribute exists when there are images accompanying the cast vote record. If it exists, it always contains images for both sides of the ballot. Its attributes are as follows:

Hashes of the ballot image and ballot layout files are included in the cast vote record report so that the hash (and digital signature) of the cast vote record export will reflect any change to the image or layout files.

Snapshots

The CDF specification allows detailing multiple versions of the same cast vote record as "snapshots."

For hand marked paper ballots, there are both "original" and "modified" snapshots. The "original" snapshot contains mark thresholds for every single bubble on the ballot and is included purely for auditability. The "modified" snapshot contains only the marks that were detected as definite marks and counted as valid or invalid votes.

For machine marked ballots, there is only an "original" snapshot.

The snapshot is referenced in the CVR.CurrentSnapshotId field by it's identifier, which will be the unique identifier of the cast vote record along with its type, such as

Ballot Type

The CDF specification does not have any allowance for a ballot type such as "absentee" or "precinct" at the metadata level, so it is added as information to each snapshot:

Representing Votes

The CVRContest class within each snapshot contains a list of vote records by contest. The fields are used as follows:

Ballot Images

Ballot images are .jpg files. They are included in the cast vote record in order to be used for write-in adjudication or auditing. Ballot images are generated by the scanning hardware and then normalized to reduce skew and enforce a consistent orientation. Images from VxCentralScan are in grayscale while images for VxScan are in black and white.

Ballot Layouts

Ballot layouts are JSON files which describe the discovered position of ballot content within interpreted ballots, including where each contest and contest option appears. Although the layout of ballot content within the ballot grid is specified by the election definition, the ballot content may be positioned in a slightly differently location in each scanned ballot image due to offset or skew of the ballot during scanning. As a result, the layouts are included in order to have accurate image highlights and crops for write-in adjudication.

Export Metadata

The metadata file includes data that applies to all cast vote records in the export. There is only one per export. The relevant attributes are:

Batch Manifest

Each cast vote record is associated with a batch via its BatchId metadata field. The CDF doesn't have a place within the cast vote record report to include batch metadata, so it is included here.

VxAdmin acts as the election setup hub at the beginning of the election and the results aggregation and reporting hub at the end of an election (and also at the end of testing).

Configuration and Election Packages

Only a can authenticate onto an unconfigured VxAdmin and configure it with an election package from an external system. The election package must be loaded via a USB drive. The election package must be a valid .zip . If the election package zip file, election definition file, system settings file, or metadata file are not valid, VxAdmin will surface an error to the user.

It's also possible to configure VxAdmin directly from a .json file rather than a full election package. The system will use default system settings and include no additional translations for application strings. Uploading a .json file directly is not recommended for general use because it means you are unable to customize system settings like ballot adjudication reasons. The option exists for development purposes. VxMark, VxScan, and VxCentralScan cannot be configured from an election definition alone and require a signed election package.

Once VxAdmin is configured, system administrators and election managers can export signed election packages. The exported election package is the same as the imported election package but is accompanied by a digital signature, which ensures that the election package was validated by a certified VxAdmin. The election packages loaded into VxMark, VxScan, and VxCentralScan must be signed and unsigned election packages will be rejected.

Smart Card Management

Smart cards are used for two-factor authentication on all machines in the system. They can only be programmed at VxAdmin with system administrator privileges.

Programming, like authentication, takes place via the laptop's built-in USB card reader. Once a card is inserted, the application is able to detect the card and read and write data by issuing APDUs (application protocol data units) which are the standard form of communication between smart card readers and smart cards.

For extensive details on the authentication scheme, see the .

USB Formatting

VxSuite components require USB drives to be formatted with a FAT32 partition. The majority of USB drives are sold pre-formatted as FAT32, but some come in other formats. If an improperly formatted USB drive is inserted into a VxSuite component, it will be treated as if there is no USB drive.

VxAdmin includes a utility to format USB drives to be compatible with the system. The utility is available only to system administrators. It will rewrite the partition table on the drive to include a single partition with a FAT32 formatted filesystem that takes up all available space on the drive. The reformatting clears the USB drive and is thus a destructive action. If a USB drive is already correctly formatted, the feature can be used to clear its data. VxAdmin applies a new label to the reformatted USB drive in the form of VxUSB-00000, where the 0's can be any random alphanumeric characters.

Improperly formatted USB drives can only be detected and reformatted if there is some partition already existing, so a USB drive without any partitions cannot be reformatted using VxAdmin.

CVR Management

Loading CVRs

CVRs must be loaded from a USB drive. CVRs are exported from VxScan or VxCentralScan and are accompanied by a digital signature. CVRs without a digital signature cannot be loaded. CVR exports with digital signatures that do not match the content of the CVR exports cannot be loaded in order to prevent tampering.

The CVRs from the scanners are saved to specific directory structure on the USB drive, but exports can be loaded from anywhere on a USB drive's filesystem. When selecting an export manually, the export's metadata.json file must be selected by the user.

When loading a full CVR export, each CVR is loaded into VxAdmin's backend store as one cvrs record. The CVR record includes a data blob representing the interpreted votes and a series of metadata fields: ballot style, voting method (absentee vs. precinct), batch, scanner, precinct, sheet number within a multi-sheet ballot, and flags for adjudication reasons such as overvotes, undervotes, write-ins, or fully blank ballots. The metadata fields are used later on for filtering or aggregating tallies or ballot counts into groups.

Each write-in on a CVR will map to a write-ins record, whether it is an unmarked write-in or a proper write-in. The ballot images are also each saved as database records. The write-in record links the write-in to its respective CVR, to the ballot images, and eventually to its adjudication result. The write-in adjudication interface essentially iterates through all write-ins records on a per contest basis.

If an error is found when loading any single CVR in a CVR export, the entire export is rejected and a message is surfaced to the user. CVRs can be rejected for a variety of reasons: authentication failed; a file is incorrectly formatted; a CVR is not for a currently valid election, precinct, ballot style, or contest; a CVR with an identical ID has been loaded with different data. In everyday use of the system, all of these errors are either rare or impossible because VxAdmin will not allow loading CVR files from elections with mismatched metadata.

VxAdmin allows loading CVR exports that have already been partially loaded. For example, imagine that VxCentralScan exports CVRs after scanning 5 ballots and then again after scanning 10 ballots. If we first load the 5 CVR export and then the 10 CVR export, the 10 CVR export will successfully load but will ignore the CVRs that have already been imported.

Ballot Mode

VxAdmin is always in one of three ballot modes:

• Unlocked Ballot Mode - no CVRs have been loaded

• Test Ballot Mode - test CVRs have been loaded

• Official Ballot Mode - official CVRs have been loaded

On VxAdmin, the ballot mode is determined by the ballot mode of the imported CVRs. VxAdmin differs in that respect from VxMark, VxScan, and VxCentralScan, where the ballot mode is set directly by the election manager.

Once VxAdmin is in test ballot mode, only test CVRs can be subsequently loaded. Similarly once VxAdmin is in official ballot mode, only official CVRs can be subsequently loaded.

Removing CVRs

CVRs can be removed by the user before results are marked as official or can be removed by fully unconfiguring VxAdmin. All CVRs are removed at once. The CVR data in the database along with all its dependent data - write-ins, ballot images, and adjudications - are permanently and irrecoverably deleted from the data store.

Write-In Adjudication

When ballots with write-ins are scanned at VxScan or VxCentralScan, they have not yet been adjudicated. The polls closed report at VxScan treats all write-ins simply as a generic "Write-In" and all unmarked write-ins as undervotes.

VxAdmin allows election managers to perform on-screen write-in adjudication. Each contest is adjudicated individually. The election manager can work through the queue of write-ins for that contest. The queue is ordered by least to most recently loaded into VxAdmin. Because multiple write-ins for a single CVR are loaded together, write-ins that appear on the same ballot sheet will appear next to each other in the queue.

The user can adjudicate the write-in in one of three ways:

• Official Candidate: the list of official candidates for the given contest will be displayed and the write-in can be assigned to any official candidate

• Unofficial Candidates: the list of unofficial candidates defined for the given contest by the election manager will be displayed and the write-in can be assigned to any unofficial candidate

• Undervote: the write-in can be deemed invalid and will be considered in tallies as an undervote

Adjudications are immediately persisted to the data store. Adjudications can be changed or deselected.

Unofficial Write-In Candidates

The list of unofficial write-in candidates is created by the election manager as they adjudicate. The interface has an option to add a new write-in candidate and specify their name. That candidate will then be an option for other write-ins for the same contest. If there are no longer any adjudications that reference the unofficial candidates, their name will be removed from the list.

Invalidating or Validating Marks

In most cases, the adjudication reclassifies a vote for an unadjudicated write-in to a write-in candidate. But in some cases, the adjudication effectively reclassifies a mark as a non-mark or vice versa.

If a marked write-in is adjudicated as an undervote, in addition to updating the associated write-ins record, VxAdmin will create a vote_adjudications record representing the switch from an indication to a non-indication. If an unmarked write-in is adjudicated for a candidate, VxAdmin will create a vote_adjudications record representing the switch from a non-indication to an indication.

Manual Tallies

VxAdmin offers a way to enter manual tallies that are then added to reports. When manual tallies are present in a results export, they are always displayed separately from scanned tallies so that users can easily recognize the impact of manual results and recognize any human errors. The only exception to this rule is the CDF election results export in which, due to the limitations of the CDF, the manual and scanned tallies are simply combined.

The ballot style, precinct, and voting method (absentee vs. precinct) must be specified before entering manual tallies. By associating manual tallies with these pieces of metadata, they can be filtered and grouped according to those dimensions when creating reports. Notably, manual tallies are not associated with a batch or a scanner like CVRs. When filtering on batch or scanner, manual tallies are excluded. When grouping by batch or scanner, manual tallies are treated as a single batch or scanner.

The manual tallies for each contest are validated according to a standard formula:

The same formula also applies to all results generated from scanned ballots. If a vote for three contest is overvoted, it is considered three overvotes. If the contest tallies entered by the user are incomplete or invalid, the user is presented with warning messages.

In most cases, the ballot count will be the same across all contests. In some jurisdictions it is possible for different contests to have different ballot counts if, for example, someone votes on a ballot without local contests. In these cases, the user can override the ballot count on an individual contest basis.

Unofficial write-in candidates can also be allocated votes in manual tallies and new unofficial write-in candidates can be added directly from the manual tallies interface.

Tallying & Reports

Vote Tallying

Vote tallying is a multi-step process which takes place on the VxAdmin backend:

Every tally is specified by a set of filters and groupings. The filter defines which CVRs are excluded and included. For example, a filter might limit the CVRs to the CVRs for a specific precinct. The group determines how tallies are subdivided by CVR metadata. For example, there may be a grouping on precinct which generates tallies for each precinct separately. Groups enable multiple related tallies to be efficiently generated at once.

Filters and groupings are specified by the user directly with the tally report builder or implicitly with built-in reports.

Group Determination

If there are no groupings specified, there is only one set of tallies. If the precinct grouping is specified, there will be tallies for each precinct. If multiple groupings are specified, the possible resulting groupings need to be calculated. For example, if the precinct and ballot style groupings are both specified, only some combinations are possible because not all ballot styles exist in all precincts. If filters are specified, they may rule out certain groupings. For example, if the precinct grouping is specified but only Precinct A and Precinct B are included by the filter, then the Precinct C grouping will be excluded.

If batch or scanner parameters are included, then VxAdmin will not attempt to compute the possible groupings because they may be too numerous. The potential groups will be created opportunistically during tallying.

The purpose of computing the groups when possible, rather than always creating groups opportunistically, is to know which zero tallies to expect. When we group by precinct, we'd like to generate empty results for Precinct A even if no ballots for Precinct A were cast.

CVR Aggregation

The CVRs are pulled from the data store one by one and their vote data is added into an ongoing tally of ballots, contest option votes, overvotes, and undervotes. If the tallies are being grouped, the CVR will be added into the group that matches its metadata e.g. a CVR from a Precinct A ballot will be added to the Precinct A group.

At this step in the process, the data does not contain any of the adjudication details from write-in adjudication.

CVR aggregation is the most computationally expensive step in the vote tallying so the results are cached. The cache is reset anytime a CVR file is added or removed or anytime a vote is adjudicated through write-in adjudication.

Write-In Adjudication Aggregation

The write-in adjudication records are summarized from the data store and their adjudication statuses are added into an ongoing tally of write-ins for official candidates, write-ins for unofficial candidates, invalid write-ins, and unadjudicated write-ins. They are filtered and grouped according to the same parameters as the CVRs.

Write-In Adjudication Hydration

The vote tallies from the CVRs are then hydrated with the aggregated write-in adjudication tallies to create vote tallies that include the results of write-in adjudication. Before hydration, the tallies represent all write-ins as generic write-ins. The counts for generic write-ins are reconciled to counts for specific official and unofficial candidates.

Manual Tallies Aggregation

Manual tallies are already aggregated in the sense that each can represent more than one ballot. Since they are divided by ballot style, precinct, and voting method, however, they may need to be merged to match the groupings (or lack thereof) of the scanned vote tallies.

Manual Tallies Hydration

Manual tallies are then combined with the scanned tallies in one of two ways. For most reports, the manual tallies are paired with the scanned tallies but are not immediately added together. Reports can then display the manual and scanned tallies separately in addition to showing the total tallies. For the CDF election results report, however, the manual tallies and scanned tallies are added together because there is not a clear way to represent the difference between them in the CDF.

Reporting

Ballot Count Tallying

Ballot counts are tallied as part of the vote tallying flow described above, but there is a separate tallying path that only calculates the ballot counts. It is used when generating ballot count reports and exports from VxAdmin. It follows the same steps as vote tallying, but is more efficient because it can use the underlying SQLite database to generate tallies rather than iterating through each CVR one-by-one.

Ballot Count Definition

When tallying ballot counts, VxAdmin is actually tallying sheet counts. In an election where all ballots are a single sheet, there is no distinction between ballot counts and sheet counts. In an election with multi-sheet ballots, there may be different numbers of different ballot sheets. VxAdmin tallies each sheet separately, which is displayed on tally reports and ballot count reports.

The Ballot Count is defined in VxSuite as simply the count of first sheets. For example, if there are 1,000 first sheets and 999 second sheets, the ballot count will appear in reports as 1,000.

Official vs. Unofficial Results

Results on VxAdmin are considered unofficial until the election manager marks them as official. As long as results are unofficial, CVRs can be loaded, write-ins can be adjudicated, and manual tallies can be added and edited. All reports and result exports are labelled as "Unofficial."

Once the results are final and often only after a jurisdiction's specific certification process, the election manager can mark results as official. All reports and result exports will then be labelled as "Official." CVRs can no longer be loaded, write-ins can no longer be adjudicated, and manual tallies can no longer be altered.

There are two ways to exit official results modes:

• The system administrator may unconfigure VxAdmin entirely, removing the election configuration in addition to all tallies and adjudications.

• The election manager may remove all tallies and adjudications at once, leaving the election configuration in place.

Printer Management

VxAdmin can print reports via an attached printer. The supported printer is the HP LaserJet Pro 4001dn. VxAdmin can also export reports as PDFs so, in the event of a printer failure, reports will always be available.

VxAdmin interfaces with the printer through the CUPS, the open-source printing system developed by Apple and installed on our Debian system. When a printer is attached, it is registered with the CUPS server and made available to the application. VxAdmin is able to send print jobs to the printer via CUPS commands. The HP LaserJetPro does not require any additional third-party or in-house driver because it supports the IPP (Internet Printing Protocol) which CUPS then utilizes.

Using IPP, the VxAdmin is also able to poll the detailed status (toner level, jam status, etc.) of the printer for use in the diagnostics interface.

VxAdmin can only connect with one printer at a time and will always connect with with the first attached printer.