CivitasVote Field Reference
Purpose
This reference explains the fields that users encounter in the CivitasVote web interface. It is intended for Platform Administrators, association governance officers, Electoral Committee members, voter-data officers and technical support staff. A field may be stored by the model but not exposed on every form; the distinction is stated where relevant.
1. Authorised user account
Email address
The user’s unique sign-in name. It is normalised to lower case. The same email address cannot be assigned to two application users.
Full name
The name displayed in lists, appointments, approvals and audit information. During bulk import, first_name and last_name are supplied separately and combined for display.
Temporary password
The initial password given to the authorised user. It must comply with Django’s configured password validators. The user-import preview does not retain or redisplay the plain-text password after validation; the committed account stores only the password hash.
Account is active
An inactive account cannot sign in and does not have current operational access even where an appointment record still exists.
Require password change at next sign-in
When selected, the user must choose a new password before entering the rest of the application. The manual user-creation and administrative password-reset workflows normally enable this option.
2. Association form
Name
The full official name of the association or organisational unit. It appears on public election pages, dashboards, result exports and declarations. It must be unique without regard to letter case.
Example: School of Business and Management Studies.
Short name
An optional recognised abbreviation used where the full name is too long. It must be unique when supplied.
Example: SOBAMS.
Description
A concise description of the association or its election portal. Avoid inserting temporary election details because the association may own many election cycles.
Primary colour
The main hexadecimal branding colour selected through a colour input. The default model value is #17324D.
Secondary colour
The supporting branding colour used for accents. The default model value is #D9A441.
Data controller name
The institution or body that determines why and how personal data are processed. This should normally be an institution or formally responsible office, not the name of the software technician.
Data protection contact
The official email address for privacy enquiries, data-subject requests and data-protection complaints. The model validates this as an email address.
Retention days
The organisation’s declared retention period, expressed in days. The default is 365. The value informs retention operations; it must be supported by an approved policy and should not be interpreted as permission to erase records that remain subject to petitions, audits, litigation holds or statutory requirements.
Association is active
Inactive associations should not conduct new elections. Deactivation does not erase historical records.
Logo and institutional domains
The association form exposes an optional logo and a comma-separated list of approved institutional-email domains. Enter domains without @. The general settings JSON field remains a technical/internal field and is not an ordinary form input.
3. Association governance assignment
Association
The organisation to which the appointment applies. When the form is opened from a specific association, the field is fixed.
Authorised user
An active, non-superuser, non-Django-staff application account. A user can have only one membership record in a given association.
Role
The current interface permits the governance roles Organisation owner and Organisation administrator. Other model-level organisation roles exist for internal or future use, but they are not offered by this governance-assignment form.
Active
Controls whether the membership presently grants authority. Deactivation retains the historical record.
4. Platform Administrator appointment
Authorised user
An active application user who is neither a technical superuser nor Django staff. A technical superuser does not require a separate Platform Administrator appointment.
Appointment reference
The resolution, letter, minute or internal reference authorising the appointment.
Appointment start and end
Optional validity dates. Where both are supplied, the end must be after the start. A future appointment does not grant current access, and an expired appointment ceases to be current.
Active
A revoked appointment cannot remain active. Revocation requires a recorded reason in the operational workflow.
5. Election-cycle creation and configuration
Title
The public name of the election cycle.
Example: 2026 School Executive Election.
Description
An optional public or operational explanation of the election.
Election reference
A unique internal reference within the association. It appears in reports and audit records.
Example: SOBAMS-2026-EXEC-01.
Election type
Available values are Welfare Committee election, Mutual Fund Committee election, Main Executive election, By-election, Runoff election, Confirmatory election and Other election.
The three ordinary election types participate in the harmonised scheduling checks. A by-election, runoff or confirmatory election is not automatically treated as an ordinary annual cycle.
Nomination mode
Controls how candidate records originate. The four modes are documented fully in NOMINATION_MODES.md.
Nominations open and nominations close
Required for Self-nomination and Self-nomination-and-upload modes. The closing time must be after the opening time and must not be later than voting opening. The system needs a period between nomination closure and voting for vetting and final-candidate publication.
Voting opens and voting closes
The planned voting period. Closing must be later than opening. The model rejects a continuous voting period longer than 48 hours.
Required result approvals
The number of independent approval decisions required before publication. The model minimum is two.
Allow email codes
Permits the configured email-code verification workflow where the voter has an appropriate email address and delivery is operational.
Allow SMS codes
Stored in the full election edit form. SMS delivery requires a configured provider; enabling the field alone does not create an external SMS service.
Allow member PIN
Permits verification using the voter’s personal member PIN.
Allow institutional email
Permits institutional-email verification. Operational suitability depends on verified email data and the implemented verification flow.
Allow assisted verification
Displays assisted-verification support in the election interface. Assistance must never permit an officer to observe or record the voter’s selections. The current code should be reviewed to ensure every assisted route rechecks the flag server-side before a binding deployment.
Allow WebAuthn
Permits passkey registration or use where browser, HTTPS and relying-party settings are correctly configured.
Receipt verification enabled
Stored as an election option. The present receipt endpoint should be tested because the flag is not consistently enforced in all current code paths.
Provisional results enabled
Stored as an election option. The present publication workflow does not yet provide a complete separate provisional-results state; treat this as a configuration field requiring governance and code review.
Auto-close
Allows the scheduled process to close voting at the configured end time. The scheduler must actually run in production.
6. Position or ballot-question form
Title
The office or question presented to voters.
Description
Optional explanatory text.
Kind
The supported kinds are single-seat candidate contest, multiple-seat candidate contest, Yes/No question and referendum question.
Seats
The number of available offices for a multiple-seat contest. For a single-seat contest this should normally be one.
Maximum selections
The greatest number of candidates a voter may choose for that position. It must reflect the governing rules and should not exceed the meaningful number of seats or candidates.
Order
The position’s display order on the ballot and in result documents.
Required
Where enabled, the voter must make a valid choice unless abstention is allowed and selected.
Allow abstain
Adds an abstention choice for supported ballot questions or positions. The legal meaning of abstention should be defined in the election rules.
7. Candidate form
Ballot name
The candidate’s public name as it will appear on the ballot and reports.
Biography
A concise background statement.
Manifesto
A longer campaign or service statement where permitted.
Photograph
A clear JPEG, PNG or WebP image. The current validator permits a maximum file size of 5 MB, requires at least 400 × 400 pixels and rejects dimensions above 6000 × 6000 pixels. An approved candidate must have a photograph.
Ballot order
The candidate’s order within the position.
Status
Candidate states include pending, approved, rejected and withdrawn. Only approved candidates are included in the final candidate list and ballot.
Nominee reference
An optional external or internal reference. For candidates generated from approved self-nominations, the system records the nomination public identifier.
8. Committee appointment form
User
Any active authorised application user who satisfies the form’s account rules. The person does not have to be in the voter directory or the election register. Appointment and voting eligibility are separate decisions.
Role
Available roles include Commissioner/Chairperson, Deputy Commissioner, Secretary, ICT and Data Protection Commissioner, Gender and Inclusion Commissioner, Appeals Panel Chairperson, Appeals Panel Member, Committee Member, Returning Officer, Registration Officer, Polling or Verification Officer, Observer and Election Auditor.
The mandatory core consists of three distinct people: Commissioner/Chairperson, Secretary and ICT and Data Protection Commissioner. Other roles are optional.
Appointment reference
The official reference for the appointment.
Appointment starts and ends
The period of operational authority. After the appointment ends, the code may provide a seven-day read-only grace period for historical inspection. It does not permit new operational actions.
Appointment letter
A protected PDF required by the appointment validation. The file is stored outside public media, and its SHA-256 digest is recorded.
Active
An inactive or revoked appointment does not grant operational authority.
9. Voter identity form
Staff or membership number
The reusable identifier for the association member. A keyed hash is stored for lookup and duplicate control. Handle this field as personal data.
Full name
The voter’s official name.
Email and phone
Optional contact and verification channels. Accuracy should be confirmed before enabling related verification methods.
Institution, campus or branch, department or unit
Organisational attributes used for administration and, where applicable, register filtering or review.
Membership category and constituency
Classification fields used by the association’s rules. They do not by themselves make a person eligible for a specific election.
Active
An inactive voter identity cannot be treated as an active eligible voter.
10. Election eligibility form
Status
Typical values include eligible, ineligible and excluded. Only active voter identities with eligible election status may vote.
Eligibility reason
The basis for eligibility or ineligibility.
Exclusion reason
The formal explanation for exclusion, where applicable.
Verification notes
Administrative notes supporting the review. Do not enter ballot choices, secret credentials or unnecessary sensitive information.
11. Register-source form
Source
Creates the election register from the association directory, a previous election, an uploaded file or an empty register, depending on the available choices.
Previous election
Used only when copying a prior register. The copied records become a new election-specific register and must be reviewed and certified again.
12. Register certification
Certification reference
A Commission minute, resolution or other reference of at least five characters. Certification stores the register digest and the certifying user. Any later change invalidates the certified digest and requires a new review and certification.
13. Self-nomination form
Staff or membership number and personal voter PIN
Used to verify the nominee against the certified eligible register. The PIN is not saved on the nomination or ballot.
Position sought
Only configured single-seat or multiple-seat candidate positions for the election are offered.
Nomination statement
Required, between 20 and 3000 characters. It should state the nominee’s interest, experience and willingness to serve.
Candidate photograph
Required and subject to the candidate-photo validation rules.
Supporting document
Optional PDF or DOCX, maximum 5 MB. It is stored as protected nomination evidence.
14. Nomination review form
Status
Reviewers may place the submission under review, approve it, reject it or record withdrawal.
Candidate photograph
A reviewer may replace an unsuitable photograph. Approval is impossible without a valid photograph.
Review comment
Records the decision basis. Rejection and withdrawal require a reason of at least ten characters.
15. Public objection form
The form records the objection type, complainant details, subject candidate where applicable, statement and requested remedy according to the model and election context. Public submitters receive a reference for follow-up. Avoid including secret credentials or irrelevant sensitive information.
16. Officer complaint form
The complainant selects the appointed officer, complaint type, description, requested remedy, whether recusal is requested and optional supporting evidence. The form determines the competent review authority. Evidence is protected and restricted to authorised reviewers.
17. Result approval
An authorised approver records an approve or reject decision with an optional comment. The same committee membership cannot create duplicate approvals for the same snapshot. Publication occurs only after the required independent approvals and absence of a blocking rejection under the implemented service rules.
18. Result declaration upload
Declaration reference
The official reference for the signed declaration.
Declared at
The formal declaration date and time.
Declaration file
A validated PDF stored in protected media. It is distinct from the system-generated declaration and may be replaced only through the controlled workflow.
19. Destructive-action reasons
Revocation, cancellation, invalidation and certain complaint decisions require a reason. The reason becomes part of the audit and evidence trail. It should be factual, specific and free from unnecessary personal data.
20. Fields that must never contain ballot selections or credentials
Never place ballot choices, member PINs, one-time codes, passkey secrets or voting-ticket values in descriptions, review notes, complaint notes, audit metadata or uploaded spreadsheets. CivitasVote’s anonymity design depends not only on database separation but also on disciplined human use.