元数据升级指南(2010年更新版).doc

元数据升级指南文档版本V1.0发布日期2010-12-16版权所有 金蝶软件（中国）有限公司本书著作权属于金蝶软件(中国)有限公司所有，在未经本公司许可的情况下，任何单位或个人不得以任何方式对本书的部分或全部内容擅自进行增删，改编，节录，翻译，翻印，改写。注意由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。关于金蝶金蝶国际软件集团有限公司是亚太地区领先的企业管理软件及电子商务应用解决方案供应商，是全球软件市场中成长最快的独立软件厂商之一，是中国软件产业的领导厂商。金蝶开发及销售的软件产品包括针对快速成长的新兴市场中企业管理需求的、通过互联网提供服务的企业管理及电子商务应用软件和为企业构筑电子商务平台的中间件软件。同时，金蝶向全球范围内的顾客提供与软件产品相关的管理咨询、实施与技术服务。金蝶独特的“快速配置，快速实施，快速应用，快速见效”的全球化产品与服务定位，能够帮助顾客从容面对动态不确定商业环境带来的挑战，实现业务流程与IT技术的完美结合，有效管理变革，确保组织快速持续和健康成长。金蝶国际软件集团有限公司是中国第一个WINDOWS版财务软件，第一个纯JAVA中间件软件，第一个基于互联网平台的三层结构的ERP系统金蝶K/3的缔造者，其中金蝶K/3是中国中小型企业市场中占有率最高的企业管理软件。2003年3月，金蝶正式对外发布了第三代产品金蝶EAS (KINGDEE ENTERPRISE APPLICATION SUITE)。金蝶EAS构建于金蝶自主研发的商业操作系统金蝶BOS之上，面向中大型企业，采用最新的ERP管理思想和一体化设计，有超过50个应用模块高度集成，涵盖企业内部资源管理、供应链管理、客户关系管理、知识管理、商业智能等，并能实现企业间的商务协作和电子商务的应用集成。金蝶软件（中国）有限公司地址深圳市高新技术产业园南区科技南十二路2号金蝶软件园Kingdee Software（China）Co.,Ltd邮编518057网址 客户服务电话86-755-26612299客户服务传真86-755-26615016客户服务邮箱元数据升级指南前 言前 言概述本文档针对元数据升级相关背景概念、应用场景、操作步骤、注意事项、常见问题和相关规范做统一梳理，以释众惑。读者对象本手册主要适用于以下用户：l 实施人员l 二次开发人员约定符号约定在本文中可能出现下列标志，它们所代表的含义如下。符号说明表示有潜在风险，如果忽视这些文本，可能导致操作错误、数据丢失、设备性能降低或不可预知的结果。表示可以帮助您获取更多相关信息或提示您通过其它方式也可以获得相同结果。强调或补充说明所描述的信息。内容约定本文档以EAS V7.0.1、BOS V6.3.1版本为参照，其他版本元数据升级可以参考使用。文档版本 V1.0 (2010/12/16)版权所有 金蝶软件（中国）有限公司28元数据升级指南目录目录1 概述31.1 基本概念31.2 元数据升级的必要条件42 BOS开发工具元数据升级操作介绍52.1 整体操作流程52.2 准备二次开发列表52.3 准备三份元数据62.4 元数据差异检查（可选步骤）92.5 元数据升级102.6 数据表差异检查152.7 调整控件位置162.8 发布162.9 重构单据处理172.9.1 库存调拨单172.9.2 采购申请单(PurRequest)172.10 部署182.11 测试193 补丁升级涉及的元数据合并204 服务器端元数据升级介绍225 升级合并常见问题分析处理245.1 服务端合并元数据日志的收集245.2 元数据升级中常见的问题255.2.1 BOS工具合并元数据问题255.2.2 服务器端自动合并元数据问题26元数据升级指南5 升级合并常见问题分析处理1 概述基于BOS开发的软件系统，其工作产品包括：元数据、Java代码（含BOS生成的代码、开发人员编写的代码）、数据库脚本（含BOS生成的脚本、开发人员编写的脚本）、初始数据。对于该类软件系统的版本升级同时考虑元数据、Java代码、数据库脚本、初始数据的同步升级，其中元数据升级是其它升级的基础，因此，优先保证元数据的可升级特性是EAS标准产品、EAS客户化系统可版本升级的根基。1.1 基本概念在进行元数据的升级合并之前，必须了解元数据升级过程中需要使用到的几个基本概念，此处以实际应用场景为例，对这些概念进行一一介绍。基线版本如用户在2010年8月份安装了最新的EAS7.0.1版本，并从服务端导入解决方案到BOS开发工具中进行二次开发，那么，BOS工具中新导入的解决方案的版本是将要开发的版本的基础，此处该版本称之为基线版本，此时该版本跟EAS服务器的版本是一致的。客户版本用户在基线版本上，对标准产品的采购订单进行二次开发，增加了字段“采购备用地址”，并部署到服务器上运行。此时，客户开发的采购订单的内容（实际项目中指所有二次开发的内容），称之为客户版本。客户版的内容最终会从BOS工具的工作空间部署到EAS服务器上。升级版本在一段时间之后，EAS开发部在8月份的EAS7.0.1版本基础上，进行了诸多的新功能开发，发布了新的版本EAS7.0.2，其中，也有涉及对采购订单的修改，如增加了字段“供应商备注信息”。此版本称之为升级版本。客户化升级版本如果客户要使用EAS新版本功能，就要从7.0.1版本升级到7.0.2版本，由于客户版的元数据优先加载。因此，有过二次开发的采购订单，系统运行时会被优先加载，而含有新版本字段“供应商备注”的采购单就不会被加载，产品运行必然会有异常。为了解决此问题，就需要将客户开发的内容和更新的内容进行合并，将新版本中更新的内容合并到客户开发的版本中，让产品正确加载。因此，就有了元数据升级，也叫元数据合并，这一概念。升级后的元数据，称之为客户升级版。BOS工具合并由于实际二次开发、版本升级的内容涉及的元数据内容之巨，非人力编辑所能为，因此，BOS工具提供了元数据升级的功能(后面章节会重点介绍)。此种方式为：BOS工具合并。服务器端合并很多项目二次开发阶段结束之后，进入了运维期，在此期间出现产品问题，也需要更新版本(安装补丁) 来处理。同样，更新的版本的内容跟已经部署运行的二次开发的内容也会存在上述冲突的问题。因此，在服务端主控台提供了自动合并的功能，以方便用户在更新补丁的时候，服务器能自动进行元数据升级合并的操作。此中方式为：服务器端合并。1.2 元数据升级的必要条件元数据升级的必要条件，实际项目可依此判断是否要进行元数据合并：l 项目有过二次开发，且二次开发是在标准产品业务单元上进行。l 在已经进行二次开发的解决方案(EAS服务器)上，安装补丁（更新版本）。如果安装更新的补丁包含框架元数据（补丁中会有说明），则无论二次开发的内容是否是全新开发的模块，则都需要进行元数据合并。2 BOS开发工具元数据升级操作介绍2.1 整体操作流程使用BOS工具升级(合并)元数据的过程如下：N1)准备二次开发列表)准备二次开发列表2)准备三份元数据3)检查元数据差异以及这些差异是否违反升级约束4)比较元数据table的修改是否违反数据库约束5)元数据升级6)清理BOS缓存7)调整控件位置9)发布8)重构单据处理10)部署11)测试有问题结束元数据升级流程图修正Y2.2 准备二次开发列表升级前先准备好二次开发修改的元数据列表元数据升级后检查元数据是否正确合并，二次开发的功能点列表用于完成元数据升级、部署后，验证二次开发的功能是否正确，如果有问题及时在BIM中进行代码调整，进行调试，以保证功能的正确性。升级前对二次开发的内容做好备份，避免中途操作有误删除其中的内容。完成升级验证后，建议将解决方案下所有内容提交到cvs中，做为6.0上二次开发的基线版本。2.3 准备三份元数据元数据是否成功升级，三份元数据选择至关重要。我们在新建的目录路径下分别准备三份元数据如下：上图中：l base目录放置基线版本元数据l customer目录放置客户版本元数据l new目录放置升级版本元数据l megerd目录用于放置升级合并的结果输出1） 基线版本（旧版标准产品基线元数据）：旧版本解决方案下的basemetas（二次开发的基线元数据，首选这个，可能和生产环境的不同步）。或者客户eas旧版本server端metas目录下的元数据，除去sp-bim-metas.jar（生产环境的）。2） 客户版本（旧版二次开发元数据）: 旧版本解决方案下的metadata目录（包含完整的二次开发内容，首选这个，但可能没经过生产环境的验证）。或者客户eas旧版本server端metas目录下的元数据（生产环境的比较正确，但可能不包含最新的二次开发内容）。或者：3） 升级版本（新版标准产品元数据）: 新版本解决方案下的basemetas。或者eas新版本server端metas目录下的元数据，不包括sp-bim-metas.jar4） 升级前元数据的检查项检查项目处理方法检查三份元数据是否正确，此项需要对相关的开发版本很清楚的二次开发人员确认；负责此项目二次开发，或者了解项目二次开发的人员检查确认三份元数据中，基线版本和升级版本(新版本)中务必不能包含有二次开发的内容，特别是不能含有sp-bim-metas.jar包；如果基线版本和升级版本中包含二次开发的内容，务必删除元数据目录中不要有备份的元数据；有则删除Bos工具的安装目录中不要有中文路径；如果有的话，需要修改中文路径变为非中文即可客户版本的元数据如果选择的是jar包形式，则必须是sp-bim-metas.jar包命名如果有其他非sp-bim-metas.jar命名的二次开发包，则需要将所有的jar包解压到统一的目录，然后作为客户版元数据，参与合并2.4 元数据差异检查（可选步骤）打开元数据升级检查菜单，选择基线元数据和客户化元数据路径检查的结果展示在元数据约束视图里。这些违反升级约束的修改，可以先不处理，因为升级过程中按照一定的策略会忽略掉大部分违反约束的改动。2.5 元数据升级在bim中打开新版本解决方案。使用上述三份元数据进行升级。“升级后元数据路径” 所在硬盘的剩余空间要大于1G。或者升级的日志信息在BOSModularbimbim.log里。升级后元数据目录下的merged.xml里记录的是升级过程中合并过的元数据。升级结果展示在升级结果视图里。如果没有fatal或error级别的日志（Fatal或error表示合并失败），会弹出更换元数据的对话框：l 目标元数据路径：即我们要替换的解决方案中的客户化元数据路径，一般指定到当前工作空间下的解决方案的metadata目录(此metadata目录内容为二次开发编辑的内容)。l 来源元数据路径：即刚才合并成功之后输出的合并结果，这里指定到刚才输出合并结果目录megerd下的mn目录。备注：合并结果介绍最终合并的元数据文件在mn目录下，合并成功后直接使用改mn目录下的内容替换。Merged_result.csv文件问为升级合并结果日志文件，可以用文本编辑工具打开，查看合并中是否有异常信息。如果升级结果里有fatal或error级别的日志，查看描述信息，一般为客户化元数据路径里缺少了某个元数据导致的。如果合并失败的元数据上做了二次开发，必须修复该错误以后重新做一次升级合并。如果升级结果里有fatal或error级别的日志，但该业务单元上没有做过二次开发，也可以不做修复。使用bim菜单中的元数据替换功能用升级后mn下的元数据替换当前解决方案下的metadata目录。2.6 数据表差异检查使用元数据数据表差异检查菜单来做客户化table和升级后的table比较，展示违反约束的变动。检查结果展示在数据库约束视图里。数据库约束视图里是可能在发布时报数据库约束异常的table。可以修正这些违反约束的客户化元数据；也可以现在不处理，等发布时出现违反约束的报错时，再修正。2.7 调整控件位置清理一下缓存或者重启一下，然后在bim中打开客户化的业务单元，检查控件，如果有可见性属性为“是”的控件位置重叠，手工调整控件到适当的位置。2.8 发布对于整个包下的业务单元都是客户化的业务单元，使用整包发布；对于某个包下的业务单元大部分是客户化的业务单元，也可以使用整包发布；如果整包发布有问题，再单个发布。发布的时候如果有同步数据库的错误，可以做手工调整：l 如果报Caused by: java.sql.SQLException: ORA-01400: 无法将NULL 插入 (WKYG.T_CAS_PAYMENTBILL_TEMP.FACTRECACCOUNTBANK)类似的异常。请找到T_CAS_PAYMENTBILL这个table，如果客户化不允许FACTRECACCOUNTBANK字段为空，说明数据库中的数据有问题，必须更新数据库中的数据；否则将FACTRECACCOUNTBANK字段的属性改为允许空l 如果报Caused by: java.sql.SQLException: ORA-12899: 列 WKYG.T_SM_PURCONTRACTENTRY_TEMP.FREMARK 的值太大 (实际值: 96, 最大值: 80)类似的异常。请找到T_SM_PURCONTRACTENTRY这个table，将FREMARK字段的长度改为客户化元数据的相应字段的长度（或者改为上面的实际值，不过这样可能要多次修改）2.9 重构单据处理对于新版本里重构了的单据，如果做了二次开发，需要重做一次。然后发布。例如540里重构了库存调拨单和采购申请单，如果从530升到60，这两个单据上的二次开发就需要重做。如果是从540升到60，则不需要对这两个单据做特殊处理。2.9.1 库存调拨单1. 540版调拨单做了重大重构：由1个业务单元拆分成2个业务单元，实体、UI、query等元数据都进行了拆分。原来调拨单的主实体为： StockTransferBill（调拨单），重构后2个主实体为：StockTransferBill（库存调拨单）TransferOrderBill（调拨订单） 2. 二次开发升级策略： 对于StockTransferBill 即调拨单业务进行的二次开发可以支持升级。 对于TransferOrderBill 即调拨订单，由于是新增的业务单元，需要对照StockTransferBill的二次开发，在TransferOrderBill上重做一次。2.9.2 采购申请单(PurRequest)1. 540版本采购申请单为了支持非生产性采购进行了较大的调整：主业务组织类型，有库存组织修改为财务组织（即原库存组织委托记帐财务组织）。原有的库存组织和行政组织从采购申请单头移动到单据体的申请组织和行政组织。分录增加行类型，根据行类型确定行是否必须录入物料。 2. 二次开发升级策略：如果二次开发依赖上述调整内容，则必须重新进行二次开发。例如： 根据主业务组织的变化事件进行的相关业务处理，需要修改代码移动到行上对应的属性的事件中。 根据行政组织变化进行的相关业务处理，需要修改代码移动到行上对应的属性的事件中。 以前单据默认必须有物料，如果现场依赖此约束则需要调整，根据行类型进行判断。2.10 部署全部发布完客户化的业务单元（可能存在没有关联业务单元的元数据，也需要发布）以后，生成子系统树然后部署2.11 测试做主流程特别是客户化过的单据的测试，如果有问题可能需要在bim或bos studio中做调整，然后重新发布部署。3 补丁升级涉及的元数据合并补丁升级元数据合并过程基本和大版本升级元数据合并过程相同。需要注意的地方如下：l 对于补丁升级，升级之前请更新BOS工具，即执行“工具”“更新BOS工具”l 三份元数据： 基线版本（旧版标准产品基线元数据）：解决方案下的basemetas（二次开发的基线元数据，首选这个）或者打补丁之前的server端metas目录下的元数据，除去sp-bim-metas.jar（生产环境的） 客户版本（二次开发元数据）解决方案下的metadata目录（包含完整的二次开发内容，首选这个）或者打补丁之前的server端metas目录下的元数据: 请将原jar包形式的metas目录下的jar包解压到一个目录里，解压顺序为metas下的jar包，不包括sp-bim-metas.jar，然后解压metasindustry下的jar包，然后解压metassp下的jar包（不包括sp-bim-metas.jar），最后解压sp-bim-metas.jar，解压过程中都是后面的覆盖前面的。 升级版本（新版标准产品元数据）打补丁之后的server端metas目录下的元数据或者打补丁之后，同步一下服务器，解决方案下的newMetas另外新版本元数据还可以不打补丁来获得：首先拷贝上面的base中的元数据到一个新的目录new，然后拷贝补丁中的Serverservermetas目录下的元数据jar包覆盖new中的jar包，把new作为第3份元数据。l 在BIM里做测试之前，需要同步一下服务器，以获取最新的lib和基线元数据。更新完以后，把解决方案下basemetas目录备份一下，然后把newMetas下的文件拷贝到basemetas目录下。basemetas目录就是下次合并的基线元数据。对于行业版，下次打标准版补丁的时候，如果标准版补丁里修改的元数据和行业版的有重叠，就会有对应的行业版的补丁。打标准版补丁的时候需要同时打对应的行业帮的补丁。4 服务器端元数据升级介绍服务器端在安装补丁的时候，一般默认进行元数据升级的操作。如果项目实施或者二次开发用户不希望使用服务端提供的自动升级合并的操作，可以选择在配置文件中修改相关的参数关闭自动合并功能：EAS60及以上版本，将easadminconfigadmin.vmoption文件中的bosversion61=true修改为false即可。关闭服务器端自动合并元数据的功能，一般有两种情况：l 项目没有二次开发，不需要元数据合并。l 不希望使用服务端自动合并的功能，而使用BOS工具进行合并。服务端主控台-“企业应用”的工具栏中提供合并二次开发元数据功能，提供用户在关闭自动合并的功能之后，人工指定服务端进行元数据升级合并操作。服务器端合并需要注意的几点：l 服务端合并的时候，无须人工收集三份元数据，服务端程序自行根据当前的服务器元数据版本判断基线、客户化开发以及对应的补丁内容中的新版本。但如果反复安装卸载补丁，容易导致基线元数据的不准，使用服务端自动合并功能务必注意。l 合并异常，需要收集相关日志(收集方法参考第五节)，排除异常之后，可以重新部署，再次执行服务端“合并二次开发元数据”的操作。l 服务端合并异常中断，无法在服务端完成合并，可以使用BOS工具，人工收集三份元数据，在BOS工具中进行合并，之后重新部署到服务器上即可。5 升级合并常见问题分析处理5.1 服务端合并元数据日志的收集服务端合并元数据，出现问题之后，需要通过日志进行分析，日志文件的收集路径在安装补丁出现合并元数据异常的时候会提示。问题现象如：安装补丁PT38555过程中提示合并元数据报错：查看其中的错误详细信息：自动合并元数据出错。此时需要根据提示信息，收集详细的元数据合并错误日志信息。解决方案：根据已有的异常提示信息：C:/Kingdee/600/Server/eas/admin/patch/log/mergeMetas_PT038555_2010-09-14_11-53-05.log;C:/Kingdee/600/Server/eas/admin/logs/admin.log|admin_client.log异常堆栈：com.kingdee.eas.tools.admin.domain.exception.BOSAutoMergeMetasException: Merge metas error,Run ant file C:/Kingdee/600/Server/eas/admin/config/patchmetadataupdate.xml, please check log file C:Kingdee600ServereasadminpatchlogmergeMetas_PT038555_2010-09-14_11-53-05.logcause by java.lang.Exception: Run ant file C:/Kingdee/600/Server/eas/admin/config/patchmetadataupdate.xml, please check log file C:Kingdee600ServereasadminpatchlogmergeMetas_PT038555_2010-09-14_11-53-05.logat com.kingdee.eas.tools.admin.domain.impl.NodeManagerServiceImpl.runAntFile(NodeManagerServiceImpl.java:1983)需要找到合并元数据异常的具体日志文件：C:Kingdee600ServereasadminpatchlogmergeMetas_PT038555_2010-09-14_11-53-05.log然后需要联系现场二次开发人员分析该合并元数据详细日志，分析原因，解决冲突之后，可以：1. 通过BIM工具手工合并元数据；2. 或者进入“企业应用”，选择“合并二次开发元数据”菜单，再次合并元数据；如当前正在执行补丁安装操作，请手工执行未完成的任务：执行补丁脚本(如有) - 生成子系统树(如有)。如仍有问题，请收集日志信息提单反馈到二次开发(BIM)模块。5.2 元数据升级中常见的问题元数据升级中常见的问题主要分为BOS工具合并元数据、服务端安装补丁自动合并元数据两类。5.2.1 BOS工具合并元数据问题BOS工具做元数据升级的功能本身已经比较稳定，现场遇到并反馈的问题大多是三份版本的元数据没有正确获取导致，一般根据合并后的日志来分析，即可处理。此类元数据升级出现异常的情况主要有：1） 关联的元数据丢失分析处理：需要根据日志查看确认丢失的相关元数据是标准产品的，还是二次开发的，如果是标准产品的是否三份元数据中相关的jar包丢失？或者是否二次开发的元数据有冗余的垃圾元数据。2） 合并结果输出目录中没有内容分析处理：此类问题原因主要有，BOS工具本身的问题，如BOS工具的安装路径是否包含有中文？BOS工具跟当前的解决方案的版本是否一致？三份元数据的是否完整？主要通过BOS工具的“窗口-显示视图-其他-常规-错误日志”来分析具体异常信息。5.2.2 服务器端自动合并元数据问题1） 找不到基线元数据反复安装卸载补丁或者重复安装补丁或者安装多个补丁时跳过元数据合并，都会导致基线不准，合并结果不正确。处理方案：对于补丁中增加的字段，不管基线是否准确都可以正确合并；但对于补丁中修改字段的属性，基线不准确时不能正确合并，理论上也无法保证正确合并；2） 补丁中元数据重构开发和升级约束是不允许对单据做重构的（例如MaterialCode.entity改包名）。处理方案：请设计和开发人员遵守约束3） 行业版补丁问题打了标准版补丁，而没有打对应行业版补丁，或者还没有对应行业版补丁。行业版补丁通常和标准版补丁有时间差。行业版不能打时间差期间的标准补丁。处理方案：之前有个方案是在管理控制台中增加检查，不允许行业版服务器直接打标准补丁，只能通过打行业版补丁，来关联打标准补丁。4） 元数据不完整一般是基线或者二次开发版本元数据中关联到的元数据找不到。基线元数据不全主要有两个原因：一是基线不准，二是打补丁时依赖的补丁没有打（例如设置补丁依赖时没有设全）。二次开发元数据不全，常在补丁元数据升级时遇到，原因是关联的元数据没有发布部署。处理方案：加强补丁质量，避免一些依赖不全的问题5） 发布时元数据校验错误发布时可能遇到各种元数据校验错误。处理方案：校验错误主要是由以上这种原因导致合并后元数据错误的，解决上述问题才能减少这些校验错误6） 发布后编译出错有些二次开发单据在studio里发布就有编译错误，部署到服务器，自动合并后发布后也会有编译错误。处理方案：需要现场二次开发人员先行分析处理二次开发的编译问题。然后，在用BOS工具进行合并。7） 补丁元数据合并后更新方案的易用性：自动合并后，如果继续做二次开发，可以重导解决方案，目前需要重新做发布部署，发布的单据太多。处理方案：在补丁合并元数据步骤里，增加打包源文件到固定目录；导解决方案时，把二次开发元数据解压到deployed_metas目录，源代码解压到src目录。这样继续做二次开发、部署时，就不需要发布所有的单据，只需发布自动合并后UI控件需要手工调整的单据和新的二次开发的单据。8） 找不到对应的元数据文件服务端自动合并元数据错误日志中，常见的错误信息找不到对应的元数据文件，如：异常信息：错误信息：ERROR:-com.kingdee.bos.engine.MDNotFoundException: 被引用的元数据pk=comkingdeeeasficasappR_Cas_R