Last updated

Action Script Examples

These scripts show how a Run script step creates follow-up items, moves status by name, assigns owners, and summarizes comments.

Each example is a function body, not a full program. return produces the node output, which downstream nodes read through the configured Output variable (default script_result). For the runtime, budgets, and the full reference, see Action scripts.

Read the response envelope

The v2 REST API wraps every response in a data envelope. A single resource is res.body.data; a list is res.body.data plus res.body.pagination. Always check res.ok before reading the body, and throw to fail the step when a call does not succeed.

const res = windshift.api.request({ method: 'GET', path: '/items/' + context.item_id });
if (!res.ok) {
  throw new Error('lookup failed with status ' + res.status);
}
return { title: res.body.data.title, status_id: res.body.data.status_id };

The catalog lookups in these examples read /workspaces/{workspace_id}/statuses and /workspaces/{workspace_id}/assignable-users. The minted token carries the matching read scopes, but the executor still needs permission to see the workspace.

Comment on the trigger item

Post a private note that records what the action did. The trigger item is in context.item, and context.item_id is also a global.

if (!context.item) {
  throw new Error('This action needs an item trigger');
}

const res = windshift.api.request({
  method: 'POST',
  path: '/items/' + context.item.id + '/comments',
  body: {
    content: 'Automation handled **' + context.item.title + '**.',
    is_private: true
  }
});

if (!res.ok) {
  throw new Error('comment failed with status ' + res.status);
}

return { comment_id: res.body.data.id };

Create a follow-up item under the trigger

Create a child item and return its id and key so a later step can link or reference it. Pass parent_id to keep the new item in the same hierarchy.

const res = windshift.api.request({
  method: 'POST',
  path: '/items',
  body: {
    workspace_id: context.workspace_id,
    title: 'Follow-up for ' + context.item.key,
    description: 'Created by the action on "' + context.item.title + '".',
    parent_id: context.item.id,
    item_type_id: context.item.item_type_id
  }
});

if (!res.ok) {
  throw new Error('create failed with status ' + res.status);
}

const created = res.body.data;
return { item_id: created.id, key: created.key };

Move the item to a status by name

Transitions address the target status by id, so resolve the name first. Throwing here fails the step with a readable message instead of a bare API error.

const statuses = windshift.api.request({
  method: 'GET',
  path: '/workspaces/' + context.workspace_id + '/statuses'
});

if (!statuses.ok) {
  throw new Error('status lookup failed with status ' + statuses.status);
}

const done = statuses.body.data.find((status) => status.name === 'Done');
if (!done) {
  throw new Error('No status named "Done" in this workspace');
}

const move = windshift.api.request({
  method: 'POST',
  path: '/items/' + context.item_id + '/transition',
  body: { to_status_id: done.id, fields: {} }
});

if (!move.ok) {
  throw new Error('transition failed with status ' + move.status);
}

return {
  from_status_id: move.body.data.old_status_id,
  to_status_id: move.body.data.new_status_id,
  no_op: move.body.data.no_op
};

Assign the item to a named owner

List the workspace's assignable users and match on the display name, then patch the item. Use the user id from the response, never a name.

const users = windshift.api.request({
  method: 'GET',
  path: '/workspaces/' + context.workspace_id + '/assignable-users'
});

if (!users.ok) {
  throw new Error('user lookup failed with status ' + users.status);
}

const owner = users.body.data.find((user) => user.full_name === 'Ada Lovelace');
if (!owner) {
  throw new Error('No assignable user named Ada Lovelace');
}

const res = windshift.api.request({
  method: 'PATCH',
  path: '/items/' + context.item_id,
  body: { assignee_id: owner.id }
});

if (!res.ok) {
  throw new Error('assign failed with status ' + res.status);
}

return { assignee_id: res.body.data.assignee_id };

Close every child of the trigger item

Read the children, then move them in one bulk transition. page_size caps the page, so check res.body.pagination when the tree can be larger. Failures come back per item instead of failing the whole call.

function statusIdByName(name) {
  const res = windshift.api.request({
    method: 'GET',
    path: '/workspaces/' + context.workspace_id + '/statuses'
  });
  if (!res.ok) {
    throw new Error('status lookup failed with status ' + res.status);
  }
  const match = res.body.data.find((status) => status.name === name);
  if (!match) {
    throw new Error('No status named ' + name);
  }
  return match.id;
}

const children = windshift.api.request({
  method: 'GET',
  path: '/items?parent_id=' + context.item_id + '&page_size=100'
});

if (!children.ok) {
  throw new Error('child lookup failed with status ' + children.status);
}

const childIds = children.body.data.map((child) => child.id);
if (childIds.length === 0) {
  return { requested: 0, transitioned: 0, failed: 0 };
}

const res = windshift.api.request({
  method: 'POST',
  path: '/items/bulk-transition',
  body: { item_ids: childIds, to_status_id: statusIdByName('Done') }
});

if (!res.ok) {
  throw new Error('bulk transition failed with status ' + res.status);
}

return {
  requested: res.body.data.requested_count,
  transitioned: res.body.data.transitioned_count,
  failed: res.body.data.failed_count
};

Summarize the comment thread

A read-only script can return a digest for a later step without writing anything. console.info lines land in the execution trace.

const res = windshift.api.request({
  method: 'GET',
  path: '/items/' + context.item_id + '/comments?page_size=50'
});

if (!res.ok) {
  throw new Error('comment lookup failed with status ' + res.status);
}

const comments = res.body.data.comments;
const byAuthor = {};
for (const comment of comments) {
  const author = comment.author_name || 'Unknown';
  byAuthor[author] = (byAuthor[author] || 0) + 1;
}

console.info('Scanned ' + comments.length + ' comments');

return {
  total: comments.length,
  has_more: res.body.data.has_more,
  by_author: byAuthor
};

Patterns to reuse

  • Check res.ok first. Read res.body.data only after a 2xx, and throw to stop the step.
  • Resolve names to ids. Statuses, users, and item types are referenced by id in write payloads.
  • Keep the script synchronous. async, await, promises, and timers are not available; each call returns before the next line runs.
  • Watch the call budget. Every windshift.api.request counts toward Max API calls (50 by default).
  • Do not catch policy errors. A disallowed method, path, resource, or route interrupts the node and cannot be swallowed by try/catch.
  • Action scripts for the runtime, the API bridge, and the limits.
  • Actions for triggers, steps, and the flow editor.
  • REST API for the v2 resource reference.