Scheduled tasks

A scheduled task is a script that the DocView Worker runs on a timetable. It is not a step in a batch's workflow: it runs on its own, usually after export. For example:

• every night at 02:00, zip the documents exported since the last run and e-mail the zip to the accounts team;
• every hour, send the new export files to a customer by SFTP;
• on the first day of the month, write a summary file of last month's exported batches;
• every 15 minutes, call a web service with the batches exported since the last run.

You find scheduled tasks under Administration › System › Scheduled tasks. You need the permission Scheduled tasks (Admin.ScheduledTasks). C# tasks also need the permission C# scripts (Admin.CSharpScripts).

Create a task

1. Click New task. A working example is already in the editor: it zips the PDF files exported since the last run and e-mails them.
2. Give the task a Name and, if you like, a Description.
3. Choose the language: JavaScript or C# (see JavaScript or C#?).
4. Write the script. Check tells you whether it parses (JavaScript) or compiles (C#) without running it. Example puts the example back.
5. Set the Schedule (below). Next runs shows the next five times it runs.
6. Fill in the Parameters: one name=value per line, for example folder=D:\Export and to=accounts@example.com. The script reads them with dv.parameter('folder').
7. Set the Time limit. A run that takes longer is stopped and recorded as failed.
8. Switch the task On when you want it to run on its schedule, and click Save.

Saving checks the script and the schedule; a task that does not parse or compile is not saved.

Schedules

Times of day are in the task's Time zone; summer time is taken into account.

A cron expression has five fields: minute hour day-of-month month day-of-week. For example:

Run now and the run history

Run now asks the DocView Worker to run the task straight away, even when it is switched off. The DocView Worker picks it up within half a minute; the page follows the run and opens its log when it finishes.

Every run is listed under Runs: when it started, how long it took, the result, who started it (Schedule or your name) and which DocView Worker ran it. Log shows what the script wrote with dv.log(). Runs are kept for 90 days. When a timed run fails, the person who last saved the task is told in the notification centre.

On the list of tasks, the switch turns a task on or off, and Run now runs it.

Only one DocView Worker runs each run, even when several DocView Workers are installed.

JavaScript or C#?

C# tasks do not run when C# scripts are switched off on the installation (Export:CSharpScripts:Enabled = false).

The helpers: dv

Both languages have the same helpers, as dv. JavaScript uses lower case first letters (dv.listFiles), C# capitals (dv.ListFiles). Relative paths are inside the run's own work folder, which is removed when the run ends.

Keep passwords out of scripts and parameters: store them under Settings › Secrets and pass the secret's name (for example passwordSecret: 'customer-sftp').

In the JavaScript editor, press Ctrl+Space to see the helpers.

Example: zip yesterday's exports and send them by SFTP

const folder = dv.parameter('folder');
const files = dv.listFiles(folder, '*.pdf', dv.lastRunAt, true);
if (files.length === 0) {
    dv.log('Nothing new.');
    return;
}
const zip = dv.zip(files, 'Exports ' + dv.now.toISOString().substring(0, 10) + '.zip', folder);
dv.uploadSftp({ host: 'sftp.customer.com', username: 'docview', passwordSecret: 'customer-sftp', path: '/incoming' }, [zip]);
dv.log('Sent ' + files.length + ' file(s).');

The same in C#:

var folder = dv.Parameter("folder")!;
var files = dv.ListFiles(folder, "*.pdf", dv.LastRunAt, subfolders: true);
if (files.Length == 0) { dv.Log("Nothing new."); return; }
var zip = dv.Zip(files.Select(f => f.Path), dv.WorkPath($"Exports {dv.Now:yyyy-MM-dd}.zip"), folder);
dv.UploadSftp(new { host = "sftp.customer.com", username = "docview", passwordSecret = "customer-sftp", path = "/incoming" }, new[] { zip });
dv.Log($"Sent {files.Length} file(s).");

In C#, throw new ScheduledTaskException("message") fails the run with that message, and await can be used.

Allow more folders (JavaScript)

JavaScript tasks may use their work folder and the folders of the organisation's folder export destinations. To allow other folders, list them in the DocView Worker's configuration:

"ScheduledTasks": {
  "AllowedFolders": [ "D:\\Archive", "\\\\fileserver\\handover" ]
}

See Configuration reference.

Organisations

Each organisation has its own scheduled tasks; a task sees only its organisation's batches and secrets. See Organisations and departments.

Related pages

• Output and export
• C# export scripts
• DocView Workers
• Users, roles and permissions