Data Transfer API

Lets a script attach a Data Transfer to the scheduler, detach it, and read its schedule status. A data transfer copies one variable’s value into another, optionally computing a statistic from logged history first — it does not write files.

Note

These calls only schedule a definition that already exists under Development → Data Transfers; they do not create one. A name that does not resolve throws.

Scheduling and cancelling require the SCHEDULE_DATA_TRANSFER permission, and both are recorded in the audit log as operator actions.

ins.scheduleDataTransfer(name) / (projectName, name)

Attaches the transfer to the scheduler; it then runs at the period in its definition. projectName defaults to the calling project.

ins.scheduleDataTransfer("hourly_energy_calc");
ins.scheduleDataTransfer("other_project", "hourly_energy_calc");

The project must be active — scheduling a transfer in a passive project is refused.

ins.cancelDataTransfer(name) / (projectName, name)

Detaches the transfer: remaining triggers are cancelled, and a run already in progress finishes.

ins.cancelDataTransfer("hourly_energy_calc");

ins.getDataTransferStatus(name) / (projectName, name)

Returns one of two strings:

Value	Meaning
"Scheduled"	Attached to the scheduler
"Not Scheduled"	Not attached

if (ins.getDataTransferStatus("hourly_energy_calc") === "Not Scheduled") {
    ins.scheduleDataTransfer("hourly_energy_calc");
}

An unknown name also reports “Not Scheduled”

A name that does not resolve — unknown, deleted, owned by another space, or hidden by the caller’s role access — reports "Not Scheduled", exactly like a transfer that exists and simply is not scheduled. The two are deliberately indistinguishable, so that a script cannot use this call to discover whether a name exists outside its own space.

To find out which names really resolve, match them against getDataTransferStatusesByProject(), which lists only what the caller can already see.

ins.getDataTransferStatuses(names) / (projectName, names)

Statuses of the named transfers, keyed by the requested name. Every distinct requested name gets an entry, in request order; a name that does not resolve carries the "Not Scheduled" default rather than being dropped.

var statuses = ins.getDataTransferStatuses(["hourly_energy_calc", "daily_avg_temp"]);

ins.getDataTransferStatusesByProject() / (projectName)

Statuses of every transfer of the project that the caller can see, keyed by name — space- and role-access filtered.

var all = ins.getDataTransferStatusesByProject();
for (var name in all) {
    if (all[name] === "Not Scheduled") ins.scheduleDataTransfer(name);
}

Example: make sure the rollups are running

function main() {
    var wanted = ["hourly_energy_calc", "daily_avg_temp"];
    var statuses = ins.getDataTransferStatuses(wanted);

    for (var i = 0; i < wanted.length; i++) {
        var name = wanted[i];
        if (statuses[name] === "Not Scheduled") {
            ins.scheduleDataTransfer(name);
            ins.writeLog("info", "DataTransfer", name + " scheduled");
        }
    }
}
main();