简介本资源是一份面向ERP与OA系统集成工程师、企业信息化实施顾问及中高级开发人员的Tiptop与Easyflow单据电子签核集成技术指南聚焦解决Tiptop作业审核结果需同步至OA并回写状态的核心业务痛点。文档以PDF格式呈现共1个文件1.94MB完整覆盖集成原理、12步实操流程、AWS模块架构解析含公共服务与抛转作业双类4GL程序说明、环境配置要点如.profile参数设置、字段映射逻辑单头/单身栏位JOIN机制、Columnset.xml协同维护建议及常见错误排查提示。内容预览显示其结构清晰含集成示意图、目录导航与分模块详解特别适合正在落地TiptopEasyflow电子签核项目的技术人员快速掌握双向数据交互实现路径。目前已有1517人学习下载可直接用于项目实施参考、代码改造指导与跨系统集成方案设计。1. Tiptop × Easyflow 集成不是“配个URL就能跑”一个被低估的双向签核黑匣子你是不是也试过在 Tiptop 里点下“审核”界面卡住两秒弹出“调用失败”——但日志里没报错、Appserver 进程活着、Easyflow 的收件箱空空如也或者更玄学的是单据成功抛过去了签核人点了“核准”Tiptop 却始终停在S送签中状态数据库里ta_ogaefstat死活不变成1这不是网络抖动也不是权限漏设而是掉进了 Tiptop-Easyflow 集成最典型的「双向断连陷阱」XML 发得出去SOAP 回不来表单渲染正常状态写不回库。这套集成根本不是单向导出而是一套由12 个强依赖步骤、7 个必填数据库字段、3 类 XML 栏位映射逻辑、2 套独立配置文件EF2Kweb.xml ColumnSet.xml和 1 个隐藏校验机制xxxuser所有者字段共同咬合的精密齿轮组。少拧紧一颗螺丝整条签核流水线就静默瘫痪。它适合谁不是只想“接个OA”的业务人员而是真正要落地电子签核闭环的 Tiptop 二次开发工程师、系统集成顾问以及正在接手遗留系统维护的运维同学——尤其当你面对的是已上线 5 年以上的老版本 Tiptop比如 v8.0~v9.3且 Easyflow 是 EF2K Web 2015 版本时这份文档里的每一个路径、每一行.profile变量、每一段aws_efcli()调用参数都是血泪经验凝结的后悔药。别信“自动生成功能”那只是起点真正的集成从你手动改完第 7 行g_strXMLInput拼接逻辑开始。2. Tiptop 端环境与数据层准备先让 Appserver “听见” EasyflowTiptop 和 Easyflow 的通信不是走 HTTP 直连而是通过 Tiptop for Browser 架构下的 Appserver 作为中间代理发起 SOAP 调用。这意味着Appserver 必须在线、.profile必须生效、数据库字段必须就位——三者缺一不可。任何一步跳过后续所有代码编译都只是自我安慰。2.1 启动 Appserver 并验证服务可达性Tiptop for Browser 的 Appserver 是整个集成链路的“咽喉”。它不启动aws_efcli.4gl中的CALL aws_efsrv()就永远卡在连接超时。注意startweb命令必须在 Tiptop 安装用户的 shell 下执行且需确认其监听端口默认 8080未被占用。# 切换到 Tiptop 安装用户如 tiptop su - tiptop # 启动 Appserver路径依实际安装位置调整常见于 $TIPTOP_HOME/bin $TIPTOP_HOME/bin/startweb # 验证进程是否存活关键看 java 进程是否含 AppServer 字样 ps -ef | grep AppServer | grep -v grep # 验证端口监听假设监听 8080 netstat -tuln | grep :8080提示如果startweb报错Cannot bind to port 8080不要直接改端口。先检查$TIPTOP_HOME/config/appserver.conf中http.port设置并确认是否有其他 Java 应用如 Tomcat占用了该端口。强行修改端口可能导致 Tiptop Web 界面无法加载这是新手最常翻车的第一步。2.2 配置.profile三个环境变量决定 SOAP 调用生死.profile是 Tiptop 运行时读取全局配置的唯一入口。Easyflow 的 IP、服务名、WSDL 地址必须在这里明确定义且必须 export。任何拼写错误、多余空格、IP 地址写错一位都会导致aws_efsrv.4gl内部的soap_call()返回空字符串或SOAP_ERROR。# 编辑 .profile路径通常为 /home/tiptop/.profile 或 $TIPTOP_HOME/.profile vi /home/tiptop/.profile # 在文件末尾追加以下三行⚠️ 注意等号前后无空格分号结尾引号内地址需与 Easyflow 实际部署一致 # EasyFlow Server IP务必是 Easyflow 服务器能被 Tiptop 主机 ping 通的 IP EFSITEIP192.168.0.250; export EFSITEIP # EasyFlow Server Name必须与 EF2Kweb.xml 中 serverName 标签值完全一致 EFSITENAMEEF2KWeb; export EFSITENAME # EasyFlow SOAP Location必须是 WSDL 文件的完整 URL且确保该 URL 在浏览器中可直接访问 EFSOAPhttp://192.168.0.250/EF2KGateWay/EF2KGateWay.WSDL; export EFSOAP逻辑说明aws_efsrv.4gl会读取这三个变量构造 SOAP 请求头和 endpoint。EFSITEIP用于建立 TCP 连接EFSITENAME用于在 SOAP Header 中标识调用来源Easyflow 用它路由到对应租户EFSOAP是 WSDL 地址Appserver 会据此生成 SOAP Envelope 的 namespace 和 operation。参数说明EFSOAPURL 中的/EF2KGateWay/是 EF2K Gateway 的上下文路径不可省略若 Easyflow 启用了 HTTPS则此处必须为https://...否则调用必然失败。2.3 数据库字段校验7 个栏位是签核状态流转的“宪法”Tiptop 的签核状态pmk25、是否启用签核pmkmksg等字段是整个流程的“状态寄存器”。它们不存在于数据字典视图里而是硬编码在aws_efstat.4gl的 SQL 查询逻辑中。如果某张单据表如oga_file缺失这些字段aws_xxx.4gl在UPDATE时会直接报SQL error -206: Column (xxx) not found。-- 以销售单头表 oga_file 为例检查必需字段是否存在 SELECT colname, coltype, collength FROM syscolumns WHERE tabid (SELECT tabid FROM systables WHERE tabname oga_file) AND colname IN (ta_ogaefstat, ogaconf, ta_ogamksg, ogadays, ogaprit, ogasseq, ogasmax);常见做法是对缺失字段使用ALTER TABLE添加。但必须严格遵守 Tiptop 客制规范——字段类型必须匹配如ta_ogaefstat为CHAR(1)ogaconf为CHAR(1)且不能添加到系统保留字段区间通常colno 100。我一般会先在测试库执行INSERT INTO syscolumns ...手动插入元数据再ALTER TABLE避免触发 Tiptop 的 schema 校验拦截。2.4 Schema 更新让 r.s2 dsx 认出新字段即使数据库表里加了字段Tiptop 的 4GL 编译器仍不认识它们因为r.s2schema 文件是 4GL 编译时的“数据字典快照”。不更新它LET g_oga.ta_ogaefstat S这行代码在编译阶段就会报错Unknown field name。# 进入 Tiptop 开发环境如 4GL Studio 或命令行 # 执行 schema 更新命令路径依版本而异常见于 $TIPTOP_HOME/bin $TIPTOP_HOME/bin/r.s2 dsx # 或在 4GL Studio 中Tools → Update Schema → Select oga_file → OK参数说明r.s2 dsx命令会扫描systables和syscolumns重新生成$TIPTOP_HOME/lib/dsx目录下的二进制 schema 文件。执行后务必重启 Appserver否则新字段在运行时仍不可见。这是很多开发者忽略的“重启玄学”——编译通过了但运行时报字段未定义根源就在这里。3. AWS 模块配置与抛转作业生成从点击按钮到手撕 XML 拼接AWSApplication Workflow Service模块是 Tiptop 端的集成中枢。它分为公共函数库aws_ef*.4gl和单据专用抛转程序aws_asfi301.4gl。自动生成的aws_xxx.4gl只是骨架真正决定 XML 能否被 Easyflow 正确解析的是其中g_strXMLInput字符串的每一行拼接逻辑。3.1 使用 aws_efcfg 维护单据签核元数据aws_efcfg.4gl是图形化配置入口但它只管“元数据”不管“数据逻辑”。这里设置的单据代号、单据名称、签核等级会写入aws_cfg表供aws_efcli.4gl查询。但最关键的单头/单身栏位映射才是 XML 结构的蓝图。# 在 Tiptop 界面中执行 # Menu → AWS → aws_efcfg → 输入单据代号如 asfi301→ Enter操作要点在“单头栏位”页签中左侧字段列必须填写数据库物理字段名如oga01右侧参照字段填写 JOIN 表的字段如occ02。这会生成 SQL 中的JOIN occ_file ON oga_file.oga04 occ_file.oga04。但注意参照字段的表名必须存在于aws_efcfg的预设表列表中否则生成的 SQL 会报Table not found。我一般会先在aws_efcfg的“系统设定”里确认occ_file是否已注册。3.2 生成并修改 aws_xxx.4gl为什么“自动生成”只是开始点击aws_efcfg的“产生范式程序”后aws/4gl/aws_asfi301.4gl会被创建。但它的 XML 拼接部分g_strXMLInput ...是按aws_efcfg中的字段列表机械生成的完全不处理业务逻辑转换。比如客户编码oga04要显示为客户名称occ02自动生成的代码只会写oga04123/oga04而你需要手动改成oga04ABC公司/oga04。# 修改前自动生成仅取数据库原值 LET g_strXMLInput g_strXMLInput CLIPPED, oga04, sr.oga04 CLIPPED, /oga04, ASCII 10, # 修改后手动加入 JOIN 逻辑取客户名称 # 在文件开头声明变量 DEFINE l_occ02 CHAR(50) # 在 SQL 查询后、XML 拼接前加入 JOIN 查询 LET l_sql SELECT oga_file.*, occ_file.occ02 FROM oga_file JOIN occ_file ON oga_file.oga04 occ_file.oga04 WHERE oga_file.oga01 ? PREPARE stmt FROM l_sql DECLARE cur CURSOR FOR stmt OPEN cur USING sr.oga01 FETCH cur INTO sr, l_occ02 CLOSE cur # 在 XML 拼接处使用转换后的值 LET g_strXMLInput g_strXMLInput CLIPPED, oga04, l_occ02 CLIPPED, /oga04, ASCII 10,逻辑说明aws_xxx.4gl的核心是aws_efcli_cf()函数它返回一个 XML 字符串。g_strXMLInput的拼接顺序必须与 Easyflow 的ColumnSet.xml中column标签顺序严格一致虽然文档说“顺序无关”但实测 EF2K Web 2015 版本对顺序敏感。参数说明CLIPPED是 4GL 关键字用于去除字符串末尾空格ASCII 10是换行符提升 XML 可读性非必需但强烈建议保留。3.3 标准作业改造把“审核”按钮变成“送签”开关标准作业如axmt620的改造是集成成败的关键。它不是简单加个函数而是要重写审核流程的控制流。原有confirm()函数的事务逻辑UPDATE,COMMIT必须被“劫持”在签核启用时跳过只做状态标记。# 在 axmt620.4gl 中找到原有 confirm() 函数 FUNCTION confirm() # ... 原有业务校验逻辑如库存检查、金额校验... # 【关键插入点】在所有校验通过后、任何 UPDATE 之前插入 IF g_oga.ta_ogamksg Y AND g_oga.ogaconf N THEN CALL t600_ef() # 调用 AWS 抛转函数 IF g_success Y THEN RETURN # 成功则直接退出不执行后续 UPDATE ELSE ROLLBACK WORK EXIT PROGRAM # 失败则回滚并终止 END IF END IF # 【原有事务逻辑现在只在非签核模式下执行】 UPDATE oga_file SET ... WHERE oga01 g_oga.oga01 COMMIT WORK END FUNCTION常见做法是将原有confirm()中的UPDATE和COMMIT块剪切出来封装成新函数confirm_no_ef()然后在IF分支中调用它。这样既保证逻辑清晰又避免因RETURN导致资源未释放。我每次都会在CALL t600_ef()后加一行日志CALL cl_log(EF_SEND, asfi301: || sr.oga01 || status: || g_success)方便排查是卡在发送还是 Easyflow 侧。4. Easyflow 端部署与配置XML 解析器的“刻度尺”必须对齐Easyflow 不是被动接收 XML而是用ColumnSet.xml作为“刻度尺”去解析g_strXMLInput。如果 XML 中的tag名称、层级、甚至大小写与ColumnSet.xml中定义的column name...不完全一致Easyflow 会静默丢弃该字段表单上显示为空白。这不是 Bug是设计使然。4.1 Forms 目录结构与文件重命名路径即契约Easyflow 的表单文件存放在Program Files\EF2Kweb\ASP\CHT\Forms\下目录名、文件名、ASP 内部字符串三者必须完全统一。复制TT_SO1改为TT_AO1时漏改一个文件名整个表单就无法加载。# 正确的 TT_AO1 目录结构共 7 个文件全部含 TT_AO1 TT_AO1/ ├── TT_AO1_Approve_Init.ASP # 审批初始化 ├── TT_AO1_Create_Init.ASP # 新建初始化 ├── TT_AO1_Display_Init.ASP # 查看初始化 ├── TT_AO1_Grid.ASP # 单身表格 ├── TT_AO1_Forms.ASP # 主表单 HTML ├── TT_AO1_Print.ASP # 打印模板 └── TT_AO1_Report.ASP # 报表模板操作要点使用批量替换工具如 Notepad 的“在文件中替换”搜索整个TT_AO1/目录将所有TT_SO1替换为TT_AO1。特别注意TT_AO1_Forms.ASP中的 JavaScript 变量如var formID TT_SO1;和TT_AO1_Grid.ASP中的iframe src属性。漏掉任何一个表单加载时控制台会报ReferenceError。4.2 ColumnSet.xml 配置XML 字段名的“宪法性”定义ColumnSet.xml是 Easyflow 的 XML 解析引擎。它定义了每个column的name必须与 Tiptop XML 中的 tag 名完全一致、type影响数据绑定、length影响输入框宽度。name区分大小写且不能有下划线以外的特殊字符。!-- EF2KwebPackages\tiptop\ColumnSet.xml -- columnSet program idTT_AO1 column nameoga01 typestring length10 / column nameoga02 typestring length30 / column nameoga04 typestring length20 / !-- 必须与 Tiptop XML 中 oga04 标签名完全一致 -- column nameocc02 typestring length50 / !-- 若 Tiptop 传的是客户名称此处 name 必须是 occ02 -- column nameogauser typestring length20 requiredtrue / !-- ⚠️ 必须存在且 required -- /program /columnSet逻辑说明column nameogauser是强制要求。Easyflow 用它识别“填单人”从而决定审批流程的起始节点。如果 Tiptop XML 中没有ogauseradmin/ogauserEasyflow 会认为该单据无主直接丢弃。参数说明requiredtrue表示该字段为必填缺失会导致整个 XML 解析失败typestring对应 4GL 的CHAR若 Tiptop 传的是数字此处必须为typenumber否则 Easyflow 会尝试parseInt导致 NaN。4.3 EF2Kweb.xml 配置让 Easyflow “认识”新表单EF2Kweb.xml是 Easyflow 的“路由表”它告诉系统TT_AO1这个 ID 对应哪个物理目录、使用哪个数据库表、属于哪个模块。!-- EF2KwebPackages\tiptop\EF2Kweb.xml -- application form idTT_AO1 name工单作业 pathForms\TT_AO1\ tableTT_AO1 moduletiptop serverNameEF2KWeb / /application常见做法是复制一个已存在的form节点仅修改id、name、path、table四个属性。path必须以反斜杠结尾table必须与 SQL Server 中新建的数据表名完全一致如TT_AO1。我一般会在table属性后加注释!-- Created on 2023-10-01 --方便日后追溯。5. 集成测试与避坑指南那些让你凌晨三点还在查日志的“经典翻车现场”集成测试不是点开一个单据点“审核”就完事。它是一套包含前置检查、过程追踪、结果验证、异常注入的完整闭环。下面列出我在某高校实验室部署 Tiptop v9.2 Easyflow EF2K Web 2018 时踩过的 5 个真实坑每一个都曾让我对着日志抓狂超过 2 小时。5.1 现象Tiptop 点“审核”无反应Appserver 日志显示SOAP call timeout原因.profile中EFSOAPURL 的域名解析失败。Tiptop 主机/etc/hosts里没有 Easyflow 服务器的 IP 映射而 DNS 服务器又无法解析EF2KWeb这个主机名。解决在 Tiptop 主机的/etc/hosts中添加192.168.0.250 EF2KWeb并执行ping EF2KWeb确认连通。不要依赖 DNS生产环境必须走 hosts 映射。5.2 现象单据成功抛到 Easyflow表单能打开但所有字段都是空白原因ColumnSet.xml中column name...的值与 Tiptop XML 中的 tag 名不一致。例如 Tiptop 传oga04123/oga04但ColumnSet.xml写的是column nameoga004多了一个 0。解决用curl抓取 Tiptop 发出的原始 XML需在aws_efsrv.4gl中加CALL cl_log(RAW_XML, g_strXMLInput)再与ColumnSet.xml逐行比对。大小写、下划线、数字位数一个都不能错。5.3 现象Easyflow 签核完成后Tiptop 数据库ta_ogaefstat仍是S未更新为1原因aws_efstat.4gl中的回调 SQL 语句写错了表名或字段名。该文件会调用UPDATE oga_file SET ta_ogaefstat ? WHERE oga01 ?但如果oga_file表名在当前数据库中是oga_mst语句就失效。解决打开aws_efstat.4gl找到UPDATE语句确认表名与当前环境一致。不要硬编码表名应从aws_cfg表中动态读取但文档未提供此功能所以必须手动改。5.4 现象Easyflow 表单中单身表格Grid显示“无数据”但单头数据正常原因TT_AO1_Grid.ASP中的sqlStr变量拼接错误。该文件通过Request.QueryString(key)获取单头编号再拼 SQL 查询单身表。如果key参数名在TT_AO1_Display_Init.ASP中被写成docNo而Grid.ASP里还用Request.QueryString(key)就查不到数据。解决统一key参数名。在TT_AO1_Display_Init.ASP中确认Response.Redirect(TT_AO1_Grid.ASP?key docNo)然后在TT_AO1_Grid.ASP中用Request.QueryString(key)读取。5.5 现象签核人点击“核准”后Easyflow 页面报错Object reference not set to an instance of an object原因EF2Kweb.xml中form节点的serverName属性值如EF2KWeb与.profile中的EFSITENAME不一致。Easyflow 用它匹配租户配置不一致则找不到对应的 Tiptop 回调服务。解决严格统一。.profile中EFSITENAMEEF2KWebEF2Kweb.xml中form serverNameEF2KWebEF2KwebPackages\tiptop\EF2Kweb.xml中serverNameEF2KWeb/serverName—— 三处必须一字不差。6. 验证集成是否真正跑通用三类测试覆盖全链路装完不等于跑通。真正的验证是用三套不同维度的测试把从 Tiptop 点击“审核”到 Easyflow 签核完成、再到 Tiptop 状态回写这条链路上的每一个环节都“点亮”。我从不信任单一测试结果因为集成是分布式系统任何一个环节的微小偏差都会导致最终状态不一致。6.1 基础连通性测试确认“管道”畅通无阻这是最底层的验证绕过所有业务逻辑直击通信本质。目标是证明 Tiptop Appserver 能成功调用 Easyflow 的 SOAP 接口并收到有效响应。# 在 Tiptop 主机上用 curl 模拟 SOAP 调用需先获取 WSDL 中的 operation 名 curl -X POST \ -H Content-Type: text/xml; charsetutf-8 \ -H SOAPAction: \http://tempuri.org/GetStatus\ \ -d test_soap_request.xml \ http://192.168.0.250/EF2KGateWay/EF2KGateWay.asmxtest_soap_request.xml内容需包含标准 SOAP Envelope其中GetStatus的参数应为一个已知存在的单据号如TT_AO1-2023-001。如果返回GetStatusResulttrue/GetStatusResult说明管道畅通如果返回500 Internal Server Error则问题在 Easyflow 侧的 IIS 或 .NET 配置。这一步必须成功否则后续所有测试都是空中楼阁。6.2 单据级端到端测试用真实业务场景“压测”全流程这是最接近用户操作的验证。我习惯用一张最小化的测试单据如工单TT_AO1-TEST-001全程录像操作并在关键节点截图留证。步骤操作预期结果验证方式1Tiptop 新建单据选择“需签核”单别保存单据状态为0开立查oga_file表oga01TT_AO1-TEST-001的ta_ogaefstat值2点击“审核”按钮弹出“发送成功”提示ta_ogaefstat变为S再次查表确认值已更新3登录 Easyflow查看 439 用户收件箱出现TT_AO1-TEST-001表单所有字段有值截图表单内容与 Tiptop 原始数据比对4签核人点击“核准”Easyflow 页面提示“提交成功”表单消失查 Easyflow 数据库TT_AO1表确认status字段为15返回 Tiptop刷新单据ta_ogaefstat变为1界面上显示“核准”图标再次查表 界面截图关键技巧在步骤 2 后立即登录 Easyflow 服务器用 SQL Server Management Studio 查TT_AO1表确认记录已插入。如果表里没数据说明 XML 抛转失败问题在 Tiptop 侧如果表里有数据但字段为空问题在ColumnSet.xml映射。6.3 状态一致性校验用 SQL 脚本做“最终审判”人工测试可能遗漏边界情况。我写了一个每日自动运行的校验脚本扫描所有签核单据表对比 Tiptop 和 Easyflow 的状态字段生成差异报告。-- Tiptop 侧查询所有状态为 S 或 1 的签核单据 SELECT oga_file AS table_name, oga01 AS doc_no, ta_ogaefstat AS tiptop_status FROM oga_file WHERE ta_ogaefstat IN (S,1) AND ta_ogamksg Y UNION ALL -- Easyflow 侧通过链接服务器查询假设已配置 SQL Server 链接服务器 TIPTOP_LINK SELECT TT_AO1 AS table_name, doc_no, status AS ef_status FROM OPENQUERY(TIPTOP_LINK, SELECT doc_no, status FROM TT_AO1 WHERE status IN (S,1))运行结果中如果同一doc_no在两行中tiptop_status和ef_status不一致就标红告警。这个脚本帮我揪出了一个隐藏 Bug当 Easyflow 签核人网络中断时状态回写失败但 Tiptop 未收到错误导致状态长期不一致。从那以后我每次上线新集成都强制走一遍这个脚本并把结果邮件发送给运维负责人。希望帮到你。本文还有配套的精品资源点击获取
