【Jira】CSVで課題を一括登録する時の必須項目と文字コード確認

JiraにCSVファイルを使って課題を一括登録する方法は、多くのチームで利用されています。しかし、必須項目が不足していたり、文字コードが適切でないためにインポートが失敗するケースが少なくありません。本記事では、CSVインポートで最低限必要な項目と、文字コードの確認方法を具体例を交えて解説します。これを読めば、初めての一括登録でもスムーズに作業を進められるようになります。

JiraのCSVインポートに必要な必須項目

JiraでCSVから課題をインポートする際、最低限以下の3つの項目が必須です。これらがCSVのヘッダー行に含まれていないと、インポートがエラーになります。

• Summary(件名):課題のタイトルです。空欄にすることはできません。
• Issue Type(課題タイプ):バグ、タスク、ストーリーなどの種別です。プロジェクトで使用可能なタイプ名と完全に一致させる必要があります。
• Project(プロジェクト):プロジェクトのキー(例:PROJ)または名前を指定します。省略するとデフォルトのプロジェクトが使われますが、設定によってはエラーになります。

これらに加えて、任意のカスタムフィールドや標準フィールド(Priority、Assignee、Descriptionなど)もインポートできます。ただし、フィールド名はJira上のフィールド名と正確に一致していなければなりません。特にカスタムフィールドは内部名(cf[12345])ではなく、フィールド名(例:カスタムフィールド名)で指定する必要があります。

必須項目を満たしていない場合のエラー例

実際によくある失敗パターンとして、Summary列が空欄の行があると「Summary is required」というエラーが表示されます。また、Issue Typeに存在しないタイプ(例:BugではなくBugfix)を指定すると「Invalid issue type」となります。Projectキーを間違えると「Project is required」と表示される場合もあります。これらのエラーメッセージはJiraの画面に表示されるので、必ず確認してください。

CSVファイルの文字コードと区切り文字の確認

Jiraが推奨するのは、UTF-8 BOM付き(またはUTF-8)のCSVファイルです。WindowsのExcelでCSVを保存すると、デフォルトでShift-JIS(日本語環境)になることが多く、これが文字化けやインポート失敗の原因になります。

また、区切り文字も重要です。Jiraはカンマ区切り(,)を標準としていますが、地域設定によってはセミコロン(;)で保存される場合があります。その場合はJiraのインポート画面で区切り文字を指定する必要があります。

文字コード	メリット	デメリット
UTF-8 BOM付き	Jiraの推奨、文字化けが起きにくい	古いシステムでBOMが問題になる場合がある
UTF-8(BOMなし)	互換性が高い	JiraでBOMが必要な場合に文字化け
Shift-JIS	Excelでそのまま保存できる	Jiraで文字化けの原因になる

文字コードを確認・変換する方法

1. ExcelでCSVを開く場合、[ファイル]>[名前を付けて保存]>[CSV UTF-8(コンマ区切り)]を選択します。これでUTF-8 BOM付きで保存できます。
2. すでにShift-JISのCSVファイルがある場合は、メモ帳で開き、[名前を付けて保存]で文字コードを「UTF-8」に変更して保存します。
3. PowerShellを使って変換する方法もあります。Get-Contentで読み込み、Set-Contentに-Encoding UTF8を指定します。ただし、BOMを付ける場合はOut-File -Encoding UTF8BOMを使います。
4. サクラエディタなどのテキストエディタでも同様の変換が可能です。
5. 変換後、必ずJiraのプレビュー画面で文字化けがないか確認します。

CSVインポートの手順(Jira Cloudの場合)

Jira Cloud(クラウド版)では、以下の手順でCSVインポートを行います。Jira Server/Data Centerの場合はメニューが異なることがあるので注意してください。

1. Jiraにログインし、右上の歯車アイコン>[課題]>[CSVからインポート]をクリックします。
2. [ファイルを選択]からCSVファイルをアップロードします。このとき、ファイルサイズが大きすぎるとエラーになる場合があるので、必要に応じて分割してください。
3. アップロード後、[次へ]をクリックすると、JiraがCSVのヘッダーを解析し、各列をJiraのフィールドにマッピングする画面が表示されます。
4. 自動マッピングが正しいか確認し、必要に応じて手動でマッピングを修正します。特に、Summary、Issue Type、Projectは必須でマッピングされていることを確認してください。
5. マッピングが完了したら[インポート]をクリックします。インポート中はジョブの進捗が表示され、完了後には結果レポートが表示されます。

インポート中にエラーが発生した場合は、エラーの内容を確認してCSVを修正し、再度インポートします。なお、一度インポートした課題を削除するには、インポート後に同じジョブで[削除]オプションを使うことができますが、最初は小さなテストファイルで動作確認することをおすすめします。

マッピング時の注意点

• CSVのヘッダー名とJiraのフィールド名が完全一致していないと、自動マッピングされません。例えば、Jiraのフィールド名が「説明」の場合、CSVヘッダーを「説明」または「Description」にする必要があります。
• 複数値フィールド(例:ラベル、コンポーネント)は、CSV内ではセミコロンやパイプなどで区切って記述します。区切り文字はJiraの設定に依存するため、管理者に確認してください。
• 日付フィールドは、Jiraの設定に合わせた書式(例:YYYY-MM-DD)で記述します。Excelの日付シリアル値は使えません。

よくある失敗パターンと対処法

CSVインポートでよく発生する問題を5つ挙げ、それぞれの対処法を説明します。

1. 文字化けが発生する:原因は文字コードの不一致です。CSVをUTF-8 BOM付きに変換し、Jiraのインポート画面で「ファイルのエンコーディング」をUTF-8に設定してください。
2. 「Summary is required」エラー:Summary列に空のセルがあります。すべての行に件名を入力するか、必須項目を確認してください。
3. 「Invalid issue type」エラー:Issue Typeの値がプロジェクトで許可されていないタイプ名です。プロジェクト設定で使用可能な課題タイプを確認し、CSVに正しいタイプ名を記述してください。
4. 「Project is required」エラー:Project列が空か、存在しないプロジェクトキーです。プロジェクトキーは大文字小文字を区別しないので、正しいキー(たとえば「PROJ」)を入力します。
5. 日付が正しくインポートされない:日付の書式がJiraのロケール設定と一致していません。管理者に日付書式を確認し、それに合わせてCSVを修正します。

管理者に確認すべきこと

CSVインポートがうまくいかない場合、以下の点をJiraの管理者に確認すると問題解決が早まります。

• 使用しているJiraのバージョン(Cloud、Server、Data Center)と、インポート機能の利用権限(プロジェクト管理者権限が必要な場合があります)
• プロジェクトに設定されている必須フィールド(インポート時にすべての必須フィールドがCSVに含まれている必要があります)
• 文字コードや区切り文字に関する組織のポリシー(UTF-8 BOMを強制しているかなど)
• カスタムフィールドの内部名または画面に表示される名前(マッピングに必要)

よくある質問

Q1. 1つのCSVで複数のプロジェクトに課題を登録できますか?

はい、可能です。CSVの各行に異なるProject列の値を設定すれば、それぞれのプロジェクトに課題が作成されます。ただし、インポートを実行するユーザーがすべてのプロジェクトの作成権限を持っている必要があります。

Q2. インポート後に課題を一括削除する方法はありますか?

Jira Cloudでは、インポート結果画面から「インポートを元に戻す」機能を使って、そのインポートで作成された課題を一括削除できます。ただし、インポート後に手動で編集した課題は削除されないため注意してください。

Q3. 大量の課題をインポートする際の制限はありますか?

Jira Cloudの場合、1回のインポートで1000件まで推奨されています。2000件を超えるとタイムアウトする可能性があります。また、添付ファイルを含める場合はCSVではなく、専用の移行ツールを検討してください。

まとめ

JiraでCSVインポートを成功させるためには、必須項目(Summary、Issue Type、Project)を過不足なく含め、文字コードをUTF-8 BOM付きにし、区切り文字をカンマに統一することが基本です。エラーが発生した場合は、エラーメッセージを手がかりにCSVの内容やマッピングを見直してください。管理者に確認すべきポイントを事前に整理しておくと、スムーズにトラブルシューティングできます。初めての一括登録では、必ず小さなサンプルファイルでテストしてから本番データをインポートするようにしましょう。