Skip to content

USER_GUIDE

Jump to bottom
2000433 edited this page May 29, 2026 · 6 revisions

SmartScript for Jira — User Guide

Last Updated: May 30, 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, or open Apps → SmartScript from the Jira navigation.

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.

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 name and optional description.
  3. Select a trigger type.
  4. Write ES5 JavaScript in the editor or load a template.
  5. Toggle Active on when ready.
  6. Click Save Changes.

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

5. 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

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.

6. 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

7. 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)
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. searchIssues returns up to 50 matching issues.

8. 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);
    });
}

9. 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 successful mock responses.
  • 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.

10. 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.

11. 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 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.

12. 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.

13. 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.

14. 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.

15. Support

For support or security questions, contact:

JMC Labs
Email: wjdals9058@gmail.com

Clone this wiki locally