Skip to main content

Flag stale work items every night

Add the label stale every night to open work items that nobody has updated for 30 days, so the team can review them in one filter.

Problem: Open work items that nobody touches pile up in the backlog. Nobody notices them until someone runs a clean-up by hand, and that rarely happens.

Solution: You try the search in the Script Console first, as yourself and read-only. Then you run the same search in a scheduled job that labels the work items every night, and you watch its runs in the job's History.

What you'll need​

  • Script Master for Jira, with an active license. See Get started.
  • The Administer Jira global permission.
  • A Companion App connected to Script Master. Scheduled jobs run there. See The Companion App.
  • A space to clean up, for example DEMO.

Set it up​

1. Check which work items match​

  1. In Script Master, select the Script Console tab.

  2. Replace the script in the editor with this one. It only reads:

    const query = new URLSearchParams({
    jql: 'project = DEMO AND statusCategory != Done AND updated < -30d ORDER BY updated ASC',
    maxResults: '50',
    fields: 'summary',
    });
    const response = await requestJira(`/rest/api/3/search/jql?${query}`);
    if (!response.ok) throw new Error(`Jira answered ${response.status}`);
    const { issues } = await response.json();
    return issues.map(issue => `${issue.key} ${issue.fields.summary}`);
  3. Select Run. The Result panel shows an indented list of the work items the job will label, one per line. If no work item matches, it shows [].

  4. If the list holds work items you want to keep, change the JQL until it's right.

2. Create the scheduled job​

  1. Select the Scheduled Jobs tab, then Create scheduled job.

  2. In Title, enter Flag stale work items in DEMO.

  3. In Schedule, enter 0 2 * * *. The job then runs every day at 02:00 UTC. Next at: under the field shows the next run in UTC.

  4. In Backend JavaScript, paste this script, with your JQL from phase 1:

    const query = new URLSearchParams({
    jql: 'project = DEMO AND statusCategory != Done AND updated < -30d ORDER BY updated ASC',
    maxResults: '50',
    fields: 'summary',
    });
    const response = await api.asApp().requestJira(route`/rest/api/3/search/jql?${query}`, {
    headers: { Accept: 'application/json' },
    });
    if (!response.ok) throw new Error(`Search failed: ${response.status}`);
    const { issues } = await response.json();

    for (const issue of issues) {
    const update = await api.asApp().requestJira(route`/rest/api/3/issue/${issue.key}`, {
    method: 'PUT',
    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
    body: JSON.stringify({ update: { labels: [{ add: 'stale' }] } }),
    });
    if (!update.ok) console.error(`${issue.key}: Jira answered ${update.status}`);
    }

    return `Labeled ${issues.length} work items`;
  5. Turn on Test this Scheduled Job, then select Test. The test runs the script for real, so the matching work items get the label now.

  6. Turn on Enable, then select Save.

    The scheduled job editor with the title, the schedule 0 2 * * * and the script

The job runs as the app, not as you, and labels at most 50 work items a run. Adding the label updates each work item, so it isn't picked up again the next night.

What your team will experience​

  1. Every night, open work items in DEMO with no update for 30 days get the label stale.
  2. The team opens a filter such as project = DEMO AND labels = stale and closes, updates or keeps each work item.

Check that it works​

  1. On the Scheduled Jobs tab, select β€’β€’β€’ > Run in the job's row. The job starts at once, and its run shows in History when it finishes.
  2. Refresh the list, then select the latest run in the History column. Confirm that its log ends with return: Labeled and a number, with no errors.
  3. In Jira, search for labels = stale. Confirm that the work items from phase 1 have the label.

Runs start when Forge next checks the schedules, so a run can start up to an hour after its time.