課題のインポート

準備

スクリプトを実行する前に行う必要があることがいくつかあります。

プロジェクト。両方のトラッカーでプロジェクトを確認してください。ステータスの種類は一致していますか ? Space プロジェクトに存在しない YouTrack ユーザーはいますか ? 可能であれば、事前に調整を行っておくと、置換またはスキップされるデータが少なくなります。不一致のユーザー名に対してできることはあまりありませんが (インポート中のマッピングと置換以外に)、たとえば、YouTrack には存在するが Space には存在しないステータスを追加することはできます。

権限。スクリプトがユーザーに代わって両方のプロジェクトにアクセスするため、両方のプロジェクトに対して十分な権限があることを確認してください。Space プロジェクトでは、プロジェクト管理者であるか、このロールに含まれる課題のインポート権限を持っている必要があります。YouTrack では、インポートするすべての課題に対する読み取り権限が必要です。通常、課題とそのフィールド、特に Status と Assignee が表示されれば、それをインポートできます。

認証。Space と YouTrack の両方からの認証トークンが必要です。スクリプトを実行するときに、引数値として指定します。YouTrack トークンをスキップできますが、課題が一般公開されており、どのゲストアカウントでも表示できる場合に限ります。

Docker。Docker インスタンスがマシンにインストールされ、実行されている必要があります。お持ちでない場合は、インストールガイド(英語)を参照してください。

スクリプトを実行する

スクリプトは、public.registry.jetbrains.space のパブリックレジストリに Docker イメージとして保存されます。

ターミナルで docker run コマンドを実行して、イメージを実行します。例:

すべてが計画どおりに動作するかどうかを確認するには、まず --dryRun 引数を渡してテストモードでスクリプトを実行します。Space では課題は作成されませんが、調査できるレポートが得られます。

このスクリプトをテンプレートとして使用し、特定のタスクに合わせてカスタマイズできます。コードは、GitHub (https://github.com/JetBrains/space-issues-import(英語)) で誰でも利用できます。

エンドポイント

POST /api/http/projects/{project}/planning/issues/import

ここで、{project} は、課題をインポートする Space プロジェクトの識別子です。プロジェクト ID またはプロジェクトキーのいずれかを使用できます。

key:MY-PROJECT-KEY

または

id:my-project-id

プロジェクトキーは、プロジェクト設定ページの情報タブで取得できます。または、API Playground を使用して正しい値を見つけます。

エンドポイントは、最も重要な課題フィールドに対応する多数のパラメーターを受け入れます。各課題について、概要 (課題のタイトル)、ステータス、課題 ID、担当者と説明をインポートできます。

リクエスト

外部ソースからフェッチされた課題データは、ネストされたキーと値のペアを持つ JSON オブジェクトとしてリクエスト本文で送信されます。

metadata と importSource では、インポートした課題の出所 (JIRA など) を指定するため、後で Space プロジェクトで課題を特定して管理できます。

issues 要素にはオブジェクトの配列が含まれており、各オブジェクトにはインポートされた各課題のパラメーターが含まれています。

• summary: 課題の見出しまたはタイトル。

• description: 課題の説明。

• status: 課題のステータス (「オープン」、「進行中」など)。

• assignee: 課題を担当する担当者。ユーザー名 (john.doe) または姓名を渡すことができます ( ジョンドウ )

• externalId: 外部ソースの課題の ID。

• externalName: 外部 ID の代わりに Space に課題を表示するために、課題に指定するエイリアス。

• externalURL: 元のトラッカーの課題の完全な URL。課題の外部 ID を Space 内のリンクに変換します。

簡単なリクエストの例を次に示します。

Space プロジェクトにインポートされたすべての課題には、一意の externalId が必要です。たとえば、2 つの異なる GitHub プロジェクトから課題をインポートし、それらの課題が同じ ID を共有している場合、Space に送信する前に、ソースの 1 つでこれらの ID を置き換える必要があります。元の ID を依然として Space に表示したい場合は、前述の externalName 値として渡すことができます。

以前にインポートした課題に加えて、同じ外部 ID を持つ課題をインポートするとどうなりますか ? それらはスキップされます。これはデフォルトの動作ですが、以前にインポートした課題を実際に更新するように簡単に変更できます。

インポートされた課題を更新する

インポートされた課題を更新するときは、onExistsPolicy を定義する必要があります。値 update を渡すと、以前にインポートされた課題が、ID に一致する課題で段階的に更新されます。この機能は、2 つの異なるトラッカー間で課題を管理し、同期を保つ必要がある場合に便利です。

ステータスの種類と担当者が欠落しているか不一致です

元の (ソース) 課題のステータスが、ターゲットの Space プロジェクトでは見つからないという状況に直面する可能性があります。または、ユーザー名が一致しない、または存在しないため、課題を提出した担当者を Space が認識できません。このような場合に対処するには、assigneeMissingPolicy および statusMissingPolicy を渡すことができます。

ステータスが欠落している場合のオプションは次のとおりです。

• statusMissingPolicy:replace-with-default を指定すると、認識されないステータス値が、Space プロジェクトに設定されている未解決タイプの最初のステータス値に置き換えられます。(例: 開く )

• statusMissingPolicy:skip を指定するか、この引数をまったく渡さない場合、認識されないステータスの課題はインポート中にスキップされます。

不在の担当者に対しても同様のオプションがあります。

• assigneeMissingPolicy:replace-with-default は、認識できない担当者の値を「未割り当て」に置き換えます。

• 認識できない担当者がいる場合、assigneeMissingPolicy:skip は課題をインポートしません。

実際に課題を Space にインポートする前に、引数 dryRun:true を渡してテスト実行を実行することをお勧めします。Space は、潜在的な課題を特定して解決するのに役立つ詳細なレポートを送り返します。

レスポンス

デフォルトでは、Space はサーバーメッセージとインポートされた課題の 3 つのリストを返します。

• created

• updated

• skipped

各エンティティの詳細を示します。

リクエストにクエリパラメーターを追加することで、レスポンスをフィルタリングできます。

次に例を示します

/api/http/projects/{project}/planning/issues/import?$fields=message

次のようなサーバーメッセージのみを返します

"message": "Created 15 Updated 0 Skipped 1"

許可

インポートを正常に実行するには、ImportIssues 権限が必要です。詳細情報と手順については、Space での認証を参照してください。