# Functions & Scheduling

> Run units of code on demand, with Jobs, or on a CRON schedule.

URL: https://www.trakhound.com/docs/trakhound-framework/functions

A Function is a unit of code that runs on demand and returns a result. Functions are typically used to process or import data, and can be run manually, from other modules, or on a schedule with Scheduled Tasks.

Diagram: A Function can be run from the admin UI, from another module, from an AI assistant through the MCP Server, or by a Scheduled Task. A Scheduled Task has a CRON schedule and time zone and runs the Function with a Job's Parameters. Each run is recorded with its status, output, and log.

## Create a Function

```
dotnet new trakhound.function
```

```
using TrakHound;
using TrakHound.Functions;

[FunctionParameter("machine", Description = "The machine to process", Required = true)]
public class Function : TrakHoundFunction
{
    public Function(ITrakHoundFunctionConfiguration configuration) : base(configuration) { }

    protected override async Task<TrakHoundFunctionResponse> OnRun(IReadOnlyDictionary<string, string> parameters, CancellationToken cancellationToken)
    {
        parameters.TryGetValue("machine", out var machine);

        Log(TrakHoundLogLevel.Information, $"Processing {machine}..");

        return Ok($"{machine} processed");
    }
}
```

`OnRun` receives the input parameters and a cancellation token, and returns a `TrakHoundFunctionResponse`. The same helpers as APIs are available: `Ok`, `Created`, `Accepted`, `BadRequest`, `NotAuthorized`, `NotFound`, `InternalError`, and `File`. The Instance creates the Function with its configuration, then sets `Client`, `Volume`, and `Variables`. The older `(configuration, client, volume)` constructor still loads, but is only kept for existing Packages.

The template's `Program.cs` runs the Function once on your computer and prints the response. Its input parameters are `input` in `trakhound.debug.json`, or JSON in the first argument (ex. `dotnet run -- "{\"machine\":\"M001\"}"`). See [Debugging & Testing](https://www.trakhound.com/docs/trakhound-framework/debugging).

## Input Parameters

Describe each input parameter with a `[FunctionParameter]` attribute on the class:

```
[FunctionParameter("days", Description = "How many days of Runs to keep", Type = TrakHoundFunctionParameterType.Integer, DefaultValue = "30")]
[FunctionParameter("table", Description = "The table to clean up", Required = true, Options = new[] { "function_run", "function_log" })]
[FunctionParameter("apiKey", Description = "The key for the remote service", Secret = true)]
public class Function : TrakHoundFunction
```

- The admin UI shows a field for each one on the **Run** tab and in the Job editor, with its description, default, and a list of the `Options`.
- When a run starts, the Instance adds the `DefaultValue` of each parameter that isn't passed, and refuses the run (status code 400, with the reason in the log) when a `Required` parameter is missing, or a value doesn't fit its `Type` (`String`, `Integer`, `Number`, `Boolean`, `DateTime`, or `Json`) or `Options`.
- A `Secret` parameter is masked when it's entered and isn't saved with the run's input.
- Values are still strings in `parameters`, and a Function can be passed parameters it doesn't describe.
- The parameters are listed in the Function's information and by the [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server)'s `functions_get` Tool, so AI assistants know what to pass.

## Running Functions

Each Function configuration has a `functionId` that is used to run it:

- From the Function's **Run** tab in the admin UI **Explorer**, with Parameters entered directly or loaded from a [Job](https://www.trakhound.com/docs/trakhound-framework/functions#jobs) (see [Runs](https://www.trakhound.com/docs/trakhound-framework/functions#run-page))
- On a schedule, with [Scheduled Tasks](https://www.trakhound.com/docs/trakhound-framework/functions#scheduled-tasks)
- From another module using the client:

```
var parameters = new Dictionary<string, string> { { "machine", "M001" } };

var response = await Client.Functions.Run("process-machine", parameters);
```

The client can also follow a run with `SubscribeRunStatus(runId)` and `SubscribeRunLog(runId)`. AI assistants can list and run Functions through the [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server).

## Runs

The **Run** tab has **Run** at the top, beside the status, duration, start time, CPU time, and message of the latest run. It becomes **Cancel** while a run is active.

- The left side shows the run's **Logs** (filter by level; times are since the run started) and its **Output** when it succeeds.
- The right side holds what a run uses: a **Job**, the input parameters (a field for each [described parameter](https://www.trakhound.com/docs/trakhound-framework/functions#parameters), with a missing required parameter reported before the run starts), **Save as Job**, and the last 5 runs from the page (**Load** puts a run's Job and input back).
- **View Run** opens the recorded run: its status, duration, CPU time, what started it (Manual, API, or a Scheduled Task), its Job, the Package version that ran, and its **Logs**, **Input**, and **Output**. **Run Again** opens the Run tab with the same Job and input.

> Input parameters are saved in the database with each run, like a Job's, so don't pass secrets as parameters unless they're described as `Secret`. Without the `TrakHound.Functions.Api` Package, the Function is run directly and the run isn't recorded.

## Jobs

A Job is a named set of Parameters for a Function, such as one Job per machine or per report. Add, edit, and delete Jobs on the Function's **Jobs** tab.

- Each Job has an ID made from its Name (ex. `line-3-report`) that is the same on every Instance, so Scheduled Tasks copied to another Instance still find their Job.
- A Scheduled Task reads its Job's Parameters when each run starts, so editing a Job changes the next run.
- A Job used by a Scheduled Task can't be deleted. The Jobs tab shows the Scheduled Tasks that run each Job.

> A Scheduled Task without a Job runs the Function with no Parameters, so give your Function defaults for missing parameters.

## Scheduled Tasks

The `TrakHound.ScheduledTasks.Worker` Package runs Functions on a CRON schedule, and `TrakHound.ScheduledTasks.Api` manages the tasks. Add and edit Scheduled Tasks on a Function's **Schedule** tab, which shows each Task's Last Run, Next Run, Runs (24h), Success, and Missed runs, or on the Schedule Board.

| Setting | Description |
| --- | --- |
| `id` | ID of the task. |
| `enabled` | Whether the task runs. Paused tasks are not enabled. |
| `description` | Description of the task. |
| `functionId` | The Function to run. |
| `jobId` | The [Job](https://www.trakhound.com/docs/trakhound-framework/functions#jobs) whose Parameters the Function is run with. No Parameters when empty. |
| `schedule` | A CRON expression. Use five fields (minute, hour, day of month, month, day of week) or six fields to include seconds. |
| `timeZone` | The time zone the schedule is in (IANA or Windows ID). The server's local time zone when empty. |
| `runMissed` | Run once when the Scheduled Tasks Worker starts if an occurrence was missed while it was stopped. |

```
{
  "id": "nightly-report",
  "enabled": true,
  "description": "Create the daily production report",
  "functionId": "daily-report",
  "jobId": "all-shifts",
  "schedule": "0 2 * * *",
  "timeZone": "America/New_York",
  "runMissed": true
}
```

> `0 2 * * *` runs every day at 2:00 AM. With six fields, the first is seconds (ex. `*/30 * * * * *` runs every 30 seconds).

## Schedule Board

**Explorer > Functions > Schedule Board** schedules Functions by drag and drop. It has a column per schedule:

- Drag a Function, or one of its Jobs, from the palette onto a column to schedule it (**Add Column** for a new schedule), and drag a card to another column to move it.
- Pause, resume, or delete each card, and **Undo** the last change.
- The top of the Board shows the Scheduled Tasks Worker's status: whether it is running, its busy Run Slots and overlap policy, what is **Running Now**, waiting, and **Upcoming**, and **Recent Events**.
- A card warns when its runs take longer than its schedule interval, so occurrences are skipped.
- The palette and cards show each Function's full ID, and the palette's filter box finds Functions by ID, Job name, or Package.

## Summary

**Explorer > Functions > Summary** shows run metrics for every Function (Runs, Success Rate, Avg Duration, Errors, Missed Runs, and Next Run) and for each of its Scheduled Tasks, with a run timeline.

## Export and Import

**Export** and **Import** (on the Schedule Board, and on a Function's Schedule tab for that Function) copy Jobs and Scheduled Tasks between Instances as a `.json` file, which can also be written by hand. Export saves the Tasks with the Jobs they use.

Import checks the file first without writing anything (a dry run), listing what would be added, replaced, or kept, and any Task whose Job is missing. Choose what happens when a Job or Task already exists: **Don't import (show the differences)**, **Keep the existing one**, or **Replace it**.

> The Summary, Jobs, Schedule, and Schedule Board need the `TrakHound.Functions.Api` Package, and scheduling needs `TrakHound.ScheduledTasks`.
