tracking_kits/docs/api-contracts.md

tracking_kits - Route and Integration Contracts

Date: 2026-03-13

Important Note

This project does not expose a conventional JSON REST API. Its primary contract surface is a set of Classic ASP controller routes that render HTML pages and process form submissions. In addition, it has file-based export/import interfaces used by batch automation.

Web Route Surface

Routing is initialized by ../App/app.config.asp, and requests are dispatched from controller ASP files under App/Controllers.

HomeController

• Index
  • Purpose: render the switchboard/home screen
• CreateKit
  • Purpose: list jurisdictions with pagination for kit creation
• Search
  • Purpose: search jurisdictions by JCode, Name, address fields, and IMB values
• Print
  • Purpose: render a sample/report PDF using Label_Report.rep

KitController

• Index
  • Purpose: paged list of kits
• Search
  • Purpose: search kits by ID, JobNumber, and JCode
• SwitchBoardIndex
  • Purpose: operational list for label-based kits
• SwitchBoardEdit
  • Purpose: edit/view a single kit switchboard entry
• SwitchBoardPurpleEnvelopsIndex
  • Purpose: list purple-envelope kits
• SwitchBoardPurpleEnvelopeEdit
  • Purpose: edit purple-envelope kit details, color options, and precinct color data
• SwitchBoardPurpleEnvelopeEditPost
  • Purpose: update purple-envelope form fields and status
• AssignKitColorPost
  • Purpose: assign a color to all labels/records in a kit
• AssignPrecinctColorsPost
  • Purpose: assign colors at the precinct level
• ExportTrackingLabels(id)
  • Purpose: generate and move a kit label PDF
• ExportSnailWorksTracking(id)
  • Purpose: generate SnailWorks CSV export data

Other Controllers

The repository structure implies standard CRUD routes for:

• JurisdictionController
• ContactsController
• InkjetRecordsController
• SettingsController
• CustomOfficeCopyJobController
• KitLabelsController

These are primarily view-rendering and form-post endpoints.

Form / POST Contracts

Observed POST patterns:

• Classic HTML forms
• anti-CSRF tokens managed by HTMLSecurity.SetAntiCSRFToken
• redirect-on-success flow with flash messaging
• model hydration via Automapper.AutoMap(Request.Form, model)

File-Based Integration Contracts

Tracking Label PDF Export

• Triggered from kit workflows
• Uses Data/Label_Report.rep
• Writes PDF output to app-local Data/ temporarily
• Moves final artifact into ExportDirectory\<Jurisdiction>\...

SnailWorks Export

• Generates CSV files per kit
• Includes a header section plus detail records
• Output path depends on configured ExportDirectory

Inkjet Export / Proof / Import Processing

• ImportService/TrackingDataImport.vbs performs status-driven processing
• Outputs CSV and PDF artifacts
• Reads and writes from configured directories and network shares
• Uses COM-based CSV/report/SFTP functionality

Security and Validation Notes

• CSRF checks are present for important form posts.
• Input validation exists unevenly; some validation calls are commented out in controllers.
• There is no API schema enforcement layer; the contract is defined by forms, SQL expectations, and downstream file formats.

Change Guidance

• Treat controller action names, form field names, status strings, and export file names as part of the operational contract.
• Before changing an export format, inspect both web controllers and import-service scripts.
• Before changing a status value, search for every status-dependent branch in both App/ and ImportService/.

---

Generated for brownfield analysis.