金蝶s-HRV8.5OSFWebService服务实现指南【免责声明】：本文档仅用于学习使用，未经授权，禁止转载。本文档中所用数据均为虚构的模拟数据，不代表任何一家企业的真实情况，如有权利人认为文档中的任何内容存在侵权情况，请反馈给金蝶官方邮箱（DataSubjectRequest@kingdee.com），我们将在7个工作日内处理。金蝶软件（中国）有限公司2018年10月金蝶s-HRV8.5OSFWebService服务实现指南目录1.概述.....................................................................21.1.OSF的定义.........................................................21.2.BOSWebService服务................................................21.3.s-HROSFWebService服务...........................................22.发布OSFWebService服务...................................................22.1.发布流程...........................................................22.2.定义Facade........................................................32.3.发布Facade........................................................42.4.发布WebService....................................................52.5.服务端OSF程序.....................................................63.部署OSFWebService服务...................................................73.1.服务端组件.........................................................73.2.部署服务端程序.....................................................73.3.开启安全模式.......................................................83.4.验证部署...........................................................94.客户端代码生成...........................................................94.1.登录接口集成.......................................................94.1.1.获取登录接口描述文件.........................................94.1.2.编写登录/登出方法............................................94.2.获取OSFWebService接口描述文件...................................104.3.生成客户端代码(JAVA)..............................................114.3.1.新建客户端程序工程..........................................114.3.2.目标wsdl复制到工程内.......................................124.3.3.生成WebServiceClient......................................124.3.4.编写ClientAPI工具类........................................144.4.生成C#客户端....................................................144.4.1.使用命令行..................................................154.4.2.运行命令生成客户端..........................................155.第三方系统调用s-HROSFWebService......................................165.1.获取SDK..........................................................165.2.SDK对外发布的接口................................................165.3.调用客户端SDK代码示例............................................175.4.用户信息配置文件详解..............................................18金蝶s-HRV8.5OSFWebService服务实现指南1.概述1.1.OSF的定义OSF（OpenServiceFramework），开放服务框架。以HTTP+Json的方式提供数据接口。s-HR系统预置了大量数据接口，同时支持客户二次开发，为第三方系统提供所需要的接口。1.2.BOSWebService服务WebService是一个平台独立的，低耦合的，自包含的、基于可编程的web的应用程序，可使用开放的XML（标准通用标记语言下的一个子集）标准来描述、发布、发现、协调和配置这些应用程序，用于开发分布式的互操作的应用程序。BOSWebservice基于ApacheAxis1.4实现，提供在各个不同平台的不同应用系统的协同工作能力。使各个异构系统之间实现无缝交互。在本质上是要为应用程序之间提供数据通讯的标准，为企业应用之间动态地提供大颗粒度的服务，并不适合于非常精细的基于会话的方法调用以及复杂的事务（transaction）处理之中。1.3.s-HROSFWebService服务在8.2SP以前调用s-HROSF接口需要先配置单点登录，完成单点登录配置后才能在第三方调用到OSF。WebService的引入，通过SOAP协议中转HTTP请求，在服务端完成数据操作后同样以Json的方式返回操作结果。从实施难度上看，配置OSFWebService服务要比根据现场网络、硬件、BOS版本以及各种私包的影响来配置单点登录简单、快速很多，仅仅需要将OSFWebService服务发布到BOS中即可。其它内容均预置。2.发布OSFWebService服务本章节旨在阐述BOSWebService服务如何发布，指导开发人员进行WebService服务开发。2.1.发布流程通过BOSStudio发布s-HROSFWebService，发布的OSFFacade，建立粗粒度的业务金蝶s-HRV8.5OSFWebService服务实现指南方法，提供简单数据类型的数据参数和返回参数。图s-HROSFWebService发布流程2.2.定义Facade在BOSStudio中发布webService时，只能发布Entity和Facade两种元数据类型成WebService服务端的代码。由于Entity或Facade函数参数和返回值可能包含很多复杂的业务类型，在发布时会生成许多辅助类，一些复杂类型在其他异构系统中生成webService客户端时不能很好的支持，因此建议在建立webService功能时，最好使用Facade，并且提供简单类型的输入和返选择要发布为WebService的实体或Facade在BosStudio中发布为WebService将生成的.java文件编译将编译后的.class文件或.jar文件部署在web容器中使用产生的.wsdd文件部署WebService生成.java文件和.wsdd文件提供.wsdl文件客户端调用金蝶s-HRV8.5OSFWebService服务实现指南回参数。图定义OSFWebServiceFacade2.3.发布Facade发布Facade为java文件，生成服务端程序。金蝶s-HRV8.5OSFWebService服务实现指南图发布OSFWebserviceFacade文件2.4.发布WebService运行BOSStudio，打开“包分类”视图，在其中选中要发布WebService的实体或Façade对象（可同时选中多个），点击鼠标右键，在弹出菜单中选择“发布WebService”,将弹出“发布WebService”向导，选择实体或Façade对象下要发布的方法，手工输入或者点击“浏览”按钮来指定发布生成代码存放的目录，可以同时勾中“追加到配置文件”。这样BOSStudio将会根据选中的对象和要发布的方法生成WebService代码和wsdl描述。金蝶s-HRV8.5OSFWebService服务实现指南图发布s-HROSFWebService2.5.服务端OSF程序完成以上步骤后，得到s-HROSFWebService服务端程序，文件列表如下图所示：图s-HROSFWebService程序金蝶s-HRV8.5OSFWebService服务实现指南修改业务处理方法，以实现OSF请求转发功能，代码片段如下：图OSF请求转发代码片段3.部署OSFWebService服务3.1.服务端组件s-HR8.5OSFWebService属于标准产品的一部分，全部内容包含服务端程序、元数据以及WebService描述文件(wsdd)。3.2.部署服务端程序部署服务端程序，执行以下4步操作：1)服务端jar发布到lib目录，如{EAS_HOME}\eas\server\lib\server\eas\shr_webservice-server.jar；2)元数据jar发布到meta目录，如{EAS_HOME}\eas\server\metas\eas\shr_webservice-metas.jar；3)将WebService描述文件添加到{EAS_HOME}\eas\server\deploy\eas.ear\web.war的WEB-INF目录中，如下图所示；金蝶s-HRV8.5OSFWebService服务实现指南图将wsdd文件添加到web.war4)注册OSFWebService，将以OSFWebService描述信息添加到{EAS_HOME}\eas\server\deploy\eas.ear\web.war的WEB-INF\server-config.wsdd中；
3.3.开启安全模式EAS默认是不开启WebService安全模式，在集群环境下会出现登录请求与业务请求被分发到不同实例，导致业务请求有可能被判定为“未登录”状态，需要修改配置文件开启安全模式。修改{EAS_HOME}\eas\server\profiles\server1\config\webservice.propetties文件，添加一下配置项：isRomoteLocate=false金蝶s-HRV8.5OSFWebService服务实现指南3.4.验证部署查看BOS所有的WebService的链接为：http://ip:port/ormrpc/services，搜索关键字关键字“WSOSFWebserviceFacade”，搜索到结果可视为部署完成。如下图所示：图验证部署结果4.客户端代码生成4.1.登录接口集成基于安全及业务考虑，调用s-HROSFWebService客户端需要进行BOS体系的登录校验。登录的客户端代码以安全模式完成BOSWebService的单点登录，此种方式才能实现用户会话粘贴功能。4.1.1.获取登录接口描述文件登录接口的描述文件为EASLogin.wsdl，可从http://ip:port/ormrpc/services/EASLogin?wsdl获取。4.1.2.编写登录/登出方法以下为登录、登出方法示例：金蝶s-HRV8.5OSFWebService服务实现指南图登录代码示例图登出代码示例4.2.获取OSFWebService接口描述文件服务端程序部署完成后，通过浏览器访问http://ip:port/ormrpc/services/WSOSFWebserviceFacade?wsdl可请求到WSOSFWebserviceFacade描述文件内容，将其保存为wsdl文件可取得最新的WebService描述文件WSOSFWebserviceFacade.wsdl。金蝶s-HRV8.5OSFWebService服务实现指南图获取最新的WSOSFWebserviceFacade.wsdl4.3.生成客户端代码(JAVA)下面将基于Eclipse来介绍如何生成s-HROSFWebServiceClient。4.3.1.新建客户端程序工程在Eclipse中新建一个JavaProject，编译版本建议选择jdk1.6x以兼容较早的EAS环境。图新建WebService客户端工程金蝶s-HRV8.5OSFWebService服务实现指南4.3.2.目标wsdl复制到工程内将上述步骤获得的wsdl文件复制到工程内，以便生成客户端代码。图将wsdl文件拷贝到工程内4.3.3.生成WebServiceClient用鼠标右键点击要生成客户端的WSDL文件，选取“新建”，在弹出的新建项目类型中选择“WebServicesClient”，按照指引选择下一步直到完成WebServiceClient。并将生成的杂乱无章的代码整理成我们想要的形式，如修改包路径等金蝶s-HRV8.5OSFWebService服务实现指南图生成WebServiceClient图整理生成的WebServiceClient金蝶s-HRV8.5OSFWebService服务实现指南4.3.4.编写ClientAPI工具类调用s-HROSFWebService的API类，推荐以EndPoint+QName的方式来调用，保证能灵活改变s-HR地址，代码片段参考。注意：用同一个Call实现贯穿登录=>调业务方法=>登出方法，才能实现高可用（集群）方式实现会话粘贴。图编写CleintAPI工具类–1图编写CleintAPI工具类–24.4.生成C#客户端在此，以MicrosoftVisualStudio.Net2003为例说明如何生成C#客户端。用户在正确安装完MicrosoftVisualStudio.Net2003后，需要设置一个环境变量Path=C:\ProgramFiles\MicrosoftVisualStudio.NET2003\SDK\v1.1\Bin，其中C:\ProgramFiles\MicrosoftVisualStudio.NET2003是MicrosoftVisualStudio.NET2003的金蝶s-HRV8.5OSFWebService服务实现指南安装路径。4.4.1.使用命令行运行“cmd”，打开命令行窗口，并进入WSDL文件所在目录（在此为C:\wsdl目录）：4.4.2.运行命令生成客户端运行命令wsdlXXX.wsdl（XXX为wsdl文件的文件名），即可生成C#的WebService客户端代码：输入途中命令，按回车键，即可自动生成C#客户端代码：金蝶s-HRV8.5OSFWebService服务实现指南如上图所示，生成了一个文件WSLoginService.cs，这就是我们所需要的客户断代码。5.第三方系统调用s-HROSFWebService由金蝶HR事业部封装的s-HROSFWebServiceClientSDK是正式发布的客户端调用WebService的客户端。5.1.获取SDK通常情况下，从s-HR系统上下载下来的SDK可直接使用，无须进行额外配置。SDK中所使用的接口用户信息为s-HR系统中“客户端维护”里所配置的用户信息。s-HROSFWebServiceClientSDK可在s-HR系统中获取到(获取SDK操作参照s-HR操作指引)。5.2.SDK对外发布的接口第三方系统拿到SDK后，可直接调用SDK中对外发布的两个调用s-HROSFWebService方法的接口：➢com.kingdee.shr.api.proceedOSF(StringshrAddr,StringserviceName,Mapparams);➢com.kingdee.shr.api.proceedOSF(StringshrAddr,StringserviceName,Mapparams,UserInfouserInfo);金蝶s-HRV8.5OSFWebService服务实现指南调用参数详解：参数参数名称说明shrAddrs-HR访问地址--serviceNameOSF接口名称OSF接口名称，可从s-HR系统中获取(支持二开接口)paramsOSF接口参数OSF接口定义中所配置的参数，以key-value的方式传入userInfo登录用户信息登录BOS的用户信息，若不传此参数则使用用户信息配置文件中所配置的用户信息5.3.调用客户端SDK代码示例登录需要传入用户及账套信息，故封装的代码需要传入userInfo信息。目前支持配置文件的方式和参数传入的方式(配置文件方式见后续章节描述)。publicstaticvoidmain(String[]args)throwsIOException{UserInfouserInfo=newUserInfo();userInfo.setDbType(1);//数据库类型:SQLServer:0,Oracle:1,DB2:2;userInfo.setDcName("SHRDB");userInfo.setLanguage("L2");userInfo.setPassword("apiuserpasswd");userInfo.setSlnName("eas");userInfo.setUserName("apiuser");StringshrAddr="http://172.18.8.35:8080/shr";StringserviceName="personSearchService";Mapparams=newHashMap();params.put("searchKey","陈");//若不使用userInfo参数,则使用配置文件userInfo.properties中配置的用户信息来登录并调接口Stringresult=newOSFWSClient().proceedOSF(shrAddr,serviceName,params);Stringresult1=newOSFWSClient().proceedOSF(shrAddr,serviceName,params,userInfo);System.out.println("callosfbyinitproperties:"+result);System.out.println("callosfbybuiltuserInfos:"+result1);}金蝶s-HRV8.5OSFWebService服务实现指南5.4.用户信息配置文件详解用户信息配置文件目录位于/OSFWebServiceClient/src/com/kingdee/shr/osf/webservice/client/userInfo.properties，请按具体环境进行修改图用户信息配置文件描述
