信息交换平台应用方案手册-2021.11用友网络科技股份有限公司版权用友集团未经用友集团的书面许可，本应用方案手册任何整体或部分的内容不得被复制、复印、翻译或缩减以用于任何目的。本应用方案手册的内容在未经通知的情形下可能会发生改变，敬请留意。请注意：本应用方案手册的内容并不代表用友所做的承诺。用友网络科技股份有限公司目录版权.1目录.2变更记录.5第一章总体概述.61.1信息交换平台总体结构.61.2信息交换平台功能特点.6第二章产品应用.82.1外部系统信息设置.82.1.1应用概述..82.1.2应用详解..82.2辅助信息配置.92.2.1应用概述..92.2.2应用详解..92.3检验文件管理.102.3.1应用概述..102.3.2应用详解..102.4基础数据对照表.182.4.1应用概述..182.4.2应用详解..182.5手动加载界面.192.5.1应用概述..192.5.2应用详解..192.6交换平台日志.202.6.1应用概述..202.6.2应用详解..202.7输入流监控.222.7.1应用概述..222.7.2应用详解..232.8ID对照表..232.8.1应用概述..232.8.2应用详解..232.9翻译器配置.242.9.1应用概述..242.9.2应用详解..24第三章实施简介及相关注意点..263.1外系统数据导入的一般步骤.263.2Servlet的URL地址参数与XML交换文档头属性的关系..27用友网络科技股份有限公司3.3向NCCloud系统发送数据方式..283.3.1手动界面发送..283.3.2后台预警发送..293.3.3自定义程序发送(开发参考使用)..323.4回执及异常出错信息.333.4.1回执格式..333.4.2异常和错误编码..343.5信息交换平台总体参数设置.343.5.1外部系统默认帐套..353.5.2单篇最大传输上限..353.5.3导入过程是否记录中间文件..353.5.4回执文件后台备份..363.5.5回执和导出文件编码格式..363.5.6单据导入规则设置..363.6单据流水号和单据并发控制.363.6.1单据流水号的概念和作用..363.6.2单据并发控制..373.7日志查看.373.8翻译器配置（开发参考使用）.39附录.41发送结果错误码.41用友网络科技股份有限公司导读此手册面向实施顾问以及企业关键用户，旨在为实施规划、解决方案制定和落实提供指导。手册围绕产品能够解决的主要业务场景展开，并以此为依托展现产品的关键应用功能，提供业务需求与产品功能相匹配的思路。为了便于用户对整体内容加深理解，手册中对一些关键的名词进行了解释，并在附录中对一些可能需要对照查询的关键点进行了补充说明，以便用户查找对照。为突出重点，本手册定位于方案性说明，仅对产品操作中的重要控制点有所描述。若读者希望深入了解特定板块的产品应用，可结合本手册，查阅如下资料：1.《应用方案手册-组织管理》-----深入阐述了产品关键概念（如集团、组织、业务委托关系等）以及建模思路，是实施规划、蓝图设计的重要参考资料。2.《应用方案手册-权限管理》-----可对权限模型的搭建和应用进行更详细深入地了解。3.《应用方案手册-流程管理》-----提供关于交易类型、流程设计工具的应用指导。4.《应用方案手册-基础数据》-----可对有关基础数据的理解和应用进行更详细深入地了解。用友网络科技股份有限公司变更记录编写人丁习芳版本修订人审核人起止时间修订/审核章节修订/审核内容1909丁习芳李聪慧2019/11新增2020.05丁习芳李聪慧2020/06无无变化2021.05丁习芳李聪慧2020/062.3检验文件管理更换产品界面：增加【导入/导出检验文件】功能2021.11丁习芳李聪慧2021/12无无变化用友网络科技股份有限公司第一章总体概述1.1信息交换平台总体结构图1.1-1信息交换平台总体结构图信息交换平台主要用于外部系统和NCCloud系统进行集成。利用信息交换平台，可以将外系统的基本档案和业务数据发送到NCCloud系统中，并进行相关的业务操作，如审批、弃审，也可以通过发送XML格式的查询条件导出NCCloud系统的数据（需业务插件支持），导出的数据可以附着在回执文件中，也可以直接向外部系统回发HTTP请求。1.2信息交换平台功能特点采用XML格式作为统一的数据交换标准，为数据访问提供简便、统一的模式。XML格式在数据表达和描述方面有着很大的优势，逐渐成为业界的标准，采用XML格式作为交换标准格式可以很好的保护企业投资。面向服务的架构。这使得第三方系统可以随时随地向NCCloud系统发送相关的业务数据，NCCloud内部的预警服务及工作流引擎使得NCCloud系统可以在合适的时候向第三方系统传送需要的数据，并且满足第三方系统的格式规范。用友网络科技股份有限公司灵活配置。数据转换的规则可灵活定义，独立于应用集成和业务逻辑，也就是说根据不同的外部数据结构，直接通过修改交换规则文件的定义，即可达到各种异构数据无缝集成的目的。自由扩充。对于标准产品不支持的业务单据，如果有集成需求，信息交换平台集成了与二次开发相关的功能及配置，支持动态部署，可以在用户环境上进行快速有效的开发。用友网络科技股份有限公司第二章产品应用信息交换平台属于产品集成平台中的数据交换管理模块，涉及到应用节点有外部系统信息设置、辅助信息配置、检验文件管理、基础数据对照表、手动加载界面、交换平台日志、输入流监控、ID对照表、翻译器配置。本章将分别进行介绍。2.1外部系统信息设置2.1.1应用概述外部系统信息设置是对外部系统信息的设置。主要设置内容包括：外部系统的编码、名称，即：数据要从哪个系统导入到NCCloud系统；导入的档案数据的默认匹配规则。2.1.2应用详解进入【数据交换管理】→【外部系统信息设置】节点，界面如下。图2.1-1外部系统信息设置 外部系统编码、名称：根据实际业务设置即可。此处可以增加多个外部系统，每个系统可以设置不同的匹配规则。在待导入数据对应的配置文件（XML）中有sender字段，将该字段值设置为需要进行匹配的外部系统编码，数据导入时系统会根据sender字段值匹配出外部系统，然后根据此外部系统下设置的档案匹配规则进行档案翻译。用友网络科技股份有限公司 默认匹配规则：分为“仅按对照表”、“按PK”、“按编码”、“按名称”四类。 明细规则：界面下方空白处可以定义档案的明细匹配规则，如档案没有在明细规则处定义规则，则在进行数据导入时按照默认匹配规则进行匹配。档案明细的匹配规则优先级高于外系统默认匹配规则2.2辅助信息配置2.2.1应用概述一般用于外系统向NCCloud系统导入凭证时配置使用，可以根据这里的配置来控制凭证不同部分是否允许修改和删除，具体使用说明参见下方应用详解。2.2.2应用详解进入【数据交换管理】→【辅助信息配置】节点，界面如下。图2.2-1辅助信息配置以凭证为例： 辅助信息名称表示单据来源（例如：GL）,表示根据凭证来源控制是否允许修改和删除。 辅助信息值填写外系统的凭证类型，表示根据凭证类型控制是否允许修改和删除。 辅助信息扩充值填写控制字符串，例如：-NYYYYNNNNNNNNNNNNNNNNNNN-，该字符串共24位长。由四部分组成，分别控制凭证不同部分的删除和修改权限。第一部分是第一个字符，控制凭证是否可以删除；第二部分是第二个字符，表示凭证分录是否可以增删；第三部分是第三、四、五个字符，表示凭证表头的日期、凭证类型、附单据数是否可以修改；第四部分是第五个字符以后的共19个字符，分别控制凭证分录里具体可以修改的信息，包括：1）科目编码2）摘要内容3）币种编码4）辅助核算5）对方科目6）单价7）组织本币汇率8）借方数量9）原币借方10）组织本币借方11）数量贷方12）原币贷方13）组织本币贷方14)集团本币汇率15）集团本币借方16）集团本币贷方17)全局用友网络科技股份有限公司本币汇率18）全局本币借方19）全局本币贷方。2.3检验文件管理2.3.1应用概述检验文件管理用于定义单据进行外系统与NCCloud系统之间交换规则的定义。由于外系统数据与NCCloud标准数据之间在名称、结构和语义上的差异，需要通过手工配置来修改自动生成的单据交换规则，以保证内外系统交换时数据的完整性和有效性。2.3.2应用详解2.3.2.1检验文件全局配置由于外系统数据与NCCloud标准数据之间在名称、结构和语义上的差异，需要通过手工配置来修改自动生成的单据交换规则，以保证内外系统交换时数据的完整性和有效性。图2.3-1可编辑交换规则2.3.2.2字段属性项的配置接下来，我们需要配置表记录中的每个字段。先介绍两个概念：字段元素和实体元素。DOM树中的叶子节点（简单元素）我们称之为简单字段元素，因为一般情况下它与我们NCCloud系统中的一个数据对象的属性或者数据库表中的一个字段对应。除了简单字段元素之外，还有复杂字段元素。关于复杂字段元素的介绍请参考高级篇。图2.3.2.2-1示例了数据文件中的简单字段元素。由字段元素（简单字段元素或者复杂字段元素）组成的父元素我们称之为实体元素。用友网络科技股份有限公司图2.3-2数据文件中简单字段元素示例下面介绍字段的各个属性的含义和配置：【该字段在NC的名称】这个字段在NCCloud的数据结构中的名称，这个名称是由NCCloud系统的元数据决定的，由校验文件自动生成时自动填充，用户一般不需要修改它。【该字段在外系统中的名称】表示字段元素的标签名。数据交换的本质是数据映射，让一个系统中有意义的数据变为另一个系统中同样有意义的数据，但两者的名称可能不一样。在这个地方我们要正确填写外系统数据文件中跟NCCloud中某字段对应的字段元素的标签名，否则就会丢失信息。简单来说就是导入的xml文件中对应字段的名称图2.3-3校验文件默认生成的“该字段在外系统中的名称”用友网络科技股份有限公司【字段描述】对字段的详细描述，使易于理解。检验文件管理界面左侧树上的字段节点的名称显示为字段描述设置的值。【数据类型】字段在NCCloud的数据结构中的数据类型，在转换过程中用于校验外系统数据。可以设置的值包括字符串、整型、UFBoolean、UFDouble、日期、时间戳等等。通过元数据自动生成。【允许为空】字段值是否允许为空，在转换过程中用于校验外系统数据的合法性。通过元数据自动生成。【最大长度】字段值的最大长度，在转换过程中用于校验外系统数据的合法性。通过元数据自动生成，一般不用修改。【默认值】通过该属性为字段定义一个默认值，当外系统数据文件中没有该字段的值，那么取此默认值导入到NCCloud系统中。适合于NCCloud内的非空字段，但外系统不具备相应字段元素值的情形，比如导入U860的部门档案、会计科目时，U860相应数据文件均没有公司字段元素，所以需要修改数据文件，或者在校验文件中设置默认值，相对来说，在校验文件中设置默认值显得一劳永逸一些。下面的图例说明了如何设置默认值以及默认值的作用。如果导入时相应字段没有填写值，那么这个字段元素就会取检验文件中配置的默认值。图2.3-4为字段定义默认值属性【是否需要导出】数据导出时是否导出该字段【字段在外系统中的位置】用友网络科技股份有限公司该项用于指定当前字段元素在整个单据元素中的位置，一般情况下，字段元素都是其父元素即实体元素的子元素，然而当该字段元素没有遵循这个常规，如在某些情况下字段元素是其实体元素的兄弟结点，或者在是其他节点的子节点，这时候就需要设置这个属性。设置字段位置时可以用相对路径（相对路径的默认起点是当前字段元素的父元素），也可以使用绝对路径（绝对路径必须以_root开头，_root表示当前单据元素节点，而不是<ufinterface>元素节点）。路径由外系统元素标签名或者符号“^”构成，之间用记号“|”分隔，标签名表示找子元素，“^”符号表示寻找父元素。如“^|a”表示先找到当前实体元素（即当前字段元素的父元素）的父元素，然后再在其下找名为a的元素。下面我们用例子说明这个属性项。假设现在我们的数据文件如下图所示，简单字段元素<deftranslator>并不是简单实体元素<exsystem_EX>的子元素，而是它的兄弟元素，是单据元素<billdata>的子元素。这种情况下我们就需要设置字段deftranslator的【字段在外系统中的位置】项。因为字段deftranslator对应的字段元素并不是实体元素（此处也是单据表头元素）的子元素节点，而是其兄弟节点，所以将【字段在外系统中的位置】项值设置为“^”，这样就会从实体元素的父元素（此处也是单据元素）取得该字段元素。图2.3-5需要定义字段“该字段在外系统中的位置”属性的数据图2.3-6为字段定义“该字段在外系统中的位置”属性用友网络科技股份有限公司图2.3-7根据字段的位置属性转换后的数据【参照的元数据实体】该元素定义了当前字段属于何种基本档案。因为如果当前字段是基础档案数据，那么和NCCloud系统交换时需要进行翻译，将外系统值翻译成NCCloud系统基础档案的PK值。如对于部门，为“部门档案”，人员则为“人员档案”等等，具体编辑时根据参照选择即可。至于如何为外部系统配置基础数据的翻译策略和设置基础数据硬对照，需要参照信息交换平台的使用手册。通过元数据自动生成，在元数据中表现为REF字段。图2.3-8为字段定义需要参照的基本档案【自定义翻译器】当该前字段的翻译不能通过默认的翻译器进行翻译时，需要自定义翻译器进行翻译。只要在“自定义翻译器注册”界面中注册自己的翻译器，并在此处选择对应的翻译器即可。【自定义翻译器变量参数列表】用友网络科技股份有限公司自定义翻译器中可能需要特定的变量值用于翻译，如集团，组织等等信息，此处将需要在上下文中使用的变量名按“；”分隔的方式填写，就可以将定义的变量供翻译器使用。此处填写的变量名称，必须是当前字段之前已经翻译的字段，即在左侧树中当前字段上部的字段。【基础数据对照依赖的组织变量名称】在进行数据翻译时，需要根据基础数据对照表中的数据进行翻译（参照基础数据对照节点），其中要求根据不同的组织设置不同的对照关系，所以此处需要设定组织变量名称，根据不同的组织进行对照翻译。将组织字段定义为变量，并将变量名称填写在此处，则在翻译的时候就可以根据不同的组织进行数据对照翻译了。如果不设置该字段，则使用上下文中的组织进行对照，即URL或数据文档头中的orgcode设置的接收组织。【枚举类型】该元素定义了当前字段属于何种枚举类型。通过元数据自动生成，在元数据中表现为枚举字段【变量名称定义】将当前字段设置为变量，用于自定义翻译器使用，只有设置为变量的数据才能供翻译器的上下文使用。【简单对照规则】用于外系统和NCCloud系统数据间的简单映射，比如“False=0;True=1”表示如果外系统当前字段的值为False那么导入到NCCloud系统为0，如果当前字段的值为True，那么导入到NCCloud系统的值为1；导出时则恰好相反。下面的图例说明了如何定义字段的规则，将外系统的布尔值对照到NCCloud系统的字符串值上。图2.3-9为字段定义规则属性下面两张图分别是利用字段规则转换前和转换后的数据：用友网络科技股份有限公司图2.3-10根据规则转换前的数据图2.3-11根据规则转换后的数据【导入公式】如前所述，在导入数据时，外部系统的XML文件首先被转换为符合NCCloud标准数据格式的XML文件，此XML文件紧接着再被转换为NCCloud系统内部的数据结构VO。导入公式主要用于标准XML文件到VO这一过程中对字段的取值做进一步的处理。下面的图例说明了如何设置字段的导入公式，以及导入公式在单据导入时的作用。图2.3-12检验文件管理中的导入公式用友网络科技股份有限公司图2.3-13为字段定义导入公式属性图2.3-14转换前数据图2.3-15根据导入公式生成的VO内容【导出公式】当把NCCloud单据(VO形式)的导出为外部XML文件时，会根据该字段的导出公式对VO中的数据进行转换，以导出需要的数据。下面的图例说明了如何设置字段的导出公式，以及导出公式在单据导出时的作用。图2.3-16为字段定义导出公式属性用友网络科技股份有限公司图2.3-17导入的数据图2.3-18导出的数据2.4基础数据对照表2.4.1应用概述在外部系统信息设置处进行设置时，档案的匹配规则分为：“仅按对照表”、“按PK”、“按编码”、“按名称”四类，其中仅按照对照表指的就是按照基础数据对照表中设置的档案对照关系进行档案匹配。当档案的匹配规则设置为“按PK”、“按编码”或“按名称”都需要外部系统与NCCloud系统的档案存在某个相等的值，但是客户应用新系统后有可能对档案进行了重新规划，可能两个系统间的数据没有对等信息。在基础数据对照表进行配置即可将无规律的数据建立对应关系。基础数据对照表节点支持根据不同的组织设置不同的对照关系，根据不同的组织进行对照翻译（此功能需要设定组织变量名称才可以实现）。2.4.2应用详解进入【数据交换管理】→【基础数据对照表】节点，选择外部系统及档案、组织信息，在子表中维护外部系统的值及其对应的NCCloud系统的基础数据值。编辑界面提供了“基础数据自动增加”及“基础数据文件导入”按钮用于快速维护档案对照关系信息。通过“基础数据自动增加”可实现将NCCloud系统的基础数据分类下的档案信息加载出来。通过“基础数据文件导入”可以实现将在excel中维护好的基础数据对照信息导入到NCCloud系统中。用友网络科技股份有限公司图2.4-1基础数据对照表2.5手动加载界面2.5.1应用概述进行“手动加载界面”后在“数据文件目录”后点击“选择文件”按钮，选取完文件后会将路径下的待导入的xml文件信息读取并显示到此界面的下方。根据需要选择需要发送的文件后点击右上方“发送”按钮，即完成手动发送数据的全部过程。2.5.2应用详解进入【数据交换管理】→【手动加载界面】节点，界面如下。图2.5-1手动加载界面 数据文件目录：要发送的数据的xml文件所在的位置。用友网络科技股份有限公司 查看回执文件：数据导入的结果信息在点击发送完之后会下载在本地，可以选择并打开相应回执文件进行查看 回执文件最大数目:回执目录中允许存在的最大回执文件数量，不勾选则不限制回执目录中的文件数量，勾选则当回执目录中的文件数量达到此处设置的数值则自动删除已存在的回执数据。 回执文件命名规则：生成的回执文件的命名格式。 单篇传输上限（KB）：单个XML文件的大小的极限值。 目标URL地址：这些信息项目按照是否必设置可以分为三类：必须设置的属性、根据Servlet的URL参数设置决定是否必设的属性和根据需要决定是否设置的属性。 https：勾选https后目标URL中http自动变换为https，按照https格式进行传输。2.6交换平台日志2.6.1应用概述交换平台日志记录了导入数据的执行情况。2.6.2应用详解交换平台日志通过【数据交换管理】→【交换平台日志】可以进入，分为详细日志、日志统计两部分，下面分别介绍这两部分的参数设置。2.6.2.1详细日志图2.6-1交换平台日志-详细日志记录文件导入的详细信息日志，具体如下： 单据类型：发送文档上的单据类型； 发送方：外部系统；用友网络科技股份有限公司 接收方：接收公司； 单据编码：文档id，取xml文件中的filename值，如配置文件中filename值为空则系统字段生成一个单据编码。 发送文件名：发送文件的标识 是否成功接收：否表示失败；是表示成功； 描述：发送文件的处理结果描述信息 业务单据返回值：业务插件返回的值； 文档编码：对应单据在ID对照表中的记录的id 原始文档:点击可查看到原始导入的文档； 原始文档存放路径：存放于文件服务器上，对应路径是/pfxx/pfxxtemp/indocs/ 翻译后文档：点击可查看信息交换平台翻译后的文档； 翻译后文档存储路径：存放于文件服务器上，对应路径是/pfxx/pfxxtemp/translated/2.6.2.2日志统计统计导入的xml文件总单据数量、成功单据数量、失败单据数量信息。图2.6-2交换平台日志-日志统计2.6.2.3参数设置 外部系统默认帐套:决定外部数据导入时默认导入到哪个帐套里。在“手动加载界面”的目标url地址的account参数和导入文档的根属性account中均可指定导入的帐套值，此处设置的该参数只有当url中的account参数值和导入文档的根属性account均未设置时才起作用。三个参数的优先级：url中的acount值>导入文档的根属性account值>参数设置的外部系统默认帐套 最大单篇传输上限：每个待导入xml文件的最大值； 导入过程中记录中间文件：用于控制所导入文档的每张单据是否在文件服务器上做备份记录，主要做两次备份，分别是原始单据备份和转换翻译后单据的备份。用友网络科技股份有限公司前者备份至文件服务器目录/pfxx/pfxxtemp/indocs/下，后者备份至文件服务器目录/pfxx/pfxxtemp/translated/下。 记录输入流：勾选则启用输入流监控，启用后所有通过信息交换平台传输的数据将会被记录到此处。不勾选则不启用输入流监控。记录输入流影响系统性能，因此不支持同时勾选大文件模式与记录输入流。 回执文件后台备份：参数控制是否后台备份回执文件。对于导入的每一张单据，信息交换平台都会给客户端或者发送方一个回执信息即一个XML格式的，如果勾选此参数，则会在文件服务器目录/pfxx/pfxxtemp/responses/中再备份一份回执文件。 大文件模式：通的传输方式对xml文件大小限制为10M，当勾选打文件模式时导入xml文件大小将没有限制。此外当使用大文件模式导入文件时，由于单据数据会特别多前台若返回日志将特别乱，因此前台将不再返回回执，只能到后台查看导入日志来确定单据是否导入成功。 保留大文件模式临时文件：勾选该选项时，在使用大文件传输模式进行数据传输的时候可以在文件服务器目录/pfxx/pfxxtemp/_work_temp_/目录下查看导入的大文件是否正确被传送到后台。 回执和导出文件编码格式：用户控制信息交换平台导出的XML数据文件或者单据回执文件的编码格式可配置，默认系统默认回执和导出文件的编码格式是UTF-8，信息交换平台同时支持UTF-8和gb2312格式文件的导入。 单据导入规则设置：分为“同一文档里的所有单据批量处理”和“同一文档里的每张单据单独处理”。当选择“同一文档里的所有单据批量处理”时，则导入时同一文档内的数据一个导入不成功则所有数据处理失败；当选择“同一文档里的每张单据单独处理”时，统一文档内一张单据导入失败不影响其他单据的导入。 最大线程数：允许多少个线程同时导入数据，0表示不限制。图2.6-3交换平台日志-参数设置2.7输入流监控2.7.1应用概述输入流监控将文件导入过程的日志分为4类：输入流正常、一般业务校验错误、文档本身不符合XML用友网络科技股份有限公司格式、输入流因为网络问题而出错。从细化文件导入的错误类型角度记录导入过程的日志，以便于更有效的定位和解决文件导入时出现的问题。2.7.2应用详解进入【数据交换管理】→【输入流监控】节点，界面如下。启用输入流监控：在交换平台日志界面的上方点击“参数设置”后勾选“记录输入流”即可，此后所有通过信息交换平台传输的数据将会被记录到此处。图2.7-1输入流监控2.8ID对照表2.8.1应用概述ID指的是发送的xml文件bill标签的ID属性.外部交换平台是根据这个ID来判断单据的导入是新增还是更新，所以如果此前导入的时候没有定义ID，之后又想修改这条数据，那么就可以从这个节点找到对应的记录，将ID字段填写到需要更新的单据的bill标签的ID属性上，从而实现档案或者单据的更新操作。2.8.2应用详解进入【数据交换管理】→【ID对照表】节点，界面如下。用友网络科技股份有限公司图2.8-1ID对照表2.9翻译器配置2.9.1应用概述翻译器主要是外系统导入NCCloud系统时涉及到的某些字段需要通过特殊处理，从而才能翻译成正确的数据，这时候就需要配置翻译器，这个节点存放了当前系统可用的所有翻译器信息，无论是进行客开或者需要配置交换规则，都可以从这里增加翻译器实现自己的需求。2.9.2应用详解进入【数据交换管理】→【翻译器配置】节点，界面如下。用友网络科技股份有限公司图2.9-1翻译器配置用友网络科技股份有限公司第三章实施简介及相关注意点NCCloud信息交换平台的主要功能就是将不同外系统的数据导入NCC.
