YouTrack および Hub ヘルプの開発者ポータル

アプリの設定

アプリ開発者は、アプリにカスタム設定を追加できます。YouTrack のシステム管理者またはプロジェクト管理者は、アプリの設定タブで、それぞれグローバルレベルまたはプロジェクトレベルでアプリ設定の値を指定できます。

設定値は、アプリパッケージ内のカスタム JavaScript スクリプト (HTTP ハンドラー、ワークフロールール、その他のスクリプトなど) で使用できます。設定値は ctx.settings.<settingName> として参照できます。

JS コードとコードサンプルでアプリ設定を使用する方法の詳細については、スクリプトで設定値を使用するを参照してください。

アプリ設定を定義する

カスタムアプリ設定を定義するには、settings.json という名前のファイルをアプリパッケージに追加します。settings.json ファイルは、YouTrack 側で検証されるために、JSON スキーマ 2020-12 に準拠している必要があります。JSON スキーマ 2020-12 の詳細については、JSON スキーマドキュメント(英語)を参照してください。

サンプル設定ファイル

ここでは、アプリの settings.json ファイルの例を見つけることができます。

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "title": "App Settings", "description": "Here you can provide values for the app settings", "properties": { "stringSetting": { "title": "Name", "type": "string", "minLength": 1 }, "booleanSetting": { "type": "boolean" }, "integerSetting": { "type": "integer", "x-scope": "GLOBAL" }, "numberSetting": { "type": "number", "x-scope": "PROJECT" }, "secretSetting": { "type": "string", "format": "secret" }, "arraySetting": { "type": "array", "items": { "x-entity": "User", "type": "object" } }, "userSetting": { "type": "object", "x-entity": "User" } } }

サポートされている設定タイプ

カスタムアプリ設定には、次のいずれかのエンティティタイプを使用できます。

  • string
  • integer
  • number
  • boolean
  • array
  • object
  • secret

設定宣言

settings.json ファイルには次のフィールドがあります。

フィールド

タイプ

説明

必須

type

文字列

settings.json ファイルのルートに配置されているエンティティのタイプ。このフィールドの値は常に object である必要があります。

✓

title

文字列

設定宣言を含むファイルのタイトル。このタイトルはアプリの設定タブに表示されます。

このタイトルを使用すると、このアプリで構成できる設定に関する詳細情報をアプリユーザーに提供できます。

description

文字列

設定宣言が書かれたファイルの説明です。アプリの設定タブのタイトルに表示されます。

この説明を使用すると、このアプリで構成できる設定に関する詳細情報とコンテキストをアプリユーザーに提供できます。

properties オブジェクト

アプリ設定の定義を含むオブジェクト。

✓

required

Array。<string>

必要なアプリ設定を表すプロパティの配列。

Properties

各アプリ設定は、settings.json ファイル内の properties オブジェクトのフィールドとして宣言する必要があります。

properties オブジェクトの各キーは設定のキー名を表し、フィールド値は設定を定義するオブジェクトです。

YouTrack アプリは、JSON スキーマドラフト 07(英語) のプロパティパラメーターをサポートします。

プロパティは次のパラメーターで定義されます。

パラメーター

タイプ

説明

必須

const

任意

プロパティが制限される値。

description

文字列

設定の説明。設定にテキストラベルとして UI に表示されます。

enum

配列。<任意>

ユーザーが選択できる値のクローズドリストを定義します。リストの各要素は一意である必要があります。

exclusiveMaximum

数

数値の排他的上限。このパラメーターは、integer および number 型の設定にのみ適用されます。

exclusiveMinimum

数

数値の排他的下限。このパラメーターは、integer および number 型の設定にのみ適用されます。

format

文字列

期待値の形式。YouTrack アプリは JSON スキーマドラフト 07(英語) の形式をサポートします。

利用可能な形式の詳細については、以下を参照してください。

フォーマット

説明

secret

パスワードや非表示にする必要があるその他の入力値にはこの形式を使用します。

date

日付。この形式の設定では、ユーザーが日付を選択するためのカレンダーが表示されます。

items

オブジェクト

このパラメーターは、array -typed パラメーターに使用する必要があります。このパラメーターの値は、コア YouTrack エンティティの 1 つへの参照を含むオブジェクトです。詳細については、配列を参照してください。

maximum

数

この設定に許可される値の非排他的上限。このパラメーターは、integer および number 型の設定にのみ適用されます。

maxLength

integer

この設定が受け入れる文字列の最大長。このパラメーターは、string 型の設定にのみ適用されます。

minimum

数

この設定で許可される値の非排他的下限。このパラメーターは、integer および number 型の設定にのみ適用されます。

minItems

integer

配列内の項目の最小数。このパラメーターは、array 型の設定にのみ適用されます。

array -typed 設定を必須にするには、このパラメーターを使用し、必要な設定の配列にも設定をリストします。

minLength

integer

この設定が受け入れる文字列の最小の長さ。このパラメーターは、string 型の設定にのみ適用されます。

multipleOf

数

値は、このパラメーターの値で割った結果が整数になる場合にのみ有効です。値は 0 より大きくなければなりません。

このパラメーターは、integer および number 型の設定にのみ適用されます。

readOnly

boolean

true の場合、設定の値は読み取り専用であり、更新できません。

title

文字列

YouTrack UI のアプリ設定に表示される設定の名前。

✓

type

文字列

設定値として期待されるエンティティのタイプ。次のタイプが許可されます。

  • string
  • integer
  • number
  • boolean
  • array
  • object

array および object タイプは、YouTrack コアエンティティのみを表すことができます。これらのタイプの詳細と、アプリ設定での使用方法については、値の設定に YouTrack エンティティを使用するを参照してください。

✓

x-entity

文字列

このパラメーターは、アプリ設定で使用できる YouTrack コアエンティティを参照します。これは、array および object 型の設定にのみ使用できる特別な設定パラメーターです。

array -typed 設定の場合、このパラメーターの値は配列内のエンティティの型を表します。

詳細については、値の設定に YouTrack エンティティを使用するを参照してください。

x-scope

文字列

設定の範囲を定義します。

使用可能な値:

スコープ

説明

GLOBAL

このスコープの設定は、グローバルレベルでのみ構成できます。

PROJECT

このスコープの設定は、プロジェクトレベルでのみ構成できます。

配列

各 array -typed プロパティは、次のパラメーターを使用して定義する必要があります。

パラメーター

タイプ

説明

必須

x-entity

文字列

このパラメーターは、アプリ設定の配列で使用できる YouTrack コアエンティティを参照します。これは、array および object 型の設定にのみ使用できる特別な設定パラメーターです。

array -typed 設定の場合、このパラメーターの値は配列内のエンティティの型を表し、array -typed プロパティの対応する x-entity パラメーターの値と一致する必要があります。詳細については、値の設定に YouTrack エンティティを使用するを参照してください。

✓

type

文字列

パラメーターの型を定義します。items オブジェクトの場合、このパラメーターは常に object に設定する必要があります。

✓

値の設定に YouTrack エンティティを使用する

array および object 型のアプリ設定では、設定値にコア YouTrack エンティティの一部を使用できます。x-entity 設定パラメーターは、特定の設定でアプリが期待する YouTrack エンティティの正確な型を定義します。

アプリ設定では次の YouTrack エンティティを使用できます。

  • Issue
  • Article
  • Project
  • User
  • UserGroup

アプリ設定の値を構成する

YouTrack でインストールされたアプリを構成する場合、グローバルレベルまたはプロジェクトレベルでアプリの設定を指定できます。プロジェクトレベルで構成された設定は優先度が高く、グローバル設定を上書きします。アプリ設定にプロジェクトレベルの値を設定していない場合は、これらの設定のグローバルレベルの値が適用されます。

グローバルレベルでアプリ設定の値を設定するには:

  1. 管理メニューからアプリを選択します。

  2. リストから対象のアプリを選択します。

  3. このアプリの設定タブを開きます。

  4. アプリの設定の値を更新します。

  5. 準備ができたら、保存ボタンをクリックしてください。

    • アプリ設定の値はグローバルレベルで保存されます。

    • このアプリがアタッチされ、アプリ設定がグローバルアプリ設定と同期されているすべてのプロジェクトで値が更新されます。

プロジェクトレベルでアプリ設定の値を設定するには:

  1. プロジェクト設定で、アプリタブを開きます。

  2. リストから対象のアプリを選択します。

  3. このアプリの設定タブを開きます。

  4. アプリの設定の値を設定します。

  5. 準備ができたら、保存ボタンをクリックしてください。

    • アプリ設定の値はプロジェクトレベルで保存されます。

    • 設定した値は、これらの設定のグローバルレベルの値をすべて上書きします。

    • 更新した設定は、アプリのグローバル設定と同期されなくなります。

シークレットの設定の操作

secret を保存するようにフォーマットされた設定を宣言すると、YouTrack は設定に保存された値を他の設定とは異なる方法で処理します。これらの値は安全に保存され、アプリケーションの承認された部分だけがアクセスできるようになります。つまり、ユーザーは認証トークンとアプリを承認するための資格情報を保存でき、この情報が他人の手に渡ることはありません。

YouTrack は、シークレットとして保存された値を次のように処理します。

  • 秘密が保存されると、YouTrack 内のどこからも誰もそれを読み取ることができなくなります。実際の値は、HTTP リクエストを認証する必要がある場合にのみ http.js パッケージで使用されます。

  • http.js パッケージを使用して送信された HTTP リクエストは JVM 内で処理されるため、シークレット設定に保存された値はログのどこにも表示されません。

You can also declare secret settings as required in the Settings.json file. When declare as required, the app remains inactivated until these settings are configured, and a corresponding warning is displayed in the アプリ admin UI. This ensures that the app cannot be activated with empty values for secret settings, preventing potential failures in HTTP requests.

スクリプトで設定値を使用する

アプリパッケージ内の任意の JavaScript ベースのスクリプトで、設定値を ctx.settings.<settingName> として参照できます。例: HTTP ハンドラー、ワークフロールール、インポートスクリプト、その他の JS スクリプトで設定値を使用できます。

HTTP ハンドラーで設定値を使用するコードサンプルを次に示します。

const entities = require('@jetbrains/youtrack-scripting-api/entities'); exports.httpHandler = { endpoints: [ { method: 'GET', path: '/test', scope: 'issue', handle: function (ctx) { const issue = ctx.issue; issue.description = ctx.settings.stringSetting; if (ctx.settings.booleanSetting) { console.log('integer: ' + ctx.settings.integerSetting); console.log('number: ' + ctx.settings.numberSetting); console.log('array size: ' + ctx.settings.arraySetting.size); } issue.Assignee = ctx.settings.userSetting; } } ], requirements: { Assignee: { type: entities.User.fieldType } } };

secret 形式の設定を使用する HTTP ハンドラーのコードサンプルを次に示します。

const http = require('@jetbrains/youtrack-scripting-api/http'); const URL = "http://some-third-party-service.io/api"; exports.httpHandler = { endpoints: [ { method: 'POST', path: '/test', handle: function (ctx) { let connection = new http.Connection(URL); // set 'Authorization: Bearer <token>' header with the secret app setting connection.bearerAuth(ctx.settings.secretSetting); connection.addHeader('Content-Type', 'application/json'); let response = connection.postSync("/test", {}, requestJson); } } ] };
App Manifest 拡張機能のプロパティ