App Manifest

各アプリパッケージには、パッケージディレクトリのルートに manifest.json ファイルが含まれている必要があります。マニフェストファイルには、アプリの名前、説明、アプリに含まれるモジュールのリストなど、アプリに関する一般的な情報が記載されています。

サンプルマニフェスト

以下はアプリのサンプルマニフェストです。

{ "$schema": "https://json.schemastore.org/youtrack-app.json", "name" : "sample-app", "title" : "Sample App", "description" : "App description", "version": "1.0.0", "url": "https://github.com/example/youtrack-app", "icon": "icon.svg", "iconDark": "icon.svg", "minYouTrackVersion": "2022.2.0", "maxYouTrackVersion": "2024.2.0", "changeNotes": "Version 0.0.1: Feature 1", "vendor": { "name": "JetBrains", "url": "jetbrains.com", "email": "support@jetbrains.com" }, "widgets": [ { "key": "fields-first", "name": "Sample Widget", "description": "Optional description for the issue view widget", "extensionPoint": "ISSUE_FIELD_PANEL_FIRST", "indexPath": "index.html", "iconPath": "icon.png", "settingsSchemaPath": "sample-widget-settings.json", "permissions": ["READ_USER"], "defaultDimensions": { "height": "40px", "width": "80%" }, "expectedDimensions": { "height": "200", "width": "1000" } } ] }

マニフェストスキーマ

YouTrack アプリのマニフェストを検証するために使用されるスキーマは、SchemaStore(英語) でホストされています。その Web アドレスは、このページで提供されているサンプルマニフェストに含まれています。

JSON スキーマをサポートするエディターは、スキーマに基づいて自動補完とコンテキストヘルプを提供するため、開発環境でスキーマを必ずロードしてください。

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

フィールド	タイプ	説明	必須
`$schema`	文字列	YouTrack アプリのマニフェストを検証するために使用されるスキーマの Web アドレス。このスキーマは、https://json.schemastore.org/youtrack-app.json の SchemaStore でホストされています。 JSON スキーマをサポートするエディターは、スキーマに基づいて自動補完とコンテキストヘルプを提供します。これにより、マニフェストの作成と編集のプロセスが高速化されるため、この参照をファイルに必ず含めてください。
`name`	文字列	アプリの名前。これは、YouTrack で一意の識別子として使用されます。同じ名前のアプリを 2 つ YouTrack サイトにアップロードすると、同じ名前のアプリの既存のバージョンが上書きされます。これは、JetBrains マーケットプレイスでアプリの一意の ID としても使用されます。このフィールドには、小文字の英数字、ハイフン、アンダースコア、チルダのみを含めることができます。	✓
`title`	文字列	アプリのタイトル。これは、JetBrains マーケットプレイスと YouTrack UI に表示されるユーザーフレンドリーな名前です。このフィールドはオプションです。空の場合、その場所にアプリの名前が表示されます。
`description`	文字列	アプリの説明。この説明は、アプリ管理ページのアプリ詳細で確認できます。これは、JetBrains マーケットプレイスのアプリの説明としても使用されます。
`version`	文字列	`major.minor.bugfix` 形式でアプリパッケージに割り当てられたバージョン番号。デフォルト値は `0.0.0` です。
`url`	文字列	アプリの Web サイト。例: 会社または製品の GitHub ページまたはランディングページ。この値は、JetBrains マーケットプレイスではプラグインサイトとして表示されます。
`icon`	文字列	アプリアイコンのファイルの名前。このファイルをアプリパッケージのルートレベルに保存します。
`iconDark`	文字列	ダークテーマのアプリアイコンを含むファイルの名前。このファイルは、アプリパッケージのルートレベルに保存します。ダークテーマに別のアイコンを含めない場合、YouTrack はダークテーマとライトテーマの両方に `icon` イメージを使用します。
`minYouTrackVersion`	文字列	アプリと互換性のある最小の YouTrack バージョン。マニフェストで指定された値よりも低いバージョンを実行する YouTrack インストールでアプリをアップロードまたはインストールしようとすると、操作は失敗します。 JetBrains マーケットプレイスでは、この値を使用して、ユーザーが YouTrack サーバーのインストールと互換性のあるアプリを見つけられるようにします。このフィールドは、マニフェストスキーマの以前のバージョンの依存関係フィールドの `workflow-scripting-api` と下位互換性があります。
`maxYouTrackVersion`	文字列	アプリと互換性のある最大の YouTrack バージョン。マニフェストで指定された値よりも高いバージョンを実行する YouTrack インストールでアプリをアップロードまたはインストールしようとすると、操作は失敗します。
`changeNotes`	文字列	アプリの特定のバージョンで利用可能な変更の説明。この情報は、JetBrains マーケットプレイスにのみ表示されます。変更メモはマーケットプレイスで直接追加および更新することもできます。
`vendor`	ベンダー	アプリベンダーの説明を含むオブジェクト。この情報は、YouTrack サイトに直接アップロードされたアプリにのみ使用されます。JetBrains マーケットプレイスからインストールされたアプリは、マーケットプレイスのベンダープロファイルから名前、URL、メールを取得します。
`widgets`	配列 < ウィジェット >	アプリに含まれるウィジェットオブジェクトの配列。各ウィジェットはフロントエンド拡張機能を表します。

ウィジェット

各ウィジェットオブジェクトは、特定のフロントエンド拡張機能を表します。各ウィジェットは、ネイティブ YouTrack UI に埋め込むカスタムインラインフレーム (iFrame) オブジェクトです。

ウィジェットには次のフィールドがあります。

フィールド	タイプ	説明	必須
`key`	文字列	ウィジェットの一意の識別子。これはアプリ内で一意である必要がある必須フィールドです。このフィールドには、小文字の英数字、ハイフン、アンダースコア、ピリオド、チルダのみを含めることができます。	✓
`name`	文字列	YouTrack のアプリ設定に表示されるウィジェットのユーザーフレンドリーな名前。ウィジェット名は 1 つのアプリ内で一意である必要があります。
`description`	文字列	ウィジェットの説明。 `HELPDESK_CHANNEL` 拡張ポイントに埋め込まれたウィジェットに必要です。その他の拡張ポイントの場合はオプションです。
`extensionPoint`	文字列	ウィジェットが埋め込まれる YouTrack UI 内の場所。利用可能な拡張ポイントの完全なリストについては、拡張ポイントを参照してください。	✓
`indexPath`	文字列	ウィジェットのコンテンツと構造を定義する index.html ファイルへのパス。パスは、アプリパッケージ内のウィジェットフォルダーを基準とします。ソースコードを `index.html` という名前の HTML ファイルに保存します。このファイルを `widgets` フォルダーに直接配置するか、専用のサブフォルダーに配置します。	✓
`iconPath`	文字列	アプリパッケージ内のウィジェットのアイコンを含むファイルへの相対パス。 `HELPDESK_CHANNEL` 拡張ポイントに埋め込まれたウィジェットに必要です。 `ARTICLE_OPTIONS_MENU_ITEM` および `ISSUE_OPTIONS_MENU_ITEM` 拡張ポイントに埋め込まれたウィジェットの場合はオプションです。
`settingsSchemaPath`	文字列	Markdown ウィジェットの設定スキームを保存する JSON ファイルへのパス。これは、この特定のウィジェットのコードが保存されているフォルダー内のどこかにあるファイルへのパスである必要があります。
`permissions`	配列 <文字列>	ウィジェットを表示および使用するために必要な権限のセット。アプリのスコープに応じて、これらの権限はグローバルレベルまたはプロジェクトレベルで必要になる場合があります。プロジェクトスコープを持つウィジェット拡張ポイントの場合、プロジェクトカテゴリ権限はプロジェクトごとにチェックされます。例: プロジェクトスコープの `ISSUE_BELOW_SUMMARY` 拡張ポイントを使用するウィジェットを表示するためにプロジェクトカテゴリ `LINK_ISSUE` 権限が必要な場合、ユーザーには `LINK_ISSUE` 権限が付与されているプロジェクトで作業しているときのみこのウィジェットが表示されます。権限を参照するには、その一意の識別子を使用します。
`expectedDimensions`	オブジェクト	ウィジェットの予想される寸法（ピクセル単位）。モニターの設定で許可されている場合、YouTrack はこれらの寸法に従ってウィジェットを表示しようとします。サポートされている属性は、`width` (整数) と `height` (整数) です。このフィールドは、`MARKDOWN` と `DASHBOARD_WIDGET` を除くすべての拡張ポイントでサポートされています。これら 2 つの拡張ポイントのいずれかを使用するウィジェットに値が指定されている場合、その値は YouTrack によって拒否されます。
`defaultDimensions`	オブジェクト	ウィジェットのデフォルトの幅と高さ。サポートされている属性は、`width` (整数) と `height` (整数) です。このフィールドは、`MARKDOWN` および `DASHBOARD_WIDGET` 拡張ポイントを使用するウィジェットでのみサポートされます。他の拡張ポイントを使用するウィジェットに値が指定されている場合、YouTrack によって拒否されます。 `MARKDOWN` ウィジェットの場合、寸法をピクセルまたはパーセンテージで指定できます。例: `"width": "100px"` または `"height": "40%"` `DASHBOARD_WIDGET` の寸法は分数単位で指定されます。分数はダッシュボードグリッドの 1 つのセルに相当します。例: `"width": "8fr"`)