# 数据导入

# 目标读者

本文档的目标读者可能包括：

本系统的开发及实施人员
准备导入数据的用户数据管理员

# 功能说明

本系统遵循一切皆数据的原则，所有类型的数据，均支持通过 CSV 文件导入数据，导入时支持新建、更新、删除等操作。

提示

本系统的 CSV 解析格式遵循 RFC 4180 (opens new window) 标准。

# 数据导入方式

当前支持的导入方式有：

# 系统启动时自动导入

系统支持在启动时从配置的服务器目录自动导入一组CSV文件，详细信息请参阅配置导入文件路径开发

# 从数据列表页面导入

对于每种领域模型，系统界面支持手动导入CSV文件。

# 使用 `Reload Seed Data` 动作导入

在域模型列表页面，使用 Reload Seed Data 动作从配置的种子数据文件夹重新加载种子数据，导入的文件列表与系同启动时自动导入相同。

# 使用 `Import Seed Data Package` 导入

在域模型列表页面，使用 Import Seed Data Package 操作上传包含.CSV和其他引用文件的打包zip文件。

平台开发环境附带一个名为 packageSeedData 的gradle任务，用于生成这样的zip文件

导入完成后，支持在系统的界面上，查看导入的过程记录。

提示

种子数据(Seed Data) 一般是指在应用程序初始化或部署时，插入到数据库中的一组初始数据。这些数据用于提供应用程序所需的基本数据结构和参考数据，以确保应用程序能够正常运行。

特别的，牧言低代码平台的设计原则是包括定制代码在内的一切皆数据，所以整个业务系统完全是由种子数据构建的。

支持的导入对象范围为：

所有系统中的对象定义，如用户、用户组、角色等权限相关数据及组织、合同、合同行、合同行定义等数据，也包括领域模型定义，领域模型字段定义，表单定义，动态字段、动态字段定义等所有元数据。

如果你习惯使用一个例子来进行学习，可以直接查看一个完整的例子。

# 功能启用开发

本功能默认启用，功能的启用无需进行配置，但本功能正常工作依赖导入文件路径的配置，具体叙述如下

# 配置导入文件路径开发

需要在 application.yml 文件中配置 seedData.folder 选项，该选项指定了 CSV 文件的读取根路径，如下展示了一个针对 development 环境的配置示例：

development:
    seedData:
      folder: ${SEED_DATA_FOLDER:/app/data}

1
2
3

提示

该配置会优先从环境变量 SEED_DATA_FOLDER 中读取

其目录结构示意简述如下, 该目录的第一层子目录对应不同的系统环境，如希望在 development 环境导入的所有 CSV 文件，需要放置在 development 子目录下，当前系统已经预定义的环境如下所列:

在各个环境的目录下，不同的租户的种子文件存放在不同租户的子目录下。

development
testing
staging
production

在每个环境的数据目录下，会有一个 Organization.csv 文件，保存系统中首先导入的顶级租户的列表，该文件将会导入每个租户下的顶级组织及租户标识，是导入所有分租户数据的依据。

├── README.md
├── attachments --> 一般需要导入的附件放在该目录下，如 DyanmicTheme 使用到的 logo 等
│   ├── README.md
│   ├── background.jpeg
│   ├── favicon.png
│   └── logo.png
├── css --> 一般 DynamicTheme 的客制化 css 文件放在该目录下
│   └── README.md
├── development --> (development 环境) 
├── groovy --> 一般客制化 DynamicLogic 的源代码放在该目录下
├── review --> (review 环境)
│   ├── Organization.csv --> (最先导入的系统中所有顶级租户列表)
│   ├── README.md
│   ├── jiayu --> 对应顶级租户的租户名称
│   │   ├── DomainColumnClientSideTypeConfig.csv
│   │   ├── DynamicAction.csv
│   │   ├── DynamicActionDomainClass.csv
│   │   ├── DynamicActionDomainClass_jiayu.csv
│   │   └── UserGroup.csv
│   └── muyan --> 对应顶级租户的租户名称
│       ├── Group.csv
│       ├── GroupRole.csv
│       ├── Organization.csv
│       ├── RequestMap.csv
│       ├── Role.csv
│       ├── User.csv
│       └── UserGroup.csv
└── tree.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 文件更新判断

在导入前，对于每个 CSV 文件，系统都会判断本次导入的 CSV 文件的 md5 码与上次导入的 CSV 文件的 md5 码是否相同，如果两个文件的 md5 码相同，且上次导入的状态为成功，则系统会跳过本次导入。

# 数据准备及导入

以下章节描述了CSV文件数据准备相关的内容

# 文件名称

所有 CSV 文件需要以该对象的，不包含包定义的类名称开始，如 tech.muyan.Contract, tech.muyan.security.GroupRole 对象的导入 CSV 文件可以分别被命名为 Contract.csv 和 GroupRole.csv，或者 Contract_2019.csv， GroupRole_security.csv 等形式， .csv 后缀需要小写。

# 导入顺序及依赖

对于具有关联关系的一组数据，系统会自动根据模型定义中对象间的关联关系，识别出其之间的依赖关系，并在导入时，自动将被依赖的数据在依赖数据之前导入。

如果需要特殊处理的依赖关系，请在 domain 定义的 extInfo 中，通过 loadAfter 进行定义，

# 动态领域模型

动态领域模型定义中，指定 Seed Data 导入顺序的详细信息可以参考领域模型元数据章节。

# Legacy Domain

Legacy Domain 定义中的 loadAfter 属性定义例子如下：

如下是 DynamicIntegration Domain 定义中的例子:

  //表示在导入 DynamicIntegration 之前，需要先导入 Organization, DynamicLogic, User 三种对象
  static loadAfter = [Organization, DynamicLogic, User]

1
2

如果某种对象应该首先被导入，为阻止系统从其 Domain 定义中解析出其依赖，可将 loadAfter 属性设置为空数组，如下是 DynamicLogic Domain 定义中的例子:

  static loadAfter = []

# 标题行

所有待导入的 CSV 文件中，第一行均应该是标题行，标题行描述了该 CSV 文件中，数据的结构，以下是一个 Contract 对象导入的 CSV 文件标题行的示例及其说明

name(*),title,effectiveDate,ownerOrganization.name,Tags(#),Purpose(#),Total Amount(#),Seal Type(#),Contract Quantity(#),language,DELETE_FLAG

在模型中定义的基本字段，列的名称是该对象在模型定义中的字段名称。
在界面自定义的动态字段，列的名称是该字段在对象的界面上显示的 Label 字段的值。
后缀 (\*) 的列，如 name(\*) ，是查询字段，其描述如后查询字段小节所述。
包含 . 的列，如 ownerOrganization.name，是关联对象字段，其描述如后关联对象的查询小节所述。
后缀 (#) 的列，如 Purpose(#)，是动态字段，其描述如后动态字段小节所述。
名为 DELETE_FLAG的列，是一个特殊列，该列的值可为 Y 或 N，为 Y时，表示系统在导入时，需要删除通过查询字段找到的对象。
后缀为 (F) 的列，如 code(F), 表示该列的内容会从文件读取，文件的起始目录为 seedData.folder 所配置的目录
如果某一列在 Domain 中定义的字段类型为 StorageFieldValue, 则该列中的值应该为待导入的附件文件的文件路径。

注意

在系统内部，这个字段名称保存在 DynamicFieldInstance 对象的 label 字段中，要注意区分，这里不是 DynamicFieldDefinition 字段的 label 字段。

# 注释行

以英文分号(;) 开头的行是注释行，在导入时会被忽略，如下是一个包含注释的导入 CSV 文件的样例，所有以 ; 开头的行，为注释行，不会影响导入过程。

name(*)
; Normal user, only have permission to login
USER
; Admin user
ADMIN
; Developer user
DEVELOPER
; Biz user, can operate on biz objects(contract)
BIZ_USER
; Biz Admin
BIZ_ADMIN

1
2
3
4
5
6
7
8
9
10
11

# 查询字段

为了支持通过 CSV 文件创建或更新现有记录，系统支持通过查询字段查询现有记录，所有在导入文件第一行的标题中，后缀是 (\*) 的列，会被系统识别为查询字段。系统会根据所有查询字段的值，使用严格相等匹配，从系统中查询现有记录，并进行如下的相应处理：

如果查询结果为空，则系统会尝试新建一条数据并保存，并将导入记录中，该行数据的操作记录为新建。
如果查询结果不为空且只存在一条记录，则系统会尝试更新该条数据, 并将导入记录中，该行数据的操作记录为更新。
如果查询结果不为空且存在超过一条记录，则系统会跳过该行数据的导入，并将导入记录中，该行数据的操作记录为跳过。

提示

如果导入的 CSV 文件中，没有任何查询字段，则表示更新和删除功能不可用，导入时，所有的记录均会以新建方式处理。

# 关联对象的查询

系统支持通过关联对象字段，查询其关联对象，并将查询到的关联对象与待导入对象进行关联。

如上述字段 ownerOrganization.name, 表示在导入该对象的 ownerOrganzation 字段(该字段是一个 Organzation 对象）时，对于每一行数据导入时，都使用 Organization 类型的 name 属性，根据 CSV 文件中该列的值去查询现有的 Organzation 对象记录，并将查询到的记录与待导入的 Contract 对象关联起来，根据查询的结果不同，具体处理可能如下：

如果查询到的关联对象不存在，则终止该行的导入，并将导入记录中，该行数据的操作记录为失败。
如果查询到的关联对象有且只有一个，则继续该行的导入，具体最终结果取决于其他列的操作。
如果查询到的关联对象有多个，则终止该行的导入，并将导入记录中，该行数据的操作记录为跳过。

提示

关联字段也可以作为查询字段

注意

在导入某对象，无论新建还是更新时，其所依赖的关联对象必须已经在系统中存在，否则该对象的导入将会失败

# 动态字段

导入数据时，系统同时支持在界面上建立的动态字段的值的导入，所有动态字段在导入的 CSV 文件的标题行中，需要以 (#) 结尾。动态字段值的保存发生在主对象的保存完成后。如上述示例中，CSV 文件中，标题为 Purpose(#) 的列，系统在导入时，系统会查询 Label 为 Purpose 的合同动态字段，并进行数据导入。

如果该字段是一个选择字段，那么在导入时，系统会校验 CSV 文件中，该列的值是否在该字段的可选项范围中，如果其值不在备选范围中，则会终止该行数据的导入，并将该行数据的导入标记为失败。

系统限制

因为动态字段的保存与主对象的保存不在同一个事务中，因此可能发生主对象保存成功，但动态字段保存失败的情况，此时，主对象的状态与 CSV 文件中，会发生数据不同步。

# 特殊字符的转义

如果某列的内容中，包含英文逗号(,)，则该列需要使用英文引号(")包裹起来。
如果某列的内容中，包含英文的引号，且该列处于引号的包裹中，则需要将其用\进行转义。

# 空白字符处理

在从 CSV 文件中读取数据时，系统会自动将每列前后的空白字符删除。

注意

如 CSV 文件中的列前后存在空白字符，则每次导入时，该行均会被识别为需要更新，且更新后，数据库中保存的值，前后不包含空白字符。

# 对象删除

CSV 文件导入时，支持删除现有数据，通过如下的方式实现：

在 CSV 文件的标题行中，增加 DELETE_FLAG 列
对于要删除的行，在 CSV 文件中，将其 DELETE_FLAG 列的值设置为 Y

注意

CSV 文件的标题行中，必须指定了可以唯一确定一条记录的查询字段，对象的删除操作才能正确工作。

对于被标记为执行删除操作的行，下面是相关的错误处理逻辑：

如果查询到的现有数据有0条，那么系统会跳过这一行的删除处理。
如果查询到的现有数据有多条，那么系统会跳过这一行的删除处理。
如果导入的 CSV 文件中没有查询字段，则系统会跳过所有标记为删除的行的处理。

# 数据类型映射

如下列出了系统当前支持导入的类型，及其导入后的数据类型

数据类型	导入后的数据类型
`Boolean`	`java.lang.Boolean`
`String`	`java.lang.String`
`datetime`	`java.time.LocalDateTime`
`date`	`java.time.LocalDate`
`decimal`	`java.math.BigDecimal`
`integer`	`java.lang.Integer`
`long`	`java.lang.Long`
`Enum`	`java Enum`
`httpMethod`	`org.springframework.http.HttpMethod`
`java class name`	`Domain Object`
`StorageFieldValue`	`tech.muyan.storage.StorageFieldValue`

# Boolean

对于 Boolean 类型的字段，如下列出了值的对应关系，如果 CSV 文件中的字段值不在如下的范围中，则系统会将该行的导入标记为失败

CSV 文件中的值	导入后的值
`Y`, `y`, `Yes`, `YES`, `true`, `TRUE`, `T`, `t`, `是`, `1`	`true`
`N`, `n`, `No`, `NO`, `false`, `FALSE`, `F`, `f`, `否`, `0`	`false`

# 日期及时间

对于日期类型的字段，如下是支持的相关日期/时间类型列表，如下列表中的各字母所代表的时间、日期中的相关部分可参考 SimpleDateFormat (opens new window)

 "yyyyMMdd" 
 "dd-MM-yyyy"
 "yyyy-MM-dd"
 "MM/dd/yyyy"
 "yyyy/MM/dd"
 "dd MMM yyyy"
 "dd MMMM yyyy"
 "yyyyMMddHHmm"
 "yyyyMMdd HHmm"
 "dd-MM-yyyy HH:mm"
 "yyyy-MM-dd HH:mm"
 "MM/dd/yyyy HH:mm"
 "yyyy/MM/dd HH:mm"
 "dd MMM yyyy HH:mm"
 "dd MMMM yyyy HH:mm"
 "yyyyMMddHHmmss"
 "yyyyMMdd HHmmss"
 "dd-MM-yyyy HH:mm:ss"
 "yyyy-MM-dd HH:mm:ss"
 "MM/dd/yyyy HH:mm:ss"
 "yyyy/MM/dd HH:mm:ss"
 "dd MMM yyyy HH:mm:ss"
 "dd MMMM yyyy HH:mm:ss"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 枚举类型

如果枚举类型中定义了可以从其显示值反向查询到枚举对象的 get 方法，则系统支持在 CSV 文件里，列值为其界面显示值的枚举数据列导入，否则系统只能支持 CSV 中值与其内部值完全一致的枚举数据导入。

# 附件类型

对于附件类型的列，准备 CSV 文件时，对应列需要填写从配置的 seedData.folder 的目录起算的相对文件路径，导入时，系统会将该列导入为系统中的 StorageFieldValue 对象，并建立必要的对象间关联关系。

# 根目录字段

如果某个字段为 tech.muyan.Organization 类型，可以使用 $ROOT_ORG$ 这个占位符来指定引用到当前租户的根组织。

提示

本处的特殊处理是为了能够在不同租户间快速拷贝系统默认的相关种子文件，而无须针对每个租户进行组织名称的替换。

# 支持新的数据类型映射开发

所有导入时的数据类型映射均在 tech.muyan.importexport.converter.ConverterFactory 中定义，该类提供了一个registerConverter的工具方法，用于向系统中注册 CSV 导入时的数据映射实现，举例如下：

ConverterFactory.registerConverter(type -> type != null && type.contains(".enums."), new EnumConverter());

如上方法注册了一个名为 EnumConverter 的数据映射实现，
该实现启用的条件使用一个 predictor指定，该predictor接收一个字符类型的参数，该参数为：对待导入的领域模型类调用 DomainMetaController.get 方法返回的元数据中的 type 字段。
如上述的 predictor 限定了该类型映射的条件为：该字段的 type 属性不为空，且包含 .enums. 部分。

# 查看导入记录

系统输入导入的记录保存在 ImportRecord 中，可以使用具有 /ImportRecord 地址的 GET 权限的用户进行查看，默认情况下，具有 ROLE_ADMIN 和 ROLE_DEVELOPER 角色的用户具有查看导入记录的权限。

如下的信息会被保存在导入记录中：

导入对象的类型
导入 CSV 文件的 MD5 码
导入状态：可能为
- 未开始
- 成功
- 失败
- 部分成功
- 运行中
导入开始时间
导入结束时间
导入 CSV 文件的标题行
插入的对象 id 列表
更新的对象 id 列表
删除的对象 id 列表
失败行 CSV 中的原始信息
跳过行 CSV 中的原始信息
导入的 log 记录
跳过的行数
失败的行数
成功更新的行数
成功创建的行数
成功删除的行数

# 一个完整的例子

如下展示了一个完整的系统可导入的 CSV 文件的示例，并基于此，讲解了上述相关设定、概念等。

CSV 文件名称: Contract.csv

CSV 文件内容示例：

name(*),title,effectiveDate,total,ownerOrganization.name(*),contractStatus,Tags(#),Purpose(#),Total Amount(#),Seal Type(#),Contract Quantity(#),Is Important(#),language,lines.name[:],DELETE_FLAG
牧言科技2020年笔记本采购合同,笔记本采购合同,2020-01-01 00:00:00,45000,牧言科技,Active,"[\"一次性合同\",\"低风险\"]","采购开发使用笔记本",35000,公章,3,是,contracts\language_2020.docx,"[line1:line2]",N
牧言科技2019年笔记本采购合同,笔记本采购合同,2020-01-01 00:00:00,45000,牧言科技,Active,"[\"一次性合同\",\"低风险\"]","采购开发使用笔记本",35000,公章,3,是,contracts\language_2019.docx,"[line3:line4]",Y