Scripting API Reference

Complete JavaScript (Goja ES5.1) scripting API for backend scripts, widget scripts, and chart scripts.

Global Variables#

user Object#

Available in all script types. Backend scripts get read-write access.

Read Methods (all scripts)#

Write Methods (backend scripts only)#

group Object#

Available when isGroupScoped is true. Backend scripts get read-write access.

Read Methods (all scripts)#

Write Methods (backend scripts only)#

item Object#

Available when isItemScoped is true. Backend scripts get read-write access.

Read Methods (all scripts)#

Write Methods (backend scripts only)#

api Object#

Data transformation helpers, available in all script types.

Example#

var tasks = group.QueryItems("type:task");
var byStatus = api.groupBy(tasks, "status");
var totalEstimate = api.aggregate(tasks, "estimate", "sum");
var overdue = api.filterItems(tasks, function(t) {
    return t.DueDate() !== null && new Date(t.DueDate()) < new Date();
});

echarts Object#

Chart configuration helpers for widget/chart scripts.

fetch(url, options?) (Backend Scripts Only)#

Make HTTP requests to external URLs. Each call counts against the API call limit.

Parameters#

Response#

Security#

• Requests to private/loopback IPs are blocked (SSRF protection)
• Only http:// and https:// schemes allowed
• Max response body: 1MB
• Max 5 redirects
• Respects script timeout

Example#

var apiKey = secrets.get("EXTERNAL_API_KEY");
var resp = fetch("https://api.example.com/data", {
    method: "POST",
    headers: {
        "Authorization": "Bearer " + apiKey,
        "Content-Type": "application/json"
    },
    body: JSON.stringify({ query: "test" })
});

if (resp.ok) {
    var data = resp.json();
    log("Got " + data.results.length + " results");
} else {
    log("Request failed: " + resp.status);
}

secrets.get(key) (Backend Scripts Only)#

Retrieve encrypted secrets by key. Secrets are resolved with group-then-instance fallback.

Returns: string (decrypted value) or null if not found.

Security#

• You must specify the exact key - no list() or getAll() is available
• Secret values are never logged by the system
• If you pass a secret to log() or fetch(), that is your responsibility
• Each call counts against the API call limit

Example#

var token = secrets.get("SLACK_WEBHOOK_TOKEN");
if (token) {
    fetch("https://hooks.slack.com/services/...", {
        method: "POST",
        body: JSON.stringify({ text: "Item created: " + item.Title() })
    });
}

log(...args) / console.log(...args)#

Log messages during script execution. Messages appear in the execution log.

log("Processing", items.length, "items");
console.log("User:", user.Name());

Resource Limits#

API calls include: QueryItems, GetMemberById, GetMembers, fetch, secrets.get, and other data-fetching methods.

Trigger Types#

Backend scripts can be triggered in four ways:

Available Events#

CREATE, UPDATE, DELETE, STATUS_CHANGE, FIELD_UPDATE, ASSIGN, COMMENT_CREATE

Query Syntax#

The Timill query syntax supports filtering items by any field:

// Simple query
group.QueryItems("type:task")

// Multiple conditions
group.QueryItems("type:task status:open")

// Date range
group.QueryItems("type:task dueDate:>=2024-01-01")

// Complex query with parentheses
group.QueryItems("type:task (status:open OR status:in-progress)")

Supported Operators#

Supported Fields#

See also:

• Scripting Overview — All scripting environments
• Scripted Charts — Chart creation guide
• Scripted Widgets — Widget creation guide
• Backend Scripts — Backend automation guide