# Plans

Plans are higher-level records that organize Assets and Logs around a
particular goal. Modules can provide Plan types, along with additional UI and
logic for Assets and Logs that are managed by them.

## Type

Each Plan must have a type. All Plan types have a common set of attributes and
relationships. Specific Plan types may also add additional attributes and
relationships (collectively referred to as "fields"). Plan types are defined by
modules, and are only available if their module is enabled.

*farmOS core does not currently provide any Plan types.*

## ID

Each Plan will be assigned two unique IDs in the database: a universally unique
identifier (UUID), and an internal numeric ID.

The UUID will be unique **across** farmOS databases. The internal ID will only
be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
to ensure that IDs pulled from multiple farmOS databases do not conflict.
Internally, farmOS modules use the internal IDs to perform CRUD operations.

## Attributes

Plans have a number of attributes that serve to describe their meta information.
All Plans have the same standard set of attributes. Modules can add additional
attributes.

### Standard attributes

Attributes that are common to all Plan types include:

- Name
- Status
- Flags
- Notes
- Data
- Archived

#### Name

Plans must have a name that describes them. The name is used in lists of Plans
to easily identify them at quick glance.

#### Status

Plans can be given a status to indicate where they are in their process. A
default set of workflow states is provided by farmOS core, but modules that
provide Plan types may replace this with their own set of states. The default
workflow states include: "planning", "active", "done", and "abandoned".

#### Flags

Flags can be added to Plans to help with sorting and filtering. farmOS
provides a set of default flags, including "Priority", "Needs review", and
"Monitor". Modules can provide additional flags, such as "Organic".

#### Notes

Notes can be added to a Plan to describe it in more detail. This is a freeform
text field that allows a limited set of HTML tags, including links, lists,
blockquotes, emphasis, etc.

#### Data

Plans have a hidden "data" field on them that is only accessible via the API.
This provides a freeform plain text field that can be used to store additional
data in any format (eg: JSON, YAML, XML). One use case for this field is to
store remote system IDs that correspond to the Plan. So if the Plan is
created or managed by software outside of farmOS, it can be identified easily.
It can also be used to store additional structured metadata that does not fit
into the standard Plan attributes.

#### Archived

Plans can be marked as "archived" to indicate that they are no longer being
actively managed. Archived Plans will be hidden from most lists in farmOS unless
they are explicitly requested.

## Relationships

Plans can reference other record types (like Assets and Logs) that are "part of
the Plan". These relationships can be simple (referencing the Asset/Log ID), or
a Plan-type providing module can define more complex relationships by including
other metadata alongside it.

For example, a Crop Plan might reference a set of Plant Assets that represent
the crops being grown in a particular season. Apart from just referencing the
Plant Asset IDs, a Crop Plan may also reference specific Seeding and/or
Transplanting Log IDs alongside those Plantings. It may also include attributes
that are specific to the particular planning process that is being modelled. In
addition to the Asset and Log IDs, perhaps a Crop Plan wants to store pieces of
information like "days to harvest" or "harvest window" for each Plant Asset.
These pieces of information do not belong on the Asset level itself, because
they are specific to the Plan&ast;. Therefore, they should be thought of as
metadata of the relationship itself.

Another example might be an Input Plan, that allows users to enter "Target" and
"Actual" values for the amounts of a material that was applied. This Plan could
create relationships to the Input Logs that it manages. The "Actual" quantity
of material applied would be stored on the Input Log itself, but the "Target"
is stored in the relationship between the Plan and the Log.

&ast; It is worth noting that some of this data may *also* be stored generally
on Terms, and copied to the Plan when it is instantiated. For example: imagine
a Crop/variety Term that has a "days to harvest" attribute on it, allowing you
to define this as a system-wide default that is then copied into your Crop Plan
when you create a new Plant Asset that references the Crop/variety Term. This
allows the value to be overridden on the Plan+Asset level, in case conditions
require it to.

### Standard relationships

All Plans have the same standard set of relationships. Modules can add
additional relationships.

Relationships that are common to all Plan types include:

- Owners
- Files
- Images

#### Owners

Plans can be assigned to one or more Users in farmOS.

#### Images

Images can be attached to Plans. This provides a place to store photos that can
be displayed alongside the Plan in farmOS. If the photos pertain to specific
Assets or Logs within the Plan, it may be better to attach them to those
records instead of the Plan.

#### Files

Files can be attached to Plans. This provides a place to put documents such as
Shapefiles, PDFs, CSVs, or other files associated with the Plan. If the files
pertain to specific Assets or Logs within the Plan, it may be better to attach
them to those records instead of the Plan.

### Additional relationships

Plans *may* contain additional relationships:

- Assets
- Logs

However, the module that is providing the Plan type may decide to replace these
with more advanced Asset/Log relationships if necessary. So the exact
relationships may vary by Plan type.

#### Assets

Plans can reference Assets that are part of the Plan.

#### Logs

Plans can reference Logs that are part of the Plan.
