> ## Documentation Index
> Fetch the complete documentation index at: https://withforerunner.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Objects
> Learn about Custom Objects in Forerunner and how to work with flexible geospatial features
# What are Custom Objects in Forerunner?
Custom Objects are user-defined geospatial features that can represent any type of geographic data your organization needs to track. Unlike Properties (which are always address-based points), Custom Objects support any geometry type—points, lines, polygons, and more.
Custom Objects enable Forerunner users to extend the platform beyond traditional property management to support infrastructure tracking, zone management, and any other geospatial use case.
## Why Custom Objects Matter
Custom Objects provide flexibility to:
* **Track infrastructure** like stormwater systems, utilities, roads, and critical facilities
* **Define zones and regions** such as community boundaries, flood zones, or planning areas
* **Import existing GIS data** from Shapefiles, GeoJSON, and other formats
* **Create custom schemas** with exactly the fields your organization needs
* **Visualize any geometry** including points, lines, areas, and multi-part features
* **Engage public users** through the [public website](/docs/public-website/viewing-details#custom-objects), where community members can view custom object details, submit records, and attach files
Custom Objects are a newer concept in Forerunner that significantly expands what you can track and manage beyond traditional properties. They enable cross-sector use cases from emergency management to infrastructure planning.
## Key Features
### Flexible Geometry Types
Custom Objects support all standard GIS geometry types:
* **Points**: Individual locations (fire hydrants, signs, trees)
* **Lines**: Linear features (roads, pipes, power lines)
* **Polygons**: Areas (communities, flood zones, land parcels)
* **Multi-part geometries**: Complex features with multiple components
### Dynamic Field Structure
Unlike Properties with fixed address fields, Custom Objects have:
* **Label**: The primary display name for each object
* **Additional Fields**: Flexible key-value data imported from your source files
* **Auto-detected schema**: Field types automatically determined from your data
* **Custom styling**: Colors, icons, line widths, and opacity per object type
### Bulk Import Workflow
Custom Objects are typically created through bulk import:
1. Prepare GeoJSON or Shapefile data with your features
2. Upload to designated import location
3. System processes and validates the data
4. Objects appear on map and in tables
5. Attachments (records, files, tasks) are preserved during re-imports
Custom objects can be [drawn directly on the map](/docs/objects/creating-objects#creating-a-custom-object-manually) from the web or mobile app, or imported in bulk from GeoJSON or Shapefile data. See [Creating objects](/docs/objects/creating-objects) for details.
## How Custom Objects Work
### Object Types
Each set of Custom Objects belongs to an **object type** (called a CustomMap in the codebase). For example:
* "Fire Hydrants" object type containing individual hydrant objects
* "Stormwater Systems" object type containing pipe and inlet objects
* "Community Boundaries" object type containing neighborhood polygons
Object types define:
* What fields all objects of that type will have
* How objects are styled on the map (colors, icons, line styles)
* Whether labels appear on the map
* Display order and legend settings
### Object Groups
Related object types can be organized into **object groups** for easier navigation and management. For example, you might create a "Stormwater Infrastructure" group containing:
* Stormwater inlets
* Stormwater pipes
* Outfall structures
* Drainage basins
Groups enable:
* Organized navigation in the sidebar
* Combined table views across multiple object types
* Logical grouping of related features
[Learn more about Object Groups](/docs/objects/object-groups)
### Object Information Panel
Click any custom object on the map or in a table to open the Object Information Panel (OIP):
View object details including:
* Object type and name (label)
* Coordinates (interior point for areas)
* All custom fields from your data
* Geometry information
See a complete history of:
* User actions and changes
* Comments and discussions
* Activity timestamps
Manage tasks associated with the object:
* Maintenance tasks
* Inspection schedules
* Work orders
Access records attached to the object:
* Inspection reports
* Maintenance logs
* Custom record types configured for this object type
Browse files uploaded to the object:
* Photos and documentation
* Technical drawings
* Inspection reports
## Importing Custom Objects
### Supported Data Formats
Forerunner accepts two primary formats for custom object imports:
**GeoJSON:**
* Standard web-friendly geospatial format
* JSON-based, human-readable
* Supports all geometry types
* Includes feature properties as fields
**Shapefiles:**
* Traditional GIS format
* Requires .shp, .shx, .dbf, and .prj files
* Converted to GeoJSON during import
* Supports coordinate system transformations
### Import Process
Ensure your GeoJSON or Shapefile includes:
* Valid geometry in WGS 84 (EPSG:4326) projection
* A `source_id` field for each feature (important for re-imports)
* All attribute fields you want to track
* Consistent field names and types
Work with your administrator to:
* Upload file to designated S3 bucket
* Trigger import command with appropriate map ID
* Monitor import progress
Forerunner automatically:
* Converts shapefiles to GeoJSON if needed
* Auto-detects schema from first 100 features
* Creates partition table for efficient storage
* Generates map tileset for visualization
* Performs atomic swap to new data
After import completion:
* Check objects appear on map
* Verify fields display correctly in tables
* Test filtering and search
* Confirm styling and labels
Always include a stable `source_id` field in your import data. This identifier allows Forerunner to match features during re-imports, preserving all attachments (records, files, tasks) even when you update your data.
### Re-Importing and Updates
When you re-import Custom Objects:
* **Matching by source\_id**: Objects with matching `source_id` values are updated (not recreated)
* **Attachments preserved**: Records, files, tasks, and comments remain linked
* **Schema must match**: New imports must have the same fields as existing data
* **Removed objects tracked**: Objects missing from new import are flagged if they have attachments
Re-importing without `source_id` fields will create new objects instead of updating existing ones, and any attachments on old objects will be lost. Always use stable identifiers in your source data.
## Map Visualization
### Styling Options
Custom Objects support rich styling configurations:
**For Points:**
* Icon selection from library
* Icon size and color
* Custom marker images
**For Lines:**
* Line color and opacity
* Line width
* Dash patterns
**For Polygons:**
* Fill color and opacity
* Border color and width
* Border opacity
**Labels:**
* Toggle labels on/off per object type
* Automatic label positioning
* Collision detection
### Layer Controls
Each custom object type appears as a separate map layer:
* Toggle layers on/off in map controls
* Control layer order (z-index)
* Visibility based on zoom level
* Legend showing all active layers
## Common Use Cases
Track stormwater systems, utilities, roads, bridges, and other physical assets
Define and monitor community boundaries, planning zones, or regulatory areas
Map critical facilities, evacuation routes, and emergency resources
Track natural features, conservation areas, or environmental observations
## Custom Object vs. Property
Understanding when to use each type:
| Feature | Properties | Custom Objects |
| ------------------- | ----------------------- | ------------------------------------- |
| **Geometry** | Points only | Any type (points, lines, polygons) |
| **Creation** | Individual UI entry | Draw on web or mobile, or bulk import |
| **Schema** | Fixed address fields | Flexible custom fields |
| **Address** | Required | Not applicable |
| **Parcel data** | Supported | Not applicable |
| **Elevation certs** | Special support | Not applicable |
| **Best for** | Buildings and addresses | Infrastructure and zones |
Use **Properties** when:
* You're tracking buildings or addresses
* You need elevation certificates
* You want manual entry through UI
* You need parcel data integration
Use **Custom Objects** when:
* You need line or polygon geometry
* You're importing existing GIS data
* You need flexible field structure
* You're tracking non-address features
## Limitations and Constraints
### Schema Constraints
* Additional fields must be flat key-value pairs (no nested objects or arrays)
* Field types limited to: string, number, boolean, null
* Field names must be valid JSON keys
* Schema changes require re-import of all data
### Import Constraints
* Large imports (>10,000 features) may take significant processing time
* Only one import per object type at a time
* Import is atomic (all features succeed or all fail)
* Maximum file size depends on system configuration
### Editing
* Objects created manually on web or mobile can have their label and geometry edited in the app
* Objects brought in through a GIS import are updated by re-importing the source data
* Field values are updated by re-importing
In-app editing covers the label and geometry of manually-created objects. Imported objects and field values are maintained through re-import, reflecting the bulk data management nature of large geospatial datasets. See [Editing a custom object](/docs/objects/creating-objects#editing-a-custom-object).
## Next Steps
Learn how to prepare and import geospatial data
Create groups to organize custom object types
Learn how to find and filter custom objects
Add records and files to custom objects