Triggers

Every trigger takes the same path. The server reads the mode, the principal and the script from stored configuration, then stores the run and queues it.

• Where: the console’s Listeners, Schedules and API triggers, or Add trigger on the run panel’s Where it runs tab.
• Who: only an administrator changes them.
• The script: every form that names one has Show the script under its picker. It shows the published revision, or the draft if there is none. Edit opens the script in the console.
• On and off: a switch in each row turns the trigger on or off and changes nothing else. One awaiting review cannot be switched on until it is reviewed.
• Needs attention: awaiting review, paused after a failed run, or not running is written under the name, with the reason.

Listeners

A listener runs a script when a Jira or Confluence event happens, such as a work item created or a page published. It can filter by space and work type, and runs in the sandbox or in production. A new event type can take a few minutes after saving before Forge starts sending it.

Full size

• The event is the one ScriptRunner scripts expect. Atlassian’s events are thin, so before the script runs Code Studio fetches what the event names (the whole work item, the page, the user) and hands the script the payload Jira’s webhook or Confluence Connect would have sent: webhookEvent, issue, user, changelog, comment. A ScriptRunner Connect listener runs unchanged. The raw Forge event is context.forgeEvent.
• Test it on a real item. In the run panel, Test event lists every listener event. For one that names a work item, page, blog post or space, choose that item and the JSON becomes what the event would hand the script for it, read with your permissions: Work item updated carries the item’s newest change, a comment or work log event its newest comment or work log. What only the moment of the event knows, such as a moved page’s previous place, is left out, and user is you.
• Each event runs once per listener, even when Forge delivers it twice.
• A loop is stopped. A run caused by another run’s change is one deeper. The eleventh in a chain is stopped before it does anything, as ScriptRunner stops its eleventh self-triggered run.
• A failing listener pauses after the number of failed production runs set under Pause after failed runs. Switching it on again, or a successful run in the console, resumes it.

Schedules

A schedule runs a published script at the times it names, in its own time zone. How often offers every few minutes, hourly, daily, weekdays, weekly and monthly, or a cron expression.

Full size

A cron expression of your own can be:

• Standard cron, five fields: minute hour day-of-month month day-of-week, as Unix writes it.

• Quartz, six or seven fields with seconds and ?, as ScriptRunner for Jira Data Center writes it. L, W and # are refused with a message.

• @hourly, @daily, @weekly, @monthly and @yearly.

• Queued about ten minutes early and started on its minute. Until then it shows as Scheduled, with Cancel.

• Deleting a schedule, switching it off or changing its script or mode cancels its waiting runs.

• Missed while the app could not run: it runs once, and the schedule moves on from now.

• Pauses after failed runs, as a listener does.

API triggers

An API trigger gives a script a URL that another system calls with GET or POST, authenticated with the trigger’s secret.

• One address for the app, with the trigger named in the query parameter cc-trigger.
• Its secret travels as Authorization: Bearer <secret>. A secret in the address is refused. Only the secret’s SHA-256 is stored, compared in constant time.
• The script’s event is the request. A JSON body’s fields are also on event, so a webhook-shaped body reads as an event.
• The trigger answers 202 at once, or waits up to 45 seconds and answers with what the script returns ({ statusCode, headers, body }, or its result as JSON). A run that outlasts the wait is read later with GET and cc-run=<id>, with the same secret.

Calling one:

• From Code Studio on another site: a connection of type An HTTP API, the address up to the ? as its Base URL, Bearer token holding the secret.
• From a Forge app: declare the trigger’s host, keep the address and secret in encrypted variables.
• With curl: the whole address in quotes.

export default async function () {
    return http.post('invoices', '/', { invoice: 'INV-1042' }, {
        query: { 'cc-trigger': '<the trigger id from its address>' },
    });
}

import { fetch } from '@forge/api';

const response = await fetch(process.env.TRIGGER_URL, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TRIGGER_SECRET}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ invoice: 'INV-1042' })
});
console.log(response.status, await response.json());

curl -X POST "$TRIGGER_URL" \
  -H "Authorization: Bearer $TRIGGER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "invoice": "INV-1042" }'

Jira automation

Run a Code Studio script is an action in Jira automation. It needs Jira: the Jira listing, or the Confluence listing with Jira connected.

Later steps read the run’s runId, status and, when it finished within the wait, its result as JSON. A failed run fails the step. The rule runs the script as the app.

Their smart values are {{triggeredCodestudioRun.runId}}, {{triggeredCodestudioRun.status}} and {{triggeredCodestudioRun.result}}. Jira builds the name from the action and allows no capital inside it, so it reads Codestudio.

Common questions

What can start a Code Studio script?

The console, a Jira or Confluence event through a listener, a schedule, a Jira automation rule, or an HTTP request through an API trigger.

How does an API trigger authenticate a request?

With its secret, sent as Authorization: Bearer <secret>. A secret in the address is refused.

Can a Confluence automation rule run a script?

Through an API trigger, with Send web request. Run a Code Studio script is an action in Jira automation.

How soon does a listener run after a change?

When Atlassian delivers the event, up to 3 minutes after the change.

Related

• Sandbox and production
• Fields and forms
• Limits

A problem or a question? Write to support@oktul.com or open a request in the Help Center (opens in a new tab).