19.3. Scheduled jobs

Scheduled jobs are used when you need to perform particular periodic or one-time actions according to a schedule.

Scheduled jobs are stored in the infobase. They are created based on the metadata defined in the configuration. Metadata define such scheduled job parameters as called method, name, key, applicability, predefinition flag, and so on. When you create a scheduled job, you can also specify its schedule (it can be set in the metadata), method parameter values, name of the user on whose behalf it will be executed, and so on.

You can create and manage scheduled jobs programmatically from any join if you have administrative rights.

The method called upon scheduled job execution is linked to the scheduled job. The scheduled job method can be any procedure or function of a non-global common module that can be called on the server. Any values that can be passed to the server can be scheduled job parameters. Such parameters must fully match the parameters of the procedure or function the job calls. If the scheduled job method is a function, its return value is ignored.

The scheduled job can have a key being any applied value. The key restricts the number of concurrent scheduled jobs related to a single metadata object. Only one scheduled job with a certain key value can be executed at a time. The key allows grouping scheduled jobs linked to the same metadata object by a certain applied flag to ensure that no more than one scheduled job is executed within one group.

While configuring, you can define predefined scheduled jobs. Predefined scheduled jobs do not differ from ordinary scheduled jobs, except for the fact that they cannot be explicitly created and deleted. If a job is marked as predefined in the scheduled job metadata, it will be created automatically in the infobase upon configuration update. If the predefined check box is cleared, the predefined scheduled job will be automatically deleted from the infobase upon configuration update. You can set initial property values of predefined scheduled jobs (for example, the schedule) their metadata. You can later change them during application runtime using corresponding 1C:Enterprise language methods. Changes in properties of predefined scheduled jobs already created in the metadata will have no effect on the actual parameters of these jobs in the infobase. Predefined scheduled jobs do not have parameters.

The scheduled job schedule defines the time it must be triggered. Use the schedule to set:

• Date and time of job execution start and end.
• Execution period.
• Weekdays and months of scheduled job execution, and so on. For details, see 1C:Enterprise language description).

Examples of schedules of scheduled jobs:

Schedule	Parameter values
Every hour, one day only	DaysRepeatPeriod = 0 RepeatPeriodInDay = 3600
Every day once a day	DaysRepeatPeriod = 1 RepeatPeriodInDay = 0
One day, one time	DaysRepeatPeriod = 0
Every other day, once a day	DaysRepeatPeriod = 2
Every hour 01.00 - 07.00 every day	DaysRepeatPeriod = 1 RepeatPeriodInDay = 3600 BeginTime = 01.00 EndTime = 07.00
Every Saturday and Sunday at 9.00	DaysRepeatPeriod = 1 WeekDays = 6, 7 BeginTime = 09.00
Every day one week, one week off	DaysRepeatPeriod = 1 WeeksPeriod = 2
At 01.00 once	BeginTime = 01.00
Last date of each month at 9.00	DaysRepeatPeriod = 1 DayInMonth = -1 BeginTime = 09.00
The fifth date of each month at 9.00	DaysRepeatPeriod = 1 DayInMonth = 5 BeginTime = 09.00
Second Wednesday of each month at 9.00	DaysRepeatPeriod = 1 WeekDayInMonth = 2 WeekDays = 3 BeginTime = 09.00

You can check if the job is executed for the given date. To do it, use the ExecutionRequired() method of the ScheduledJobsSchedule object. Scheduled jobs are always executed on behalf of a certain user. If the user of the scheduled job is not specified, execution is performed with the rights defined by a set of roles specified in the DefaultRoles configuration property. If no role is specified in this property, execution is performed without access rights restriction.

Scheduled jobs are executed using background jobs. When the scheduler determines that a scheduled job must be started, it automatically creates a background job based on this scheduled job. This background job performs all further processing. If this scheduled job is already being executed, it will not be started again regardless of its schedule.

Scheduled jobs can be restarted. It is especially relevant when the scheduled job method has to be executed. Scheduled jobs are restarted in case of their termination or in case of termination of the working process (in client/server mode) or client process (in file mode) where they are being performed. In the scheduled job, you can specify the number of times it must be restarted. To do it, use the Restart count on failure property. To specify the interval between restarts, use the Repeat interval on failure property. After the specified number of restarts is completed, restart attempts stop until the next time the terminated scheduled job is started according to the schedule. At the same time, the counter of restart attempts is reset. In case of another termination, the restart process is repeated from the beginning.

When you implement the restarted scheduled job method, keep in mind that it will be executed from the beginning rather than from the termination point.