用于导入元器件数据的命令行工具

Parent page: 维护

Enterprise Server 包含一个 CSV 元件数据库导入工具，可用于将元件数据从企业系统（例如公司 ERP 或 PLM 系统）导出的文件导入到 Enterprise Server Workspace 中。该桌面工具以可配置的批处理（*.bat）文件形式实现，可将目标电子表格文件（*.csv）中的元件数据导入到 Workspace；导入方式由现有的 Workspace 模板或专用配置文件决定。

► 有关 Enterprise Server 与 PLM 系统之间协同工作的更多信息，请参阅 PLM Integration。

该命令行工具位于 Enterprise Server 安装目录的 \Program Files (x86)\Altium\Altium365\Tools\CSVImport 文件夹中。有关该工具使用的命令行语法信息，请参阅 csv-import.bat，或直接在不带任何属性的情况下执行该批处理文件以获取更详细的信息。

自动模式

在不应用配置文件（选项 –c）的情况下使用时，CSVImport 工具进程会尝试将目标 CSV 文件名（例如 Resistor.csv）与支持该元件类型（Resistor）的 Workspace 元件模板进行匹配。找到的模板将决定导入数据的修订版本（Revision）、生命周期（Lifecycle）以及默认文件夹（Workspace 目标位置）。请注意，源 CSV 文件的最低数据要求是包含 PART_NUMBER 参数列及其对应的 Values。

CSVImport 实用工具在运行时会在控制台窗口中提供一般进度信息，并且还可以按命令语法（-l）指定生成日志文件。如果 CSV 文件中包含元件制造商料号参数（默认情况下为 MFR_PART_NUMBER 和 MFR_NAME），则会在 Workspace 中创建匹配的 Part Choice 条目。

可选的日志文件会提供成功导入过程的详细信息——如果过程失败，则不会生成日志文件。

配置模式

该工具的更高级模式使用 XML 配置文件来指定文件到 Workspace 的参数映射，以及导入过程中的选项（例如目标文件夹、不同的模板等）。

要获取可按需修改的基础配置文件，请使用生成配置文件设置（-g）运行该工具。这将创建指定的 XML 文件，其中包含从源 CSV 文件提取的参数键/值对，以及从匹配模板提取的 Revision、Lifecycle 和目标文件夹设置。还包括 PLM（源）与 Workspace（目标）的元件类型条目——在本示例中为 Resistor——以及模板 ID。

该工具的典型命令字符串为：
csv-import.bat -s http://HPZ600:9780 -u admin -p admin -g MyConfig.xml -i C:\Users\Public\Documents\CSV_Files\Resistor.csv

► 生成的配置文件示例（下载）

生成后，可编辑配置文件（MyConfig.xml），将源 Value 参数映射到 Workspace 中的 Resistance，并将 Format 参数映射到 Package。在配置文件的 ToAltium 部分（针对 Resistor PLM 类）中相应编辑这些属性字符串，以按需完成映射。

<ns2:Attribute attributeType="revision">
  <ns2:Key>Format</ns2:Key>
  <ns2:Value>${attribute.Format}</ns2:Value>
</ns2:Attribute>
<ns2:Attribute attributeType="revision">
  <ns2:Key>Value</ns2:Key>
  <ns2:Value>${attribute.Value} </ns2:Value>
</ns2:Attribute>

<ns2:Attribute attributeType="revision">
  <ns2:Key>Package</ns2:Key>                 <!-- Updated -->
  <ns2:Value>${attribute.Format}</ns2:Value>
</ns2:Attribute>
<ns2:Attribute attributeType="revision">
  <ns2:Key>Resistance</ns2:Key>              <!-- Updated -->
  <ns2:Value>${attribute.Value}</ns2:Value>
</ns2:Attribute>

随后在工具中使用该配置文件（选项 –c）来执行所需映射：
csv-import.bat -s http://HPZ600:9780 -u admin -p admin -c MyConfig.xml -i C:\Users\Public\Documents\CSV_Files\Resistor.csv

其他映射选项

其他配置选项包括：通过编辑文件中的 <Entity altiumType="Resistor" plmType="Resistor"> 行来设置 PLM 与 Workspace 的元件类型类（Component Type class），该行会按本示例生成。典型更改可能包括：

• 指定 altiumType="ResistorSMT" 以将导入的元件设置为该类型（前提是该类型已在 Workspace 中注册）。指定 plmType="PLM-Export_Resistors" 以允许导入名为 PLM-Export_Resistors.csv 的源文件。请注意，源 CSV 文件名若与现有 Workspace 元件类型（Resistor、Capacitor 等）不匹配，则除非以这种方式指定 plmType，否则不会被识别。

为确保导入成功，所应用配置文件中的 Attribute 条目（自动生成的那些）必须与源 CSV 文件列标题中的条目匹配。例如，CSV 列组 Format 必须具有配置属性条目 Value 为 ${attribute.Format} 的对应项，而不受任何参数映射（如 above 所述）的影响。不过，也可以为某个元件实体（Entity）添加额外的 Attributes，例如固定标识符，其格式可能如下：

<ns2:Attribute>
  <ns2:Key>DataSource</ns2:Key>
  <ns2:Value>Imported from PLM</ns2:Value>
</ns2:Attribute>

在这种情况下，导入到 Workspace 的元件数据将包含一个 DataSource 参数，其值设置为 Imported from PLM。

Additional features:

• 所应用的配置文件将独立于相关 Workspace 模板，决定导入过程的所有设置，包括参数映射。
• 可映射所有参数以适配输入 CSV 文件参数，包括文件中用于 PLM Number 的名称以及元件制造商数据（Part Choices）的名称。
• 一个配置文件中可包含多个 Entity 定义及其组成参数 Attributes。复制一个现有的 Entity 组条目（例如 Resistor），然后粘贴/编辑以创建另一个（例如 Capacitor）。
• 元件模板中设置了默认值的参数将应用于导入的元件，除非在导入的 CSV 数据中存在对应属性——若存在，则源属性值将导入到 Workspace 参数中。在 CSVImport 自动模式 下，应用的模板将是该元件类型的模板，由源 CSV 文件名定义。在 配置模式 下，模板由配置文件中的 <ComponentTemplate>[CMPT-xxxx]</ComponentTemplate> 行设置。
• 当指定源路径为 without CSV 文件时，该工具会在源文件夹中搜索与配置文件中实体（Entity）定义相匹配的 CSV 文件名。因此，如果配置中存在针对 Capacitor 和 Resistor 的实体引用，并且找到了匹配的 CSV 文件，那么这些元件的数据将被导入到 Workspace 中。这实际上就是该工具的批处理操作模式。

Part Choices handling

将元件制造商 Part Choice 数据从外部企业系统（例如 PLM）传播到 Workspace 的方式经过设计，以避免数据重复或被意外删除的可能性。无论元件数据是 directly from the external system 导入到 Workspace，还是通过 CSV 文件导入，Part Choice 条目的创建和/或修改都会基于当前条件与数据历史进行智能处理：

• 如果正在导入的元件 Part Choice 条目在该 Workspace 库元件中已存在，则不会重复创建。
• 如果某个 Workspace 库元件的 Part Choice 条目是在 Workspace 内部添加的（非导入），则不会被导入的 Part Choice 数据替换。导入的 Part Choice 会作为该元件新的、额外的 Part Choice 添加。
• 如果为某个元件导入了新的 Part Choice 数据，它将替换该元件先前导入的 Part Choice 条目。

总结来说，除了会尊重元件现有的 non-imported Part Choice 数据之外，从外部系统导入的 Part Choice 数据将决定 Workspace 库元件的 Part Choice 条目。

在下面所示的示例图片中，输入的 CSV 文件不包含 PLM 条目 CVS-RES-1001（10k Resistor）的 Part Choice 数据（Manufacture Name 和 Manufacturer Part Number 参数），因此不会将其添加到 Workspace 库元件中。不过在该示例中，已从 Altium Designer Explorer 面板内手动为该 Workspace 库元件添加了一个 Part Choice 条目（Vishay）。

如果在后续导入/同步的 CSV 文件中包含了该元件（CVS-RES-1001）的 Part Choice 数据，如下所示，则新的 Part Choice 条目（Rohm）将被 added 到该元件——因为现有的“原生（native）”Part Choice 条目不能被导入的 Part Choice 数据替换。

如果再之后导入/同步的 CSV 文件为该元件提供了新的 Part Choice 数据，如下所示，则该 Part Choice 数据（Yageo）将替换之前导入的 Part Choice 条目（Rohm）——现有的“原生”Part Choice 条目（Vishay）保持不变。或者，如果 CSV 的 Part Choice 数据已被移除（MFR_.. 条目为空），导入过程将删除 Workspace 中现有的已导入 Part Choice 条目（Yageo）。

Multiple Manufacturer Part Choices

CSV Importer 也支持为同一元件导入多组制造商料号数据：通过在源 CSV 文件中使用重复结构，为每种制造商料号变体增加额外的元件条目。例如，如果源元件 CSV-RES-1001 有三个相关料号，则会为该元件包含三条 CSV 记录，每条记录指定不同的 MFR_NAME 和 MFR_PART_NUMBER 列数据（其中一条来自 Vishay Dale，另外两条来自 Yageo）。

当这些元件数据导入到 Workspace 时，会为料号 CSV-RES-1001 创建一个单一的元件条目，但会基于额外的 CSV 数据引用生成多个 Part Choice 条目。

Parameter Unit and Value handling

当通过 CSVImport 工具将元件数据从外部企业系统导入到 Workspace 时，Workspace 的自动化参数单位（Unit）处理会同时解析数值数据并处理其中的错误。

在元件数据导入或同步过程中，适用的 Component Template 中任何被指定为具备单位感知的 Type（Percent(%)、Watts(W) 等）参数，都会按相应方式进行解析。由于导入的参数值格式可能差异很大（它们是在外部系统（如 PLM）中定义的），Workspace 的单位感知数值处理能够覆盖所有可能的格式，并正确处理任何错误。

下图展示了一个示例：一组 Workspace 库元件通过一个 CSV 导入文件进行更新，该文件为每个元件条目包含 Power 参数。源 CSV 文件中的 Power 参数值使用了多种格式，其中还包含一个数值错误（62500x），对应 CSV-RES-1001 元件条目。在导入之前，Workspace 库元件不包含 Power 参数数据，并且都处于其第一个修订版（Revision 1）——如上方 Explorer 面板所示。

CSV 导入过程的结果如（上图）下方 Explorer 面板所示，体现了单位感知参数解析及其错误处理的效果：

• 由于 CSV 源数据格式错误，未为元件 CSV-RES-1001 添加 Power 值。未为元件 CSV-RES-1001 创建新修订版（仍为 Revision 1）。
• 其他所有元件的 Power 值源格式都已从源数据中被正确解析。已为正确更新的元件创建了新的修订版。随后进行的元件数据导入过程中，针对元件 CSV-RES-1001 的修订后 Power 值（62500u）也被正确解析——如下图所示。Workspace 库元件数据已更新，并创建了新的修订版（Revision 2）。