以 XML 格式导入和导出工件

项目跟踪工具能够以 XML 格式导入和导出工件。

关于 XML 导入

导入 XML 工件需提取已导出到 XML 文件的工件内容。导入 XML 文件时,会将工件表格中的内容导入到项目中,并根据它们所呈现的结构进行重新排列。

要导入 XML 工件,请执行以下操作:

  1. 导航到“项目跟踪工具”链接,该链接位于“项目”选项卡中您的项目的左侧导航窗格中。
  2. 单击“管理”>“XML 导入工件”链接。
  3. 再单击“浏览”按钮,并选择要导入的文件名。导入的文件必须为 XML 格式,例如 scarab-issues.xml。如果找不到 XML 文件,请单击“所有文件”下拉框,该框会显示可供搜索的完整文件列表。
  4. 单击“导入文件”按钮,将工件内容置入项目中。

关于 XML 导出

可以导出 XML 格式的工件,这样工件内容还可以用于其它应用程序。可以从查询结果页导出工件,也可以从项目跟踪工具的 XML 导出页导出工件。只能将当前项目中的工件导出为 XML 格式。无法从跨项目查询中将以工件导出为 XML 格式。

注意:在 XML 导入阶段,不会强制执行为状态属性定义的转变和为依赖属性定义的规则。这样就可以导入在定义状态转变之前创建的工件。

从查询结果页导出 XML 格式的工件

  1. 请在使用项目跟踪工具的项目中,单击左侧导航窗格中的“项目跟踪工具”>“查询工件”。
  2. 单击“创建”按钮,或单击现有查询的链接。
  3. 如果要创建新查询,请输入查询条件,然后单击“提交”。
  4. 在查询结果页的“查询结果”部分中,单击标记为“导出结果至”的下拉列表,并选择“XML(完整的工件)”。

注意:如果查询与日期属性相关联的工件类型的工件,请使用“输出结果至”选项将工件导出为 Excel (XLS) 格式,并使用 Excel 编辑器(例如,Microsoft Excel)将其打开;而具有“日期”属性的单元格可能无法以项目跟踪工具使用的格式“YYYY-MM-DD”显示日期。这是由 Excel 编辑器所使用的日期设置造成的(即使实际日期相同,也不能以项目跟踪工具的格式显示)。若要更改导出的 Excel 文件中的日期外观,请在 Excel 编辑器中执行以下操作:

  1. 在 Excel 工作簿中,选择与日期属性关联的整列、整行或特定的单元格。
  2. 右键单击,然后选择“设置格式单元格”选项。
  3. 在“数字”选项卡中,选择“自定义”分类选项。
  4. 在右侧出现的子菜单的“类型”文本框中,输入以下内容:“yyyy-mm-dd”(不带引号)
  5. 单击“确定”保存这些更改。

这样可确保无论操作系统使用何种日期设置,日期都将以“yyyy-mm-dd”格式显示。更改操作系统的日期设置也会影响其它应用程序。

从导出页导出 XML 格式的工件

  1. 请在使用项目跟踪工具的项目中,单击左侧导航窗格中的“项目跟踪工具”>“XML 导出工件”。
  2. 按照屏幕说明文字的指示,输入一个或多个工件 ID。
  3. 请选择要导出到文件还是要导出到浏览器窗口。
  4. 单击“导出”按钮。

导入类型

XML 文件中的 <import-type> 元素定义了导入的两种方式。

create-same-db(与 create-different-db 并立)- 它意味着,在执行导入操作时,要导入的所有工件都将被视为新工件,而已存在的任何数据都将被忽略,XML 文件中的所有数据都将作为新数据导入。

此导入类型用于:

update-same-db - 这意味着,系统将根据 <id> 元素尝试查找数据库中现有的工件。<issue> 表示的现有工件,将会对现有工件进行修改。在同一 XML 中,可能也包含另外一些 <issue> 表示的工件,它们的 <id> 元素与现有工件不匹配;这些工件将作为新工件导入。

执行现有更新的使用实例支持特定客户端使用 PT,以方便在各种外部事件跟踪工具之间移动工件数据。有关此用法的详细信息,现在仍未知。

由于不清楚 update-same-db 的主要用法,因此在开发过程中假定一个路径可作为 Web 服务 API 的有限替代。但人们可能更愿意使用 CGI 参数编写脚本。下面的案例将不同程度地使用当前的执行:

先决条件

成功导入的当前先决条件为,系统中必须已存在所有被 XML 文件引用的项目、用户名、工件类型、属性、属性选项。如果无法找到这些内容,导入将失败。

用户界面

“XML 导入”中输入的是一个单个 XML 文件,此文件的详细信息由 DTD 指定。DTD 中包含了一些描述性的注释,在此处会有进一步的解释。该文件可通过 HTTP 文件上载引入,或作为服务组和操作组之间达成共识的过程的一部分,置于服务器的文件系统中。

HTTP 文件上载

具有在项目中输入工件的权限的用户,可以使用“文件上载”选项。然而,只有具有“项目事件跟踪 - 配置”或“项目 - 编辑”权限的用户(通常指项目所有者和其他管理角色),才能使用访问功能性的链接,此功能性显示为管理导航条目。

导入的结果由 HTTP 响应提供,如果响应时间超过了预设时间(当前为 30 秒),将通过电子邮件将这些结果发送给用户。无论是立即响应还是通过电子邮件发送,错误结果都是相似的。发送成功的电子邮件信息中包含了通过 Web 界面查看结果的链接。如果导入的内容已编写到脚本中,则可能需要添加查询参数:format=xml,结果将作为 XML 文档返回。如果此参数值已存在,则响应将一直等到导入完成。对于将在多长时间后发送电子邮件没有限制;但 HTTP 客户端或服务器可能会强制设定一个最大时间限制。

在 XML 中允许有文件附件元素,但会忽略这些元素。对于 update-same-db 类型,将会发出警告。

命令行(在服务器上)

将项目从 Issuezilla 转换为 PT 时,会通过文件系统导入 XML;在服务过程中,客户端也可导入 XML。XML 中允许存在文件附件元素,但这些元素必须指向服务器中已存在的文件。在导入 XML 前,服务程序必须擦除由客户端提供的 XML,以防止访问服务器上的敏感性文件。

可能需要指定一个目录,其中包含若干将要导入的 XML 文件。这样会很便利,而且这些文件将被视为独立的导入内容。

如果导入成功,则不会显示任何警告信息。将以标准输出方式打印错误和警告。

确认

确认操作可包括根据 DTD 检查 XML。还会将 XML 文件中包含的数据与应用程序中的状态进行比较。

XML 确认

如果 XML 文件中已给定 DOCTYPE 标记,则必须在 3.0.1 以及更高版本中将此标记指定为 <!DOCTYPE scarab-issues SYSTEM "PROTO://www.DOMAIN/dtd/pt.dtd">(其中,PROTO 为 httpshttp);而在 3.0.0 和 2.6.x 版本中,则必须将其指定为 <!DOCTYPE scarab-issues SYSTEM "http://project.domain.com/dtd/scarab-0.16.29.dtd">。如果已给定上述 DOCTYPE 标记,则将根据相应版本当前的 DTD 对此 XML 进行确认。

语法确认

根据 PT 数据库中当前的元数据检查 XML 文件中包含的数据。要求所有元数据(如工件类型和属性)都可作为先决条件。在 XML 中,给定值的属性必须与给定工件的工件类型相关联,尽管这些属性可能处于未激活状态。必须将 XML 中的属性名映射为全局属性名。属性选项可以使用全局名称,也可以使用项目及工件类型中使用的选项别名。

确认依赖关系需检查所涉及的类型和工件是否存在。有关未确认信息的详细信息,请参见创建类型和更新类型的比较部分。

XML 中给定的日期字符串,必须能够根据该日期的格式字符串进行解析。

XML 中使用的用户名必须映射到域中的实际用户(或将主机映射到主机用户)。

文件附件必须包含有效路径,指向服务器中的文件。仅当允许文件附件时,才需对此确认。

在导入开始前会确认所有的数据,在从确认到导入结束的过程中,更改元数据会导致导入失败,从而造成导入部分工件。

注意:使用 XML 导入功能导入属性时,将忽略必需的属性。即,当通过 CollabNet 用户界面创建新工件时,必须为所有必需的属性提供一个值,这些必需的属性通过“*”标记。不过,系统允许创建通过 XML 导入而创建的新工件,即使此新工件缺少必需的属性值。

属性依赖关系

导入线程禁用属性依赖关系。对于转变和必需的属性,审查信息不可用,因而无法知道过去某个时间点导入包含活动的工件是否合法。即使项目跟踪工具一直对此信息进行审查,XML 导入功能也能从旧的事件跟踪工具中导入数据,从而针对工件的活动可能会早于项目跟踪工具中元数据的更改日期。假定此数据在任何给定的时间都满足状态要求。

可以导入不带必需属性值的工件。在项目跟踪工具中第一次编辑该工件时,将会强制执行必需的值。

工件依赖关系

可在同一 XML 文件中的各工件之间指定依赖关系。不可在导入的不同 XML 文件中的工件之间声明依赖关系。对于 create-same-db 类型,无法指定 XML 中的工件和已输入到 PT 中的工件之间的依赖关系。但可以使用 update-same-db 类型为已输入的工件指定依赖关系。

操作集

可将同时发生的活动分为一组,但有些活动通常并不与其它活动分为一组,因此将被指定为包含单一活动的操作集:

  1. 将文件附件添加到工件。
  2. 将注释添加到工件。

单一操作集中可能包含若干改变了属性值和依赖关系的活动。但您不应有类似以下的操作 输入:在同一操作集中既有“从 NEW 更改为 STARTED 的状态”,又有“从 NEW 更改为 FIXED 的状态”。此类组合将无法通过确认。

对于包含注释/原因、URL 以及文件的附件元素,将忽略已创建和修改的日期信息。通过 Web 上载 XML 时,将忽略文件附件。如果活动中的附件与 XML 中以前的附件具有相同的 ID,将生成此初始附件的另一个历史记录,但不会对原始附件进行修改。因此,第一次引用 XML 中的附件时必须包含最终状态,其它引用则大致相同,但只要这些引用共享同一 ID,它们都将被忽略。

使用活动中的旧值和新值元素添加或修改属性值。单值属性可以既包含旧值又包含新值,这种情况被解释为值的更改。多值属性应只能具有其中一个元素。受派者不会由“user 1”更改为“user 2”;“user 1”将作为一个受派者被删除,而“user 2”将作为另一个受派者被添加。若将选项或用户名作为旧值,新值不包含任何项,这种情况被解释为值的删除。

示例 XML

可在活动签名文档中获得若干修改示例,这些示例将显示更多与 XML 相关的部分。还可获得以下示例:

创建类型和更新类型的比较

确认

XML 中的依赖关系可以引用已输入到此系统中的“更新”类型的工件。“创建”类型要求 XML 中的依赖关系和工件之间应彼此一致。

新工件

“创建”类型经常为 XML 中的每个事件元素生成新保存的工件。使用“更新”类型,可以比较 ID 元素与已保存的工件。如果此 ID 与已保存的工件相匹配,则将修改该工件;否则将创建与此“创建”类型类似的新工件。将根据项目使用的前缀和计数器,向新保存的工件分配新 ID。

操作集

在“创建”类型中,将按照 XML 输入中所指定的来使用操作集日期。对于 update-same-db 导入,如果正在更新工件,会同时将此操作集的创建日期与此工件的上次修改日期及当前时间进行比较。将忽略上次修改日期之前的操作集,并发出一个警告。以后的日期将被转换为导入完成的时间;从而提供了一种方法,可以在 DTD 的限制范围内指定使用当前时间的更新。

活动

如果活动的结束日期为空,将会导致两种类型的任意一种新活动。通常情况下,如果与活动相关的属性的结束日期为空,意味着此活动表示属性的当前值。对于“更新’导入类型,将忽略具有结束日期值的活动。

依赖关系

对于“更新”类型,将忽略添加已有的依赖关系或删除不存在的依赖关系的尝试。对“创建”类型执行相同的操作将导致异常,结果是不会保存该依赖关系和其后发生的任何依赖关系。但仍将保存所有的工件。对于这两种类型,都将忽略对不存在的依赖关系的更新。