リファレンス

これは ONEScript スクリプトを書くための構文とヘルパーのリファレンスです。タスクベースのガイダンスについては、まずはじめにとガイドをご覧ください。すぐに応用できるレシピについては、クックブックを参照してください。

トリガー​

スクリプトのトリガーは、いつ実行されるか、そして何が許可されるかを決めます。ONEScript は 7 種類のトリガータイプを提供します。

トリガーポリシーマトリクス​

L0 トリガーは同期的で高頻度のため、ネットワークもストレージも使えません。L1 トリガーは、読み取り/書き込みルールに従う範囲で、制御されたアダプターを使えます。

現在のトリガーで許可されていないヘルパーは、公開前にエディターのインライン診断によってフラグが付けられます。

スクリプトコンテキストオブジェクト​

スクリプト内では、次のオブジェクトを利用できます。

セマンティックフィールド構文​

読みやすい構文は、フィールド、ステータス、プロジェクト、課題タイプ、オプションを表示名で解決します。名前と値は大文字小文字を区別し、完全一致します。User Story と User story は別の値であり、ランタイムが小文字化したりあいまい一致したりすることは決してありません。

現在値のチェック​

issue.project.is("Project Name")
issue.issueType.is("Requirement")
issue.status.is("In Review")
issue.statusCategory.is("In progress")
issue.field("Priority").is("Highest")

フィールドの識別​

• issue.field("Field Name") は課題のフィールドメタデータに対して解決します。正確なフィールド表示名またはフィールド UUID が有効です。推測した名前、翻訳した名前、あいまいな名前は無効です。
• 2 つのフィールドが同じ表示名を共有している場合、その参照はあいまいです。推測する代わりに、一意な名前またはフィールド UUID を指定してください。

型を意識した値​

値は単なる文字列として扱われません。ONEScript はすべての値をフィールドの型に応じて解釈・エンコードします。これは値が読み取られ、比較され、書き込まれるあらゆる場所に適用されます。.is(...)、.contains*(...) / .isExactly(...)、変更ヘルパー（.changedTo(...)、.changedFrom(...)）、issue.update({...}) による書き込みは、すべて同じ型ルールを使います。値は自然で人間が理解できる形式（表示名、業務上の数値、日付文字列、ブール値）で指定すれば、ランタイムがそれを保存形式に変換し、比較時にはまた元に戻します。

解決が型を意識して行われるため、同じ値がマッチングでも書き込みでも機能します。例えば issue.field("Sprint").is("Sprint 12") と issue.update({ Sprint: "Sprint 12" }) は、いずれも "Sprint 12" を保存された ID に解決します。表示値は大文字小文字を区別し、完全一致のままです。

複数値のマッチング​

複数値フィールドでは、意図に合うヘルパーを選んでください。

issue.field("Tags").is("A")                 // この 1 つの値を含む
issue.field("Tags").is(["A", "B"])          // 完全な集合の一致（順序は問わない）
issue.field("Tags").containsAll(["A", "B"]) // これらすべてを含む
issue.field("Tags").containsAny(["A", "B"]) // これらのうち少なくとも 1 つを含む
issue.field("Tags").isExactly(["A", "B"])   // ちょうどこの集合

複数値の意図には containsAll / containsAny / isExactly を優先してください。読みやすく、正式な形式です。

変更ヘルパー​

event、taskActionDone、taskPreAction でのみ利用可能です（変更フィールド情報を持つトリガー）。

issue.anyFieldChanged()
issue.anyStatusChanged()
issue.status.changedTo("Done")
issue.statusCategory.changedTo("In progress")
issue.statusCategory.changedFromTo("To do", "In progress")
issue.assignee.changedTo("Bob")
issue.assignee.changedFromTo("Alice", "Bob")
issue.field("Found in Production").changedTo("Yes")
issue.field("Priority").changedFrom("Low")
event.changedField("Status").isChanged()

updated イベントでのステータス関連ルールには、issue.anyStatusChanged() に加えて issue.status.changed* または issue.statusCategory.changed* を優先してください。

書き込みヘルパー​

書き込み可能なトリガー（taskActionDone、event、timer）でのみ利用可能です。api.reject(...) は例外で、taskPreAction に属します。

issue.update({ Priority: "Highest" })          // 正式なバッチフィールド更新
issue.addComment("Handled by ONEScript.")       // プレーンテキストのコメントを追加
api.reject("Reason shown to the user.")          // taskPreAction のみ

コメントとメンション​

issue.addComment({
  text: "The status changed, please check",
  mentions: [issue.assignee.mention()]
})

issue.addComment(...) はサポートされています。メンション（.mention() / .mentions()）は文書化されていますが、再検証待ちです。依拠する前に、ドライラン / 実行ログで検証してください。

カスタムメンバーフィールドには、issue.field("Reviewer").mention()（単一ユーザー）または issue.field("Reviewers").mentions()（複数ユーザー）を使ってください。コメントテキストは text に保持し、フィールドヘルパーでメンションを供給できる場合は生のユーザー UUID を読み取らないでください。

遷移のブロック： 変更をブロックするのは api.reject(...) だけです。スローしたり、タイムアウトしたり、ポリシー制限に達したりしたスクリプトは診断のためにログに記録されますが、遷移をブロックしません。そのため、api.reject(...) を意図的に呼び出すか、何もしないかのいずれかのガードを書いてください。

データのクエリ​

const issues = await api.queryIssues({
  query: "select uuid, name from issues limit 20",
  variables: []
})
api.log("Matched issues: " + issues.length)

ネットワークが許可されている場所（L1 トリガー）で利用できます。1.0 には専用のクエリ UI はありません。クエリはスクリプト内で行います。

ランタイムの状態と変数​

const token = vars.get("WEBHOOK_TOKEN")                 // リソース → 変数
const cursor = await api.storage.get("lastCursor")       // get: 読み取り専用、L1 で OK
await api.storage.set("lastCursor", { issue: context.taskUUID }) // set/delete: 書き込み可能な L1
api.log("Cursor saved")

api.storage は ONEScript 自身のランタイム状態です。（これは Hosted-App のオブジェクト/エンティティストレージではありません。それは 1.0 では公開されていません。）

外部 HTTP と OpenAPI​

外部 HTTP​

const response = await api.fetchExternal({
  url: "https://example.com/hooks/onescript",
  method: "POST",
  headers: { Authorization: "Bearer " + vars.get("WEBHOOK_TOKEN") },
  body: { issue: context.taskUUID },
  timeoutMs: 5000
})
api.log("Webhook status: " + response.statusCode)

ルール：

• L1 のネットワーク可能なトリガーのみ（taskPreAction や scriptedField は不可）。
• ランタイムは localhost、プライベートネットワーク、メタデータアドレス、.local ホストをブロックします。許可リスト（SCRIPT_RUNNER_HTTP_ALLOWLIST）によってホストがさらに制限される場合があります。
• トークンは vars.get(...) を通じて読み取ってください。トークン、認証ヘッダー、シークレットのペイロードは決してログに出力しないでください。
• アダプターを使ってください。生の fetch は決して使わないでください。

OpenAPI ヘルパー（制限あり）​

カタログに基づくヘルパーは、名前で ONES OpenAPI を呼び出します。名前空間には openapi.issue.*、openapi.workflow.transit、openapi.issueComment.*、openapi.worklog.*、openapi.wiki.*、openapi.account.*、openapi.project.*、openapi.testcaseLibrary.* が含まれます。

const response = await openapi.issue.create({
  query: { teamID: context.teamUUID },
  body: {
    projectUUID: context.projectUUID,
    issueTypeUUID: context.issueTypeUUID,
    summary: "Follow-up from ONEScript"
  }
})
api.log("Created issue status: " + response.statusCode)

openapi.request(...) / api.fetchOpenAPI(...) はエスケープハッチですが、それでもトリガーポリシーと操作チェックに従います。OpenAPI のパスやヘルパー名を勝手に作り出さないでください。

注意すべき現在の制限：

• Copilot ヘルパー — 検証済みプロファイルではサービスレベルでブロックされています。
• サマリー工数ログヘルパー — 一致するチーム工数ログプロファイルでゲートされています。
• Hosted-App のオブジェクト/エンティティストレージ — 公開されていません。api.storage を使ってください。

インバウンド REST エンドポイント​

httpEndpoint スクリプトは、外部システムが HTTP 経由で呼び出します。ScriptRunner の「カスタム REST エンドポイント」に相当します。REST エンドポイントタブで作成します（公開済みの httpEndpoint スクリプト、slug、認証モードを選びます）。POST /hooks/<slug>（POST のみ）でアクセスします。

context.request でリクエストを読みます。

api.response.send(...) でレスポンスを送ります。そうしない場合、スクリプトの通常の出力が 200 の JSON ボディになります。

const order = context.request.body
api.response.send({
  status: 201,
  headers: { "Content-Type": "application/json" },
  body: { received: order.id }
})

失敗状態（タイムアウト、ポリシー拒否、拒否）は安全なステータスコードにマッピングされ、スクリプトの出力を漏らしません。

認証（エンドポイントごとに設定）：

ポリシー。 L1 — ネットワーク、書き込み、ストレージが許可されます。10 秒のタイムアウト、256 KB のレスポンス上限。スクリプトは自身のエンドポイントの認証シークレットを読むことはできません。

サンドボックスで禁止されているもの​

スクリプト検証は、動的なエスケープハッチとホストアクセスを拒否します。

eval、Function、require、動的な import、モジュールローダー、process、globalThis、Buffer、ファイルシステム（fs）、子プロセスアクセス、そして生の fetch です。また、サンドボックスグローバルの可能性が高いタイポや、サポートされていないヘルパーシグネチャも、公開やドライランの前にフラグを立てます。

サポートされていない機能​

ONEScript 1.0 は次をサポートしません。

• フォームが開く前にネイティブの ONES 遷移/アクションボタンを非表示にすること（taskPreAction は送信時に拒否できますが、ボタンの早期の表示制御はできません）。
• 完全な Jira Behaviours（フォーム入力中の任意のネイティブフィールドの非表示/表示/名前変更/説明変更）。
• 選択/リストのスクリプトフィールド（数値 float のみ。選択/リストは ONES でネイティブに対応）。
• SaaS のネイティブスクリプトフィールド（現在はプライベートデプロイ向けに限定）。
• カスタム JQL / ネイティブ ONESQL 関数の注入。
• 任意の Node.js、ファイルシステム、プロセス、パッケージインポート、生の HTTP、または制限のないランタイムアクセス。
• L0 トリガー（taskPreAction、scriptedField）でのネットワークまたはストレージ（OpenAPI の読み取りを含む）。
• Hosted-App のオブジェクト/エンティティストレージへの書き込み。OAuth トークンまたはアプリ認可の管理エンドポイント。
• ユーザーのなりすまし / 別ユーザーとしての実行。

これらが Jira/ScriptRunner からどのようにマッピングされるかについては、Atlassian からの移行を参照してください。

バージョン管理​

このリファレンスは ONEScript 1.0（ビルド 1.0.8）を対象としています。アップグレードする際は、次を再確認してください。

• トリガーの一覧とポリシーマトリクス、
• ヘルパーの可用性（特に OpenAPI の名前空間とメンション）、
• サポートされていないもののリスト。

変更履歴は早期プレビュー以降維持されています（リソース → 変更履歴を参照してください）。