Working with Ag Operations 🚜
Overview
The Ag Operations domain provides a comprehensive system for managing agricultural tasks and field operations throughout the farming lifecycle. This domain enables organizations to plan, track, and record agricultural activities across properties, fields, and crop zones, supporting both planned operations (work orders) and completed operations (work records).
Cardinality summary
- Ag Operation ➜ 1 Organization (org_id)
- Ag Operation ➜ 0..1 Work Order (planned operation)
- Ag Operation ➜ 0..* Work Records (completed operations)
- Ag Operation ➜ 0..* Properties (farm properties)
- Ag Operation ➜ 0..* Seasons (growing seasons)
- Ag Operation ➜ 0..* Linked Documents (related plans, groups, schemas)
Ag Operation
├── Organization (1)
├── Properties 0..*
├── Seasons 0..*
├── Work Order 0..1
│ └── Resources (assignees, products, equipments, crop zones, etc.) 0..*
├── Work Records 0..*
│ └── Resources (assignees, products, equipments, crop zones, etc.) 0..*
└── Linked Documents 0..*
Key Concepts
| Concept | Description |
|---|---|
| Ag Operation | Agricultural task entity representing a planned or completed field operation |
| Operation Type | Classification of agricultural activity (spraying, planting, harvesting, scouting, etc.) |
| Operation Status | Lifecycle state: PLANNED, IN_PROGRESS, COMPLETED, or ARCHIVED |
| Work Order | Planned operation with intended dates, resources, and locations |
| Work Record | Completed operation record with actual dates, resources used, and outcomes |
| Resources | Materials, products, equipment, and machinery used in operations |
| Linked Document | Reference to related entities (smart plans, operation groups, schemas) |
| Source | System or application that created the operation |
Operation Types
The platform supports the following operation types, each with specific attributes and requirements:
| Operation Type | Description | Key Features |
|---|---|---|
| IRRIGATION | Water application to crops | Water volume, irrigation method, duration |
| LAND_PREPARATION | Soil preparation before planting | Tillage type, equipment used, soil conditions |
| PLANTING | Seed/seedling planting operations | Seeds, planting method, population, depth |
| SAMPLING | Collection of crop/soil samples | Sample type, quantity, analysis purpose |
| SCOUTING | Field inspection and monitoring | Pest/disease observations, crop stage, severity |
| TRAPS_SCOUTING | Monitoring using traps | Trap type, pest counts, locations |
| SPRAYING | Application of crop protection products | Products, application rate, spray type (ground/aerial) |
| HARVESTING | Crop harvesting operations | Yield, harvested area, moisture content |
| MAINTENANCE | Field/equipment maintenance | Maintenance type, equipment serviced |
| CP_TREATMENT | Crop protection treatment | Treatment products, application method |
| TRANSPORTATION | Material/product transportation | Origin, destination, weight, distance |
| SOIL_TEST | Soil analysis operations | Test type, sample locations, analysis parameters |
| DETASSELING | Removal of tassels (corn) | Gender type, rows detasseled |
| FLOWERING | Flowering stage monitoring | Flowering stage, observations |
| ROGUING | Removal of undesired plants | Roguing method, gender, plants removed |
Operation Status Lifecycle
Ag Operations follow a defined status lifecycle:
PLANNED → IN_PROGRESS → COMPLETED
↓ ↓
←------- ARCHIVED -------←
- PLANNED: Work order created, operation scheduled
- IN_PROGRESS: Operation started, work in progress
- COMPLETED: Operation finished, work records recorded
- ARCHIVED: Operation archived for historical purposes
API Documentation
For complete API reference including request/response schemas, authentication, and interactive testing, visit:
📚 Ag Operations API Documentation - Interactive API documentation with request/response examples
Available Endpoints
Basic Operations
| Method | Endpoint | Description |
|---|---|---|
| POST | /v3/operations/ag/ | Create a new ag operation |
| GET | /v3/operations/ag/{id} | Get ag operation by ID |
| PUT | /v3/operations/ag/{id} | Update ag operation |
| DELETE | /v3/operations/ag/{id} | Soft delete ag operation |
Batch Operations
| Method | Endpoint | Description |
|---|---|---|
| POST | /v3/operations/ag/batch-read | Get multiple ag operations by IDs |
| POST | /v3/operations/ag/batch-create | Create multiple ag operations |
| POST | /v3/operations/ag/batch-delete | Delete multiple ag operations |
| PUT | /v3/operations/ag/{id}/records | Add work records to existing operation |
| DELETE | /v3/operations/ag/{id}/record/{work_record_id} | Delete work record from ag operation |
Search & Query
| Method | Endpoint | Description |
|---|---|---|
| POST | /v3/operations/ag/filtered | Advanced search ag operations with filters |
| POST | /v3/operations/ag/latest | Get latest agrop operations filtered by specified criteria |
Business Rules
Work Order and Work Records Requirements
- An ag operation must have at least a work order OR one work record
- Operations cannot exist with both work order and work records empty
- Work records must share the same operation type as the parent ag operation
Status Validation
- When adding work records to an operation, status must be IN_PROGRESS or COMPLETED
- Status transitions must follow the lifecycle: PLANNED → IN_PROGRESS → COMPLETED → ARCHIVED
Operation Type Constraints
- Operation type is immutable after creation
- Organization ID (org_id) is immutable after creation
- Each operation type has specific required and optional fields
Error Codes
| Code | Message | HTTP Status | When Triggered |
|---|---|---|---|
| EAGOP002 | An Agro Operation need to have at least a WorkOrder or one WorkRecord! | 400 BAD_REQUEST | Creating/updating operation without work order or work records |
| EAGOP003 | Invalid operation type | 400 BAD_REQUEST | Unsupported or malformed operation type provided |
| EAGOP004 | Agro Operation status should be IN_PROGRESS or COMPLETED | 400 BAD_REQUEST | Adding work records to operation with invalid status |
| EAGOP005 | Agro Operation ({id}) already exists on the database! | 400 BAD_REQUEST | Attempting to create operation with duplicate ID |
| EAGOP006 | Work Records must share the same type as the Agro Operation! | 400 BAD_REQUEST | Work record operation type doesn't match parent operation |
| EAGOP007 | Agro Operation(s) ({ids}) was/were not found! | 404 NOT_FOUND | Requested operation ID(s) not found during GET, UPDATE, or DELETE |
Typical Workflows
Planning and Execution Workflow
- Create Planned Operation - Create ag operation with work order containing scheduled dates, crop zones, and planned resources
- Start Execution - Update status to IN_PROGRESS when field work begins
- Add Work Records - Record actual work performed with start/end times, actual resources used, and outcomes
- Complete Operation - Update status to COMPLETED when all work is finished
- Review and Archive - Optionally archive completed operations for historical reference
Search and Filtering Workflow
- Define Search Criteria - Specify filters (date range, operation type, status, properties, etc.)
- Execute Search - Use search or find endpoint with pagination parameters
- Process Results - Handle paginated results, iterate through pages as needed
Next Steps
- Use the Products catalog to register products that will be associated with ag operations (fertilizers, pesticides, and other agricultural inputs used in work orders and work records)