红皮书-1.0信息交换平台技术新一代云ERP解决方案2目录一.总体概述.51.1.信息交换平台总体结构..51.2.信息交换平台功能特点..61.3.信息交换平台新增功能..7二.实施简介及相关注意点.92.1.实施方法简介..92.1.1.外系统数据导入的一般步骤.92.1.2.信息交换平台服务器端文件目录结构.112.2.Servlet的URL地址参数与XML交换文档头属性的关系.122.3.向U8cloud系统发送数据方式..152.3.1.手动界面发送.152.3.2.后台预警发送.152.3.3.自定义程序发送.182.4.回执及异常出错信息..232.4.1.回执格式.232.4.2.异常和错误编码.242.4.3.查询及回执格式样例.252.5.信息交换平台总体参数设置..392.5.1.单据导入方式.402.5.2.单篇最大传输上限.40新一代云ERP解决方案32.5.3.导入过程是否记录中间文件.402.5.4.外部系统默认帐套.412.5.5.设置客户端IP范围.412.5.6.接收公司匹配规则.412.5.7.回执文件后台备份.412.5.8.回执和导出文件编码格式.422.6.单据流水号和单据并发控制..422.6.1.单据流水号的概念和作用.422.6.2.单据并发控制.422.7.日志查看..43三.单据交换规则定义.473.1.基础篇—简单单据配置.473.1.1.表头记录的配置.493.1.2.表体记录的配置.503.1.3.字段属性项的配置.513.2.高级篇—复杂字段配置.613.2.1.VO记录的配置规则.613.2.2.简单数组记录的配置规则.633.2.3.VO数组记录的配置规则.653.2.4.简单集合记录的配置规则.683.2.5.VO集合记录的配置规则.71新一代云ERP解决方案4四.基于信息交换平台的单据集成开发.764.1.注册单据相关信息..764.2.生成＆配置交换规则定义文件..804.3.辅助信息项设置..844.4.插件代码维护..85五.单据集成示例.875.1.问题描述..875.2.设计885.3.具体开发指导..885.3.1.单据插件信息注册.885.3.2.单据转换规则定义.905.3.3.插件代码编写和部署.905.3.4.修改单据转换规则.925.3.5.手动加载测试.93六.安全.966.1.加密类编写..966.2.加密类注册..99七.扩展.101八.交换规则合并.104九.JMS及大文件传输模式.106新一代云ERP解决方案59.1.外部数据交换平台异步通信解决方案..1069.1.1.外部数据交换平台现状及存在的问题.1069.1.2.需求分析.1079.1.3.JMS简介..1079.1.4.JMSClient消息交互图.1099.1.5.解决方案.1109.2.jms传输模式..1129.3.JMSClientForU8cloud..1139.3.1.JMSClientAPI..1149.3.2.JMS实例代码.1459.4.大文件传输模式..146十.附录.14810.1.发送结果错误码.14810.2.K系统自定义项目档案样本defdoc.xml.153一.总体概述1.1.信息交换平台总体结构新一代云ERP解决方案6图1.1.1信息交换平台总体结构图外部数据交换平台主要用于外部系统和U8cloud系统进行集成。利用外部数据交换平台，可以将外系统的基本档案和业务数据发送到U8cloud系统中，并进行相关的业务操作，如审批、弃审，也可以通过发送XML格式的查询条件导出U8cloud系统的数据（需业务插件支持），导出的数据可以附着在回执文件中，也可以直接向外部系统回发HTTP请求。1.2.信息交换平台功能特点采用XML格式作为统一的数据交换标准，为数据访问提供简便、统一的模式。XML格式在数据表达和描述方面有着很大的优势，逐渐成为业界的标准，采用XML格式作为交换标准格式可以很好的保护企业投资。面向服务的架构。这使得第三方系统可以随时随地向U8cloud系统发送相关的业务数据，U8cloud内部的预警服务及工作流引擎使得U8cloud系统可以在合适的时候向第三方系统传送需要的数据，并且满足第三方系统的格式规范。灵活配置。数据转换的规则可灵活定义，独立于应用集成和业务逻辑，也就是说根据不同的外部数据结构，直接通过修改交换规则文件的定义，即可达到各种异构数据无缝集成的目的。新一代云ERP解决方案7自由扩充。对于标准产品不支持的业务单据，如果有集成需求，信息交换平台提供了向导式的二次开发工具，集成了所有与二次开发相关的功能及配置，支持动态部署，可以在用户环境上进行快速有效的开发。1.3.信息交换平台新增功能与信息交换平台之前序列的产品相比，新版信息交换平台在功能上得到了进一步的完善，在易用性上也有了很大改进。1)单据交换规则的定义更加丰富和灵活。可以为某一单据模型中的某一字段定义路径，也可以为一个集合中的实体元素定义路径，甚至可以为某个字段定义XML结构查询的公式。这些都得益于对XPath功能的模拟，使得XML文件间结构转换的能力更强，但这个交换规则的学习成本可能比较大，后续版本需要图形化和简洁化。2)为基于信息交换平台的自定义单据的集成提供了一个快速开发工具。这个工具以向导方式将集成一个自定义单据所要做的工作贯穿起来，包括：单据插件信息注册、校验文件生成、样本数据导出、辅助信息规则配置、业务插件类代码生成和编写，甚至还包括业务插件类代码的实时编译和部署，样本数据的导入测试和结果展示等。3)启用新缓存机制。这不但使得外部系统设置、辅助信息设置和基础数据对照表的设置能够实时地作用于外部数据导入过程中，而且对于基本档案数据的访问也实现了实时性，效率得到了更高的优化。4)基础数据对照导入功能更加丰富。新增了基础数据对照的XML文件增加和EXCEL文件增加的功能，基础数据对照界面EXCEL内外对照数据导入分为两列，其中第一列为外系统值，第二列为U8cloud所对应值，系统会自动检查U8cloud值的合法性，不合法则置空。5)信息交换平台总体参数配置功能更加丰富和完整。这部分配置主要包括单据导入方式、接收公司匹配规则、导入过程是否记录中间文件、回执和导出文件编码格式、设置客户端IP范围等，这些功能的可配置性极大地提高了信息交换平台的灵活性和可扩展性。6)对单据导入过程中的并发程度进行控制。对于某一单据类型，一共给出了四种并发控制程度，实施人员可根据具体情况设置合理的并发控制级别，避免单据并发导入引发新一代云ERP解决方案8的错误。7)外系统数据实现后台异步发送。借助预警平台的定时触发功能，系统可以自动将保存在服务端某个目录下的外系统数据导入U8cloud系统中，实现了异步驻留的数据发送方式。8)对数据导入过程中的异常进行了重新划分，对于错误信息进行了编码。前者带来的好处就是错误提示信息更加明确化，后者主要用于第三方系统程序内部识别导入过程中是否出现错误以及具体的错误信息。9)进一步约束信息交换平台导入单据的语义。对每个单据需要定义一个组织字段，用于确保往某个接收方，比如说A公司做加载数据时，导入的数据能真正进入A公司，这个组织字段一般是公司或者主体账簿。为单据定义组织字段之后，如果数据里相应组织字段的值不为空，则要求其值与接受方保持一致，如果数据里相应组织字段的值为空，则取接受方的内容为组织字段的值。10)易用性改进。【手动加载界面】对文件目录、回执目录、目标URL地址、加载成功转移目录的配置增加记忆功能，就是说以相同公司相同用户登陆时，上述各项的配置内容默认显示为最后一次用户设置的值，避免用户每次都需要重新设置。【交换规则定义】增加了查找、定位字段的功能，单据交换规则树上的右击菜单也更加简练明确，同时为字段的导入导出公式定义增加新版本的公式编辑器，定义公式更加方便简洁。11)【手动加载界面】增加对Excel文件的导入支持。12)最大传输上限界面最大20M。13)业务插件扩展功能见七.扩展14)交换规则增加合并功能15)Ufinterfacevo填充U8cloud操作员信息16)增加日志统计和输入流监控，便于进行日志分析，定位网络错误上述功能我们在接下来的内容中会具体提到。新一代云ERP解决方案9二.实施简介及相关注意点U8cloud信息交换平台的主要功能就是将不同外系统的数据导入U8cloud系统。由于不同系统之间对于相同单据的数据在表示上千差万别，需要信息交换平台对单据的XML格式的外系统数据进行格式转换和数值翻译，然后将转换后生成的XML格式的U8cloud标准数据实例化为U8cloud系统对应单据的数据对象，并调用业务模块的接口（服务）进行保存或者更新。U8cloud系统在后台有一个Servlet伺候服务，等待并处理客户端的POST方法请求（信息交换平台提供界面客户端和预警客户端，对于同步集成方式，外系统可以自定义发送客户端）。客户端往根据Servlet的URL建立的连接的输出流中写待发送数据文件的内容，而后台服务端则从请求的输入流中读取数据文件内容，然后再进行后续处理。关于客户端发送数据的具体内容请参考2.3节。2.1节介绍了要将某个外系统的某种单据类型的数据文件导入至U8cloud系统的最简单方法。其余小节介绍了在实施数据导入过程中容易混淆而需要注意的地方，或者是一些常用的工具等。2.1.实施方法简介2.1.1.外系统数据导入的一般步骤外系统根据单据类型将相同单据类型的数据组织在一个XML文件中，然后将其发送到U8cloud系统的某个账套下的某个公司或集团中（对于有账簿信息的单据而言，比如会计科目或者凭证，则是某个公司的某个账簿之下）。一般来说，如果需要发送某种单据类型的数据至U8cloud系统中，需要如下几步：一、注册外部系统。如果不存在可用的外系统的话，请在“外部系统信息注册”界面中注册一个外部系统。新一代云ERP解决方案10二、准备外系统数据。这份数据可能是外系统直接输出的，也可能是二次开发人员通过写程序从第三方系统数据库中抓出来的，或者由Excel格式或其他格式文件转换过来的。写这份数据时，可以参考U8cloud安装盘附带的XML模板，XML文件头或者说文档头的属性项请参照2.2节详细说明。三、配置辅助信息（可选）。如果要导入的单据数据需要辅助信息配置，在“辅助信息配置”界面根据外部系统、单据类型、接收公司及主体帐簿（如果带的话）为此次文件发送配置辅助信息。四、设置基础数据对照（可选）。如果要导入的单据数据需要作基础数据对照（对于需要参照基本档案的字段，如果其值不能按名称或者编码自动翻译过来的话，在导入过程中系统会自动提示必须为该值做基础数据对照），在“基础数据对照”界面根据需要参照的外部系统、需要参照的基本档案、公司（取当前登陆公司）及主体帐簿（如果带的话）为需要对照的值做基础数据对照。六、配置Servlet的URL地址。将要发送至的帐套编码作为account属性值写入要发送到的Servlet的URL中（或者写入XML文件的头中），将接收公司和主体帐簿（如果带的话）的代码拼成接收方（接收公司编码@接收主体账簿编码）作为receiver属性写入要发送到的Servlet的URL中（或者XML文件的头中）。详细说明请参见2.2节。最后，就可以利用客户端触发该单据类型的数据文件的发送了。U8cloud信息交换平台内置了常用单据类型数据的导入功能，对于这些单据类型，如果外系统数据遵照了这些单据类型的交换规则定义(即如果外系统的数据严格按照U8cloud安装盘附带的相应单据的XML模板生成)，那么按上述步骤相对比较简单地就可以导入数据。但是如果外系统数据未能遵照单据类型的交换规则定义，则需要修改该单据类型的交换规则定义。做法就是将该单据的普通交换规则定义文件另存为特定该外部系统的交换规则定义文件，并根据单据交换规则定义规范修改该特定交换规则定义文件，具体需要参见第三章[单据交换新一代云ERP解决方案11规则定义]，然后再行导入。对于非系统内置或者自定义的单据的导入，需要基于外部数据交换平台做二次开发，这部分内容可参见第四章。2.1.2.信息交换平台服务器端文件目录结构信息交换平台服务端的目录结构安排如图2.1.1所示，其中u8c_COMMON为安装盘根目录，也是中间件的工作目录。从上图可以看出，信息交换平台配置文件目录pfxx与webapps一样同在安装盘根路径下，其中：pfxxtemp目录，存贮信息交换平台接受到的原始数据文件、转换翻译完毕的标准XML文件、传送失败的文件。xmleditor目录，存放校验文件管理的样式文件，可不用考虑。exportbills目录，存放信息交换平台发送给外系统的数据文件。billdefine目录，存放所有需要交换的档案和单据的交换规则文件。auxiregister目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据的辅助信息格式。详细情况参考4.3节辅助信息项设置。businessprocessor目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据在信息交换平台的注册信息，如单据类型、业务插件类名称、业务操作、单据导入范围、单据加锁级别等。详细内容参考4.1节注册单据相关信息。billconfiginfo目录，每个模块在这个目录下注册一个文件，文件的内容是模块所涉及单据的基本信息，如表和VO对象名。详细内容参考4.1节注册单据相关信息。sendurl.xml文件，定义了U8cloud系统通过HTTP回发数据给外系统时的各种参数，如发送地址、业务操作、发送方、接受方、单据类型等等。globalset.xml用于存放信息交换平台的全局参数，如默认帐套、单篇最大传输上限等。新一代云ERP解决方案12图2.1.1信息交换平台服务端文件目录结构2.2.Servlet的URL地址参数与XML交换文档头属性的关系在外系统的单据数据的导入过程中需要用到一些初始化信息，如帐套、接收方（包括接收公司和主体账簿）、数据所属外部系统（发送方）、单据类型、业务处理（新增、更新还是查询）等。这部分数据可以在Servlet的URL地址的参数中指定，也可以在XML数据文件的文档头属性中指定，但是在Servlet的URL地址的参数中指定的信息比在XML数据文件的文档头属性中指定的信息有更高的优先级别。比如在Servlet的URL地址参数中指定receiver=yk，而在XML数据文件的文档头属性中指定receiver=yy，则最终还是将数据发送到yk公司。下面我们依据实例来逐一介绍各个常用属性。图2.2.1是一个典型的U8cloud服务器的Servlet的URL地址，“http://10.7.3.226:80/service/XChangeServlet”是后台Servlet的服务名，指定的是包装之后的服务名。“?”号之后的“account=0001&receiver=yy”就是设置的URL地新一代云ERP解决方案13址参数，一般情况下这个地方只设置帐套编码和接收方两个属性。至于这两个属性的含义下面会介绍到。图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属性,这个属性指定要将数据导入至U8cloud系统的哪个帐套。receiver属性，这个属性指定数据的接收方。接收方又是有一定格式的，可以将这个格式用一个正则表达式表示为：接收方=（公司编码|公司主键）(@主体帐簿编码)？也就是说接收方根据单据类型的需要，可以是公司或者公司下的主体帐簿。当接收方是公新一代云ERP解决方案14司，如编码为“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属性，这个属性值决定了在外系统的数据在导入U8cloud系统的过程中，是否使用信息交换平台提供的翻译转换和校验功能。正常情况下应将这个属性设置为“Y”，或者干脆不设。除非从其他U8cloud系统产生的符合U8cloud转换后标准的XML数据直接导入U8cloud系统，并且很多基础档案数据字段直接用的是PK值，此时可以设置属性为“N”和“n”，可避免无谓的翻译转换。replace属性，这个属性值决定是否允许将相同单据往同一个接收方重复导入。V50版的插件一般允许相同单据重复导入，除了将第一次导入视作新增之外，其余导入视作更新。关于这方面的具体内容请参见2.6节内容。如果不允许相同单据的重复导入，那么将这个属性值设置为“N”或者“n”。否则将其设置为“Y”或者干脆不设。operator属性，这个属性指定当前发送方对应的U8cloud操作员pk，在手工加载界面会自动使用当前登陆用户pk，无需设置。对于外系统发送到U8cloud系统，需要在其发送url里加上对应得U8cloud操作员pk总的来说，XML文档头的【必须设置的属性】和【根据Servlet的URL参数设置决定是否必设的属性】，均为在外系统交换文档发送过程中必须得到的初始化信息，可以在Servlet的URL地址参数中设置，也可以在XML文档头属性中设置，但必须进行设置。而对于XML文档头的【根据需要决定是否设置的属性】，也可以在Servlet的URL地址的参数中设置，但一般不推荐这么做。新一代云ERP解决方案152.3.向U8cloud系统发送数据方式U8cloud信息交换平台支持客户端以同步和异步两种方式发送（加载）外部数据。其中U8cloud信息交换平台为异步加载方式内置了两类客户端：界面和预警，而对于同步加载方式，外系统需要编写往U8cloud后台Servlet发送文件的代码，下面分别介绍它们：2.3.1.手动界面发送这是外部数据最简单也最常用的一种客户端发送方式，点击：[企业建模平台]→[信息交换平台]→[外部数据发送]，在打开的界面中选择需要发送的文件，如有必要，修改目标URL地址的receiver参数值，选择“发送”菜单即可。详细内容请参考信息交换平台的用户手册。图2.3.1外部数据发送界面2.3.2.后台预警发送点击：[企业建模平台]→[预警平台]→[预警条件配置]→[条目配置]→[增加]，在弹出的预警条目设置对话框中配置一个类型为“外部交换数据后台发送”的预警条目，其预警条件的配置如图2.3.2所示。在该预警条件标签页中内置了四个预警条件：待发送文件目录新一代云ERP解决方案16该预警条件阈值用于设置用户数据文件目录（不能为空）；回执目录该预警条件阈值用于设置存放单据导入之后的回执信息的目录，每张单据一个回执文件，如果用户不设置这个阈值，系统在待发送文件目录下默认创建目录/logdir作为回执目录；发送后文件转移目录该预警条件阈值对于想将能够成功加载的文件备份走的用户有用（一般不用设置）；发送配置信息该预警条件阈值是一个可扩展的预警条件阈值，它用于配置将什么样的文件发送到哪个URL地址（不能为空）。这个配置值的格式如下：第一部分是单据类型：第二部分是外系统编码：第三部分是目的URL地址：上面所列发送配置信息项取值的意思就是将单据类型是“Test1”，外部系统编码为“1101”的文件发送到U8cloud外部数据接收的Servlet地址：urladdress=http://localhost:80/service/XChangeServlet?account=0001&receiver=yy。这个地方如果我们将单据类型的取值设为“XX”或“xx”的话，表示任何单据类型的文件都可以往某个地址发送，相当于通配符的意思，但对于外部系统编码没有通配符。新一代云ERP解决方案17图2.3.2预警条目配置发送配置信息是一个可扩展的预警条件阈值，其的意思就是用户可以在预警平台的类型注册对话框中修改名为“外部交换数据后台发送”的预警类型定义，增加作为预警条件的发送配置信息项，以实现数据文件的多点发送。点击：[企业建模平台]→[预警平台]→[预警条件配置]→[在“类型配置”标签页选中“外部数据交换后台发送”行]→[类型配置]→[编辑]，弹出“类型注册”对话框，如图2.3.2所示，为其增加了一个发送配置信息阈值项。需要注意的是该新增阈值项的名称必须以字符串“postconfig”打头，如“postconfig1”、“postconfig12”，……等。这样配置更多的发送配置信息，使得能有选择地将某个特殊单据类型特殊外部系统的数据文件能够发送到某个指定服务器地址去。新一代云ERP解决方案18图2.3.2预警类型注册配置完毕，即可由预警平台调度和执行发送任务。另请注意，在待发送文件目录、回执目录和发送后转移目录的设置上本地客户端和服务器端文件系统的差别，如目录“c:/aaa”指的是服务器端文件系统路径而非客户端文件系统地址。2.3.3.自定义程序发送外系统对接U8cloud外部交换平台上传报文时，需要对报文进行加密处理，同时平台会进行权限校验（要求上传可以唯一标识友户通用户身份的accessToken），具体报文加解密和友户通对接事宜请联系U8cloud开发人员。以Java代码为例，介绍如何自定义程序向U8cloud系统发送数据，以下代码仅做参考：packagecom.yonyou.test.demo;importjava.io.BufferedReader;新一代云ERP解决方案19importjava.io.FileInputStream;importjava.io.InputStream;importjava.io.InputStreamReader;importjava.io.OutputStreamWriter;importjava.io.Writer;importjava.net.HttpURLConnection;importjava.net.URL;importorg.apache.commons.io.IOUtils;publicclassSendDemo{//接口调用地址privatestaticfinalStringurl=-http://127.0.0.1:80/service/XChangeServlet-;//待发送文件privatestaticfinalStringfilePath=-C:/Users/Administrator/Desktop/待发送文件.xml-;publicstaticvoidmain(String[]args)throwsException{//获取友户通accessTokenStringtoken=createToken();pfxxSend(token);}/**新一代云ERP解决方案20*获取友户通accessToken*@return*/privatestaticStringcreateToken(){return-token-;//此处引号内换成获取到的友互通token值，获取token方法见后面}/***文件发送*@paramtoken*@throwsException*/privatestaticvoidpfxxSend(Stringtoken)throwsException{HttpURLConnectionconn=(HttpURLConnection)newURL(url+-?token=-+token).openConnection();conn.setDoOutput(true);conn.setRequestProperty(-Content-type-,-text/xml-);conn.setRequestMethod(-POST-);Writerw=newOutputStreamWriter(conn.getOutputStream(),-UTF-8-);BufferedReaderreader=null;reader=newBufferedReader(newInputStreamReader(newFileInputStream(filePath),-UTF-8-));StringtempString=null;StringBuffersb=newStringBuffer();//一次读入一行，直到读入null为文件结束新一代云ERP解决方案21while((tempString=reader.readLine())!=null){sb.append(tempString);}w.append(sb);reader.close();w.flush();w.close();InputStreami=conn.getInputStream();System.out.println(newString(IOUtils.toByteArray(i),-UTF-8-));}}获取token描述获取accesstoken路径http://ip:port/service/YhtUserWebServer?usercode=XXXX&md5pwd=XXX&shapwd=XXXX请求方法POST请求参数ipStringU8cloud地址portStringU8cloud端口usercodeString用户编码md5p.
