Scheduled Jobs

Part of: Tagnet Admin Console — control when background jobs run without editing cron expressions by hand

The Scheduled Jobs page in the Tagnet Admin Console controls when each background job runs: the hour of day and the time zone used to interpret the schedule. It does not control what the job does or how long it keeps data. Retention horizons (how many days of tag-read events, telemetry, scan events, and so on to retain before they are deleted) are configured separately on the Policies page in the Tagnet web UI. Think of it this way: Scheduled Jobs = when. Policies = how long.

Changes saved here take effect within approximately 60 seconds. The running Tagnet service picks up the new schedule automatically; no service restart is required.

When to use this page

Use Scheduled Jobs when you need to:

• Move a job to a quieter maintenance window. For example, if the default run time conflicts with a nightly backup or a high-traffic shift, shift the job to an off-peak hour.
• Align the job's schedule with your local time zone rather than UTC. The default schedule is expressed in UTC; if your team monitors job outcomes in local time, selecting your time zone makes the "next run" preview match what you expect.
• Confirm when a job is next scheduled to run without examining cron syntax.

If you want to trigger a job immediately rather than wait for its scheduled time, use the Run job menu on the Background Jobs page in the Tagnet web UI.

What you need

• The Tagnet Admin Console installed on the Windows server that hosts Tagnet.
• Local administrator rights on that Windows server. The page reads and writes appsettings.Production.json, which is protected by Windows ACLs.

How to change a job's schedule

1. Open the Tagnet Admin Console from the Start menu on the server.

2. In the left navigation, click Scheduled Jobs.

3. If you see the Restart as administrator button, click it. The console relaunches with UAC elevation and returns you to the Scheduled Jobs page.

4. Each job appears as a card with two controls:

   • Run at: a dropdown listing every hour from 00:00 to 23:00. Select the hour you want the job to run.
   • Time zone: a dropdown populated from the time zones available on this machine, with UTC at the top. Select the time zone the hour should be interpreted in.

5. As you make selections, the card updates a preview showing the resulting cron expression and the next scheduled run time in both your chosen time zone and UTC. Use this preview to confirm the job will run when you expect.

6. When each card shows the schedule you want, click Save. The page writes the new schedule to appsettings.Production.json and shows a confirmation message. The Tagnet service picks up the change within about a minute.

7. To abandon your changes without saving, click Discard.

Note: The Save and Discard buttons are only enabled when you have made at least one change. The hint text below the buttons tells you whether there are unsaved changes.

Override badges

Each job card shows a badge indicating whether the current schedule comes from the shipped default or from a saved override in appsettings.Production.json:

Badge	Meaning
Default	The job is running on the shipped schedule. No override is in the Production configuration file.
Override	A custom schedule is saved in appsettings.Production.json and is currently active.
Override (unsaved)	You have changed the inputs but have not clicked Save yet.

Resetting to the shipped default

If you want to remove your override and return a job to its default schedule, change the inputs back to the default values and click Save. The page detects that the selected values match the shipped default and removes the override keys from appsettings.Production.json automatically, rather than writing a redundant copy of the default. Alternatively, if a Clear override button is visible on the card, clicking it resets the inputs to the default values in one step, then click Save to commit.

Jobs available today

The framework supports multiple scheduled jobs. Currently one job is registered:

Job	Display name	What it does
Retention.All	Retention	Runs the retention engine across every active retention policy in a single pass. Deletes rows older than the configured horizon for tag reads, telemetry, scan events, workflow executions, and other retention categories. Runs nightly by default.

Retention horizons (how many days to keep each data type) are set on the Policies page in the Tagnet web UI; see Policies. The Scheduled Jobs page only controls when the retention pass runs, not what it keeps or discards.

Run history for each job (every past run, its outcome, row counts affected, and any error messages) is available on the Background Jobs page in the Tagnet web UI.

How hot-reload works

When you click Save, the Admin Console writes the new cron expression and time zone directly into appsettings.Production.json in the Tagnet data directory. The Tagnet service monitors this file for changes using IOptionsMonitor<SchedulingOptions> with reloadOnChange enabled. Within approximately 60 seconds the scheduler reads the updated file and uses the new schedule for all subsequent runs.

This is intentionally different from most App Settings changes, which require a service restart. Scheduling is designed to be hot-reloadable so you can adjust run times without disrupting active users or in-flight operations.

What this page does not cover

• Triggering a job immediately: use the Run job menu on the Background Jobs page.
• Configuring retention horizons (how many days of each data type to keep): use the Policies page in the Tagnet web UI.
• Viewing job run history and outcomes: use the Background Jobs page in the Tagnet web UI.
• Disabling all scheduled jobs: this is an emergency killswitch (Scheduling:DisableAllScheduledJobs) in appsettings.Production.json. It is not exposed in the Admin Console UI. Set it manually if you need to suspend all scheduling for incident response; manual triggers via Run job are not affected.

Troubleshooting

"Administrator rights are required"

The page shows a Restart as administrator button instead of the job list. Click it, and the Admin Console relaunches with elevated privileges via Windows UAC. The page requires administrator rights because appsettings.Production.json is protected by Windows ACLs and is only writable by members of the local Administrators group.

"Data directory does not exist"

The Admin Console could not find the Tagnet data directory. Verify that Tagnet is installed and has been through first-run setup. The Home page of the Admin Console shows the current server state. On Windows the default data directory is C:\ProgramData\Stratum Global\TagNet\.

"Could not read scheduled-job configuration"

The data directory exists but the configuration file could not be parsed. This can happen if appsettings.Production.json has been hand-edited and contains malformed JSON. Open the file in a text editor, verify its JSON structure is valid, and try again. The error message shown on the page includes details from the parser to help you locate the problem.

Save fails with "administrator rights are required"

The Admin Console was opened without elevation, or a per-file ACL change has restricted write access. Click Restart as administrator and try saving again.

Save fails with an unexpected error

The error message is shown in the result panel. Common causes: the data directory is on a network share and the share is temporarily unavailable, or the file is locked by another process. Verify you can browse the data directory in File Explorer and try again.

Related

• Tagnet Admin Console: all Admin Console pages and server configuration
• Policies: configure retention horizons
• Background Jobs: view job run history, outcomes, and active runs, and trigger jobs on demand via Run job