Skip to content

USER_GUIDE

Jump to bottom
2000433 edited this page Jun 16, 2026 · 6 revisions

SmartScript for Jira — User Guide

Last Updated: June 16, 2026

SmartScript for Jira is a Forge-native automation app for Jira Cloud. It lets Jira administrators create, test, and manage JavaScript automations with a Monaco editor, reusable templates, sandboxed execution, and execution logs.

1. Installation

  1. Install SmartScript for Jira from the Atlassian Marketplace.
  2. Approve the requested Jira scopes.
  3. Open Jira and go to Settings → Apps → SmartScript-Jira.

Only Jira administrators can use the app. Non-admin users will see an access denied message.

2. Core Concepts

Concept Description
Script A saved automation containing JavaScript code, metadata, trigger type, and active state.
Trigger The Jira or scheduled event that runs a script.
Template A prebuilt script generator with editable parameters.
Manual Run A sandbox test run from the editor using mock event data.
Execution Log A recent script run record with status, duration, issue key, and output/error details.
Version History A rollback list of previous saved script versions.
Export / Import JSON backup and restore for saved SmartScript scripts.

3. Supported Triggers

SmartScript currently supports:

  • Issue Created (issue_created)
  • Issue Updated (issue_updated)
  • Issue Transitioned (issue_transitioned)
  • Attachment Added (attachment_added)
  • Scheduled Run (scheduled_run)
  • Manual (manual)

Jira Cloud does not reliably fire a comment_created Forge event for this app, so comment-created triggers are not supported.

Scheduled scripts use a five-field UTC cron expression stored on the script. The Forge scheduled trigger runs hourly, and SmartScript checks whether each script's schedule matches the current hour.

Supported cron syntax:

  • *
  • */N
  • N,M
  • plain numbers

Ranges such as 1-5 are not supported. Use 1,2,3,4,5 instead.

4. Creating a Script

  1. Click Create New Script.
  2. Enter a script name.
  3. Select a trigger type.
  4. Optionally enter comma-separated Jira project keys in Project Scope.
  5. Write ES5 JavaScript in the editor or load a template.
  6. Toggle Active on when ready.
  7. Click Save Changes.

Inactive scripts are saved but skipped by live triggers. Manual Run still works for testing.

For event-based scripts, Project Scope limits execution to the listed Jira projects. The field shows e.g. PROJ, MYAPP (leave empty for all projects) and the guidance Leave empty to apply to all projects. Leaving it empty applies the script to every project.

5. Version History, Export, and Import

SmartScript keeps previous versions of a script each time you save an existing script. Open History from the editor header to review saved versions and restore a previous version.

Version history behavior:

  • The most recent 5 previous versions are retained per script.
  • A version is captured when an existing script is saved.
  • Restoring a version saves it back as the current script.
  • Deleting a script also deletes its saved version history.

Use Export to download all scripts as a JSON file. Use Import to upload a SmartScript JSON export into the app.

Import behavior:

  • The import file must be valid JSON.
  • The top-level JSON value must be an array of SmartScript script objects.
  • Each script must include expected fields such as id, name, description, code, triggerType, isActive, createdAt, and updatedAt.
  • Unsupported trigger types or malformed script objects are rejected with a Failed to import scripts (invalid file?) message.
  • An empty array shows No scripts found in file.

6. Templates

The app includes these built-in templates:

Template Trigger
Auto-assign by Component Issue Created
Add Comment on High Priority Issue Created
Auto-label by Summary Issue Created
Comment on Done Transition Issue Updated
Transition on Attachment Upload Attachment Added
Daily Overdue Issue Alert Scheduled Run
Alert on Unassigned Issue Issue Updated
Alert on Priority Change Issue Updated
Comment on Work Started Issue Updated
Stale Issue Nudge Scheduled Run
Create QA Subtask on Done Issue Transitioned
Create Bug Triage Subtasks Issue Created
Create Release Checklist for High Priority Issue Created
Add Watcher by Component Issue Created
Add Watcher on Priority Escalation Issue Updated
Link Mentioned Issue from Summary Issue Created
Label Stale Bugs Scheduled Run
Transition Overdue Issues Scheduled Run
Comment on Attachment Upload Attachment Added
Add Label on Attachment Upload Attachment Added
Link Issues Mentioned in Summary (Regex) Issue Created
Bulk Escalate Overdue Issues (JQL Loop) Scheduled Run
Generate Release Checklist (createIssue) Manual

To use a template:

  1. Select or create a script.
  2. Click Load Template.
  3. Choose a template.
  4. Fill in the parameters.
  5. Click Apply Template.
  6. Review the generated code and click Save Changes.

Template parameters are inserted into JavaScript string literals. Avoid storing secrets or sensitive data in template fields.

7. Writing Custom Scripts

Scripts run in an ES5-only JavaScript sandbox. Use var, traditional function callbacks, string concatenation, and simple loops.

Avoid:

  • const / let
  • arrow functions
  • template literals
  • async / await
  • Promise
  • import / require
  • fetch, XMLHttpRequest, timers, filesystem access, or arbitrary network calls

8. Available Globals

Scripts can access only the following globals:

Global Signature / usage
event Forge event or scheduled/mock event payload.
console.log console.log(value) writes to execution logs.
getIssue getIssue(key, callback)
updateIssue updateIssue(key, jsonBody, callback)
addComment addComment(key, text, callback)
setAssignee setAssignee(key, accountIdOrEmail, callback)
transitionIssue transitionIssue(key, transitionId, callback)
createSubtask createSubtask(parentKey, dataJson, callback)
createIssue createIssue(projectKey, dataJson, callback)
getUser getUser(accountId, callback)
addWatcher addWatcher(key, accountId, callback)
linkIssues linkIssues(inwardKey, outwardKey, linkType, callback)
searchIssues searchIssues(jql, callback)

Callbacks return an object such as { status: 200 } on success or { error: "message" } on failure. createSubtask and createIssue validate their JSON payload and return { error: "Invalid JSON: ..." } for malformed input. searchIssues returns up to 50 matching issues.

Creating a standalone Jira issue

Use createIssue(projectKey, dataJson, callback) to create a standalone issue in a Jira project. SmartScript adds the project field and defaults issuetype to Task; fields in dataJson can override the issue type.

var data = JSON.stringify({
    summary: "Follow up from automation",
    description: "Created by SmartScript",
    issuetype: { name: "Task" }
});

createIssue("TEST", data, function(res) {
    if (res.error) {
        console.log("Create failed: " + res.error);
    } else {
        console.log("Created issue: " + res.key);
    }
});

9. Example Script

var issue = event.issue;
var priority = issue.fields && issue.fields.priority ? issue.fields.priority.name : "";

if (priority === "Highest") {
    addComment(issue.key, "This issue needs immediate attention.", function(res) {
        console.log("Comment result: " + res.status);
    });
}

10. Manual Run and Sandbox Testing

Click Run to execute the current script in a mock sandbox. SmartScript injects mock event data based on the selected trigger type, such as issue-created, issue-updated, issue-transitioned, attachment-added, scheduled, or manual test data.

In sandbox mode:

  • Jira helper functions do not modify real Jira data.
  • Helper functions log mock API calls and return mock responses.
  • createIssue and createSubtask still validate JSON payloads in sandbox mode, so malformed JSON returns an error instead of a mock success.
  • Results and console.log output appear in the execution result panel.

Manual Run is useful for syntax and control-flow checks. Always test important automations on a non-production Jira project before enabling them broadly.

11. Execution Logs

Open the Execution Logs tab to view recent script runs.

Logs include:

  • Time
  • Script name
  • Trigger type
  • Issue key when applicable
  • Success or error status
  • Duration
  • Result, error, or console.log output

Logs are capped to the most recent 50 records. Use Clear All to delete current logs.

12. Permissions

SmartScript requests these Atlassian scopes:

Scope Purpose
read:jira-work Read issue data for triggers and helper functions.
write:jira-work Update issues, add comments, transition issues, create issues and subtasks, add watchers, and link issues.
read:jira-user Resolve or read Jira user details for assignment-related helpers.
storage:app Store scripts and execution logs in Forge storage.

13. Privacy and Security

  • The app is hosted on Atlassian Forge.
  • JMC Labs does not operate external app servers or databases for SmartScript.
  • The app does not use Google Analytics, Segment, Mixpanel, Sentry, or similar third-party tracking tools.
  • Scripts and logs are stored in Forge storage.
  • Logs may contain Jira data if your scripts write such data with console.log.
  • Do not store passwords, Personal Access Tokens, API keys, or shared secrets in scripts or logs.

14. Limitations

  • Scripts must be ES5-compatible.
  • Long-running scripts are constrained by Forge function runtime limits.
  • Scheduled checks run hourly.
  • Execution logs retain only the most recent 50 records.
  • Comment-created triggers are not supported.
  • The app does not provide arbitrary outbound HTTP access from user scripts.

15. Troubleshooting

Script does not run

  • Confirm the script is Active.
  • Confirm the selected trigger matches the Jira event.
  • Confirm the app has been upgraded after any scope or manifest changes.
  • Check the Execution Logs tab.

SyntaxError

The script likely uses modern JavaScript. Replace let, const, arrow functions, template literals, async, or await with ES5-compatible syntax.

Jira API helper returns 400

The request body or transition ID is probably invalid for that Jira project. Check the Jira REST API shape and project workflow configuration.

Jira API helper returns 401 or 403

The app or acting context lacks permission for the action. Check Jira permissions, app scopes, issue security, and whether the site admin approved the latest app version.

Manual Run succeeds but live execution fails

Manual Run uses mock data and does not call real Jira APIs. Test live behavior on a safe Jira project before relying on production automations.

Import fails

SmartScript only imports valid SmartScript JSON exports. If a text file, malformed JSON file, or unrelated JSON array is selected, the app shows Failed to import scripts (invalid file?) and does not import partial data.

16. Support

For support or security questions, contact:

JMC Labs
Email: support@jmclabs.dev

Clone this wiki locally