画鸵萌宠网
外部交换平台 实施技术红皮书
NC-UAP 5.0
用友NC-UAP 2014-08-18
目 录
第一章
1. 2. 3.
第二章
1.
1.1
1.2
2. 3.
3.1 3.2 3.3
4.
4.1 4.2
5.
5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8
6.
6.1 6.2
第三章
1.
1.1 1.2 1.3
2.
2.1 2.2 2.3
总体概述 .................................................................................. 1
外部交换平台总体结构........................................................................... 1 外部交换平台功能特点........................................................................... 1 外部交换平台V50版新增功能 .............................................................. 2
实施简介及相关注意点 .......................................................... 4
实施方法简介........................................................................................... 4
外系统数据导入的一般步骤 ................................................................................... 4 外部交换平台服务器端文件目录结构 ................................................................... 5
Servlet的URL地址参数与XML交换文档头属性的关系 ................. 7 向NC系统发送数据方式 ....................................................................... 8
手动界面发送 ........................................................................................................... 8 后台预警发送 ........................................................................................................... 9 自定义程序发送 ..................................................................................................... 11
回执及异常出错信息............................................................................. 12
回执格式 ................................................................................................................. 12 异常和错误编码 ..................................................................................................... 12
外部交换平台总体参数设置................................................................. 13
单据导入方式 ......................................................................................................... 13 单篇最大传输上限 ................................................................................................. 14 导入过程是否记录中间文件 ................................................................................. 14 外部系统默认帐套 ................................................................................................. 14 设置客户端IP范围 ............................................................................................... 14 接收公司匹配规则 ................................................................................................. 15 回执文件后台备份 ................................................................................................. 15 回执和导出文件编码格式 ..................................................................................... 15
单据流水号和单据并发控制................................................................. 15
单据流水号的概念和作用 ..................................................................................... 15 单据并发控制 ......................................................................................................... 16
单据交换规则定义 ................................................................ 17
基础篇—简单单据配置......................................................................... 17
表头记录的配置 ..................................................................................................... 19 表体记录的配置 ..................................................................................................... 20 字段属性项的配置 ................................................................................................. 21
高级篇—复杂字段配置......................................................................... 29
VO记录的配置规则 .............................................................................................. 29 简单数组记录的配置规则 ..................................................................................... 31 VO数组记录的配置规则 ...................................................................................... 33
第 2 页
2.4 2.5 简单集合记录的配置规则 ..................................................................................... 35 VO集合记录的配置规则 ...................................................................................... 37
第四章
1. 2. 3. 4.
基于外部交换平台的单据集成开发 .................................... 43
注册单据相关信息................................................................................. 43 生成＆配置交换规则定义文件............................................................. 46 辅助信息项设置..................................................................................... 49 插件代码维护......................................................................................... 50
第 3 页
第一章 总体概述
1. 外部交换平台总体结构
日志和中间文件整理服务基础数据对照表辅助信息配置外系统自动发送数据手动加载数据XML数据包XML数据包ServletXML数据包接收外系统的文档XML数据包XML处理器解析数据并翻译转换NC业务模块适配器NC财务业务模块NC供应链业务模块自动加载代理外系统接收代理NC基础数据模块外部交换平台数据高速缓存外部系统注册转换规则定义
图 1.1.1 外部交换平台总体结构图
外部数据交换平台主要用于外部系统和NC系统进行集成。利用外部数据交换平台，可以将外系统的基本档案和业务数据发送到NC系统中，并进行相关的业务操作，如审批、弃审，也可以通过发送XML格式的查询条件导出NC系统的数据（需业务插件支持），导出的数据可以附着在回执文件中，也可以直接向外部系统回发HTTP请求。
2. 外部交换平台功能特点
采用XML格式作为统一的数据交换标准，为数据访问提供简便、 统一的
模式。XML格式在数据表达和描述方面有着很大的优势，逐渐成为业界的标准，采用XML格式作为交换标准格式可以很好的保护企业投资。
面向服务的架构。这使得第三方系统可以随时随地向NC系统发送相关
的业务数据，NC内部的预警服务及工作流引擎使得NC系统可以在合适
第 1 页
的时候向第三方系统传送需要的数据，并且满足第三方系统的格式规范。
灵活配置。数据转换的规则可灵活定义，独立于应用集成和业务逻辑，
也就是说根据不同的外部数据结构，直接通过修改交换规则文件的定义，即可达到各种异构数据无缝集成的目的。
自由扩充。对于标准产品不支持的业务单据，如果有集成需求，外部交
换平台提供了向导式的二次开发工具，集成了所有与二次开发相关的功能及配置，支持动态部署，可以在用户环境上进行快速有效的开发。
3. 外部交换平台V50版新增功能
与外部交换平台V3序列产品相比，V50版外部交换平台在功能上得到了进一步的完善，在易用性上也有了很大改进。
1) 单据交换规则的定义更加丰富和灵活。可以为某一单据模型中的某一字
段定义路径，也可以为一个集合中的实体元素定义路径，甚至可以为某个字段定义XML结构查询的公式。这些都得益于对XPath功能的模拟，使得XML文件间结构转换的能力更强，但这个交换规则的学习成本可能比较大，后续版本需要图形化和简洁化。
2) 为基于外部交换平台的自定义单据的集成提供了一个快速开发工具。这
个工具以向导方式将集成一个自定义单据所要做的工作贯穿起来，包括：单据信息注册、校验文件生成、样本数据导出、辅助信息格式配置、业务插件类代码生成和编写，甚至还包括业务插件类代码的实时编译和部署，样本数据的导入测试和结果展示等。
3) 启用NCV50新缓存机制。这不但使得外部系统设置、辅助信息设置和基
础数据对照表的设置能够实时地作用于外部数据导入过程中，而且对于基本档案数据的访问也实现了实时性，效率得到了更高的优化。 4) 基础数据对照导入功能更加丰富。基础数据对照在V35版根据基本档案
自动增加的基础上，新增了基础数据对照的XML文件增加和EXCEL文件增加的功能。
5) 外部交换平台总体参数配置功能更加丰富和完整。这部分配置主要包括
单据导入方式、接收公司匹配规则、导入过程是否记录中间文件、回执和导出文件编码格式、设置客户端IP范围等，这些功能的可配置性极大地提高了外部交换平台的灵活性和可扩展性。
6) 对单据导入过程中的并发程度进行控制。对于某一单据类型，一共给出
了四种并发控制程度，实施人员可根据具体情况设置合理的并发控制级别，避免单据并发导入引发的错误。
7) 外系统数据实现后台预警发送。借助预警平台的定时触发功能，系统可
以自动将保存在服务端某个目录下的外系统数据导入NC系统中，实现了异步驻留的数据发送方式。
8) 对数据导入过程中的异常进行了重新划分，对于错误信息进行了编码。
前者带来的好处就是错误提示信息更加明确化，后者主要用于第三方系统程序内部识别导入过程中是否出现错误以及具体的错误信息。
第 2 页
9) 进一步约束外部交换平台导入单据的语义。对每个单据需要定义一个组
织字段，用于确保往某个接收方，比如说A公司做加载数据时，导入的数据能真正进入A公司，这个组织字段一般是公司或者主体账簿。为单据定义组织字段之后，如果数据里相应组织字段的值不为空，则要求其值与接受方保持一致，如果数据里相应组织字段的值为空，则取接受方的内容为组织字段的值。 10) 易用性改进。【手动加载界面】对文件目录、回执目录、目标URL地址、
加载成功转移目录的配置增加记忆功能，就是说以相同公司相同用户登陆时，上述各项的配置内容默认显示为最后一次用户设置的值，避免用户每次都需要重新设置。【交换规则定义】增加了查找、定位字段的功能，单据交换规则树上的右击菜单也更加简练明确，同时为字段的导入导出公式定义增加新版本的公式编辑器，定义公式更加方便简洁。
上述功能我们在接下来的内容中会具体提到。
第 3 页
第二章 实施简介及相关注意点
NC外部交换平台的主要功能就是将不同外系统的数据导入NC系统。由于不
同系统之间对于相同单据的数据在表示上千差万别，需要外部交换平台对单据的XML格式的外系统数据进行格式转换和数值翻译，然后将转换后生成的XML格式的NC标准数据实例化为NC系统对应单据的数据对象，并调用业务模块的接口（服务）进行保存或者更新。
NC系统在后台有一个Servlet伺候服务，等待并处理客户端的POST方法请求（外部交换平台提供界面客户端和预警客户端，对于同步集成方式，外系统可以自定义发送客户端）。客户端往根据Servlet的URL建立的连接的输出流中写待发送数据文件的内容，而后台服务端则从请求的输入流中读取数据文件内容，然后再进行后续处理。关于客户端发送数据的具体内容请参考2.3节。
2.1节介绍了要将某个外系统的某种单据类型的数据文件导入至NC系统的最简单方法。其余小节介绍了在实施数据导入过程中容易混淆而需要注意的地方，或者是一些常用的工具等。
1. 实施方法简介
1.1 外系统数据导入的一般步骤
外系统根据单据类型将相同单据类型的数据组织在一个XML文件中，然后将其发送到NC系统的某个账套下的某个公司或集团中（对于有账簿信息的单据而言，比如会计科目或者凭证，则是某个公司的某个账簿之下）。一般来说，如果需要发送某种单据类型的数据至NC系统中，需要如下几步：
一、注册外部系统。如果不存在可用的外系统的话，请在“外部系统信息注册”界面中注册一个外部系统。
二、准备外系统数据。这份数据可能是外系统直接输出的，也可能是二次开发人员通过写程序从第三方系统数据库中抓出来的，或者由Excel格式或其他格式文件转换过来的。写这份数据时，可以参考NC安装盘附带的XML模板，XML文件头或者说文档头的属性项请参照2.2节详细说明。
三、配置辅助信息（可选）。如果要导入的单据数据需要辅助信息配置，在“辅助信息配置”界面根据外部系统、单据类型、接收公司及主体帐簿（如果带的话）为此次文件发送配置辅助信息。
四、设置基础数据对照（可选）。如果要导入的单据数据需要作基础数据对照（对于需要参照基本档案的字段，如果其值不能按名称或者编码自动翻译过来
第 4 页
的话，在导入过程中系统会自动提示必须为该值做基础数据对照），在“基础数据对照”界面根据需要参照的外部系统、需要参照的基本档案、公司（取当前登陆公司）及主体帐簿（如果带的话）为需要对照的值做基础数据对照。
六、配置Servlet的URL地址。将要发送至的帐套编码作为account属性值写入要发送到的Servlet的URL中（或者写入XML文件的头中），将接收公司和主体帐簿（如果带的话）的代码拼成接收方（接收公司编码@接收主体账簿编码）作为receiver属性写入要发送到的Servlet的URL中（或者XML文件的头中）。详细说明请参见2.2节。
最后，就可以利用客户端触发该单据类型的数据文件的发送了。
NC外部交换平台内置了常用单据类型数据的导入功能，对于这些单据类型， 如果外系统数据遵照了这些单据类型的交换规则定义(即如果外系统的数据严格按照NC安装盘附带的相应单据的XML模板生成)，那么按上述步骤相对比较简单地就可以导入数据。但是如果外系统数据未能遵照单据类型的交换规则定义，则需要修改该单据类型的交换规则定义。做法就是将该单据的普通交换规则定义文件另存为特定该外部系统的交换规则定义文件，并根据单据交换规则定义规范修改该特定交换规则定义文件，具体需要参见第三章[单据交换规则定义]，然后再行导入。对于非系统内置或者自定义的单据的导入，需要基于外部数据交换平台做二次开发，这部分内容可参见第四章。
1.2 外部交换平台服务器端文件目录结构
外部交换平台服务端的目录结构安排如图2.1.1所示，其中NC_COMMON为安装盘根目录，也是中间件的工作目录。
从上图可以看出，外部交换平台配置文件目录pfxx与webapps一样同在安装盘根路径下，其中：
pfxxtemp目录，存贮外部交换平台接受到的原始数据文件、转换翻译完毕的标准XML文件、传送失败的文件。
xmleditor 目录，存放校验文件管理的样式文件，可不用考虑。 exportbills 目录，存放外部交换平台发送给外系统的数据文件。 billdefine目录，存放所有需要交换的档案和单据的交换规则文件。 auxiregister目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据的辅助信息格式。详细情况参考4.3节辅助信息项设置。
businessprocessor目录，每个模块在这个目录下注册一个文件，文件的内容
第 5 页
是模块所涉及单据在外部交换平台的注册信息，如单据类型、业务插件类名称、业务操作、单据导入范围、单据加锁级别等。详细内容参考4.1节注册单据相关信息。
billconfiginfo目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据的基本信息，如表和VO对象名。详细内容参考4.1节注册单据相关信息。
sendurl.xml 文件，定义了NC系统通过HTTP回发数据给外系统时的各种参数，如发送地址、业务操作、发送方、接受方、单据类型等等。
globalset.xml 用于存放外部交换平台的全局参数，如默认帐套、单篇最大传输上限等。
图 2.1.1 外部交换平台服务端文件目录结构
第 6 页
2. Servlet的URL地址参数与XML交换文档头属性的关系
在外系统的单据数据的导入过程中需要用到一些初始化信息，如帐套、接收方（包括接收公司和主体账簿）、数据所属外部系统（发送方）、单据类型、业务处理（新增、更新还是查询）等。这部分数据可以在Servlet的URL地址的参数中指定，也可以在XML数据文件的文档头属性中指定，但是在Servlet的URL地址的参数中指定的信息比在XML数据文件的文档头属性中指定的信息有更高的优先级别。比如在Servlet的URL地址参数中指定receiver=yk，而在XML数据文件的文档头属性中指定receiver=yy，则最终还是将数据发送到yk公司。
下面我们依据实例来逐一介绍各个常用属性。图2.2.1是一个典型的NC服务器的Servlet的URL地址，“http://10.7.3.226:80/service/XChangeServlet”是后台Servlet的服务名，V50之前的版本直接指定Servlet的类名，现在指定的是包装之后的服务名。“?”号之后的“account=0001&receiver=yy”就是设置的URL地址参数，一般情况下这个地方只设置帐套编码和接收方两个属性。至于这两个属性的含义下面会介绍到。
图2.2.1 典型Servlet的URL地址
图2.2.2是一个典型的XML文档头，文档头的根标签名是ufinterface，后面跟着就是各种初始化信息的设置。我们将这些属性分为三类：必须设置的属性、根据Servlet的URL参数设置决定是否必设的属性和根据需要决定是否设置的属性。
图2.2.2 典型XML文档头
【必须设置的属性】：
billtype属性，这个属性值决定了这个XML文件（文档）中所有单据的单据类型，外部交换平台所有的处理都是围绕单据类型的。
sender属性，这个属性值设置的是外系统编码，指定的是数据的来源系统，即习惯上所说的发送方。
proc属性，这个属性值设置对文件中所有单据要做的操作，如新增add、更新update、删除delete、查询query等等。单据具体支持哪些业务操作可以到[二次开发工具]-[交换平台设置]-[交换单据设置]中查询。 【根据Servlet的URL参数设置决定是否必设的属性】：
这些属性其实也是必设属性，但如果Servlet的URL参数里面设置了这几个属性的话，XML文档头里面可以不设置这几个属性值，即使设置了也不会起作用。
account属性,这个属性指定要将数据导入至NC系统的哪个帐套。
receiver属性，这个属性指定数据的接收方。接收方又是有一定格式的，可以将这个格式用一个正则表达式表示为：
接收方=（公司编码|公司主键）(@主体帐簿编码)？
第 7 页
也就是说接收方根据单据类型的需要，可以是公司或者公司下的主体帐簿。当接收方是公司，如编码为“yy”名称为“yk”的公司，其主键为“1046”，那么根据外部交换平台总体参数设置中的接收公司匹配规则的设置（参考2.5节）可设为receiver=yy或者receiver=1046。当接收方是公司下的主体帐簿时，如编码为“yy”名称为“yk”主键为“1046”的公司下有一编码为“yy-0001”名称为“yy公司基准帐簿”的主体帐簿时，根据外部交换平台总体参数设置中的接收公司匹配规则可将接收方属性设置为receiver=yy@yy-0001或者receiver=1046@yy-0001。
【根据需要决定是否设置的属性】：
filename属性，在数据导入过程中，对于每张单据我们都可以记录其原始数据、翻译后数据，对整个文档我们也可以记录其导入后的回执信息，这个filename属性的值就是用于记录上述数据文件时的文件名。当然，如果您没有设置的话，系统会为每个导入的文档默认生成文件名。
isexchange属性，这个属性值决定了在外系统的数据在导入NC系统的过程中，是否使用外部交换平台提供的翻译转换和校验功能。正常情况下应将这个属性设置为“Y”，或者干脆不设。除非从其他NC系统产生的符合NC转换后标准的XML数据直接导入NC系统，并且很多基础档案数据字段直接用的是PK值，此时可以设置属性为“N”和“n”，可避免无谓的翻译转换。
replace 属性，这个属性值决定是否允许将相同单据往同一个接收方重复导入。V50版的插件一般允许相同单据重复导入，除了将第一次导入视作新增之外，其余导入视作更新。关于这方面的具体内容请参见2.6节内容。如果不允许相同单据的重复导入，那么将这个属性值设置为“N”或者“n”。否则将其设置为“Y”或者干脆不设。
总的来说，XML文档头的【必须设置的属性】和【根据Servlet的URL参数设置决定是否必设的属性】，均为在外系统交换文档发送过程中必须得到的初始化信息，可以在Servlet的URL地址参数中设置，也可以在XML文档头属性中设置，但必须进行设置。而对于XML文档头的【根据需要决定是否设置的属性】，也可以在Servlet的URL地址的参数中设置，但一般不推荐这么做。
3. 向NC系统发送数据方式
NC外部交换平台支持客户端以同步和异步两种方式发送（加载）外部数据。其中NC外部交换平台为异步加载方式内置了两类客户端：界面和预警，而对于同步加载方式，外系统需要编写往NC后台Servlet发送文件的代码，下面分别介绍它们：
3.1 手动界面发送
这是外部数据最简单也最常用的一种客户端发送方式，点击：[客户化]→[外
部交换平台]→[外部数据发送]，在打开的界面中选择需要发送的文件，如有必要，修改目标URL地址的receiver参数值，选择“发送”菜单即可。详细内容请参考外部交换平台的用户手册。
第 8 页
图2.3.1 外部数据发送界面
3.2 后台预警发送
点击：[客户化]→[预警平台]→[预警条件配置]→[条目配置]→[增加]，在弹出的预警条目设置对话框中配置一个类型为“外部交换数据后台发送”的预警条目，其预警条件的配置如图2.3.2所示。在该预警条件标签页中内置了四个预警条件： 待发送文件目录
该预警条件阈值用于设置用户数据文件目录（不能为空）； 回执目录
该预警条件阈值用于设置存放单据导入之后的回执信息的目录，每张单据一个回执文件，如果用户不设置这个阈值，系统在待发送文件目录下默认创建目录/logdir作为回执目录； 发送后文件转移目录
该预警条件阈值对于想将能够成功加载的文件备份走的用户有用（一般不用设置）； 发送配置信息
该预警条件阈值是一个可扩展的预警条件阈值，它用于配置将什么样的文件发送到哪个URL地址（不能为空）。这个配置值的格式如下：
第一部分是单据类型：
第 9 页
第二部分是外系统编码：
第三部分是目的URL地址：
上面所列发送配置信息项取值的意思就是将单据类型是“Test1”， 外部系统编码为“1101”的文件发送到NC外部数据接收的Servlet地址：urladdress=http://localhost:80/service/XChangeServlet?account=0001&receiver=yy。这个地方如果我们将单据类型的取值设为“XX”或“xx”的话，表示任何单据类型的文件都可以往某个地址发送，相当于通配符的意思，但对于外部系统编码没有通配符。
图2.3.2 预警条目配置
发送配置信息是一个可扩展的预警条件阈值，其的意思就是用户可以在预警平台的类型注册对话框中修改名为“外部交换数据后台发送”的预警类型定义，增加作为预警条件的发送配置信息项，以实现数据文件的多点发送。点击：[客户化]→[预警平台]→[预警条件配置]→[在“类型配置”标签页选中“外部数据交换后台发送”行]→[类型配置]→[编辑]，弹出“类型注册”对话框，如图2.3.2所示，为其增加了一个发送配置信息阈值项。需要注意的是该新增阈值项的名称必须以字符串“postconfig”打头，如“postconfig1”、“postconfig12”，„„等。这样配置更多的发送配置信息，使得能有选择地将某个特殊单据类型特殊外部系统的数据文件能够发送到某个指定服务器地址去。
第 10 页
图2.3.2 预警类型注册
配置完毕，即可由预警平台调度和执行发送任务。另请注意，在待发送文件目录、回执目录和发送后转移目录的设置上本地客户端和服务器端文件系统的差别，如目录“c:/aaa”指的是服务器端文件系统路径而非客户端文件系统地址。
3.3 自定义程序发送
以Java代码为例，介绍外系统作为客户端如何向NC系统发送数据：
// 获取Servlet连接并设置请求的方法
String url = “http://10.7.3.225:8080/service/XchangeServlet”; URL realURL = new URL(url);
HttpURLConnection connection = (HttpURLConnection)realURL.openConnection(); connection.setDoOutput(true);
connection.setRequestProperty(“Contect-type”, “text/xml”); connection.setRequestMethod(“Post”); // 将Document对象写入连接的输出流中 File file = new File(“C:/samples/psndoc.xml”); InputStream input = new FileInputStream(file);
Document doc =XMLUtil.getDocumentBuilder().parse(input);
Writer writer = new OutputStreamWriter(connection.getOutputStream(), “UTF-8”); XMLUtil.printDOMTree(writer, doc, 1); // 按照XML文件格式输出 // 从连接的输入流中取得回执信息
InputStream inputStream = connection.getInputStream();
Document resDoc = XMLUtil.getDocumentBuilder().parse(inputStream); // 解析为Doc对象 // 对回执结果的后续处理 …
[说明] 关于XML操作可以用XMLUtil类,关于发送的API，可以直接用PostFile类
第 11 页
4. 回执及异常出错信息
4.1 回执格式
加载外部系统数据时，对于导入的数据文件中的每张单据，都会给客户端返回一个回执信息，记录单据导入成功与否，以及失败的原因。回执信息也是一个XML文件，其一般格式如下：
图2.4.1 回执文档的一般格式
回执信息中还可以嵌套单据，这个时候可以将外部交换平台看作简单的信息中心，外系统发送过来一个消息，NC系统回应一个消息。如查询类的单据，外系统发送一个表示查询条件的信息，NC系统返回所有符合查询条件的单据，这些单据就是内嵌在回执信息中的。再如，用这个功能来实现NC系统和外系统在某种程度上的流程集成，外系统发送一张走流程平台的单据，然后再由外部交换平台返回流程平台处理后得到的单据。
4.2 异常和错误编码
异常信息对于使用外部交换平台是极为重要的，有助于实施人员分析数据导入结果，查找数据导入失败原因。外部交换平台中的异常分类：环境初始化异常、单据转换异常和业务插件处理异常。这个划分是基于一个外系统某单据类型的XML交换文档在导入NC系统过程中所需处理阶段而给出的。如果单据导入失败，那么在回执信息的 错误编码则直接定位于发生错误的分类：配置错误、数据错误、系统错误，然后在某种错误下再进行细分。这些错误信息都通过错误编码的方式在单据导入 第 12 页 的回执信息的 5. 外部交换平台总体参数设置 点击：[客户化]→[外部交换平台]→[交换平台日志]→[参数设置]，在交换平台日志界面打开参数设置对话框，如图2.5.1所示。在这个对话框中，可以设置在外部数据导入过程中起到相当作用的参数，您可以根据需要对这些参数的设置进行改动。设置的参数值实时生效，不用重起后台服务器。 图2.5.1 总体参数设置 下面我们来介绍这些参数的功能及需要注意的地方： 5.1 单据导入方式 外部交换平台以交换文档中的单据为单位，支持非独立事务和独立事务两种导入方式，即同一XML文档对象中的所有单据批量处理和同一XML文档对象中的每张单据单独处理。例如，一个凭证类型的XML文档由一百张凭证组成，如果将交换平台总体参数的单据导入规则设置为“同一文档里的所有单据批量处理”的话，那么如果在导入这个文档的过程中有任何一张凭证发生错误，将导致 第 13 页 所有的这一百张凭证导入失败，但是如果单据导入规则设置为“同一文档里的每张单据独立处理”的话，那么即使这一百张凭证里有些凭证在导入过程中失败了，也不会影响到其余单据的成功导入。通俗一点的说话就是，非独立事务就是文档中的所有单据要么一块儿成功，要么一块儿失败，而独立事务就是文档中的每张单据的成功导入与否不会受其他单据导入成功与否的影响，当然如果从文档中导入的单据有先后顺序的话，选择独立事务可能也就起不到作用了。系统默认的单据导入方式是“同一文档里的所有单据批量处理”。 5.2 单篇最大传输上限 对于要导入的单篇文档或者单个文件来说，其大小是受服务器端系统性能影 响的。系统默认单篇最大传输上限是2048KB，这个大小一般系统的存储器都能够满足。如果用户导入的文件大于设置的值，回执文件就会提示“文件长度超过设定长度”的错误。因此，用户可以根据需要，如待导入文件的大小和机器性能调整这个值，最大大概能设置到214–215KB，也就是20000KB左右，建议设置在5000KB以下，以便得到较好的传输性能。 5.3 导入过程是否记录中间文件 这个参数主要用于控制所导入文档的每张单据是否在服务器本地做备份记录，主要做两次备份，分别是原始单据备份和转换翻译后单据的备份，前者备份至目录NC_HOME/pfxx/pfxxtemp/indocs/下，后者备份至目录NC_HOME/pfxx/pfxxtemp/translated/下。这些信息在找错排错中是非常有用的，比如发生找不到某个字段元素的错误，它可能是交换规则定义错误引起，也可能是外系统数据格式错误引起，这个时候将备份的导入原始单据和转换后的单据做一个对比，便可以很快定位问题。系统默认是勾选“导入过程是否记录中间文件”。 5.4 外部系统默认帐套 将某个外系统数据文档导入到哪个帐套是由Servlet的URL地址的account参数或者文档根属性account决定的，但是如果这两个地方都没有申明这个值，那么系统就将外部数据导入至这个参数设置的帐套中。系统默认没有设置这个属性，但打开对话框就会显示当前系统所有帐套编码。 5.5 设置客户端IP范围 这个参数属于外部交换平台安全性方面的设置。我们在这里设置允许向NC系统发送数据文件的地址范围，这样我们可以确保与合法的外部系统进行数据集成。如，假设目前我们只允许地址为10.7.3.255和10.7.3.233两个IP地址的客户端发送数据，那么我们就启用这个属性设置，并将这两个IP地址输入至其输入框中，中间使用；号隔开。设置完这个属性之后，我们再去利用这两个IP地址 第 14 页 上的客户端发送外系统数据的话，回执文件就会提示“发送方地址不合法！”。 5.6 接收公司匹配规则 接收公司匹配规则是指在导入过程中如何对接收方参数中指定的公司值进行翻译，有两个可选值：按编码或者按PK，系统默认值是“按编码”。比如用户现在要将外部数据发送到编码为“yk”，PK为“1046”的公司，如果用户将其设置成“按编码”，那么在Servlet的URL参数或者待导入文档根属性的地方写上：receiver=yk，如果用户将其设置成“按PK”，那么相应写的是receiver=1046。这方面的内容可以参考2.2节。 5.7 回执文件后台备份 对于导入的每一张单据，外部交换平台都会给客户端或者发送方一个回执信 息即一个XML格式的回执文档。如果您使用的数据发送方式是手动界面发送或者后台预警发送的话，回执信息都会以文件的形式保存到指定目录下，但是如果通过自定义程序实时发送数据的话，当出现传输异常时就需要在后台备份一下单据的每个回执文件，目的就是检查返回给发送方的数据是否正确。回执文件后台备份这个参数就是用于控制是否后台备份这个文件，系统默认不进行备份。 5.8 回执和导出文件编码格式 这也是一个便利工具，目的就是使得外部交换平台导出的XML数据文件或者 单据回执文件的编码格式可配置。如果与NC系统交互的第三方系统只能处理gb2312编码格式的文件，经过配置之后就可以相当方便的达到目的，只是此时如果回执信息包含非gb2312编码字符，则可能显示不正常。系统默认回执和导出文件的编码格式是UTF-8，外部交换平台同时支持UTF-8和gb2312格式文件的导入。 6. 单据流水号和单据并发控制 6.1 单据流水号的概念和作用 单据流水号在外部交换平台中是一个相当重要的概念，可以将其看作一张单据在外部交换平台中的标识。一般情况下，需要为待导入的每张单据定义一个流水号，如果未定义的话，系统会自动为导入的每张单据生成一个独一无二的流水号。外部交换平台将同一单据类型并具有相同流水号的单据看作是同一张单据，如果重复往同一接收方发送具有相同流水号的单据时，第一次会在NC系统新增该单据，其后均更新已导入单据。但如果往不同接收方导入具有相同流水号的单据，第一次同样是新增该单据，其后也是新增且是往不同接收方新增，但往往会发生编码名称重复等错误，取决于不同的档案或者单据在不同组织内是否控制编 第 15 页 码或者名称重复。 我们可以将数据导入与界面录入做一比较：往某个接收方如A公司发送某种单据类型的数据，就相当于A公司某个用户登陆并打开相应单据界面进行制单。第一次往A公司发送某个流水号的单据，就相当于在界面新增一个单据；再一次往A公司发送具有相同流水号的单据，就相当于在界面上修改原来新增的单据一样。这个时候如果将具有相同流水号的单据发送至B公司的话，就相当于以B公司某个用户登陆系统，在相应单据界面上新增一张与原来在A公司新增的单据在数据上一模一样的单据。如果根据业务这在很多系统中是不允许的，外部交换平台跟前台界面操作一样，同样会报错。 6.2 单据并发控制 点击：[客户化]→[二次开发工具]→[交换平台设置]→[交换单据设置]，打开业务插件配置界面如下。 图2.5.2 为业务单据设置并发级别 系统为每种单据类型的数据内置了四个并发加锁级别，由低到高分别是：单据类型、单据类型+公司（账簿）、单据类型+流水号、单据类型+公司（账簿）+流水号。 第 16 页 第三章 单据交换规则定义 本章介绍在“交换规则定义”界面上如何为在外部交换平台中注册的单据进 行外系统与NC系统之间交换规则的定义。外部交换平台除了支持内置单据的标 准外系统数据以及U8系统数据的集成之外，利用单据交换规则定义扩展对其他外部系统（Sibeil,SAP等等）的第三方数据的集成的支持。关于单据交换规则的定义，我们分两部分来介绍，基础部分介绍如何完整地为一张单据配置交换规则，高级部分介绍单据交换规则中复杂字段及其对应结构的配置。 1. 基础篇—简单单据配置 简单单据是指没有复杂字段的单子表、主子表单据。单子表只需要在交换规则中定义一个表头记录。主子表则需要同时分别定义表头和表体记录。 我们结合一个主子类型的测试单据的交换规则的配置，来介绍配置外部交换平台交换规则文件的一般知识。关于针对包含复杂字段的单据交换规则文件的配置，需要参考本文的高级篇。 我们建立了一个简单的主子表测试单据，单据类型是“Test6”。在NC系统里为之建立名为pfxx.example6.CustomerVO的表头VO类，名为pfxx.example6.PersonVO的表体VO类，类图如下所示： 图3.1.1 主子单据数据结构类图 借助于我们的交换规则自动生成工具，可以直接将VO结构映射为XML的交换规则。图3.1.2就是根据该单据类型注册的VO信息和表信息自动生成的交换规则。但由于外系统数据与NC标准数据之间在名称、结构和语义上的差异，需要通过手工配置来修改自动生成的单据交换规则，以保证内外系统交换时数据的完整性和有效性。 第 17 页 图3.1.2 可编辑交换规则轮廓 现在假设有一外部的XML数据样本文件，如图1.2所示。 我们将单据根标签 图3.1.3 外部XML数据文件样本 由于外系统数据文件的单据根标签为 第 18 页 图3.1.4 修改交换文档根标签 接下来，就需要分别配置表头和表体记录定义了。 1.1 表头记录的配置 表头记录定义了NC系统里单据表头VO的信息及与外系统文件相应单据表头元素的对照关系。由于各种类型的记录其属性项的意义并不完全相同，我们对于每种记录类型，依次介绍其属性项的意义和配置。首先让我们来看默认生成的表头记录定义，如图3.1.1.1所示。 图3.1.1.1 名为billhead的表头记录定义 【转换后标准的表标签】是生成NC标准XML文件时使用的标签名，由NC统一发布，用户一般不应该做修改。 【外系统定义的表标签】是外系统数据文件中单据表头元素的标签名，在上述数据文件中是 图3.1.1.2 设置表头记录“外系统定义的表标签”属性项的值 【表定义名称】该记录定义的ID，也是校验文件管理界面中右部结构树上记录 第 19 页 定义节点的显示名称，用户可以修改。 【表类型】表示该记录定义的类型，有“表头”、“表体”和“内嵌结构”三种，一般也不用做修改。“表头”值表示该记录是表头记录。表头记录的字段是为该记录对应表头VO类型定义的字段。我们将会在字段属性项的配置一节中详细介绍如何配置每个字段。 1.2 表体记录的配置 表体记录定义了NC系统里单据表体VO的信息及与外系统数据文件相应单据表体元素和表体分录元素的对照关系。图3.1.2.1是默认生成的表体记录。 图3.1.2.1 名为billbody的表体记录定义 【转换后标准的表标签】是生成NC标准文件时使用的标签名，由NC统一发布，用户一般不应该做修改。如图3.1.2.2所示。 【外系统定义的表标签】在此处是外系统数据文件中单据表体元素的标签名，在本例的数据文件中是〈person_EX〉，因此该属性值设置为person_EX。 图3.1.2.2 设置表体记录“外系统定义的表标签”属性项的值 【表体记录标签】表示表体分录元素的标签名，因为在此处数据文件中的表体分录元素的标签名跟默认生成的表体记录标签名相同，都为 【表定义名称】该记录定义的ID，也是校验文件管理界面中右部结构树上记录定义节点的显示名称，用户可以修改。 【表类型】属性项在自动生成时默认为“表体”，表示该记录是表体记录，不用修改。 需要提醒大家注意的是，表体记录所有字段是为表体VO定义的，我们正是根据这些字段定义去转换翻译每个表体分录元素的。我们将会在字段属性项的配置一节中详细介绍如何配置每个字段。 第 20 页 1.3 字段属性项的配置 接下来，我们需要配置表头和表体记录中的每个字段。先介绍两个概念：字段元素和实体元素。DOM树中的叶子节点（简单元素）我们称之为简单字段元素，因为一般情况下它与我们NC系统中的一个数据对象的属性或者数据库表中的一个字段对应。除了简单字段元素之外，还有复杂字段元素。关于复杂字段元素的介绍请参考高级篇。图3.1.3.1示例了数据文件中的简单字段元素。 图3.1.3.1 数据文件中简单字段元素示例 由字段元素（简单字段元素或者复杂字段元素）组成的父元素我们称之为实体元素。实体元素可能是表头数据元素，也可能是表体分录元素，还有可能是高级篇中的VO类型的复杂字段元素、简单数组类型的复杂字段元素以及简单集合类型的复杂字段元素（参考高级篇复杂字段配置）。图3.1.3.2示例数据文件中的一个表头数据元素形式的实体元素和一个表体分录元素形式的实体元素。 第 21 页 图3.1.3.2 数据文件中实体元素示例 下面介绍字段的各个属性的含义和配置： 【该字段在NC里的名称】 这个字段在NC的数据结构中的名称，这个名称是由NC系统的数据结构决定的，由校验文件自动生成时自动填充，用户一般不需要修改它。 【该字段在外系统中的名称】 表示字段元素的标签名。数据交换的本质是数据映射，让一个系统中有意义的数据变为另一个系统中同样有意义的数据，但两者的名称可能不一样。在这个地方我们要正确填写外系统数据文件中跟NC中某字段对应的字段元素的标签名，否则就会丢失信息。如表体记录定义的字段customerNumber默认的外系统名称为 图3.1.3.3 校验文件默认生成的“该字段在外系统中的名称” 第 22 页 图3.1.3.4 数据文件中简单字段的标签名 图3.1.3.5 修改字段的“该字段在外系统中的名称”属性 【字段描述】 对字段的详细描述，使易于理解。校验文件管理界面右边树上的字段节点的名称显示为字段描述设置的值。 【数据类型】 字段在NC的数据结构中的数据类型，在转换过程中用于校验外系统数据。可以设置的值包括字符串、整型、UFBoolean、UFDouble、日期、时间戳、复杂类型等等。这个属性一般由系统自动生成，用户不必修改。当字段是复杂类型时，同时需要设置属性【该字段对应的表结构定义】的值，在交换规则中，去引用另外一个记录来定义复杂字段的内容。关于这部分的内容，请参考复杂字段配置一节。 【最大长度】 字段值的最大长度，在转换过程中用于校验外系统数据的合法性。对于复杂字段，这个属性项没有意义。 【规则】 用于外系统和NC系统数据间的简单映射，比如“False=0;True=1”表示如果外系统当前字段的值为False那么导入到NC系统为0，如果当前字段的值为True，那么导入到NC系统的值为1；导出时则恰好相反。下面的图例说明了如何定义字段的规则，将外系统的布尔值对照到NC系统的字符串值上。 第 23 页 图3.1.3.6 为字段定义规则属性 下面两张图分别是利用字段规则转换前和转换后的数据： 图3.1.3.7 根据规则转换前的数据 图3.1.3.8 根据规则转换后的数据 【需要参照的NC基本档案】 该元素定义了当前字段属于何种基本档案。因为如果当前字段是基础档案数据，那么和NC系统交换时需要进行翻译，将外系统值翻译成NC系统基础档案的PK值。如对于部门，为“部门档案”，人员则为“人员档案”等等，具体编辑时根据参照选择即可。至于如何为外部系统配置基础数据的翻译策略和设置基础数据硬对照，需要参照外部交换平台的使用手册。 假设我们在测试单据的字段city需要参照基本档案“地区分类”进行翻译，我们设置将[需要参照的NC基本档案]属性值“地区分类”，这个属性值可以使用参照进行编辑。 图3.1.3.9为字段定义需要参照的基本档案 下面两张图分别是经过基本档案翻译转换前和转换后的数据： 第 24 页 图3.1.3.10 根据基本档案翻译转换前的数据 图3.1.3.11 根据基本档案翻译转换后的数据 【默认值】 通过该属性为字段定义一个默认值，当外系统数据文件中没有该字段的值，那么取此默认值导入到NC系统中。适合于NC内的非空字段，但外系统不具备相应字段元素值的情形，比如导入U860的部门档案、会计科目时，U860相应数据文件均没有公司字段元素，所以需要修改数据文件，或者在校验文件中设置默认值，相对来说，在校验文件中设置默认值显得一劳永逸一些。下面的图例说明了如何设置默认值以及默认值的作用。 图3.1.3.12 为字段定义默认值属性 图3.1.3.13 定义默认值字段的转换前数据 图3.1.3.14 定义默认值字段的转换后数据 【导入公式】 如前所述，在导入数据时，外部系统的XML文件首先被转换为符合NC标准数据格式的XML文件，此XML文件紧接着再被转换为NC系统内部的数据结构VO。导入公式主要用于标准XML文件到VO这一过程中对字段的取值做进一步的处理。下面的图例说明了如何设置字段的导入公式，以及导入公式在单据导入时的作用。 第 25 页 图3.1.3.15 为字段定义导入公式属性 图3.1.3.16 转换前数据 图3.1.3.17 根据导入公式生成的VO内容 【导出公式】 当把NC单据(VO形式)的导出为外部XML文件时，会根据该字段的导出公式对VO中的数据进行转换，以导出需要的数据。下面的图例说明了如何设置字段的导出公式，以及导出公式在单据导出时的作用。 图3.1.3.18 为字段定义导出公式属性 第 26 页 图3.1.3.19 导入的数据 图3.1.3.20 导出的数据 【该字段对应的表结构定义】 当字段的【数据类型】为复杂类型时，字段的取值不再是一个简单的XML元素，而是带有层次结构的复杂XML数据。如此一来，必须进一步定义该字段的数据结构。【该字段对应的表结构定义】就是用来定义复杂字段的内部结构的，它通过一个“内嵌类型”的表结构定义来详细描述复杂字段的结构。关于这部分高级内容，请参考复杂字段配置一节。 【字段在外系统中的位置】 该项用于指定当前字段元素在整个单据元素中的位置，一般情况下，字段元素都是其父元素即实体元素的子元素，然而当该字段元素没有遵循这个常规，如在某些情况下字段元素是其实体元素的兄弟结点，或者在是其他节点的子节点，这时候就需要设置这个属性。 设置字段位置时可以用相对路径（相对路径的默认起点是当前字段元素的父元素），也可以使用绝对路径（绝对路径必须以_root开头，_root表示当前单据元素节点，而不是 下面我们用例子说明这个属性项。假设现在我们的数据文件如下图所示，简单字段元素 第 27 页 图3.1.3.21 需要定义字段“该字段在外系统中的位置”属性的数据 图3.1.3.22 为字段定义“该字段在外系统中的位置”属性 第 28 页 图3.1.3.23 根据字段的位置属性转换后的数据 2. 高级篇—复杂字段配置 复杂字段在NC数据结构中对应属性的数据类型不是简单类型，而是ValueObject、数组和集合等，对应在外系统数据文件中的则是实体元素或者实体元素的集合。我们将外系统数据文件中与复杂字段对应的元素称为复杂字段元素。根据字段属性的数据类型，还可以进一步将分为复杂字段元素分为VO记录元素，VO数组记录元素，简单数组记录元素，VO集合记录元素和简单数组记录元素等。 在校验文件中需要为每个复杂字段建立一个记录定义，来描述该复杂字段对应的数据类型以及与外系统数据文件中复杂字段元素之间的对应关系，我们将这种记录定义称为内嵌结构的记录。根据字段的数据类型，我们又把内嵌结构的记录分为VO记录、VO数组记录、简单数组记录、VO集合记录和简单集合记录五种类型，它们配置规则不尽相同，下面结合示例逐一介绍。 2.1 VO记录的配置规则 VO记录描述NC系统中VO类信息，该记录的字段定义了记录对应的VO类的所有属性。 图3.2.1.1 VO类型的数据结构 假设我们有如图3.2.1.1所示的VO类CustomerVO，其含有对另一个VO类PersonVO的引用。这时候的person字段是一个复杂字段，我们需要在校验文件中为之单独定义一个记录。根据这样的VO结构，我们自动生成的校验文件如图3.2.1.2所示。 第 29 页 图3.2.1.2 根据内部数据结构自动生成的校验文件 对于billhead记录的person字段的属性项定义，我们需要特别注意的是【数据类型】属性项的值默认设为了“复杂类型”，【该字段在外系统中的位置】属性项的值设置为复杂字段描述记录的表定义名称，而且系统为这个复杂字段定义好了名为person的VO记录。另外，假设我们有如图3.2.1.3所示的外系统数据文件，因为复杂字段元素的标签名为 图3.2.1.3 数据文件中的VO类型的复杂字段元素 我们再来看名为person的VO记录定义的属性。 图3.2.1.4 VO类型记录的定义 【复杂字段对应的类名称】填写该记录对应的VO类的全名称。如此处“pfxx.example.PersonVO”。这个属性项的值必须设置，否则系统无法实例化对象。 第 30 页 【内嵌结构数据类型】填写复杂字段的具体类型，有“简单数组”，“VO数组”，“VO类型”，“集合”四种类型的值。在这儿系统默认生成的是“VO类型”，用户不必修改。 【表类型】一共有“表头”、“表体”和“内嵌结构”三种类型值。对于描述复杂字段的记录，都应该是“内嵌结构”型。用户也不必修改这个属性值。 【表定义名称】该记录的名称，如果用户为某个记录修改了名称，而又有复杂字段要参照这个记录，则需要同时修改复杂字段的【该字段对应的表结构定义】属性值。 【转换后标准的表标签】和【外系统定义的表标签】这两个属性在VO集合类型的记录定义中没有意义，50版外部交换平台在生成这种类型的记录定义时不再具有这两个属性。 2.2 简单数组记录的配置规则 简单数组记录描述了NC系统中基本数据类型数组的信息。该记录的字段定义有且仅有一个，描述的是该简单数组的元素信息。 图3.2.2.1 简单数组类型的数据结构 假设我们有如图3.2.2.1所示的VO类CustomerVO，其含有对字符串数组persons的引用。这时候的persons字段是一个复杂字段，我们需要在校验文件中为之单独定义一个记录。根据这样的VO结构，我们自动生成的校验文件如图3.2.2.2所示。 对于billhead记录的persons字段的属性项定义，我们需要注意的是【数据类型】属性项的值默认设为了“复杂类型”，【该字段在外系统中的位置】属性项的值设置为复杂字段描述记录的表定义名称，并且系统为这个复杂字段定义好了名为persons的VO记录。另外，假设我们有如图3.2.2.3所示的外系统数据文件，因为复杂字段元素的标签名为 第 31 页 图3.2.2.2 根据内部数据结构自动生成的校验文件 图3.2.2.3 包含简单数组类型的复杂字段元素的外系统数据 我们再来看名为persons的记录的属性设置。 图3.2.2.4 默认生成的简单数组类型的记录定义 【复杂字段对应的类名称】属性项填写此记录对应的数据对象的类名，因为此记录是简单数组类型的记录，应该填写简单数组类名的全称，此处是“java.lang.String[]”。 【内嵌结构数据类型】属性项指定该内嵌结构记录的具体类型。Persons记录是个基本类型数组的记录。 【表类型】一共有“表头”、“表体”和“内嵌结构”三种类型值。对于描述复杂字段的记录，都应该是“内嵌结构”型。用户也不必修改这个属性值。 【表定义名称】该记录的名称，如果用户为某个记录修改了名称，而又有复杂字段要参照这个记录，则需要同时修改复杂字段的【该字段对应的表结构定义】属性值。 【转换后标准的表标签】和【外系统定义的表标签】这两个属性在VO集合类型的记录定义中没有意义，50版外部交换平台在生成这种类型的记录定义时 第 32 页 不再具有这两个属性。 2.3 VO数组记录的配置规则 VO数组记录描述了NC系统中ValueObject类型数组的信息。该记录的字段定义是该记录相应数组元素的类型ValueObject类所有属性的字段定义，也就是说其字段定义描述的是其元素的属性内容。 图3.2.3.1 VO数组类型的数据结构 假设我们有如图3.2.3.1所示的VO类CustomerVO，其含有对另一个VO类PersonVO的多重关联，并且在Java中我们用一个数组来实现这个多重关联。这时候的persons字段是一个复杂字段，我们需要在校验文件中为之单独定义一个记录。根据这样的VO结构，我们自动生成的校验文件如图3.2.3.2所示。 图3.2.3.2 根据内部数据结构自动生成的校验文件 对于billhead记录的persons字段的属性项定义，我们需要注意的是【数据类型】属性项的值默认设为了“复杂类型”，【该字段在外系统中的位置】属性项的值设置为复杂字段描述记录的表定义名称，而且系统为这个复杂字段定义好了名为persons的VO记录。另外，假设我们有如图3.2.3.3所示的外系统数据文件，因为复杂字段元素的标签名为 我们再来看名为persons的VO数组类型的记录定义。 【复杂字段对应的类名称】属性项填写此记录对应的数据对象的类名，因为此记录是VO数组类型的记录，应该填写VO数组类名的全称，此处是“pfxx.example4.PersonVO[]”。 【内嵌结构数据类型】属性项指定该内嵌结构记录的具体类型。Persons记 第 33 页 录是个“VO数组”类型的记录。 图3.2.3.3 数据文件中的VO数组类型的复杂字段元素 【表类型】一共有“表头”、“表体”和“内嵌结构”三种类型值。对于描述复杂字段的记录，都应该是“内嵌结构”型。用户也不必修改这个属性值。 【表定义名称】该记录的名称，如果用户为某个记录修改了名称，而又有复杂字段要参照这个记录，则需要同时修改复杂字段的【该字段对应的表结构定义】属性值。 【实体元素外系统标签名】这个属性项只有在VO数组类型和VO集合类型的表记录中才会定义。在VO数组类型的记录中，【实体元素外系统标签名】指的是VO数组类型的复杂字段元素（VO数组记录元素）中每个实体元素（数组元素）的根标签名。因此需要将这个属性值设置为“person_EX”。 【实体元素NC系统标签名】NC系统生成标准数据文件时使用的标签名，用户一般不需要修改。 图3.2.3.4 默认生成的VO数组类型的记录定义 第 34 页 图3.2.3.5 配置修改后的VO数组类型的记录定义 【转换后标准的表标签】和【外系统定义的表标签】这两个属性在VO集合类型的记录定义中没有意义，50版外部交换平台在生成这种类型的记录定义时不再具有这两个属性。 2.4 简单集合记录的配置规则 简单集合记录描述了NC系统中数据类型为基本数据类型集合的数据结构的信息。该记录的字段定义有且仅有一个，描述的是集合的元素信息。 图3.2.4.1 简单集合类型的数据结构 假设我们有如图3.2.4.1所示的VO类CustomerVO，其含有对字符串类型的多重引用，并且在Java中我们用一个List来实现这个多重关联。Customer类代码类似于下图。 图3.2.4.2 集合类型数据结构的Java代码实现 这时候的persons字段是一个复杂字段，我们需要在校验文件中为之单独定义一个记录。根据这样的VO结构，系统自动生成的校验文件如图3.2.4.3所示。 第 35 页 图3.2.4.3 根据内部数据结构自动生成的校验文件 对于billhead记录的persons字段的属性项定义，我们需要注意的是【数据类型】属性项的值默认设为了“复杂类型”，【该字段在外系统中的位置】属性项的值设置为复杂字段描述记录的表定义名称，而且系统为这个复杂字段定义好了名为persons的VO记录。另外，假设我们有如图3.2.4.4所示的外系统数据文件，因为复杂字段元素的标签名为 图3.2.4.4包含简单集合类型的复杂字段元素的外系统数据 我们再来看名为persons的记录的属性设置。 图3.2.4.5 默认生成的简单集合类型的记录定义 【复杂字段对应的类名称】属性项的默认值是“java.util.List”，因为在CustomerVO类的申明中persons属性的类型是List接口而不是具体List实现类，在这儿需要填写List接口的具体实现类。如将该属性项的值设置为“java.util.ArrayList”。 第 36 页 图3.2.4.6 配置修改后的简单集合类型的记录定义 【内嵌结构数据类型】填写复杂字段的具体类型，有“简单数组”，“VO数组”，“VO类型”，“集合”四种类型的值。在这儿系统默认生成的是“集合”，用户不必修改。 【表类型】一共有“表头”、“表体”和“内嵌结构”三种类型值。对于描述复杂字段的记录，都应该是“内嵌结构”型。用户也不必修改这个属性值。 【表定义名称】该记录的名称，如果用户为某个记录修改了名称，而又有复杂字段要参照这个记录，则需要同时修改复杂字段的【该字段对应的表结构定义】属性值。 【Collection内部元素的数据类型】和【Collection内部元素对应的类名】两属性项分别设置集合内部元素的数据类型和类名，如前所述，系统在自动生成校验文件时将persons记录的【Collection内部元素的数据类型】属性项值设置为基本类型，【Collection内部元素对应的类名】属性项的值设置为“java.lang.String”。我们的例子中集合的元素类型是字符串，所以这个默认设置恰好符合要求，则不必再作修改，但如果集合的元素类型是整型，则需要将【Collection内部元素对应的类名】属性项的值设置为“java.lang.Integer”。 【转换后标准的表标签】和【外系统定义的表标签】这两个属性在VO集合类型的记录定义中没有意义，50版外部交换平台在生成这种类型的记录定义时不再具有这两个属性。 2.5 VO集合记录的配置规则 ValueObject集合记录描述了NC系统中数据类型为ValueObject集合的信息。它的字段定义描述的是集合元素的ValueObject类型的属性。 图3.2.5.1 VO集合类型的数据结构 假设我们有如图3.2.5.1所示的VO类CustomerVO，其含有对另一个VO类PersonVO的多重关联，并且在Java中我们用一个List来实现这个多重关联。Customer类代码类似于图3.5.2.2。 第 37 页 图3.2.5.2 集合类型数据结构的Java代码实现 这时候的persons字段是一个复杂字段，我们需要在校验文件中为之单独定义一个记录。根据这样的VO数据结构，我们自动生成的校验文件如图3.2.5.3所示。这个例子中不用修改。 图3.2.5.3 根据内部数据结构自动生成的校验文件 对于billhead记录的person字段的属性项定义，我们需要特别注意的是【数据类型】属性项的值默认设为了“复杂类型”，【该字段在外系统中的位置】属性项的值设置为复杂字段描述记录的表定义名称，并且系统为这个复杂字段定义好了名为persons的集合记录。另外，假设我们有如图3.5.2.4所示的外系统数据文件，因为复杂字段元素的标签名为 第 38 页 图3.5.2.4 包含VO集合类型的复杂字段元素的外系统数据 接下来让我们来看那个名为persons的集合记录，这里的配置可能要稍微麻烦一些。从图3.5.2.5中可以看到，由于不能从List类型集合persons中得到集合元素的确切类型，系统在自动生成校验文件时假设集合元素的类型是基本类型java.lang.String，也就是说生成的是一个简单集合类型的记录。我们需要将其替换为一个相应的VO集合类型的记录定义。 图3.5.2.5 默认生成的VO集合类型的记录定义 目前的最佳解决办法如下： 首先，右击单据交换文档的根节点，选择“添加表定义记录”菜单项。弹出如图3.5.2.6所示的“添加表定义记录”对话框。 第 39 页 图3.5.2.6 新增记录定义 然后配置VO集合类型的表记录信息。由于我们是要用新建的这个记录定义去替换交换规则自动生成时生成的简单集合类型的表记录，所以“记录名称”必须跟简单集合类型的表定义名称一致，设为“persons”，“结构对应类名”填写这个集合关系的具体实现类，此处为“java.util.ArrayList”，类名非ValueObject派生类的记录不用填写“数据库表名”。 VO集合类型和VO数组类型的记录定义还需要进行其实体元素的高级配置。打开“高级配置”对话框，“实体元素外系统标签名”必须填写外系统数据文件中VO集合类型的复杂字段元素下实体元素的标签名，此处为“person_EX”。“实体元素NC系统标签名” 是NC系统生成标准数据文件时使用的标签名，随便指定一个名称，但不能为空。最后配置“实体元素类名”和“实体元素表名”，“实体元素类名”就是VO集合的元素的对象名称，在此处为“pfxx.example5.PersonVO”，由于没有建立该类的数据库表，所以“实体元素表名”的地方为空，数据库表信息一般用于提供对象中字段的多语信息。 图3.5.2.7示例了配置本例的VO集合记录信息。 第 40 页 图3.5.2.7 配置记录信息 配置完表记录信息之后，点击“确定”便可生成相应名为persons的VO集合类型的表记录。另外，特别需要提醒的是，必须将自动生成交换规则时的简单集合记录persons删除掉。图3.5.2.7就是新的persons表记录定义。 图3.5.2.7 新增的VO集合类型记录 【复杂字段对应的类名称】属性项填写此记录对应的数据对象的类名，就是我们在新增该记录时填写的结构对应类名：java.util.ArrayList。 【内嵌结构数据类型】填写复杂字段的具体类型，有“简单数组”，“VO数组”，“VO类型”，“集合”四种类型的值。在这儿系统默认生成的是“集合”，用户不必修改。 【表类型】一共有“表头”、“表体”和“内嵌结构”三种类型值。对于描述复杂字段的记录，都应该是“内嵌结构”型。用户也不必修改这个属性值。 【表定义名称】该记录的名称，如果用户为某个记录修改了名称，而又有复 第 41 页 杂字段要参照这个记录，则需要同时修改复杂字段的【该字段对应的表结构定义】属性值。 【Collection内部元素的数据类型】和【Collection内部元素对应的类名】两属性项分别设置集合内部实体元素的数据类型和类名。 【实体元素外系统标签名】在VO集合类型的记录中，其指的是VO集合类型的复杂字段元素（VO集合记录元素）中每个实体元素（数组元素）的根标签名。即我们在新增该记录时填写的“实体元素外系统标签名”的值。 【实体元素NC系统标签名】NC系统生成标准数据文件时使用的标签名，即我们在新增该记录时填写的“实体元素NC系统标签名”的值。 【转换后标准的表标签】和【外系统定义的表标签】这两个属性在VO集合类型的记录定义中没有意义，50版外部交换平台在生成这种类型的记录定义时不再具有这两个属性。 第 42 页 第四章 基于外部交换平台的单据集成开发 从V5版本开始，外部交换平台配套的二次开发向导工具，利用这个工具，可以非常方便的给NC系统里还没有集成功能的单据，或者用户自定义的单据，快速添加集成的功能。 从[二次开发工具]-[集成开发工具]打开单据集成开发，然后在左边选择功能节点导航，选中相应的需要进行交换功能开发的单据节点，点击菜单项的外部交换平台－插件开发，便会出现外部交换平台的二次开发向导工具。 下面按照向导的步骤依次介绍开发工具的使用方法及注意事项： 1. 注册单据相关信息 第 43 页 图4.1.1 单据插件信息注册 说明： ＝＝模块信息＝＝ [模块名] – 单据所属模块，比如部门档案属于”uapbd”模块，凭证属于”gl”模块，模块会影响交换插件最终的部署位置。 ＝＝插件配置＝＝ [单据标识] 一般填写相应的单据类型即可，如果没有单据类型，比如基础档案，可以取一个能唯一标识当前档案的名称。比如部门档案取名为”bsdept” [单据描述] 一般写单据的名称或者简单的功能描述。 [业务操作] 选择框，常见的业务操作有add、update、delete、query、audit、unaudit…等等，用户发送数据时，会在XML文件头里写上各种的业务操作，如果这里没有注册相应的业务操作，则会提示相应的业务插件没有找到。所以如果希望支持各种业务操作，这里就一定要在这里进行注册。 [导入范围] 选择框，表示该单据是否只能导入到集团，还是只能导入到公司，或者集团公司均可。 [单据加锁级别] 选择框，锁的控制级别，用户控制并发问题，对于大多数单据，如果没有特别的要求，保持默认值即可。关于单据并发控制，详情可以参考2.6节。 [插件类名称] 针对该单据＋选定的业务操作，最终的插件处理类名称，如果这个插件类写的比较通用，不同的业务操作也可以注册同一个业务插件类，关键要看业务插件类的处理能力。这里插件类需要遵循特定的接口，具体可以看后面的[插件类生成及维护]。 [扩展插件类名称] 这个主要是为了兼容V30及以前版本的老插件而设置的，因 第 44 页 为老的插件不符合新的接口规范，如果新开发交换插件，此处无需填写。 ＝＝单据信息＝＝ [VO类型] 根据单据在NC内部的VO结构的不同，我们将其分为三类： 单子表 ―― 无聚合关系，整个单据对应一个VO(此VO内部可能还嵌套其他VO)，大多数基础档案都属于这个类型，包括凭证，虽然是比较复杂的结构，但早期的设计还是属于单子表类型。 主子表 ―― 有明显的聚合关系，整个单据对应一个聚合VO(主子表VO)，聚合VO的表头VO对应单据的主表数据，聚合VO的子表VO对应单据的子表数据，大多数业务单据均属于这种类型，这种类型的VO对应了UI工厂里的管理型界面。 多子表 ―― 同主子表类似，整个单据对应一个聚合VO(多子表VO)，聚合VO的表头VO对应单据的主表数据，只是聚合VO有多个子表VO，每个子表VO对应单据里相应的子表数据。 根据以上分类，可以快速的定位当前单据的VO类型。选择了不同的VO类型，下面的注册信息也各有不同。 图4.1.2 主子表VO及数据表信息配置 第 45 页 图4.1.3 多子表VO及数据表信息配置 另外对于我们前面提到的VO里如果还有嵌套VO的情况，可以通过[内嵌VO]来设置内嵌VO和数据表的信息，如下图所示： 图4.1.4 内联VO配置 2. 生成＆配置交换规则定义文件 配置好单据注册相关信息后，就可以自动生成交换规则定义文件的大纲了，之所以叫大纲，是因为生成后的文件，还需要进一步配置，比如对需要翻译的字段配置参照档案等。 首先是设置一些生成参数，以决定是否重新生成，生成通用的规则定义文件，还是针对特定外部系统生成等，如下图所示： 第 46 页 图4.2.1 校验文件生成规则 生产后的规则校验文件： 图4.2.2 校验&对照文件维护 具体如何配置规则定义文件，请参考第三章的内容。这里主要介绍一下V35老的规则文件如何顺利迁移到V5版本。 第 47 页 【老插件升级】V35之前已有的校验文件不用重新生成，但需要根据新的规则定义文件配置规则进行微调。注意在老校验文件中追加两个属性： 1、单据号备选字段，这个属性定义在“交换文档”单据根标签上，用于在单据没有明确指定单据号时，将该字段的内容作为单据号，插件开发人员可选； 2、数据所属组织字段，这个属性定义在字段上，用于在导入过程中对接收方中指定的公司或者主体帐簿进行校验，以此保证数据的正确性。一般一张单据的组织字段定义在表头上，当然也可以同时将表体的某个字段定义为组织字段，这个由插件开发人员自己控制，但必须为单据定义一个组织字段。组织字段一般为公司或者主体账簿，定义单据的组织字段可以保证单据数据的确发送到了指定接收方。 配置好规则定义文件，就可以生成相应的样本数据，其数据格式符合当前的规则定义，可以直接发送到NC系统中。如果修改了规则定义文件，最好重新生成一下样本数据，以免样本数据和规则定义不相符。 根据规则定义生成样本数据，对于外系统没有明确数据格式的情况下，生成的样本数据可以作为外系统生成数据的模板；如果外系统已经有了具体的数据格式，只需要对比一下外系统的数据格式与生成的样本是否一致，便可检验规则定义正确与否。 图4.2.3 样本数据预览 此界面右上方有一保存按钮，可以保存生成的样本数据到本地硬盘。 第 48 页 3. 辅助信息项设置 图4.3.1 辅助信息项设置 利用交换平台做数据交互时，业务数据一般都放在具体的XML文档中，但是，发送过程中往往还有一些数据，并不需要也不能写到每个具体的XML文档里，这些数据，用户往往需要根据当前的发送方、接受方、单据类型及具体的业务场景进行设定，比如说发送凭证时，针对凭证表头表体的控制参数是根据不同的发送方、接受方、及凭证类别由用户灵活控制的；另外如存货基础档案发送到集团时，用户也需要配置，档案可以分配到那些公司。诸如此类的信息，在交换平台中称之为辅助信息。 辅助信息分设计态和运行态，设计态是指从程序开发的角度，交换平台提供了一个类似数据池的数据存贮区，插件开发人员先定义当前单据所需要的辅助信息项目，比如上面所说的凭证控制信息、存货的分配公司等，插件开发人员定义好这些项目之后，在[交换平台维护]-[辅助信息设置]界面，用户就可以在运行态时配置这些项目的值，最终在业务插件类里，用户配置好的这些值被交给插件使用。简单的说就是插件开发人员借助外部交换平台辅助信息这个数据池，存放一些特定的项目，在运行态时收集用户的设置，最终在插件处理这些用户的设置信息。 第 49 页 4. 插件代码维护 图4.4.1 插件代码维护 【插件全路径类名】根据单据注册信息自动带过来，不可以再修改，插件的基类取决于是否还需要兼容V30以前的老插件，也就是注册时有没有注册扩展插件类，一般新做的插件基类为AbstractPfxxPlugin，也无需修改。新插件一般也无需再实现别的接口。 【包含测试代码】如果选中此项，生成的代码中会包含测试代码，主要是将转换后的VO序列化到后台，最终在前台进行展现，以便开发人员观察转换后的VO是否正确，便于定位错误。仅适合在测试时使用，最终代码开发时一定要删除测试代码。 【包含导出代码】如果选中此项，会生成如何将VO转换为XML文档的代码实例，以便开发人员参考。 选择生成代码的存放路径，便可以按“生成”，生成代码。 这个代码是插件的通用框架，如果有辅助信息或者其他的业务处理，请自行拷贝到ECLIPSE修改。 修改好的代码也可以拷贝到这里，进行编译(中间件需要设置参数enableHotDeployed=true),然后便可以测试了。 第 50 页 图4.4.2 交换平台测试 测试OK后，可以导出相关的配置文件，提交到CC服务器或者其他的测试环境上。 第 51 页 因篇幅问题不能全部显示，请点此查看更多更全内容