> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 1.3: Events and Datapoints

> Define event types and their datapoints, work with required and optional fields, and attach evidence to events.

<Panel>
  <Card title="Accounting Academy" className="accounting-academy-card">
    <div className="accounting-academy-content">
      <Steps className="my-0">
        <Step title="MODULE 1: Fundamentals" icon="bookmark" iconType="solid" stepNumber={1} titleSize="p">
          * [1.1: Core Concepts & the Data Lifecycle](/accounting-academy/module-1/1-1-core-concepts-data-lifecycle)
          * [1.2: Translating Methodologies to Mangrove](/accounting-academy/module-1/1-2-translating-methodologies-to-mangrove)
          * [1.3: Events and Datapoints](/accounting-academy/module-1/1-3-events-and-datapoints)
          * [Exercise: Design and Build](/accounting-academy/module-1/1-exercise-design-and-build)
        </Step>

        <Step title="MODULE 2: Calculations" icon="bookmark" iconType="solid" stepNumber={2} titleSize="p">
          * [2.1: Calculation Architecture](/accounting-academy/module-2/2-1-calculation-architecture)
          * [2.2: Expanding Your Data Model](/accounting-academy/module-2/2-2-expanding-your-data-model)
          * [Exercise: Multi-Step Calculations](/accounting-academy/module-2/2-exercise-multi-step-calculations)
        </Step>

        <Step title="MODULE 3: Batch Partitioning & LCA" icon="bookmark" iconType="solid" stepNumber={3} titleSize="p">
          * [3.1: What Is a Batch?](/accounting-academy/module-3/3-1-what-is-a-batch)
          * [3.2: Batch Partitioning Strategies](/accounting-academy/module-3/3-2-batch-partitioning)
          * [3.3: Life Cycle Assessment & Emissions](/accounting-academy/module-3/3-3-lca-and-emissions)
          * [3.4: Allocating Emissions to Batches](/accounting-academy/module-3/3-4-allocating-emissions-to-batches)
          * [Exercise: Batch Partitioning & LCA](/accounting-academy/module-3/3-exercise-batch-partitioning-and-lca)
        </Step>

        <Step title="MODULE 4: Mass Balance with Ledgers" icon="bookmark" iconType="solid" stepNumber={4} titleSize="p">
          * [4.1: Introduction to Mass Balance](/accounting-academy/module-4/4-1-intro-to-mass-balance)
          * [4.2: Designing the Ledger Structure](/accounting-academy/module-4/4-2-designing-the-ledger-structure)
          * [4.3: Multiple Batch Types for Different Stages](/accounting-academy/module-4/4-3-multiple-batch-types)
          * [Exercise: Design & Build Mass Balance](/accounting-academy/module-4/4-exercise-design-and-build-mass-balance)
        </Step>

        <Step title="MODULE 5: Integration Testing" icon="bookmark" iconType="solid" stepNumber={5} titleSize="p">
          * [5.1: The Complete Model Assembly](/accounting-academy/module-5/5-1-the-complete-model-assembly)
          * [5.2: Testing Patterns](/accounting-academy/module-5/5-2-testing-patterns)
          * [5.3: Common Integration Pitfalls](/accounting-academy/module-5/5-3-common-integration-pitfalls)
          * [Exercise: Integration Testing](/accounting-academy/module-5/5-exercise-integration-testing)
        </Step>

        <Step title="MODULE 6: Advanced Patterns & Production" icon="bookmark" iconType="solid" stepNumber={6} titleSize="p">
          * [6.1: Model Design Best Practices](/accounting-academy/module-6/6-1-model-design-best-practices)
          * [6.2: Advanced Techniques](/accounting-academy/module-6/6-2-advanced-techniques)
          * [6.3: Production Readiness](/accounting-academy/module-6/6-3-production-readiness)
          * [Exercise: Production Deployment](/accounting-academy/module-6/6-exercise-production-deployment)
        </Step>
      </Steps>
    </div>
  </Card>
</Panel>

<Check>
  **What you'll learn in this lesson:**

  * Configure event types with appropriate datapoints
  * Distinguish required vs. optional fields when creating events
  * Create events manually and via bulk import
  * Attach evidence to events for audit traceability
</Check>

Events and datapoints are how operational activity enters Mangrove. Each **event** is a single occurrence of something that happened (e.g., a delivery, a meter reading). Each event holds one or more **datapoints** — the measured or recorded values that your <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">models</a>

use.

```mermaid theme={null}
flowchart TB
    ET["Event Type<br/>e.g. Biochar Delivery"] --> E1["Event Instance"]
    E1 --> DP1["Datapoint: Mass"]
    E1 --> DP2["Datapoint: Carbon %"]
    E1 --> DP3["Datapoint: Date"]
    E1 --> EV["Evidence:<br/>Delivery Ticket"]
    E1 --> TID["Tracking ID"]

    style ET fill:#42a5f5,stroke:#1976d2,stroke-width:2px,color:#000
    style E1 fill:#66bb6a,stroke:#388e3c,stroke-width:2px,color:#000
    style DP1 fill:#a5d6a7,stroke:#388e3c,stroke-width:1px,color:#000
    style DP2 fill:#a5d6a7,stroke:#388e3c,stroke-width:1px,color:#000
    style DP3 fill:#a5d6a7,stroke:#388e3c,stroke-width:1px,color:#000
    style EV fill:#ffcc80,stroke:#f57c00,stroke-width:1px,color:#000
    style TID fill:#bdbdbd,stroke:#757575,stroke-width:1px,color:#000
```

## Defining event types and their datapoints

Before you can collect data, you must configure the **event types** your project uses. An event type is a template — it defines which datapoints each instance of that event will have.

<Note>
  **Example:** A "Biochar Delivery" event type might require: delivery date, biochar mass, carbon content, and delivery ticket ID. Every event of that type will have the same structure.
</Note>

### Where to configure event types

Event types are configured in **Data Inputs > Input Settings** within each project. Only after an event type is configured can you create events — whether you <a href="/data-collection/add-data" target="_blank" rel="noopener noreferrer">add them directly</a>

or <a href="/data-collection/bulk-import" target="_blank" rel="noopener noreferrer">bulk import</a>

them.

### What an event type defines

An event type ties together:

* **A name/slug** — identifies the type (e.g., "Biochar Delivery", "CO2 Injection Measurement")
* **A set of datapoint types** — each with a slug and value type (number, string, date) so Mangrove knows how to store and validate values

In <a href="/production-accounting/data-inputs" target="_blank" rel="noopener noreferrer">data inputs</a>

, events are high-frequency inputs whose measurements change from batch to batch — unlike static inputs, which stay constant.

**Examples of event types and their datapoints:**

| Event Type       | Example Datapoints                                                     |
| ---------------- | ---------------------------------------------------------------------- |
| Biochar Delivery | Wet Mass Transported, Loaded Distance, Deadhead Distance, Vehicle Type |
| CO2 Injection    | Hourly Mass Injected, Flow Rate, Temperature, Density, Meter Status    |

### Linking event types to models

For event data to feed calculations, your <a href="/production-accounting/models" target="_blank" rel="noopener noreferrer">production models</a>

must reference the datapoints from these event types.

<Tip>
  When designing an event type, think ahead: which datapoints will feed into which model nodes? Defining event types in line with your model's expected inputs keeps the dataflow coherent.
</Tip>

## Required vs. optional fields

When you create an event, some fields are required and others are optional.

<Tabs>
  <Tab title="Adding events directly">
    For each event you <a href="/data-collection/add-data" target="_blank" rel="noopener noreferrer">add directly</a>

    in the Data Inputs section:

    | Field                | Required?  | Notes                                                 |
    | -------------------- | ---------- | ----------------------------------------------------- |
    | **Event type**       | Required   | Select a configured input type                        |
    | **Date range**       | Required   | Start and end date/time                               |
    | **Datapoint values** | Per config | Required/optional set per datapoint in the event type |
    | **Tracking ID**      | Optional   | External reference ID (e.g., invoice number)          |
    | **Locations**        | Optional   | Associate with one or more locations                  |
    | **Evidence**         | Optional   | Files or URLs supporting the event                    |
  </Tab>

  <Tab title="Bulk import">
    Bulk imports use <a href="/data-collection/bulk-import" target="_blank" rel="noopener noreferrer">transformations</a>

    that output event objects:

    **Required fields:**

    * `start_time`, `end_time` — format: `%Y-%m-%d %H:%M:%S%z`
    * `data_points` — array of `slug` and `value` pairs

    **Optional fields:**

    * `tracking_id`, `locations`, `feedstock`, `evidences`, `notes`

    <Tip>
      Including optional fields when you have the data improves linkage and auditability.
    </Tip>
  </Tab>
</Tabs>

## Creating events

You can create events two ways: one-by-one in the UI, or in bulk via a file upload.

### Creating events manually

To <a href="/data-collection/add-data" target="_blank" rel="noopener noreferrer">add events directly</a>

:

<Steps>
  <Step title="Select event type">
    Open the project's **Data Inputs** section and add a new event. Select the event type.
  </Step>

  <Step title="Set date range">
    Set the start and end date/time of the event.
  </Step>

  <Step title="Enter datapoint values">
    Fill in the values for each datapoint defined by the event type.
  </Step>

  <Step title="Add optional fields">
    Optionally set Tracking ID, locations, and attach evidence (files or URLs).
  </Step>
</Steps>

### Creating events via bulk import

To <a href="/data-collection/bulk-import" target="_blank" rel="noopener noreferrer">bulk import</a>

events:

<Steps>
  <Step title="Prepare your data">
    Use a CSV, XLS, or XLSX file. Populate required columns with correct date formats and units.
  </Step>

  <Step title="Upload the file">
    Upload to the corresponding **Data Source** for the project.
  </Step>

  <Step title="Review loaded events">
    Events appear in the Events feed and Analytics. Check **Data Inputs > Bulk Jobs** for status — failed imports show as `errored` with a message. You can **Reverse** or **Retry** as needed.
  </Step>
</Steps>

<Tip>
  Best practice: paste values only to avoid bringing in formulae or links from spreadsheets.
</Tip>

<Accordion icon="code" title="Advanced: Writing transformations for bulk import">
  Admin users can define **transformations** on each data source — Python code that turns each incoming file into a `results` array of event objects. Each object specifies `event_type`, `start_time`, `end_time`, `data_points` (array of `slug` and `value`), and optionally `tracking_id`, `locations`, `feedstock`, `evidences`, and `notes`.

  Transformations can also generate evidence from the file (e.g., attaching parsed content as JSON or CSV evidence).
</Accordion>

## Attaching evidence to events

<a href="/production-accounting/fundamentals" target="_blank" rel="noopener noreferrer">Evidence</a>

is documentation that supports the data in an event. Verifiers use it to validate reporting accuracy.

### Why attach evidence

Batches and reports tie back to source data and evidence. Attaching clear, relevant evidence streamlines verification and keeps a strong audit trail from credit to source.

### How to add evidence

* **When adding events directly** — click **Add Evidence** and attach files or URLs
* **After a bulk import** — open each event and use **Upload Evidence**
* **In a transformation** — include an `evidences` array with `name`, `type` (`json`, `geojson`, `text`, `csv`), and `content`

### Supported file types

| Category   | Supported formats                                       |
| ---------- | ------------------------------------------------------- |
| Documents  | PDF, Excel (.xls, .xlsx), Word (.doc, .docx), .txt, CSV |
| Images     | JPG/JPEG, PNG, GIF                                      |
| Videos     | MP4, MOV, AVI                                           |
| Archives   | ZIP                                                     |
| Geospatial | GeoJSON, Shapefiles                                     |
| Code       | JSON                                                    |

***

### Check your understanding

<Accordion icon="circle-question" title="Where do you configure event types in Mangrove?">
  In **Data Inputs > Input Settings** within the project. You must configure an event type before you can create events of that type.
</Accordion>

<Accordion icon="circle-question" title="What fields are required when creating an event?">
  **Event type**, **date range** (start and end), and **datapoint values** for the required datapoints defined by that event type. Tracking ID, locations, feedstock, and evidence are optional.
</Accordion>

***

You're now ready to design your first event type and build it in Mangrove in the [Module 1 Exercise](/accounting-academy/module-1/1-exercise-design-and-build).