Skip to content

USER_GUIDE

Jump to bottom
just-warrior edited this page May 11, 2026 · 6 revisions

SmartScript for Jira — User Guide

A modern, template-driven scripting plugin for Jira Cloud. Bring your Jira automation to life with a VS Code-grade editor, no-code templates, and full execution logs — without ever touching Groovy.

Table of Contents

  1. Introduction
  2. Quick Start
  3. Core Concepts
  4. Using Templates (No-Code Path)
  5. Writing Custom Scripts (Pro-Code Path)
  6. Manual Run & Testing
  7. Execution Logs
  8. Activating & Deactivating Scripts
  9. Limitations
  10. Troubleshooting
  11. Privacy & Security
  12. Roadmap

1. Introduction

SmartScript is a Jira Cloud automation plugin built on the Atlassian Forge platform. It is designed to replace heavyweight, Groovy-based scripting tools with a lightweight, modern alternative that works for both administrators and developers.

Who It's For

  • Jira Administrators who need powerful automation but don't want to write code from scratch — use ready-made templates with simple form fields.
  • Developers who want to write custom logic in JavaScript with the comfort of a VS Code-grade editor (Monaco), real-time syntax checking, and instant test runs.

Key Features

  • 3 Built-in Killer Templates — Auto-assign by component, auto-comment on high priority, auto-label by keyword.
  • Monaco Editor — The same editor that powers VS Code, embedded directly in Jira.
  • Instant Test Run — Try your script with a mock event before going live.
  • Execution Logs — See exactly what happened, when, and why.
  • Active/Inactive Toggle — Pause scripts without deleting them.
  • Native Look & Feel — Built with the Atlassian Design System.

2. Quick Start

Installation

  1. Visit the Atlassian Marketplace listing for SmartScript for Jira.
  2. Click Get app and install it on your Jira Cloud site.
  3. Approve the requested permissions (read/write Jira issues and store app data).

Open the Admin Page

  1. Go to Jira Settings → Apps → SmartScript-Jira.
  2. You will see a sidebar (left) for your scripts and a main area (right) for editing.

Run Your First Template (60 seconds)

  1. Click Create New Script (top of the sidebar).
  2. Click Load Template in the editor header.
  3. Choose Add Comment on High Priority from the dropdown.
  4. Customize the comment text and click Apply Template.
  5. Make sure the Active toggle is on, then click Save Changes.
  6. Create a test issue in Jira with priority Highest — the comment appears automatically.

That's it. You just deployed a working automation without writing a single line of code.

3. Core Concepts

Concept Definition
Script A unit of automation logic. Contains JavaScript code, a trigger type, and an active/inactive flag.
Trigger The event that runs your script. Currently supported: Issue Created, Issue Updated, and Manual (run from UI only).
Template A pre-written script with parameter slots. Selecting a template generates code for you.
Execution Log A historical record of one script run. Includes timestamp, status, duration, and any console output or error.
Active / Inactive An on/off switch. Inactive scripts are kept but never executed by triggers.

4. Using Templates (No-Code Path)

Templates are the fastest way to deploy automation — no JavaScript knowledge required.

Available Templates

4.1 Auto-assign by Component

Automatically assigns newly created issues to a specific user when a chosen component is set.

Parameters:

  • Component Name — e.g. Backend
  • Assignee Account ID — The Atlassian Account ID of the assignee. You can find this by visiting the user's profile in Jira; the URL will contain accountId=....

Trigger: Issue Created

4.2 Add Comment on High Priority

Posts a predefined comment whenever an issue is created with Highest priority.

Parameters:

  • Comment Body — The text to post (e.g. "⚠️ This high-priority issue requires immediate attention.")

Trigger: Issue Created

4.3 Auto-label by Summary

Adds a label to any issue whose summary contains a chosen keyword.

Parameters:

  • Keyword to search — e.g. bug (case-insensitive)
  • Label to add — e.g. triaged

Trigger: Issue Created

Applying a Template

  1. With a script selected, click Load Template.
  2. Choose a template from the dropdown.
  3. Fill in the parameter fields.
  4. Click Apply Template. The editor populates with the generated code.
  5. Click Save Changes. Templates do not auto-save.

💡 Tip: After applying a template, you can still edit the generated code by hand — useful for combining multiple template behaviors or adding extra conditions.

⚠️ Note on quotes in parameters: If a parameter value contains a double quote ("), the generated code may break. Avoid " in parameter inputs, or remove it manually in the editor after applying.

5. Writing Custom Scripts (Pro-Code Path)

If templates don't cover your case, write your own logic.

Editor Basics

  • Click in the editor area to start typing.
  • Auto-complete and syntax highlighting are powered by Monaco (the VS Code engine).
  • Save with the Save Changes button (top right). The button is disabled when there are no unsaved changes.

Available Globals

Inside a script you can use these globals only:

Global Description
event The Jira event object. Includes event.issue.key, event.issue.fields.summary, event.issue.fields.priority.name, event.issue.fields.components, etc.
console.log(message) Prints to the execution log. Strings, numbers, and objects are supported.
updateIssue(key, jsonBody, callback) Updates an issue. jsonBody must be a JSON string matching Jira's REST API format.
addComment(key, plainText, callback) Adds a plain-text comment. Markdown/ADF is converted automatically.
setAssignee(key, accountId, callback) Sets the assignee. Pass an empty string to unassign.

Built-in browser APIs (fetch, XMLHttpRequest), Node.js modules (require, import), and timers (setTimeout) are not available in the sandbox.

⚠️ Code Style Constraints (ES5 Only)

The script sandbox only supports ECMAScript 5. Modern JavaScript will throw a SyntaxError.

❌ Don't use ✅ Use instead
const, let var
() => { ... } (arrow function) function () { ... }
`Hello, ${name}` (template literal) "Hello, " + name
async / await / Promise Callback pattern (the helpers above are async via callback)
Object.assign(...) (works), Array.includes(...) (may fail) Use for loops and indexOf for safety

Example: Custom Auto-Assign with Multiple Conditions

/**
 * Assign issues with specific labels to specific users.
 */
var issue = event.issue;
var labels = (issue.fields && issue.fields.labels) || [];

var assigneeMap = {
    "frontend": "557058:abc-account-id-1",
    "backend":  "557058:abc-account-id-2",
    "design":   "557058:abc-account-id-3"
};

for (var i = 0; i < labels.length; i++) {
    var target = assigneeMap[labels[i]];
    if (target) {
        console.log("Matched label: " + labels[i]);
        setAssignee(issue.key, target, function (res) {
            console.log("Assignment status: " + res.status);
        });
        break;
    }
}

Example: Conditional Comment

var issue = event.issue;
var summary = issue.fields ? issue.fields.summary : "";

if (summary.toLowerCase().indexOf("urgent") !== -1) {
    addComment(issue.key, "Auto-flagged as urgent. Please respond within 2 hours.", function (res) {
        console.log("Comment posted: " + res.status);
    });
}

6. Manual Run & Testing

The ▶ Run button executes your script in a mock environment so you can test logic before going live.

What Mock Mode Does

  • A fake event is injected: { eventType: 'manual_test', issue: { key: 'TEST-123', id: '10000' } }.
  • Helper functions (updateIssue, addComment, setAssignee) do not call Jira. They return { status: 200, mock: true } and log a message.
  • The script's return value and all console.log output are shown in the result panel below the editor.

How to Use It

  1. Write or load a script.
  2. Click ▶ Run.
  3. The result panel appears at the bottom of the editor:
    • Green = Success. Shows the return value.
    • Red = Error. Shows the error message.
    • Black box = Captured console.log output (always shown when present).
  4. Click Close to dismiss the panel.

💡 Mock mode is the right tool for verifying syntax, control flow, and basic logic. To verify real Jira behavior, set the trigger to Issue Created or Issue Updated, save, and create a test issue.

7. Execution Logs

Click the Execution Logs tab (top of the editor area) to view your last 50 script runs.

Log Fields

Field Description
Time When the script ran (local time).
Script The script's display name.
Issue The Jira issue key that triggered the run.
Status Success (green) or Error (red).
Duration Total execution time in milliseconds.
Result/Error The captured console.log output (success) or error message (failure). Hover for full text.

Actions

  • Refresh — Reload the latest logs.
  • Clear All — Permanently delete all execution logs.

📌 Logs are limited to the most recent 50 runs. Older logs are deleted automatically.

8. Activating & Deactivating Scripts

Use the Active toggle in the script editor header to enable or disable a script without deleting it.

State Behavior
Active (green badge) The script will run when its trigger fires.
Inactive (gray badge) The script is preserved but skipped by all triggers. ▶ Run still works for testing.

💡 Best practice: Deactivate scripts during maintenance windows or when you suspect a script is misbehaving — it's reversible and faster than deleting.

9. Limitations

Please be aware of these constraints when designing your automation:

Runtime Limits

  • 25-second execution timeout per Forge function call (Atlassian platform limit). Long-running scripts will be terminated.
  • Scripts run sequentially. If multiple scripts are active for the same trigger, they execute one after another. Total time = sum of all script times.
  • 50-log retention. Older logs are automatically purged.

Trigger Coverage (V1.0)

Currently supported triggers:

  • ✅ Issue Created
  • ✅ Issue Updated
  • ✅ Manual (run from UI only)

Not yet supported (planned):

  • Workflow transitions
  • Comments added
  • Attachments uploaded
  • Scheduled runs (cron)

Sandbox Constraints

  • ECMAScript 5 only (see §5).
  • No external HTTP calls outside the provided updateIssue, addComment, setAssignee helpers.
  • No file system access, no require, no import.

API Coverage

Currently only three high-level Jira API helpers are exposed. Other endpoints (e.g., transitions, custom fields with non-trivial schemas) require manual JSON construction passed to updateIssue.

10. Troubleshooting

SyntaxError: Unexpected identifier

You used modern JavaScript (const, let, =>, template literals). Refactor to ES5 — see §5.

Status: 401 / 403

The plugin lacks permission to perform the action. Check that:

  • The required scopes are granted (write:jira-work for issue updates).
  • The user/issue you're targeting exists.
  • The site administrator approved the latest scope changes after upgrading.

Status: 400 on updateIssue

The JSON body is malformed for Jira's API. Check the Jira REST API documentation for the exact field structure.

Script doesn't run on issue events

  • Confirm the Active toggle is on.
  • Confirm the Trigger matches the event you expect (Issue Created does not fire on updates).
  • Check the Execution Logs tab — if there's no entry for your issue, the trigger never fired (often a permission or scope issue).

Editor doesn't appear or shows a blank screen

Refresh the page. Monaco Editor occasionally fails to mount on the first load due to network conditions. If it persists, check your browser console for errors and contact support.

▶ Run succeeds but the live trigger fails

Mock mode does not call the real Jira API, so success in mock ≠ success in production. Common causes:

  • The mock issue (TEST-123) has a different field shape than your real issue.
  • Your real account lacks permission for the action.
  • Account IDs hardcoded in the script are wrong (typos, deleted users).

11. Privacy & Security

What We Store

All data is stored in Forge KV Storage, which is hosted within your Atlassian Cloud instance. We store:

  • Script definitions — name, description, code, trigger type, active state, timestamps.
  • Execution logs — the most recent 50 runs, each containing the script ID, name, issue key, status, duration, and any console.log output.

What We Do Not Store or Transmit

  • We do not transmit any data to third-party servers.
  • We do not store user credentials, OAuth tokens, or session data.
  • We do not persist Jira issue contents — only the issue key and what your script logs.

Data Lifecycle

  • Scripts persist until you delete them.
  • Execution logs are kept for the most recent 50 runs and are then automatically deleted.
  • Uninstalling the app removes all stored data.

Permissions Requested

Scope Why
read:jira-work Read issue details when triggers fire.
write:jira-work Update issues, post comments, set assignees.
read:jira-user Resolve account IDs for assignee operations.
storage:app Persist scripts and logs.

Sandbox Isolation

User scripts run inside js-interpreter, a pure-JavaScript ES5 interpreter. The interpreter has no access to the host's network, filesystem, or environment. Only the four helpers (console.log, updateIssue, addComment, setAssignee) cross the boundary, and each enforces a fixed URL pattern that prevents arbitrary endpoint access.

12. Roadmap

We are actively working on the following features for upcoming releases:

V1.1 (Near-term)

  • Git Synchronization — Sync scripts to your GitHub/GitLab repository ("Script as Code").
  • More Built-in Templates — Subtask synchronization, due-date enforcement, label cleanup.
  • Enhanced Trigger Coverage — Workflow transitions, comments, attachments.

V2.0 (Long-term)

  • AI-Native Authoring — Generate scripts from plain-English prompts (BYOK: Bring Your Own Key).
  • Type Definitions in Editor — Full Jira REST API auto-completion via embedded .d.ts files.
  • Scheduled Triggers — Run scripts on a cron schedule.
  • Granular Permissions — Per-script edit/view permissions.

Support

  • Issues & Feature Requests: Project repository (link to be added)
  • Email: (to be added)
  • Atlassian Community: Tag posts with #smartscript-jira

SmartScript for Jira — Built on Atlassian Forge. © 2026.

Clone this wiki locally