Web Items

Web Items are clickable buttons or menu entries that you inject into Jira's interface. They appear in toolbars, navigation bars, and sidebars — giving users one-click access to custom actions.

Creating a Web Item

  1. Go to Apps → ScriptForge → Fragments
  2. Click Create Fragment
  3. Set Fragment Type to web-item
  4. Choose a Location (e.g., issue-toolbar)
  5. Set the Label (button text) and optional Icon
  6. Choose an Action Type and configure it
  7. Save

Action Types

URL Action

Opens a URL when clicked. Supports variable substitution.

{
  "actionType": "url",
  "actionConfig": {
    "url": "https://wiki.company.com/runbooks/{issueType}"
  }
}

Script Action

Runs a ScriptForge script when clicked. The script has full HAPI access.

// Script that adds a "Reviewed" label to the current issue
const issue = await WorkItems.getByKey(context.issueKey);
await issue.update()
  .setLabels([...issue.labels, 'Reviewed'])
  .execute();

Dialog Action

Opens a modal dialog with custom HTML content. Users can interact with the dialog and submit data.

{
  "actionType": "dialog",
  "actionConfig": {
    "title": "Confirm Deployment",
    "html": "<p>Are you sure you want to mark this issue as deployed?</p>",
    "submitLabel": "Confirm"
  }
}

Constrained Create Action

Opens Jira's issue creation dialog with pre-filled field values. Great for templated issue creation.

{
  "actionType": "constrained-create",
  "actionConfig": {
    "projectKey": "OPS",
    "issueType": "Task",
    "summary": "Deploy: {summary}",
    "priority": "High"
  }
}

HTML Action

Renders custom HTML inline (for web panels displayed as items).

Real-World Examples

"Escalate" Button in Issue Toolbar

A button that transitions the issue and notifies the team lead:

  • Location: issue-toolbar
  • Label: "Escalate"
  • Icon: warning
  • Action Type: script
const issue = await WorkItems.getByKey(context.issueKey);

// Transition to "Escalated" status
await issue.transition('Escalated');

// Add a comment tagging the lead
await issue.addComment('Issue escalated by user action. @team-lead please review.');

"Create Sub-Task from Template" Button

A button that creates a standard set of sub-tasks:

  • Location: issue-toolbar
  • Label: "Add QA Tasks"
  • Action Type: script
const issue = await WorkItems.getByKey(context.issueKey);
const tasks = ['Write test cases', 'Execute regression', 'Sign off'];

for (const task of tasks) {
  await issue.createSubTask()
    .setSummary(task)
    .setAssignee(issue.assignee)
    .execute();
}

A simple URL action that opens the issue in an external system:

  • Location: issue-toolbar
  • Label: "View in Monitoring"
  • Action Type: url
  • URL: https://monitoring.company.com/search?q={issueKey}

Project Sidebar Navigation Item

A menu item in the project sidebar that links to a custom report:

  • Location: project-sidebar
  • Label: "Sprint Health"
  • Action Type: url
  • URL: https://reports.company.com/sprint/{projectKey}

Conditions

Control visibility with conditions:

{
  "conditionConfig": {
    "issueTypes": ["Bug", "Incident"],
    "projectKeys": ["PROD", "SRE"]
  }
}

This shows the button only on Bug and Incident issues in the PROD and SRE projects.