Services - scheduling and events Last updated: 18. Oct 2026

The service definition file (#/Services.json) lets application developers schedule tasks and control how failing tasks are handled. Tasks can run daily, weekly, monthly, yearly or at fixed intervals, or when a file on the site changes.

Note that in order to run scheduled services and events you need to have a subscription with this feature supported / enabled.

This documentation describes the structure and usage of the service definition file. The file has three sections: Schedules, Events and Errors. Schedules need the subscription feature Scheduling, and Events need File system events. The two features are independent.

Example file - services.json

Your file must be placed at #/Services.json in your application (or app). It can be a plain .json file or a typed document (for example a Code File) — Docly reads the content either way.

/* Important note: Your subscription must have background services enabled to run services.json */
{
    "Schedules": [{
        "Name": "Name of your service",
        "Description": "Description of your service, used when sending notifications and such",

        // Runs every day at specific times
        "Daily" : ["HH:mm"],
        
        // Runs weekly: three-letter English day name, a space and the time - no comma
        "Weekly" : ["Mon 08:00"],
        
        // Runs monthly: two-digit day of month, a space and the time - no comma
        "Monthly" : ["05 08:00"],
        
        // Runs yearly at specific dates and time
        "Yearly": ["MM-dd HH:mm"],

        //"Intervals": ["HH:mm:ss"] // how often the service will be called, note that scheduling will be paused while service is running
        "Intervals": ["00:01:00"],


        "Task": {
            // Path to the JS file that is placed under "#/Services/..." folder, that will be executed
            "Path": "name of file.js",
            
            // Max execution time before timeout, default is "00:01:00" - one minute
            "TimeOut": "HH:mm:ss"
        },
    }],
    // Runs a script when a file on the site is created, changed or deleted (needs File system events)
    "Events": [{
        // Optional, but recommended: the name in the console and of the status file
        "Name": "Name of your event",
        "Description": "Description of your event",

        // Type: Created, Changed, Deleted (comma separated) or * for all
        "Type": "Created, Changed",

        // Glob patterns relative to the site root: * one folder, ** any depth, ? one character
        "Paths": ["images/**/*.jpg"],

        "Task": {
            // Path to the JS file that is placed under "#/Services/..." folder, that will be executed
            "Path": "name of file.js",
            
            // Max execution time before timeout, default is "00:01:00" - one minute
            "TimeOut": "HH:mm:ss"
        },
    }],
    "Errors": {
        // Emails to report errors to
        "ReportTo": "",
        "ReportToCc": "",
        "ReportToBcc": "",
        
        // For how long a service will pause before retrying, default "00:05:00"
        "PauseInterval" : "HH:mm:ss",
        
        // How many failures in a row before the service is suspended, default 3
        "MaxRetries": 3
    }
}

You can leave out any setting you don't need. Without an Errors section, a failing task is retried 3 times with 5 minutes between attempts and is then suspended, and the site owner is notified.

Schedules (scheduled services)

The "Schedules" section defines schedules for different tasks to be executed at specific times.

Name	Type (format)	Description
Name	String	A unique identifier for the schedule.
Description	String	A brief description of what the schedule does.
Daily	String[] ("HH:mm")	Specifies the task should run daily at a specified time.
Weekly	String[] ("ddd HH:mm")	Runs weekly. Use a three-letter English day name, a space and the time, for example "Mon 08:00". A comma makes the value invalid and the schedule never runs.
Monthly	String[] ("dd HH:mm")	Runs monthly. Use a two-digit day of month, a space and the time, for example "05 08:00". A comma makes the value invalid and the schedule never runs. A day the month does not have (29-31) runs on the last day of that month: 31 runs on 30 April and on 28 or 29 February.
Yearly	String[] ("MM-dd HH:mm")	Runs yearly on a date and time, for example 12-24 18:00. 02-29 runs on 28 February in years that are not leap years.
Intervals	String[] ("HH:mm:ss")	How often the service is called. Scheduling pauses while the service runs. The scheduler checks once a minute, so intervals shorter than a minute have no effect.
Task	Object	Defines the task to be executed. Consists of Path and TimeOut.
Path	String	Path to the task's script file, under #/Services/... folder.
TimeOut	String ("HH:mm:ss")	Maximum runtime for the task. Default is "00:01:00" (one minute).

How the next run is found: the scheduler checks once a minute and runs a task when the first matching time after its last run has passed. All times are the server's local time. A schedule that has never run counts from midnight today, or from when Services.json was last saved if that is later: a time that has already passed today runs once, but a time that passed before the file was saved waits for the next period. A time missed while the server was down runs once at the next check, and the schedule then continues as normal.

Events (file events)

The Events section runs a script in #/Services/ when a file on the site is created, changed or deleted. It needs the subscription feature File system events. The script runs in the background as the site owner, after the change has been saved. Changes are debounced: a path must be quiet for 2 seconds, never more than 10. Paths that are ready at the same time run in one call. Files the event script writes itself never trigger new events. Unzip, package install, transfer and sync between servers, cloning, and moving or renaming a folder do not trigger events.

The script is an anonymous function, function (service, ev) { … }. service.ChangeType, service.Path, service.OldPath, service.Guid and service.ChangedBy describe the last change in the run. service.Changes lists every change in the run, so read it rather than only service.Path. Paths are relative to the site root.

Status and errors work as for schedules. Each event has a status file, #/Logs/File event - .json, and the Services tab in the developer console shows the status of every event. A script error counts towards MaxRetries, and the event is then suspended until the status file is deleted or edited. PauseInterval does not apply to events: the next file change is the next attempt. See the KB entry "Run a service when a file changes" for the details.

Name	Type (format)	Description
Name	String	Optional. The name in the console and the key of the status file. Without it the name is the Type plus the first path. Two events with the same name: the second is invalid.
Description	String	Optional. Shown in the console and in the suspension mail.
Type	String	Created, Changed, Deleted, or several separated by commas, or * for all. Case does not matter. Created: a new file, an upload, a copy, a move or rename into the path, a restore. Changed: saved content (tags and sharing do not count). Deleted: deleted, or moved or renamed away. An unknown value disables only that event and is shown as Invalid in the console.
Paths	String[]	Glob patterns relative to the site root: * matches within one folder, zero or more folders, ? one character. Matching ignores case, and one matching pattern is enough. Empty Paths is invalid, so use "" for every file. does not match the system folder #/, so the pattern must itself start with #/ to see it. #/Services.json, #/Services/ and #/Logs/** never fire.
Task	Object	Defines the task for the event. Consists of Path and TimeOut.
Path	String	Path to the event's script file.
TimeOut	String ("HH:mm:ss")	Maximum runtime for the event task.

Errors (error handling)

Name	Type (format)	Description
ReportTo	String	Email addresses for sending error reports.
ReportToCc	String	Email addresses to CC on error reports.
ReportToBcc	String	Email addresses to BCC on error reports.
PauseInterval	String ("HH:mm:ss")	For how long to pause the service after a failure. Default is "00:05:00" (five minutes).
MaxRetries	Integer	How many failures in a row before the service is suspended. Default is 3. A value of 0 or less also gives 3.

Status messages (Console)

Status updates for your services are written to your site console. You can also use console.log to output information while your services run. The status of each scheduled task (LastRun, LastResult and ErrorCounter) is kept in #/Logs/Scheduled task - <Name>.json.