A8接口和增值开发手册 .doc

A8平台接口和增值开发手册© 2006 UF Seeyon Co., Ltd.All rights reserved.This document contains information that is proprietary and confidential to UF Seeyon., which shall not be disclosed outside the recipient's company or duplicated, used or disclosed in whole or in part by the recipient for any purpose other than to evaluate this file. Any other use or disclosure in whole or in part of this information without the express written permission of UF Seeyon. is prohibited. Date: 2009-01-04Author:王文友Version:V1.0修改记录31.概述41.1编写目的41.2开发背景41.3应用价值41.4接口范围52.二次开发接口62.1接口一览62.2服务列表63.Portal集成73.1单点登录(SSO)73.1.1外部平台集成A873.1.1.1实现说明73.1.1.2接口说明73.1.1.3代码示例83.1.1.4部署说明93.1.2A8集成第三方系统93.1.2.1实现方式一：Ticket93.1.2.2实现方式二：关联系统+扩展栏目113.2Portlet123.2.1概述123.2.2开发说明123.2.2.1确定栏目数据123.2.2.2确定栏目显示模板123.2.2.3开发说明133.2.2.4注册到系统133.2.3代码示例143.2.4待办事项和跟踪事项203.2.5新闻和公告204.消息集成214.1消息通道214.1.1概述214.1.2接口说明214.1.2.1方法说明214.1.2.2注册到系统214.1.2.3原理说明224.1.3代码示例224.2短信接口234.2.1概述234.2.2接口说明234.2.2.1注册到系统254.2.2.2原理说明264.2.3代码示例275.组织模型同步285.1初始化同步285.1.1导出285.1.2导入295.2实时同步295.2.1实现A8组织模型事件监听接口295.2.2注册事件监听356.BPM集成356.1准备366.2外部系统发起A8表单流程376.3轮询完成的表单流程376.4导出A8表单流程到外部系统377.附录387.1术语表38修改记录1.概述1.1编写目的1.2开发背景1.3应用价值1.4接口范围2.二次开发接口2.1接口一览62.2服务列表62.3服务调用流程73.Portal集成3.1单点登录(SSO)3.1.1外部平台集成A83.1.2A8集成第三方系统3.2Portlet133.2.1概述133.2.2开发说明143.2.3代码示例163.3基于A8 Webservice构建portlet223.3.1待办事项和跟踪事项223.3.2新闻和公告224.消息集成224.1消息通道234.1.1概述234.1.2接口说明234.1.3代码示例244.2短信接口254.2.1概述254.2.2接口说明254.2.3代码示例305.组织模型同步315.1初始化同步315.1.1导出315.1.2导入325.2实时同步325.2.1实现A8组织模型事件监听接口325.2.2注册事件监听396.BPM集成396.1准备406.2外部系统发起A8表单流程406.3轮询完成的表单流程416.4导出A8表单流程到外部系统417.附录417.1术语表41修改记录31.概述41.1编写目的41.2开发背景41.3应用价值41.4接口范围42.二次开发接口52.1接口一览52.2服务列表52.3服务调用流程63.Portal集成规范73.1单点登录(SSO)73.1.1外部平台集成A873.1.2A8集成第三方系统93.2Portlet123.2.1概述123.2.2开发说明123.2.3代码示例144.消息集成规范204.1消息通道204.1.1概述204.1.2接口说明204.1.3代码示例214.2短信接口224.2.1概述224.2.2接口说明224.2.3代码示例275.组织模型同步285.1初始化同步285.1.1导出285.1.2导入295.2实时同步295.2.1实现A8组织模型事件监听接口295.2.2注册事件监听366.BPM集成366.1准备376.2外部系统发起A8表单流程376.3轮询完成的表单流程386.4外部系统使用服务轮询完成的流程实例A8表单流程导出到外部系统387.附录387.1术语表38修改记录日期修改人修改内容备注2008-12-08王文友创建文档，编写文档模板。2008-12-15王文友增加了安装服务文档。2008-12-23王文友增加了文档导出接口例程。2008-12-29王文友合并刘娜组织模型文档，加入例程；合并于荒津BPM文档。2009-01-04王文友合并张勇Portal和消息文档，拆分API文档。2009-06-16张勇增加单点登录不打开页面方式说明和待办事项接口说明2009-9-27王文友增加组织模型同步和BPM集成1. 概述1.1 编写目的本手册主要面向二次开发人员，内容涵盖A8平台的二次开发、第三方应用集成。如果需要更详细的开发信息，请参考平台API参考手册。1.2 开发背景接口的目标是1、 与第三方应用集成，达成松散耦合，紧密集成的目标；2、 与异构应用集成；3、 降低二次开发的技术难度；4、 规范化二次开发，提升二次开发的稳定性；5、 保证二次开发的延续性，降低二次开发应用升级难度。1.3 应用价值目前平台开放的接口支持：1、 组织模型同步使用组织模型导入接口，实现外部系统到A8的组织模型初始化同步；调用组织模型管理远程接口，在外部系统组织模型发生变化时实时同步到A8。实现组织模型事件接口，将A8组织模型变更实时同步到外部系统。2、 表单流程集成外部系统通过BPM集成远程接口发起A8的表单流程，在A8中审批流转后回到外部系统，实现表单流程的打通。3、 文档导出使用文档导出SDK，将A8的协同、公文、新闻、公告、调查和讨论导出到外部系统，满足数据交换和归档的需求。4、 Portal集成A8 Portal可以集成外部系统的页面，也可以将A8集成到第三方Portal中，并且实现单点登录。5、 消息集成外部通过消息通道，实时获取A8中的消息。可以将A8的消息以邮件、IM（如GKE、RTX）消息和短信形式发送。外部系统通过消息接口向A8指定用户发送消息。待办事项集成外部系统通过待办事项接口，可以得到A8待办事项的列表，并且可以处理待办事项。6、1.4 接口范围A8协同办公平台采用Java开发，支持Oracle、mysql和Sql Server数据库。平台提供了以下接口：1、 二次开发接口：提供本地开发的Java SDK和Web Service远程接口，涵盖组织模型同步与导入导出、文档导出、表单与流程集成、新闻与公告发布支持。2、 Portal接口：提供页面集成和单点登录接口，实现外部应用在A8-Portal的集中展现。3、 消息(短信)接口：提供外部系统获得A8协同办公平台消息的机制。除标准化产品提供的短信集成支持外，A8还提供了短信二次开发接口，支持与特定的短信运营平台集成。4、5、2. 二次开发接口预备知识：1、 Web Service2、 XML支持Web Service调用的编程语言3、 其中Java已验证，C#、Php未经验证，请参照Java例程及axis2文档进行开发。A8平台接口提供基于axis2 1.4实现的标准Web service。可以采取多种方式进行客户端开发。本指南所有远程接口例程使用axis2的ADB（Axis2 DataBinding Framework）stub方式进行开发。为便于二次开发，在client/demo目录中提供了一个示例应用，示例包括以下内容：单点登录、组织模型同步、组织模型导出、公告新闻导出、文档导出、表单流程查询、BPM集成、消息集成、Portlet栏目集成2.1 接口一览l 组织模型接口：提供组织模型导入和导出接口，可以实现其他HR与A8的集成，其他系统可以与A8实现组织模型和人员信息同步。l 文档接口：提供了A8文档导出接口，支持协同、公文、新闻、公告等信息导出，通过此接口可以实现与档案软件的集成，以及A8信息发布到外部网站。l 表单流程接口：提供了外部数据导入A8进行流转审批，以及A8流程审批信息导出到其他系统（如ERP），通过此接口可以实现政府外网审批信息提交到内网进行流转审批，ERP记录数据可以转入A8进行流转，A8流程审批信息也可以转入ERP进行结果管理。l 新闻和公告发布接口：提供了单位新闻和公告的发布。待办事项接口：提供A8待办事项列表。l2.2 服务列表A8平台提供以下服务：名称服务说明验证服务authorityService用户身份验证服务人员管理服务personService人员的创建、修改、删除和启用/禁用。部门管理服务departmentService部门的创建、修改、删除和启用/禁用。岗位管理服务ocupationService岗位的创建、修改、删除和启用/禁用。职务级别管理服务otypeService职务级别的创建、修改、删除和启用/禁用。单位管理服务accountService组织模型数据服务organizationDataService人员、部门、岗位和职务级别数据导入导出服务。文档导出服务documentService协同、公文、新闻、公告、讨论、调查数据导出服务。新闻公告发布服务documentService新闻和公告发布发布服务。表单服务formService表单定义与数据导出服务BPM服务BPMService业务单据流程集成服务。事项服务affairService待办事项和跟踪事项集成服务。消息服务messageService外部系统发消息到A8的服务。文件服务downloadServiceuploadServiceA8的附件下载和上传服务。名称服务说明验证服务authorityService用户身份验证服务人员管理服务personService人员的创建、修改、删除和启用/禁用。部门管理服务departmentService部门的创建、修改、删除和启用/禁用。岗位管理服务ocupationService岗位的创建、修改、删除和启用/禁用。职务级别管理服务otypeService职务级别的创建、修改、删除和启用/禁用。单位管理服务accountService组织模型数据服务organizationDataService人员、部门、岗位和职务级别数据导入导出服务。文档导出服务documentService协同、公文、新闻、公告、讨论、调查数据导出服务。表单服务formService表单定义与数据导出服务BPM服务BPMService业务单据流程集成服务。事项服务AffairService待办事项，跟踪事项集成服务。服务详情参见平台API参考手册。2.3 服务调用流程1、 外部业务系统服务传入用户名和密码，发出验证请求；2、 A8远程接口进行服务用户验证，通过则生成token，返回令牌；否则返回一个空令牌(tokenId=-1)。3、 外部业务系统构造请求数据，封装请求参数。4、 发送服务请求；5、 A8远程接口根据请求调用A8 API，执行请求操作，获取相应的业务对象；6、 A8对请求进行处理；7、 返回处理结果；8、 返回响应数据。3. Portal集成规范3.1 单点登录(SSO)3.1.1 外部平台集成A83.1.1.1 实现说明也就是从外部系统登录到A8，这种认证是完全信任外部系统的。单点登录有2种效果：单点登录成功后直接打开A8主页面单点登录成功后并不打开A8主页面，A8维护ticket信息和登录用户信息，为以后请求服务作认证使用,比如：请求获得A8待办事项列表服务。需要配置中一个属性如下：<property name="forward" value="false"/>登录过程：l 人员登录外部平台 l 外部平台带着ticket和from跳转到A8-/login/sso?from=*&ticket=*1. 如果A8登录正常，会在response header中增加SSOOK，否则增加SSOError 例如："/login/sso?ticket="+encodeURIComponent("<%=rameter("ticket")%>")+"&from=gke"l A8根据from取得握手bean ，也就是springBean id例如：<bean id="gke" class="e.SSOLoginContext">l 调用握手bean由外部系统认证ticket并返回A8的登录名l 把ticket和username维护在内存 l A8带着ticket跳转到/login/proxy ，也就是执行一个servletl A8 JAAS的取得用户身份信息l A8退出时，会通过SSOLoginHandshakeInterface的logoutNotify()通知到外部系统l 外部系统退出时，访问A8 /login/ssologout?from=*&ticket=*通知A83.1.1.2 接口说明l 外部平台需要有A8登录名的映射表或者使用相同的登录名 l JAAS的DefaultLoginModule验证用户名（不验证密码） l SSOLoginHandshakeInterface与from映射，需要配置或二次开发，系统提供通用的SSOLoginHandshakeServletImpll A8的验证系统完全依赖和信任外部系统（存在风险） 1、 配置文件：ApacheJetspeed2webappsROOTWEB-INFclasses（如无可自己创建）<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE beans PUBLIC "-/SPRING/DTD BEAN/EN" ""><beans default-autowire="byName"><bean id="gke" class="e.SSOLoginContext"><property name="name" value="gke"/><property name="ticketName" value="ticket"/><property name="handshake"><bean class="n.8SSOLoginImp"><property name="url" value="http:/外部系统:8080/checkTicket"/><property name="logoutUrl" value="http:/外部系统:8080/ssologout"/><property name="ticketName" value="ticket"/></bean></property></bean></beans><?xml version="1.0" encoding="UTF-8"?><!DOCTYPE beans PUBLIC "-/SPRING/DTD BEAN/EN" ""><beans default-autowire="byName"><bean id="gke" class="e.SSOLoginContext"><property name="name" value="gke"/><property name="ticketName" value="ticket"/><property name="handshake"><bean class="n.8SSOLoginImp"><property name="url" value="http:/外部系统:8080/checkTicket"/><property name="logoutUrl" value="http:/外部系统:8080/ssologout"/><property name="ticketName" value="ticket"/></bean></property></bean></beans>2、 实现接口SSOLoginHandshakeInterface的handshake方法/* * 通过握手获取平台的认证信息 * param token 平台传过来的令牌信息 * return 返回当前登录者的登录名 */public String handshake(String token);3.1.1.3 代码示例从GKE登录到A8：public class GKEA8SSOLoginImp implements SSOLoginHandshakeInterface private static final Log log = g(); private static final int gkeTimeOut=60000; / “token” 就是ticket取得的参数值 public String handshake(String token) if(token=null|s("") return null; String userName="" String r=(","); if(r=null|r.length!=2) return null; userName=Passport(r0, r1); return userName; private String checkPassport(String GID,String passPort ) StringBuffer sb = new StringBuffer(); sb.append("<?xml version="1.0" encoding="UTF-8" ?>"); sb.append("<request type="login" subtype="passport" msid="">"); sb.append("<message>"); sb.append("<user"); sb.append(" GID=""+GID+"" gid="" zoneid="">"); sb.append("<passport>"); sb.append(passPort); sb.append("</passport>"); sb.append("</user>"); sb.append("</message>"); sb.append("</request>"); return getGKEResponse(postGKERequest(sb.toString(); 3.1.1.4 部署说明单点登录的开发建立的java文件放在e.包下例如：package n.gke;注意事项：Java的编译class文件， 文件，jsp文件copy到SeeyonA8/webapps/ROOT下3.1.2 A8集成第三方系统3.1.2.1 实现方式一：Ticket实现步骤:1. 添加页签2. 按下面的定义，在A8的webapps/seeyon/WEB-INF/classes目录下新建一个XML文件，如<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE beans PUBLIC "-/SPRING/DTD BEAN/EN" ""><beans default-autowire="byName"><!- id必须唯一 -><bean id="sinaNewsSpace" class="n.n.partySpace" init-method="init"><!- id必须唯一 -><property name="id" value="sinaNews"/><!- 页签上显示的名称 -><property name="name" value="Sina News"/><!- 插件id，必须存在，如果不存在，请按下面的步骤定义一个新的插件 -><property name="pluginId" value="news"/><!- 第三方系统登录地址，如果合并3、4步，可以省略 -><property name="loginURL" value=""/><!- 点击页签要打开的第三方系统页面地址 -><property name="pageURL" value=""/><!- 打开方式，值为open时在新窗口打开，为workspace时在A8页面能打开 -><property name="openType" value="open"/><!- 排序号 -><property name="index" value="4"/></bean></beans>3. 修改webapps/seeyon/WEB-INF/，增加对新增的的引用4.5.注意事项：集成第三方系统，要以A8系统插件定义在webappsseeyonWEB-INFclassesconfplugin下新建一个内容如下的XML，即可定义一个id为news，名称为“新闻插件”的新的插件<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE beans PUBLIC "-/SPRING/DTD BEAN/EN" ""><beans default-autowire="byName"><bean id="newsPluginDefintion" class="n.n.PluginDefintion"><property name="id" value="news"/><property name="name" value="新闻插件"/><property name="contextConfigLocation"><list><value>classpath*:a.xml</value></list></property></bean></beans>6. 配置第三方系统ThirdpartySpace：名称、登录地址、页面地址、打开方式、访问权限、能访问的系统角色 7. 登录过程 o 在A8中点击"空间页签" o A8产生Ticket，并维护在内存中 o A8带着Ticket访问第三方系统的"登录地址"（loginURL）进行握手 第三方系统根据Ticket回调获取A8身份信息，进行单点登录，并注册Ticket和登录用户的映射o A8带着Ticket跳转到第三方系统的"页面地址" （pageURL）o 第三方系统根据Ticket访问A8取得身份信息 8. 说明 o 第三方系统完全依赖和信任A8的身份验证，Ticket由A8发放 o 第三方系统A8和第三方系统使用与A8完全相同的登录名，或者进行二次开发，系统提供该接口 ，自己维护A8登录名与第三方系统用户的映射表。o 如果当前用户已经登录第三方系统，将跳过 ，直接到第4步，使用相同的Ticket 1. 认证ticket/获取身份信息的接口系统提供Servlet：http:/a8:80/seeyon/?ticket=*；A8将通过response header的LoginName返回登录名；2. 如果第三方回调后认为有异常，请在response header增加名称为SSOLogoutError的信息。o 第三方系统退出时，要通知给A8，地址是http:/a8:80/seeyon/?method=logoutNotify&ticket=* o 对于有些系统，根据情况可将 步可以合并 （省略loginURL）<bean id="sinaNewsSpace" class="n.n.partySpace" init-method="init"><property name="id" value="sinaNews"/><property name="name" value="Sina News"/><property name="pluginId" value="news"/><property name="pageURL" value=""/><property name="openType" value="open"/><property name="index" value="4"/></bean>注意事项：集成第三方系统，要以A8系统插件定义<beans default-autowire="byName"><bean id="newsPluginDefintion" class="n.n.PluginDefintion"><property name="id" value="news"/><property name="name" value="新闻插件"/><property name="contextConfigLocation"><list><value>classpath*:a.xml</value></list></property></bean></beans>3.1.2.23.1.2.3 实现方式二：关联系统+扩展栏目无需开发，使用关联系统管理登录信息，集成外部系统页面。1、 配置关联系统以系统管理员system登录A8，使用“关联系统管理”建立一个新的关联系统。关联系统的url为被集成系统的登录链接，将登录需要的信息如用户名和密码定义为关联系统参数。2、 建立扩展栏目由外部系统管理验证信息的栏目有两种：数据集成型栏目(SSOWebContentSection)和功能操作型栏目（SSOIframeSection）。3、 用户登录后，在个人空间中配置关联系统参数，填写集成系统的登录信息（用户名和密码）。由关联系统维护被集成系统的用户名、密码以及Session。4、 说明被集成系统的修改：登录不成功，需要在登录请求的response中增加header项：LoginError=*，否则A8无法判断是否成功登录。3.2 Portlet3.2.1 概述Portlet在A8中的概念是首页空间中的一个区域，它包含多个Tab(栏目)。Portlet的开发也就是对Tab栏目的开发3.2.2 开发说明3.2.2.1 确定栏目数据栏目中的数据由首页应用来确定需要提供的接口：在应用中专为首页提供数据抽取的接口或方法，一般有2个：1. 数据列表抽取，需要做好按量抽取2. 数据总数统计3.2.2.2 确定栏目显示模板现在栏目显示模板提供了以下几种 (不断扩充中)1. MultiRowFourColumnTemplete 重复行、4列l 4列依次是subject、createDate、createMemberName、categoryl 链接：subject、category分别都有链接l 扩展属性：importantLevel、hasAttachments、bodyType、extIcons2. MultiRowThreeColumnTemplete重复行、3列l 3列依次是subject、createDate、categoryl 链接：subject、category分别都有链接l 扩展属性：importantLevel、hasAttachments、bodyType、extIcons3. ChessboardTemplete 棋盘式l 每个项目的属性有：icon、name、linkl setLayout（row,colum） 设置行数跟列数4. HTMLTemplete HTML的输出模式l Model属性:1,直接输出，采用innerHTML方式2,采用内嵌模式l Html属性：html代码3.2.2.3 开发说明包名： n.section命名规范：*Section其它：必须继承BaseSection需要实现的方法1、 getId()栏目的唯一标识，同时也是Spring Bean定义的Id, 在中需要配置该bean; 直接返回一个有字符+数字组成的字符串，如：pendingSection2、 getName()栏目名称的国际化key，需要在资源文件/apps_res/v3xmain/js/i18n下定义3、 getIcon()栏目图标，统一放在 /apps_res/v3xmain/images/section下，如 /apps_res/v3xmain/images/section/.gif4、 getTotal()总数，如果不需要显示总数，就返回null5、 projection()在这里取得数据，并在显示模板中填充数据底部链接：1、 接口ttomButton(label, link);2、 通用按钮labela) 更多 M_BUTTON_LABEL_MORE3.2.2.4 注册到系统找到，配置spring：<!- 首页栏目1、属性：spaceTypes: 所属空间类型personal, / 个人空间department, / 部门空间corporation, / 单位空间group, / 集团空间custom, / 自定义空间不设置表示不限制2、初始化方法必须是init，否则不可用-><bean id="pendingSection"class="n.ngSection" init-method="init"><property name="orgManager" ref="OrgManager" /><property name="spaceTypes"><list><value>personal</value></list></property></bean>Ø 注意事项：bean的id必须和java类中getId()返回的值相同执行sql脚本把portlet（Tab）添加到系统：例如：INSERT INTO v3x_portlet_entity_property VALUES(15, 30, 'sections', 'relateMemberSection,projectSection,newLinkSystemSection');在其后增加你的sectionid，用逗号分隔3.2.3 代码示例以待办事项为例：例如：public class PendingSection extends BaseSection private static final Log log = g();private AffairManager affairManager;private OrgManager orgManager;public void