Import and Bulk-upload Guide

1. Controlled import principle

CivitasVote does not commit an uploaded spreadsheet directly into live operational tables. The supported import workflows create a batch, parse the file, normalise values, validate every row, identify duplicates, display a preview and commit only authorised valid rows. Uploaded source files and batch history are retained in protected storage for audit.

Supported formats are CSV and XLSX. The current upload limit is 5 MB for authorised-user, voter and candidate imports.

2. General procedure

1. Download the template from the relevant page.
2. Do not rename or omit required headers.
3. Enter one record per row.
4. Preserve identifiers exactly; avoid spreadsheet auto-formatting of staff numbers.
5. Save as UTF-8 CSV or XLSX.
6. Upload the file.
7. inspect total, valid, error and duplicate counts;
8. open row-level errors and correct the source file;
9. upload a corrected batch rather than editing the database;
10. commit only after preview approval;
11. verify the committed records in the relevant list;
12. retain the batch reference for audit.

3. Authorised-user import

Exact headers

email,first_name,last_name,temporary_password,is_active

Field rules

• email: required, valid and unique without regard to case.
• first_name: required.
• last_name: required.
• temporary_password: required and subject to configured password validation.
• is_active: use a recognised Boolean value from the template guidance.

Behaviour

Committed users are ordinary application accounts, not Django staff or superusers. Imported users are expected to change the temporary password according to the importer’s account settings. Duplicate emails are reported and must not silently overwrite an existing user.

Security handling

Do not email a spreadsheet containing temporary passwords to broad distribution lists. Deliver credentials through a controlled channel, require password change and securely delete local working copies when no longer needed.

4. Voter-directory and election-register import

Exact headers

staff_number,full_name,email,phone,institution,campus_or_branch,department_or_unit,membership_category,constituency,eligibility_status,eligibility_reason

Field rules

• staff_number: required unique membership identifier within the relevant association context.
• full_name: required official name.
• email: optional unless an enabled verification method needs it; must be valid when supplied.
• phone: optional and should use a consistent international or institutional format.
• organisational classification fields: optional but should follow controlled values where the association uses them.
• eligibility_status: must use the accepted importer choice, such as eligible, ineligible or excluded according to the template implementation.
• eligibility_reason: explains the decision and should be specific but not excessive.

Directory versus register

The reusable VoterIdentity is distinct from ElectionEligibility. Importing into an election creates or associates directory identities and election-specific eligibility records. A person’s status in one election must not be assumed for another.

Duplicate handling

Investigate duplicate staff numbers, duplicate email addresses and existing directory matches. Do not create a second identity merely because spelling differs. Where a duplicate represents the same person, correct the existing record or use the supported update/review process.

After import

Review ineligible and excluded rows, confirm active voter identities, compare eligible totals with the approved source register and certify the election register. Any later change invalidates the certified digest and requires recertification.

5. Candidate import

Exact headers

position,candidate_name,biography,manifesto,ballot_order,status,nominee_reference

Availability

The candidate-import interface is available only in Commission Upload and Mixed nomination modes. Self-nomination mode requires approved nomination records; direct candidate import would create invalid unlinked candidates.

Field rules

• position: must match an election position recognised by the importer.
• candidate_name: required public ballot name.
• biography: optional public background.
• manifesto: optional campaign statement.
• ballot_order: integer controlling display sequence.
• status: accepted candidate status; approved candidates are subject to photograph requirements.
• nominee_reference: optional reference for reconciliation and audit.

Photograph limitation

The candidate import currently has no photograph column. After commit, upload a valid photograph individually for every approved candidate before final candidate-list publication and readiness.

Duplicate control

Search the candidate register before import. In Mixed mode, compare imports with self-nominations to avoid entering the same person twice for the same position. A matching name is a warning signal, not definitive identity proof.

6. File preparation controls

• Use the supplied template rather than constructing headers from memory.
• Remove merged cells, formulas, charts, comments and hidden rows.
• Put headers on the first row.
• Avoid blank rows within the data region.
• Store dates and numbers in the exact template format.
• Do not place credentials, ballot choices or unrelated sensitive data in any column.
• Scan files for malware under the organisation’s endpoint policy before upload.

7. Validation and preview

A batch may have statuses such as Uploaded, Validated, Has errors, Committed or Rejected. The preview counts do not replace row review. Confirm:

• total rows match the source;
• every error is understood;
• duplicate rows are intentionally excluded or corrected;
• valid rows contain the expected normalised values;
• the correct association and election are selected;
• no previously committed batch is being repeated.

8. Commit controls

The commit action should be performed by an authorised user after review. It records the committing user and time. Do not refresh, resubmit or use the browser Back button during a commit without first checking batch status.

After commit:

1. inspect live records;
2. compare committed count with preview;
3. resolve any post-commit operational requirements such as candidate photographs;
4. certify or publish only after downstream checks pass;
5. preserve the batch for audit.

9. Correcting errors

Do not edit import rows directly in the database. Correct the spreadsheet and create a new batch. Where an incorrect batch was already committed, use the supported user, voter, eligibility or candidate management actions and record the reason. High-impact corrections should be documented in Commission minutes and audit review.

10. Production storage

Import source files are protected records. They must not be served from public media. Back them up with protected media and the database, encrypt backups and restrict restoration access.

11. Common errors

“Upload a CSV or XLSX file”

The extension is unsupported or the file was renamed incorrectly.

File exceeds 5 MB

Remove unnecessary formatting or split the source into controlled batches without duplicating records.

Unknown position

The candidate position value does not match the configured election position. Use the template and exact current title.

Duplicate email or staff number

The record already exists or appears twice in the source. Investigate before commit.

Import committed but candidate list cannot publish

Upload missing photographs, complete nomination decisions, remove invalid Self-mode unlinked candidates and rerun final-list checks.

Spreadsheet changed identifiers

Reformat the source column as text, restore leading zeros and upload a corrected batch.