# TritonFlow

## Overview

The TritonFlow class provides the server-side implementation for Flow and Process Builder logging. It handles automatic transaction management, Flow context capture, and validation of logging parameters.

## Flow Logging Methods

### log

```apex
@InvocableMethod(Category='TritonLogging' 
                Label='Log' 
                Description='Creates a log for a flow or process builder')
public static List<FlowLogOutput> log(List<FlowLog> flowLogs)
```

Creates logs from Flow or Process Builder. This method will:

* Create logs with default INFO level if not specified
* Handle automatic transaction management (create new or resume existing)
* Capture Flow context (Interview GUID, Flow API Name)
* Process custom field mapping through JSON
* Validate category and log level enums
* Return stacktrace information for error handling

**Returns:**

* List containing stacktrace information for each log

## Field Mapping Reference

### Core Fields

| Builder Method | Flow Source       | Required | Default                                                                                      |
| -------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------- |
| `category()`   | flowLog.category  | No       | Flow [(see Categories)](https://triton.pharos.ai/pharos-triton/apex-logging-basics#category) |
| `type()`       | flowLog.type      | No       | - [(see Types)](https://triton.pharos.ai/pharos-triton/apex-logging-basics#type)             |
| `area()`       | flowLog.area      | Yes      | - [(see Areas)](https://triton.pharos.ai/pharos-triton/apex-logging-basics#area)             |
| `level()`      | flowLog.level     | No       | INFO [(see Levels)](https://triton.pharos.ai/pharos-triton/apex-logging-basics#level)        |
| `summary()`    | flowLog.summary   | Yes      | -                                                                                            |
| `details()`    | flowLog.details   | No       | -                                                                                            |
| `operation()`  | flowLog.operation | No       | -                                                                                            |

For complete builder method documentation, see [TritonBuilder Reference](https://github.com/Pharos-AI/triton-docs/blob/main/apex-methods-reference/tritonBuilder.md).

### Context Fields

> 🔍 **Flow Context**\
> The system automatically captures and sets critical Flow execution context:
>
> * Interview GUID for tracking specific Flow runs
> * Flow API Name for identifying the Flow definition
> * Transaction ID for cross-context correlation

```json
{
  "interviewGuid": "required - from flowLog.interviewGUID",
  "flowApiName": "optional - from flowLog.flowApiName",
  "transactionId": "auto-generated if not exists"
}
```

### Additional Fields

Custom fields can be passed through the `additionalFields` JSON string:

```json
{
  "customField1": "value1",
  "customField2": "value2"
}
```

## Automatic Behaviors

> ⚡ **Smart Defaults**\
> The system provides intelligent default behaviors to ensure robust logging:

1. **Transaction Management**
   * Creates new transaction if none exists
   * Maintains transaction context across Flow elements
2. **Issue Creation**
   * Automatically creates issues for ERROR level logs
   * Links related records for context
3. **Batch Processing**
   * Buffers logs for efficient processing
   * Flushes logs after batch completion

## Validation Rules

### Required Fields

* `area` - Functional area identifier
* `summary` - Log message summary
* `interviewGUID` - Flow interview identifier

### Enum Validation

The system validates and provides fallbacks for:

| Field     | Invalid Value Behavior        |
| --------- | ----------------------------- |
| Log Level | Defaults to INFO with warning |
| Category  | Defaults to Flow with warning |

### Error Handling

📝 **Validation Messages**\
When validation issues occur, the system:

1. Applies appropriate defaults
2. Appends warning messages to the details field
3. Continues processing without interruption

## Related Classes

The TritonFlow class works with:

* [FlowLog](https://github.com/Pharos-AI/triton-docs/blob/main/apex-methods-reference/tritonFlow/flowLog.md) - Main wrapper for Flow log data
* [TritonBuilder](https://github.com/Pharos-AI/triton-docs/blob/main/apex-methods-reference/tritonBuilder.md) - Core log building functionality
* [TritonTypes](https://triton.pharos.ai/pharos-triton/methods-reference/apex-methods-reference/tritontypes) - Enums and constants

### Transaction Management

The system provides two modes of transaction handling:

1. **Auto-Create**: If no transaction exists and no ID is provided, creates new
2. **Resume**: If transaction ID is provided, resumes existing transaction

This enables correlation of logs across different Flow elements and contexts.

### Stacktrace Handling

This functionality is facilitated by the X-Ray machine only. If logging manually, disregard these values.

1. **Current Trace**: Captured in `stacktrace` field
2. **Full Trace**: Combines previous traces with current in `fullStacktrace`
3. **Automatic Chaining**: Each FlowLogOutput contains the combined trace

This is used by the X-Ray machine for tracking error propagation through multiple Flow elements.