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

アプリクイックスタートガイド

アプリは、YouTrack に特定の機能を追加するソフトウェアコンポーネントです。アプリを使用すると、システムのコア構造を変更することなく、システムの基本機能をカスタマイズおよび拡張できます。このモジュール方式により、YouTrack の機能を動的に強化し、組織のニーズに合わせてより柔軟かつ適応性の高いものにすることができます。

アプリを作成して YouTrack で使用を開始するには、次の手順に従います。

アプリパッケージを作成する

カスタムウィジェットを構築する最も早い方法は、YouTrack アプリジェネレーターを使用することです。ジェネレーターを実行すると、次のようになります。

  • ジェネレーターは基本的なプロジェクト構造を構築し、必要な依存関係をすべてインストールします。

  • コマンドラインのプロンプトを使用すると、manifest.json ファイル内の必須フィールドの値を指定できます。

  • サンプルウィジェットのコードは app サブディレクトリに保存されています。

新しい YouTrack アプリのコードを生成するには:

  1. アプリ用の空のディレクトリを準備します。

  2. コマンドラインツールを使用して、次のコマンドを実行します。

    npm create @jetbrains/youtrack-app

  3. ジェネレーターが提供するプロンプトに従ってください。

以下は、YouTrack アプリジェネレーターを使用して作成されたアプリパッケージのファイル構造を示すイメージです。

File structure of a sample app

パッケージ内でファイルを移動する必要がある場合は、ファイル構造を管理するための次のガイドラインに注意してください。

  • manifest.json ファイルは常にアプリパッケージのルートレベルに存在する必要があります。

  • 各ウィジェットのソースコードは、widgets フォルダーのサブディレクトリに保存する必要があります。widgets フォルダーは、アプリパッケージ内の任意の場所に配置できます。

    各ウィジェットには index.html が含まれている必要があります

    コンテンツを定義するファイル。このファイルは、対応するウィジェットのコードを含む widget フォルダーまたはそのサブディレクトリのいずれかに存在する必要があります。index.html ファイルを親ディレクトリに保存しないでください。

  • HTTP ハンドラーとその他の JavaScript ベースのモジュールのソースコードをルートレベルの別々のファイルに保存します。

アプリマニフェストを更新する

各アプリパッケージには manifest.json ファイルが含まれている必要があります。このマニフェストには、アプリとその構造に関する一般的な情報が含まれています。

マニフェストの詳細については、App Manifest を参照してください。

以下に、アプリの構造を定義するために変更できるマニフェストテンプレートを示します。このテンプレートには、JetBrains マーケットプレイスのアプリでサポートされているすべてのフィールドが含まれています。

{ "$schema": "https://json.schemastore.org/youtrack-app.json", "name": "template-app", "title": "Template App", "description": "App description", "version": "1.0.0", "url": "https://github.com/example/youtrack-app", "icon": "icon.svg", "iconDark": "icon-dark.svg", "minYouTrackVersion": "2022.2.0", "maxYouTrackVersion": "2024.2.0", "changeNotes": "Version 0.0.1: Feature 1", "vendor": { "name": "JetBrains s.r.o.", "url": "https://www.jetbrains.com/", "email": "support@jetbrains.com" }, "widgets": [ { "key": "sample-widget", "name": "Sample Widget", "description": "Optional widget description", "extensionPoint": "ISSUE_FIELD_PANEL_FIRST", "indexPath": "index.html", "iconPath": "icon.png", "settingsSchemaPath": "sample-widget-settings.json", "permissions": ["ISSUE_READ", "ADMIN_READ_APP"], "defaultDimensions": { "height": "40px", "width": "80%" }, "expectedDimensions": { "height": 40, "width": 150 } } ] }

アプリ設定のスキーマを提供する

アプリ開発者は、アプリのカスタム設定を提供できます。設定スキーマは settings.json ファイルに記述されています。これらの設定は、アプリの設定タブで構成するためにアクセスできます。

システム管理者またはプロジェクト管理者がアプリ設定の値を指定すると、これらの値はアプリパッケージの JavaScript ベースのスクリプトで使用できます。アプリ設定の詳細については、アプリの設定を参照してください。

ここに 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" } } }

ウィジェットを追加する

各アプリパッケージには 1 つ以上のウィジェットを含めることができます。各ウィジェットのソースコードは、widgets フォルダーの名前付きサブディレクトリに保存されます。

アプリパッケージに含まれる各ウィジェットは、アプリマニフェストで宣言する必要があります。ウィジェットの説明で最も重要な部分は、extensionPoint プロパティです。このプロパティは、ウィジェットが埋め込まれる YouTrack UI 内の場所を指定します。

YouTrack UI で可能な拡張ポイントの完全なリストについては、拡張ポイントを参照してください。

ウィジェットは、YouTrack UI の専用拡張ポイントの 1 つに埋め込むことができるカスタムオブジェクトです。ウィジェットを実装するには、HTML の基礎を理解している必要があります。CSS を使用してカスタムレイアウトとフォーマットを追加することもできます。

以下は、課題のカスタムフィールドパネルの上に埋め込まれた顧客ロゴを表示するウィジェットのコードを含む、単純な HTML ファイルのサンプルコードです。

<!doctype html> <html> <head> <link rel="stylesheet" href="../index.css"> </head> <body class="plugin" style="padding: 0; overflow: hidden;"> <img src="logo.jpeg" style="width: 100%; height: 100%; object-fit: cover;"/> <script type="module"> const host = await YTApp.register(); </script> </body> </html>

HTTP ハンドラーを追加する

カスタム HTTP ハンドラーを作成して、カスタム HTTP エンドポイントを介してアプリから YouTrack データにアクセスできます。HTTP ハンドラーを追加するときは、次のガイドラインに従ってください。

  • 各 HTTP ハンドラーのソースコードは、アプリパッケージのルートレベルにある個別の JavaScript ファイルに保存する必要があります。

  • YouTrack は、HTTP ハンドラーのプログラミング言語として JavaScript のみをサポートします。

  • アプリマニフェストに HTTP ハンドラーへの参照を追加する必要はありません。

カスタム HTTP ハンドラーの詳細については、HTTP ハンドラーを参照してください。

以下はカスタム HTTP ハンドラーのサンプルコードです。

exports.httpHandler = { endpoints: [ { scope: 'issue', method: 'GET', path: 'demo', handle: function (ctx) { ctx.response.json({message: "Hello World"}); } } ] };

このコードを別の sample-http-handler.js ファイルに保存し、アプリパッケージのルートレベルに配置します。

HTTP ハンドラーを使用するには、ウィジェットからそのメソッドを呼び出します。以下はサンプルの HTML スクリプトブロックです。

<script type="module"> const host = await YTApp.register(); host.alert('Hello world'); </script>

HTTP ハンドラーの使用の詳細については、HTTP ハンドラーを参照してください。

モジュールを追加する

YouTrack は、アプリに追加できる JavaScript ベースのモジュールをいくつかサポートしています。使用可能なモジュールのリストは次のとおりです。

利用可能なモジュールの詳細については、アプリリファレンスを参照してください。

YouTrack にアプリをアップロードする

アプリをテストする準備ができたら、YouTrack にアップロードできます。アプリをテストするには、ステージング環境を作成する必要があります。いくつかのオプションがあります。

  • YouTrack クラウドにインスタンスを登録します。YouTrack Cloud は常に最新バージョンに更新されるため、最新のバグ修正が適用された安定した環境でテストできることが保証されます。

    実稼働環境も JetBrains でホストされている場合は、テストにもこの環境を使用することを強くお勧めします。

  • ローカルマシンに YouTrack Server のコピーをダウンロードして実行します。YouTrack Server インストールを使用している場合は、これにより、運用環境に現在インストールされているのと同じ製品バージョンでアプリをテストできます。

YouTrack アプリジェネレーターを使用してアプリを作成する場合は、次のコマンドを使用してアプリをビルドし、対象の YouTrack サイトにアップロードできます。

  • npm run build

    このコマンドは、アプリパッケージをコンパイルし、アップロードの準備をします。

  • npm run upload -- --host <your YouTrack base URL> --token <permanent token>

    このコマンドは、YouTrack テスト環境のベース URL を使用して、host として指定された YouTrack サイトにアプリパッケージをアップロードします。

    permanent token の場合、アプリのアップロードに使用する YouTrack アカウント用に生成された永久トークンを提供する必要があります。このアカウントには、システム内のすべてのプロジェクトに対するプロジェクトの更新権限が必要です。永久トークンの生成方法については、YouTrack のドキュメントを参照してください。

以下の手順に従って、ZIP アーカイブを YouTrack サイトにアップロードすることもできます。この手順は認証されたユーザーによって YouTrack で直接実行されるため、永続的なトークンを生成する必要はありません。

YouTrack にアプリを手動でアップロードするには:

  1. YouTrack のテスト環境にアクセスします。

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

  3. アプリを追加ボタンをクリックして ZIP ファイルをアップロードオプションを選択します。

  4. お使いのマシン上の ZIP アーカイブを選択し、YouTrack にアップロードします。

    • アプリは、YouTrack テスト環境のアプリリストに追加されます。

    • アプリとすべてのモジュールはデフォルトで有効になっています。

  5. アプリがアップロードされ、そのモジュールがアクティブになっていることを確認するには、リストでアプリを見つけて選択します。

    • 選択したアプリの詳細パネルが開きます。

    The details panel for an app.

アプリモジュールは、さまざまなレベルで機能するように構築できます。一部のモジュールはプロジェクトレベルで動作するように設計されており、異なるプロジェクトで個別にアクティブ化できます。他のモジュールは特定のプロジェクトとの接続がなく、グローバルレベルで機能します。

  • アプリが YouTrack にインポートされアクティブ化された時点で、グローバルレベルのモジュールが YouTrack システム全体で利用できるようになります。

  • プロジェクトレベルのモジュールの使用を開始するには、YouTrack のプロジェクトにアプリをアタッチします。アプリ管理ページから、またはプロジェクト設定のアプリタブから、アプリをプロジェクトにアタッチできます。

プロジェクトレベルおよびグローバルレベルのモジュールスコープの詳細については、グローバルおよびプロジェクト範囲を参照してください。

アプリ管理ページからプロジェクトにアプリをアタッチするには:

  1. アプリのリストからアプリを選択し、詳細パネルを開きます。

  2. プロジェクトタブを選択します。

    The Projects tab of an app

  3. プロジェクトの管理ボタンをクリックしてください。

    • プロジェクトの管理ダイアログが開きます。

    Manage projects where an app is attached

  4. リストから 1 つ以上のプロジェクトを選択します。

  5. 完了したら、保存ボタンをクリックします。

    • アプリは選択されたすべてのプロジェクトにアタッチされ、アクティブ化されます。

アプリの操作

アプリのテストと更新が完了したら、組織内で使用できるようになります。新しいアプリを YouTrack にアップロードするには、グローバルレベルでプロジェクトの更新権限を持っているか、システムで低レベルの管理者書き込み権限を持っている必要があります。運用環境でこのレベルのアクセス権を持っている場合は、自分でアプリをアップロードしてアクティブ化できます。そうでない場合は、ZIP アーカイブを管理者と共有して、代わりにアップロードしてもらう必要があります。

アプリが YouTrack にアップロードされアクティブ化されると、あなたのチームはアプリが提供する拡張機能を利用できるようになります。

アプリを公開する

最後のオプションのステップは、アプリを JetBrains マーケットプレイス(英語)にアップロードして、YouTrack と連携している他の企業とアプリを共有することです。

アプリをマーケットプレイスにアップロードするには:

  1. Web ブラウザーで JetBrains マーケットプレイス(英語)にアクセスします。

  2. ヘッダーのサインインボタンをクリックしてください。

    • すでに JetBrains アカウントをお持ちの場合は、メールアドレスとパスワードを入力してください。

    • JetBrains アカウントをお持ちでない場合は、あなたのメールアドレスで登録してアカウントを作成してください。

  3. ヘッダーでプラグインのビルドオプションを選択します。

  4. プラグインのアップロードボタンをクリックしてください。

    • プラグインのアップロードページが開きます。

  5. ページのベンダーの詳細セクションで、アプリを個人または組織としてアップロードするオプションを選択します。個人オプションを選択すると、アカウントのベンダープロファイルを作成するように求められます。

  6. ページのプラグインの詳細 — プラグインセクションで、YouTrack を選択します。

  7. プラグインファイルフィールドでは、ファイルの選択ボタンをクリックし、アプリパッケージが含まれている ZIP アーカイブを選択します。

  8. ライセンスの場合、ソフトウェアの配布に使用しているライセンスを選択します。

  9. アプリがオープンソースの場合は、リポジトリの場所をソースコード URL として入力します。

  10. タグ設定を使用して、アプリに 1 つ以上のラベルを割り当てます。これらのラベルは、ユーザーがマーケットプレイスで関連するアプリを見つけるのに役立ちます。

  11. プラグインをアップロードボタンをクリックしてください。

    • アプリが JetBrains マーケットプレイスにアップロードされます。

    • モデレーターがアプリをレビューし、公開を承認すると、アプリはディレクトリに追加されます。

アプリ入門 アプリパッケージの概要

関連ページ：

App Manifest

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

拡張ポイント

YouTrack は、アプリ開発者が UI にウィジェットを埋め込むことができる拡張ポイントのコレクションを提供します。これらのウィジェットは、ユーザーがアプリをインストールしてアクティブ化しない限り利用できない特定の操作をサポートします。このページでは、これらの拡張ポイントに関する情報を確認できます。ここでは、すべての可能な拡張ポイントとそのスコープの概要を示します。ウィジェットのスコープの詳細については、スコープを参照してください。ADMINISTRATION_MENU_ITEM グローバル管...

SLA ポリシー

SLA ポリシーまたはサービスレベル契約ポリシーは、サービスプロバイダーとして顧客のリクエストに対応する際に従うことに同意するポリシーです。YouTrack では、SLA ポリシーにより、スタッフからの応答と要求の解決までの時間ゴールが定義されます。YouTrack に SLA ポリシーを設定すると、顧客のリクエストに対してスタッフが適切な対応を行うことができます。営業時間の設定：各ヘルプデスクプロジェクトの SLA の一部として、顧客がエージェントからの返信を期待できる時間枠を指定する必要が...

永久トークンの管理

YouTrack サーバーでは、永久トークンにより、開発者は OAuth 2.0 認証フローを実装しなくても、スクリプトとアプリケーションで RESTAPI 呼び出しを使用して安全に操作にアクセスして実行できます。永久トークンは、ユーザーアカウントに付与されたアクセス許可を持つサービスへのアクセスを許可します。このページでは、ユーザープロファイルで実行される永久トークンを使用した操作について説明します。永久トークンを使用した RESTAPI 呼び出しのサンプルについては、永久トークン認証を参照し...

アプリパッケージの概要

このページでは、アプリパッケージとそのコンポーネントの概要を説明します。アプリパッケージ：サンプルアプリパッケージのファイル構造は次のとおりです。パッケージの主なコンポーネントは次のとおりです。アプリマニフェストは、アプリパッケージのルートレベルに保存される JSON ファイルです。アプリ設定のカスタムスキーマ。各ウィジェットのサブフォルダーを含むフォルダー。管理ウィジェットのサブフォルダー。このサブフォルダーには、このウィジェットで使用されるファイルおよびその他の補足ファイルが含まれています...