TrakHound Docs TrakHound Framework Functions & Scheduling

Functions & Scheduling

Run units of code on demand, with Jobs, or on a CRON schedule.
Framework Docs Menu

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.

Run by
Run tabParameters typed in, or loaded from a Job
Another moduleClient.Functions.Run(id, parameters)
AI assistantThe MCP Server's functions_run Tool
Scheduled Task 0 2 * * * · time zone · run missed
Job: all-shifts
Function daily-report OnRun(parameters) returns a response
Job all-shifts A named set of Parameters, ex. shift: all. Read when each run starts, so edits apply to the next run
Run History Each run's status, output, and log, plus metrics on the Summary page
The Scheduled Tasks Worker runs Tasks on time; the Schedule Board shows what's running, waiting, and upcoming.

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.

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'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 (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.
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.

SettingDescription
idID of the task.
enabledWhether the task runs. Paused tasks are not enabled.
descriptionDescription of the task.
functionIdThe Function to run.
jobIdThe Job whose Parameters the Function is run with. No Parameters when empty.
scheduleA CRON expression. Use five fields (minute, hour, day of month, month, day of week) or six fields to include seconds.
timeZoneThe time zone the schedule is in (IANA or Windows ID). The server's local time zone when empty.
runMissedRun 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.