Services - scheduling and events Last updated: 22. Apr 2025

The service definition file in JSON format enables application developers to schedule tasks, handle system events, and manage error responses. Key features include automating recurring tasks (daily, weekly, monthly, yearly), event-driven programming for file or system changes, and robust error handling strategies.

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 a service definition file in JSON format. This file is designed for configuring various services, schedules, and error handling within a system. The file consists of three main sections: Schedules, Events, and Errors.

Example file - services.json

Your file must be placed in the #/Services.json path of your application (or publish template). The file has to me "schemaless" or otherwise it will be ignored.

/* 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 at specific week day and time
        "Weekly" : ["Name of day, HH:mm"],
        
        // Runs monthly at specific day and time
        "Monthly" : ["Day number, HH:mm"],
        
        // 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 execute
            "Path": "name of file.js",
            
            // Max executiong time before timeout, default is "00:01" - one minute
            "TimeOut": "HH:mm:ss"
        },
    }],
    "Events": [{
        // Type: delete modify create or * for all
        "Type": "*",

        // paths to listen to, wildcards supported
        "Paths": ["*"],

        "Task": {
            // Path to the JS file that is placed under "#/Services/..." folder, that will be execute
            "Path": "name of file.js",
            
            // Max executiong time before timeout, default is "00:01" - one minute
            "TimeOut": "HH:mm:ss"
        },
    }],
    "Errors": {
        // Emails to report errors to
        "ReportTo": "",
        "ReportToCc": "",
        "ReportToBcc": "",
        
        // For how long a service will pause before retrying
        "PauseInterval" : "HH:mm:ss",
        
        // How many times the service will continue running before stopping
        "MaxRetries": 10
    }
}

You can leave out any setting you don't need.

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[] ("Name of day, HH:mm")	The task runs weekly on a specified day and time.
Monthly	String[] ("Day number, HH:mm")	Sets the task to run monthly on a certain day and time.
Yearly	String[] ("MM-dd HH:mm")	Determines the task to run annually on a specific date and time.
Intervals	String[] ("HH:mm")	Specifies how often the service will be called. Pauses during service run.
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")	Maximum runtime for the task. Default is "00:01" (one minute).

Events (event services)

The "Event" section is intended to handle events occurring in the system.

Name	Type (format)	Description
Type	String	The type of event to monitor (e.g., create, modify, delete).
Paths	String[]	Paths to be monitored for changes.
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")	Maximum runtime for the event task.

Errors (error handling)

Name	Type (format)	Description
ReportTo	String	Email addresses for sending error reports.
PauseInterval	String ("HH:mm")	For how long to pause the service in case of failure.
MaxRetries	Integer	Maximum number of retry attempts before giving up.

Status messages (Console)

Status updates for your services will be output to your site console. You can also use console.log to output information and updates when your services are running.