NCV5外部交换平台技术红皮书.docx
《NCV5外部交换平台技术红皮书.docx》由会员分享，可在线阅读，更多相关《NCV5外部交换平台技术红皮书.docx（60页珍藏版）》请在冰豆网上搜索。
NCV5外部交换平台技术红皮书
外部交换平台
实施技术红皮书
NC-UAP5.0
用友NC-UAP
2018-09-05
目录
第一章总体概述1
1.外部交换平台总体结构1
2.外部交换平台功能特点1
3.外部交换平台V50版新增功能2
第二章实施简介及相关注意点4
1.实施方法简介4
1.1外系统数据导入的一般步骤4
1.2外部交换平台服务器端文件目录结构5
2.Servlet的URL地址参数与XML交换文档头属性的关系7
3.向NC系统发送数据方式8
3.1手动界面发送8
3.2后台预警发送9
3.3自定义程序发送11
4.回执及异常出错信息12
4.1回执格式12
4.2异常和错误编码12
5.外部交换平台总体参数设置13
5.1单据导入方式13
5.2单篇最大传输上限14
5.3导入过程是否记录中间文件14
5.4外部系统默认帐套14
5.5设置客户端IP范围14
5.6接收公司匹配规则15
5.7回执文件后台备份15
5.8回执和导出文件编码格式15
6.单据流水号和单据并发控制15
6.1单据流水号的概念和作用15
6.2单据并发控制16
第三章单据交换规则定义17
1.基础篇—简单单据配置17
1.1表头记录的配置19
1.2表体记录的配置20
1.3字段属性项的配置21
2.高级篇—复杂字段配置29
2.1VO记录的配置规则29
2.2简单数组记录的配置规则31
2.3VO数组记录的配置规则33
2.4简单集合记录的配置规则35
2.5VO集合记录的配置规则37
第四章基于外部交换平台的单据集成开发43
1.注册单据相关信息43
2.生成＆配置交换规则定义文件46
3.辅助信息项设置49
4.插件代码维护50
第五章单据集成示例52
1.问题描述52
2.设计52
3.具体开发指导52
3.1单据插件信息注册52
3.2单据转换规则定义53
3.3插件代码编写和部署53
3.4修改单据转换规则54
3.5手动加载测试54
附录55
1.发送结果错误码55
2.K系统自定义项目档案样本defdoc.xml58
第一章总体概述
1.外部交换平台总体结构
图1.1.1外部交换平台总体结构图
外部数据交换平台主要用于外部系统和NC系统进行集成。
利用外部数据交换平台，可以将外系统的基本档案和业务数据发送到NC系统中，并进行相关的业务操作，如审批、弃审，也可以通过发送XML格式的查询条件导出NC系统的数据（需业务插件支持），导出的数据可以附着在回执文件中，也可以直接向外部系统回发HTTP请求。
2.外部交换平台功能特点
⏹采用XML格式作为统一的数据交换标准，为数据访问提供简便、统一的模式。
XML格式在数据表达和描述方面有着很大的优势，逐渐成为业界的标准，采用XML格式作为交换标准格式可以很好的保护企业投资。
⏹面向服务的架构。
这使得第三方系统可以随时随地向NC系统发送相关的业务数据，NC内部的预警服务及工作流引擎使得NC系统可以在合适的时候向第三方系统传送需要的数据，并且满足第三方系统的格式规范。
⏹灵活配置。
数据转换的规则可灵活定义，独立于应用集成和业务逻辑，也就是说根据不同的外部数据结构，直接通过修改交换规则文件的定义，即可达到各种异构数据无缝集成的目的。
⏹自由扩充。
对于标准产品不支持的业务单据，如果有集成需求，外部交换平台提供了向导式的二次开发工具，集成了所有与二次开发相关的功能及配置，支持动态部署，可以在用户环境上进行快速有效的开发。
3.外部交换平台V50版新增功能
与外部交换平台V3序列产品相比，V50版外部交换平台在功能上得到了进一步的完善，在易用性上也有了很大改进。
1）单据交换规则的定义更加丰富和灵活。
可以为某一单据模型中的某一字段定义路径，也可以为一个集合中的实体元素定义路径，甚至可以为某个字段定义XML结构查询的公式。
这些都得益于对XPath功能的模拟，使得XML文件间结构转换的能力更强，但这个交换规则的学习成本可能比较大，后续版本需要图形化和简洁化。
2）为基于外部交换平台的自定义单据的集成提供了一个快速开发工具。
这个工具以向导方式将集成一个自定义单据所要做的工作贯穿起来，包括：
单据信息注册、校验文件生成、样本数据导出、辅助信息格式配置、业务插件类代码生成和编写，甚至还包括业务插件类代码的实时编译和部署，样本数据的导入测试和结果展示等。
3）启用NCV50新缓存机制。
这不但使得外部系统设置、辅助信息设置和基础数据对照表的设置能够实时地作用于外部数据导入过程中，而且对于基本档案数据的访问也实现了实时性，效率得到了更高的优化。
4）基础数据对照导入功能更加丰富。
基础数据对照在V35版根据基本档案自动增加的基础上，新增了基础数据对照的XML文件增加和EXCEL文件增加的功能。
5）外部交换平台总体参数配置功能更加丰富和完整。
这部分配置主要包括单据导入方式、接收公司匹配规则、导入过程是否记录中间文件、回执和导出文件编码格式、设置客户端IP范围等，这些功能的可配置性极大地提高了外部交换平台的灵活性和可扩展性。
6）对单据导入过程中的并发程度进行控制。
对于某一单据类型，一共给出了四种并发控制程度，实施人员可根据具体情况设置合理的并发控制级别，避免单据并发导入引发的错误。
7）外系统数据实现后台异步发送。
借助预警平台的定时触发功能，系统可以自动将保存在服务端某个目录下的外系统数据导入NC系统中，实现了异步驻留的数据发送方式。
8）对数据导入过程中的异常进行了重新划分，对于错误信息进行了编码。
前者带来的好处就是错误提示信息更加明确化，后者主要用于第三方系统程序内部识别导入过程中是否出现错误以及具体的错误信息。
9）进一步约束外部交换平台导入单据的语义。
对每个单据需要定义一个组织字段，用于确保往某个接收方，比如说A公司做加载数据时，导入的数据能真正进入A公司，这个组织字段一般是公司或者主体账簿。
为单据定义组织字段之后，如果数据里相应组织字段的值不为空，则要求其值与接受方保持一致，如果数据里相应组织字段的值为空，则取接受方的内容为组织字段的值。
10）易用性改进。
【手动加载界面】对文件目录、回执目录、目标URL地址、加载成功转移目录的配置增加记忆功能，就是说以相同公司相同用户登陆时，上述各项的配置内容默认显示为最后一次用户设置的值，避免用户每次都需要重新设置。
【交换规则定义】增加了查找、定位字段的功能，单据交换规则树上的右击菜单也更加简练明确，同时为字段的导入导出公式定义增加新版本的公式编辑器，定义公式更加方便简洁。
上述功能我们在接下来的内容中会具体提到。
第二章实施简介及相关注意点
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节详细说明。
三、配置辅助信息（可选）。
如果要导入的单据数据需要辅助信息配置，在“辅助信息配置”界面根据外部系统、单据类型、接收公司及主体帐簿（如果带的话）为此次文件发送配置辅助信息。
四、设置基础数据对照（可选）。
如果要导入的单据数据需要作基础数据对照（对于需要参照基本档案的字段，如果其值不能按名称或者编码自动翻译过来的话，在导入过程中系统会自动提示必须为该值做基础数据对照），在“基础数据对照”界面根据需要参照的外部系统、需要参照的基本档案、公司（取当前登陆公司）及主体帐簿（如果带的话）为需要对照的值做基础数据对照。
六、配置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目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据在外部交换平台的注册信息，如单据类型、业务插件类名称、业务操作、单据导入范围、单据加锁级别等。
详细内容参考4.1节注册单据相关信息。
billconfiginfo目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据的基本信息，如表和VO对象名。
详细内容参考4.1节注册单据相关信息。
sendurl.xml文件，定义了NC系统通过HTTP回发数据给外系统时的各种参数，如发送地址、业务操作、发送方、接受方、单据类型等等。
globalset.xml用于存放外部交换平台的全局参数，如默认帐套、单篇最大传输上限等。
图2.1.1外部交换平台服务端文件目录结构
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属性，这个属性指定数据的接收方。
接收方又是有一定格式的，可以将这个格式用一个正则表达式表示为：
接收方=（公司编码|公司主键）（@主体帐簿编码）？
也就是说接收方根据单据类型的需要，可以是公司或者公司下的主体帐簿。
当接收方是公司，如编码为“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参数值，选择“发送”菜单即可。
详细内容请参考外部交换平台的用户手册。
图2.3.1外部数据发送界面
3.2后台预警发送
点击：
[客户化]→[预警平台]→[预警条件配置]→[条目配置]→[增加]，在弹出的预警条目设置对话框中配置一个类型为“外部交换数据后台发送”的预警条目，其预警条件的配置如图2.3.2所示。
在该预警条件标签页中内置了四个预警条件：
⏹待发送文件目录
该预警条件阈值用于设置用户数据文件目录（不能为空）；
⏹回执目录
该预警条件阈值用于设置存放单据导入之后的回执信息的目录，每张单据一个回执文件，如果用户不设置这个阈值，系统在待发送文件目录下默认创建目录/logdir作为回执目录；
⏹发送后文件转移目录
该预警条件阈值对于想将能够成功加载的文件备份走的用户有用（一般不用设置）；
⏹发送配置信息
该预警条件阈值是一个可扩展的预警条件阈值，它用于配置将什么样的文件发送到哪个URL地址（不能为空）。
这个配置值的格式如下：
第一部分是单据类型：
第二部分是外系统编码：
第三部分是目的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”，……等。
这样配置更多的发送配置信息，使得能有选择地将某个特殊单据类型特殊外部系统的数据文件能够发送到某个指定服务器地址去。
图2.3.2预警类型注册
配置完毕，即可由预警平台调度和执行发送任务。
另请注意，在待发送文件目录、回执目录和发送后转移目录的设置上本地客户端和服务器端文件系统的差别，如目录“c:
/aaa”指的是服务器端文件系统路径而非客户端文件系统地址。
3.3自定义程序发送
以Java代码为例，介绍外系统作为客户端如何向NC系统发送数据：
//获取Servlet连接并设置请求的方法
Stringurl=“http:
//10.7.3.225:
8080/service/XchangeServlet”;
URLrealURL=newURL（url）;
HttpURLConnectionconnection=（HttpURLConnection）realURL.openConnection（）;
connection.setDoOutput（true）;
connection.setRequestProperty（“Contect-type”,“text/xml”）;
connection.setRequestMethod（“Post”）;
//将Document对象写入连接的输出流中
Filefile=newFile（“C:
/samples/psndoc.xml”）;
InputStreaminput=newFileInputStream（file）;
Documentdoc=XMLUtil.getDocumentBuilder（）.parse（input）;
Writerwriter=newOutputStreamWriter（connection.getOutputStream（）,“UTF-8”）;
XMLUtil.printDOMTree（writer,doc,1）;//按照XML文件格式输出
//从连接的输入流中取得回执信息
InputStreaminputStream=connection.getInputStream（）;
DocumentresDoc=XMLUtil.getDocumentBuilder（）.parse（inputStream）;//解析为Doc对象
//对回执结果的后续处理…
[说明]关于XML操作可以用XMLUtil类,关于发送的API，可以直接用PostFile类
4.回执及异常出错信息
4.1回执格式
加载外部系统数据时，对于导入的数据文件中的每张单据，都会给客户端返回一个回执信息，记录单据导入成功与否，以及失败的原因。
回执信息也是一个XML文件，其一般格式如下：
图2.4.1回执文档的一般格式
回执信息中还可以嵌套单据，这个时候可以将外部交换平台看作简单的信息中心，外系统发送过来一个消息，NC系统回应一个消息。
如查询类的单据，外系统发送一个表示查询条件的信息，NC系统返回所有符合查询条件的单据，这些单据就是内嵌在回执信息中的。
再如，用这个功能来实现NC系统和外系统在某种程度上的流程集成，外系统发送一张走流程平台的单据，然后再由外部交换平台返回流程平台
升级会员 