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.
Client.Functions.Run(id, parameters)functions_run Tool0 2 * * * · time zone · run missed
daily-report
OnRun(parameters) returns a responseall-shifts
A named set of Parameters, ex. shift: all. Read when each run starts, so edits apply to the next runCreate 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.
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
DefaultValueof each parameter that isn't passed, and refuses the run (status code 400, with the reason in the log) when aRequiredparameter is missing, or a value doesn't fit itsType(String,Integer,Number,Boolean,DateTime, orJson) orOptions. - A
Secretparameter 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's
functions_getTool, 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 (see Runs)
- On a schedule, with 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.
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, 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.
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.
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 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.
TrakHound.Functions.Api Package, and scheduling needs TrakHound.ScheduledTasks.