Defining Document Entities

[knelson-farmbeltnorth]

As implemented, there are 5 aggregate document entities that ostensibly collect other documents into a common grouping for some purpose. These inherit from the base Document class.

Work Order is a collection of Work Items and Status Updates. However, each WorkItem itself contains Status Updates. If the Status Updates on the Work Order are simply a redundant collection, they should be removed. If they are a different set of Status Updates, conceivably relating to the group of Work Items vs. individual WorkItems, we need to clearly define this and indeed validate there is a need for such a complexity.

WorkRecord is a collection of LoggedData entities, Summaries and Irrigation Records. In ADAPT to date, implementation of this concept has been limited, and it is my understanding that the WorkRecord vs. LoggedData terminology may have been an implementation tradeoff between competing opinions in the early days of ADAPT. We need to revisit this discussion and clarify intent. If there is indeed value in classifying a group of LoggedData entities as a common group, it may be more practical to place a property on the LoggedData for that purpose. Having redundant properties (e.g., field id on logged data and then a collection of field ids on WorkRecord in addition to a collection of LoggedDataIds) leads inevitably to data integrity issues. #38

Observations is a collection of ObsDatasets, each of which contains a collection of ObsCollections, each of which contains a collection of Obs entities. By definition, an Observations entity can contain only a single Grower, yet Grower Id also exists on each Obs and ObsCollection inviting the same data integrity concerns as in WorkRecord. #38

Plan and Recommendation are shallow entities having no distinction other than the name of the entity. #36

[knelson-farmbeltnorth]

Revisiting this issue, we have addressed some of the confusion above.

We've clarified the distinction between a Plan, a Recommendation and a WorkOrder (see #36). Although these concepts are not applicable to everyone, they have defined use cases. The only change I could see making would be making a single WorkItemCollection and setting the type as one of the three. Since that is a design preference, I'm inclined to default to the as-is, with three separate entities.

We've addressed the issues with #38, and I created #70 to address remaining concerns with the Documents hierarchy.

The only other open questions are how to define WorkRecord and Observations, and possibly whether Plan, Recommendation, WorkOrder, WorkRecord and Observations are the correct base types. Since the types correlate to this document, I don't think it makes sense to go back to the drawing board to attempt to redo all of that work.

The working definitions for the "actuals" document types are as follows:

WorkRecord: A collection of data documenting completed work in the field. A Work Record may contain Logged Data, Summaries and/or Irrigation Records.

LoggedData: Spatial data logged by a single configuration of equipment, scoped to an individual field over a specific period. OperationData: A collection of spatial records for a single operation within a Logged Data entity. In the case of single pass applications (e.g., seeding + application), each is a unique OperationData. DeviceElementUse: An instance of a Device Element Configuration mapped to a specific Operation Data. LoggedVariable: An individual type of measurement on a DeviceElementUse that will be populated at multiple points in the field. LoggedVariableValue: Key/Value pair associating a Logged Variable with its value.
SpatialRecord: A collection of Logged Variable Values logged at the same specific point in space and time.

Summary: Collected average and total records for a single field over a specific period.
Summary Values: A collection of contemporary Summary Values. Summary Value: A recorded value of a specific type, representing an average or total either calculated by a system or manually-entered by a user.

Irrigation & Observations definitions are t/b/d pending further discussions and will be handled in separate issues.

[knelson-farmbeltnorth]

Agreement in October 12, 2022 meeting with the constraint that a Work Record is necessarily scoped to a single activity within a single field. I've defined it as such:

A record of completed work, contemporaneous in nature and scoped to a single Field or Crop Zone. At least one Logged Data, Summary, or Irrigation Record is required. E.g.s., -The harvest of a single Crop Zone completed over three days by two combines. Each combine would record a LoggedData and/or Summary.. -The single-pass seeding/starter fertilizer/insecticide application of a corn Crop Zone by one row planter. The Work Record might contain one Logged Data itself containing three Operation Data objects for each type of application, and/or one Summary with three OperationSummaries.