从 CSV 导入数据

准备 CSV 文件

JIRA Importers 插件假设您的 CSV 文件基于默认的 Microsoft Excel 风格的 CSV 文件。字段用逗号分隔，任何必须按字面进行处理的内容（例如逗号和换行/“回车”本身）都会用引号括起来。

 对于 Microsoft Excel 和 OpenOffice，无需为单元格中的值加引号，因为这些应用会自动进行这一处理。

CSV 文件要求

除了“格式良好”之外，CSV 文件还有以下要求。

每个 CSV 文件必须拥有带“Summary”列的标题行

CSV 文件导入向导（如下所述）使用 CSV 文件的标题行来确定如何将数据从 CSV 文件的第 2 行及以后行映射到 JIRA 中的字段。

标题行应该避免包含任何标点（除了用于分隔每列的逗号），否则导入程序可能无法正常运行。

标题行必须包含“Summary”数据列。

不能遗漏逗号（作为列/字段的分隔符）

例如，以下形式有效：

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1, ,

...但以下形式无效：

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Test issue", admin, admin, 1

在 CSV 文件中封装 JIRA 数据结构

捕获跨多个行的数据

在 CSV 文件中使用双引号 (") 来捕获跨多个行的数据。例如，导入后，JIRA 会将以下形式视作带有单条记录的有效 CSV 文件：

Summary, Description, Status
"Login fails", "This is on
a new line", Open

按字面处理特殊字符

在一段文字周围使用双引号 (")，以按字面处理该部分中的所有特殊字符。一旦将此数据导入到 JIRA，这些特殊字符将作为 JIRA 字段数据的一部分存储。特殊字符的示例包括回车/Enter 字符（如以上示例中所示）和逗号等。

要按字面处理双引号，您可以使用另一种双引号字符对它们进行“转义”。因此，CSV 值：

• "Clicking the ""Add"" button results in a page not found error"
  在导入后将按以下方式存储在 JIRA 中：
• Clicking the "Add" button results in a page not found error

将多个值聚合到单个 JIRA 字段中

您可以将多个值导入到接受多个值的 JIRA 字段（例如 Fix (for) Version、Affects Version、Component、Labels）。为此，您的 CSV 文件必须为要聚合到相应 JIRA 字段的每个值指定相同的列名称。指定的列名称的数量必须与要聚合到相应字段的值的最大数量相匹配。例如：

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component
bug, "First issue", v1, , , Component1,
bug, "Second issue", v2, , , Component1, Component2
bug, "Third issue", v1, v2, v3, Component1,

在上述示例中，第二个事务的 Component 字段和第三个事务的 Fix Version 字段在导入后将在相应的 JIRA 字段中生成多个值。

 注意：只有少数 JIRA 字段支持多个值。CSV 导入程序不支持将聚合数据导入仅支持单个值的 JIRA 字段中。

导入附件

您可以将文件附加到通过 CSV 文件创建的事务。为此，请在 CSV 文件的“Attachments”列中指定附件的 URL。

Assignee, Summary, Description, Attachment, Comment
Admin, "Issue demonstrating the CSV attachment import", "Please check the attached image below.", "https://jira-server:8080/secure/attachment/image-name.png", "01/01/2012 10:10;Admin; This comment works"
Admin, "CSV attachment import with timestamp,author and filename", "Please check the attached image below.", "01/01/2012 13:10;Admin;image.png;file://image-name.png", "01/01/2012 10:10;Admin; This comment works"

 附件的 URL 支持 HTTP 和 HTTPS 协议，它们必须是 JIRA Server 能够访问的位置。此外，您还可以使用 FILE 协议访问 JIRA 主目录的 import/attachments 子目录中的文件。

创建子任务

您可以通过 CSV 文件导入创建事务的子任务，方法是在 CSV 文件中封装此结构。为此：

• 您的 CSV 文件还需要另外两列，其标题应采用与 Issue Id 和 Parent Id 类似的方式命名。
• 请确保在 Issue Id 列中为每个常规（非子任务）事务提供一个唯一（连续）编号。请勿在常规事务的 Parent Id 字段中包含任何值。
• 要在 CSV 文件中创建常规事务的子任务，请在 Parent Id 列中引用常规事务唯一的 Issue Id 编号。请勿在子任务的 Issue Id 字段中包含任何值。

例如：

IssueType, Summary, FixVersion, FixVersion, FixVersion, Component, Component, Issue ID, Parent ID, Reporter
Bug, "First issue", v1, , , Component1, , 1, , jbloggs
Bug, "Second issue", v2, , , Component1, Component2, 2, , fferdinando
Bug, "Third issue", v1, v2, v3, Component1, , 3, , fferdinando
Sub-task, "Fourth issue", v1, v2, , Component2, , , 2, jbloggs

在上述示例中，假设您在 CSV 文件导入向导运行期间，分别将 CSV 文件中的“Issue ID”和“Parent ID”字段与 Issue Id 和 Parent Id JIRA 字段匹配，那么第四个事务在导入后将是第二个事务的子任务。

将事务导入到多个 JIRA 项目

您可以通过 CSV 文件导入将事务从 CSV 文件导入到不同 JIRA 项目。为此：

• 您的 CSV 文件还需要另外两列，其标题应采用与 Project Name 和 Project Key 类似的方式命名。
• 请确保 CSV 文件中表示的每个事务在它们导入的目标 JIRA 项目的对应列中都包含相应的名称和唯一标识。
   项目名称和唯一标识数据是将事务从 CSV 文件导入到特定 JIRA 项目所需的最少 JIRA 项目数据。

IssueType, Summary, Project Name, Project Key
bug, "First issue", Sample, SAMP
bug, "Second issue", Sample, SAMP
task, "Third issue", Example, EXAM

在上述示例中，假设您在 CSV 文件导入向导运行期间，分别将 CSV 文件中的“Project Name”和“Project Key”字段与 Project name 和 Project key JIRA 字段匹配，那么第一个事务和第二个事务将导入到“Sample”项目（项目唯一标识为“SAMP”），第三个事务将导入到“Example”项目（项目唯一标识为“EXAM”）。

如何处理未解决的事务

对于到“Resolution”、“Priority”和“Issue Type”的字段映射，您将获得带有 JIRA 可用值的选择列表。此外，您可以通过单击绿色加号快速创建 JIRA 中不存在的值。

对于到“Status”的字段映射，您将获得带有 JIRA 可用值的选择列表，但无法使用加号创建新的状态值。

对于这四个字段，除了 JIRA 的可用值之外，选择列表中还有以下两个特殊选项：

• “Import as blank”— 此选项将使该字段的 JIRA 值变为空白。请注意，如果您正在导入未解决的事务，您应该为“Resolution”字段创建字段映射，并将值“Unresolved”设置为“Import as blank”。
• “No mapping”— 此选项将尝试按原样导入 CSV 文件中的值。请注意，如果 CSV 文件中的值对 JIRA 字段无效，则对字段值使用“No mapping”会导致导入失败。对于到“Status”和“Issue Type”的字段映射，如果选择“Import as blank”选项，则系统将使用默认值。

导入工作日志条目

您的 CSV 文件可以包含工作日志条目。例如：

Summary,Worklog
Only time spent (one hour),3600
With a date and an author,2012-02-10 12:30:10;wseliga;120
With an additional comment,Testing took me 3 days;2012-02-10 12:30:10;wseliga;259200

要跟踪花费的时间，您需要使用秒数。

导入到多选自定义字段

对于一个多选自定义字段，您的 CSV 文件可以包含多个条目。例如：

Summary,Multi Select,Multi Select,Multi Select
Sample issue,Value 1,Value 2,Value 3

这样将使用多个值填充多选自定义字段。

导入级联选择自定义字段

您可以使用以下语法将值导入到级联选择自定义字段：

Summary, My Cascading Custom Field
Example Summary, Parent Value -> Child Value

借助“->”分隔符，您可以导入层级。

注意：目前，JIRA 不支持通过 CSV 导入多级级联选择字段 ( JRA-34202 - Getting issue details... STATUS )。

更新现有事务

自 JIRA Importers 插件 4.3 版起，您可以更新现有事务。CSV 文件需要包含在导入向导运行期间映射到“Issue Key”的列。如果给定唯一标识存在对应的事务，则该事务将更新。例如：

issue key,summary,votes,labels,labels
TT-1,Original summary,1,label1,label2
TT-1,,7,label-1,label-2
TT-1,Changed summary,,,
TT-2,Original summary 2,1,label-1,label-2
TT-2,,<<!clear!>>,<<!clear!>>,

第一行将创建一个事务，第二行会将赞成者设为 7，并添加两个标签。接下来的行将更改标题。系统将创建附带两个标签的事务 TT-2，第二行将删除带有特殊标记 <<!clear!>> 的标签。

 导入 CSV 以更新现有事务的操作会将列重置为默认值，前提是 CSV 中没有指定这些列。

运行 CSV 文件导入向导

在开始之前，请备份您的 JIRA 数据。

1. 以具有 JIRA Administrators 全局权限的用户身份登录 JIRA。
2. 选择 Administration > System > Import & Export > External System Import。
3. 选择 CSV 以打开 CSV File import 页面。
4. 在 CSV File import 页面中，选择您的 CSV Source File。如果您要更改文件的编码和 CSV 分隔符格式，请单击 Advanced 标题，以显示此选项（如上方屏幕截图所示）。
    注意：
   
   • 文件将使用您在此处指定的文件编码（默认情况下为 UTF-8）导入。
   • 如果 CSV 文件使用了除逗号以外的其他分隔符，请在 CSV Delimiter 字段中指定该字符。
5. 如果您没有配置文件或希望创建新的配置文件，则将 Use an existing configuration file 复选框保持为未选中状态。配置文件会指定 CSV 文件标题行中的列名称与 JIRA 安装中的字段之间的映射。
    注意：
   • 如果选中此选项，则系统将要求您指定现有配置文件。
   • 如果您没有选中此选项，则在 CSV 文件导入向导结束时，JIRA 将创建可用于后续 CSV 导入的配置文件（在 CSV 文件导入向导的这一步中）。
6. 单击 Next 按钮，以继续执行 CSV 文件导入向导中的 Setup project mappings 步骤。

7. 在 Setup project mappings 页面上，您可以将所有事务导入到一个 JIRA 项目（新建或现有的）中，也可以导入到多个 JIRA 项目中（但要确保您的 CSV 文件包含最基本的必需 JIRA 项目数据，例如 JIRA 项目名称和键）。填写以下字段/选项：

   Import to JIRA Project	选择以下任意一项： 如果选择 Select a project，则请执行以下操作之一： 开始输入 JIRA 中已存在的项目的名称（或键）或使用下拉菜单选择现有的 JIRA 项目。 从下拉菜单中选择 Create New，然后在显示的 Add A New Project 对话框中，输入以下内容： 新项目的 Name 新项目的 Key 这将用作 JIRA 项目中所有事务 ID 的前缀。 Project Lead。 Defined in CSV。确保 CSV 文件中的每个事务都包含 JIRA Project Name 和 Project Key 数据。 如果要将事务从 CSV 文件导入到多个 JIRA 项目中，此选项将非常有用。请参见Importing issues into multiple JIRA projects了解详情。
   E-mail Suffix for New Users	为在导入期间要添加到 JIRA 的 CSV 文件中指定的新用户输入电子邮件地址域。
   Date format in import file	指定 CSV 文件中使用的日期格式。使用符合 Java SimpleDateFormat 的语法。

8. 单击 Next 按钮，以继续执行 CSV 文件导入向导中的 Setup field mappings 步骤。

9. 在 Setup field mappings 页面上，指定每个您想导入到所选 JIRA 项目中的 CSV Field（由 CSV 文件的标题行决定），方法是：在左侧的 Import 列下，选中对应的复选框。
    请注意：

   • 其中至少一个字段必须包含 JIRA 的 Summary 字段的数据。

   • 如果 CSV 文件包含多个与其标题行中的某个字段名称相同的字段，则 CSV 文件导入向导会将它们汇总到一个字段中，并在向导的此步骤中使用 符号进行标记。

10. 在 JIRA field 列中，选择您要与 CSV 文件中定义的字段（即您在之前步骤中选择每个 CSV Field）进行匹配的 JIRA 字段。有关将 CSV 字段与 JIRA 字段进行匹配的更多信息，请参见下面的将 CSV 数据导入到 JIRA 字段中的提示。
     请注意：

    • 必须为其中一个 JIRA 字段指定 Summary 字段，否则 Next 按钮将保持不可用。

    • 对于被 CSV 文件导入向导汇总的 CSV 字段，您只能选择支持多个值的 JIRA 字段。

    • 如果要导入子任务，请记住将 JIRA 中的 Issue ID 和 Parent ID 字段与 CSV 文件中的这些字段进行匹配。
    • 如果要将事务导入到多个项目中，请确保在上述的 Setup project mappings 步骤中选择 Defined in CSV，并请记得将 JIRA 中的 Project Name 和 Project Key 字段与 CSV 文件中的这些字段进行匹配。
11. 若要在导入 JIRA 之前修改 CSV 文件中任何字段数据的值，请选中相应字段旁边的 Map field value 复选框。
12. 单击 Next 按钮，以继续执行 CSV 文件导入向导中的 Setup value mappings 步骤。
13. 在 Setup value mappings 页面上，针对每个 CSV 文件字段值（已经由 CSV 文件导入向导检测出）指定 JIRA 字段值。
    请注意：
    
    • 本页面上将显示在 CSV 文件导入向导之前的步骤中已选中对应的 Map field value 复选框的字段。

    • 如果想按“原样”导入值，请清除字段或字段内的内容。

    • 您可以在 JIRA 中创建新的 Priority、Resolution 和 Issue Type 值（例如，基于 CSV 文件中的数据），方法是：单击相应字段旁边的 Add new ...链接（例如，以上屏幕截图中所示的 Add new issue type 'subtask'）。

    • 如果要导入基于用户名的字段（例如，Reporter 或 Assignee），但在 CSV 文件导入向导之前的步骤中没有选中此字段的 Map field value 复选框，则导入程序会自动将从 CSV 文件导入的用户名（小写）映射到 JIRA 用户名。
      如果尚未在 JIRA 中定义用户名，则无论是否选中了 Map field value 复选框，JIRA 都将基于 CSV 文件中的数据自动创建用户名。 

14. 准备好开始将 CSV 数据导入 JIRA 后，请单击 Begin Import 按钮。导入程序将随着导入进程显示更新，然后在导入完成后显示成功消息。
    注意：
    • 如果在导入过程中遇到了问题（或有疑问），请单击 download a detailed log 链接，了解有关 CSV 文件导入过程的详细信息。
    • 如果您还需要导入另一个 CSV 文件，该文件与此导入过程中使用的 CSV 文件具有相同（或类似）的设置，请单击 save the configuration 链接，下载 CSV 配置文件，以便在 CSV 文件导入向导的第一步中使用。

祝贺您，您已经成功将 CSV 数据导入到 JIRA 中！如果您有任何疑问或遇到任何问题，请联系 Atlassian 支持部门。

将 CSV 数据导入到 JIRA 字段中的提示

将数据从 CSV 文件导入到特定 JIRA 字段中时，请参考以下这些有用的提示：