Tiptop与OA接口集成：从单据签核到Easyflow流程的完整链路

简介：一份面向 Tiptop 实施顾问与 ERP/OA 集成开发人员的 PDF 技术文档，聚焦 Tiptop 与 Easyflow 的单据签核集成场景。文档从环境准备、数据表检查、Schema 更新、单据性质设置、抛转信息维护到 4GL/PER 修改、AWS 链接配置，梳理了 12 个关键集成步骤；同时详解 AWS 公共模块与抛转模块的职责，并给出集成测试及常见错误列表，可作为新单据接入 Easyflow 签核流程的实操参考。资源为单个 PDF 文件，大小约 1.94MB，内容包含 XML 数据交互、SOAP 服务回写、栏位映射等关键说明，已有 1515 人学习使用。对于需要完成类似单据签核对接的读者，可从中获取环境配置方法、抛转作业源文件修改思路和 AWS 模块调用要点，减少集成试错成本。

1. Tiptop 与 OA 接口：单据签核不是开一个开关就完事

在某制造业 ERP 项目上线冲刺阶段，操作员在生产订单作业点了“审核”，订单状态纹丝不动，OA 端收件箱也始终是空的。实施顾问查了一下午，最后发现是数据表少了签核状态字段，连“送签中”的 S 状态都写不进去。这个小场景基本代表了 Tiptop 与 OA 接口的真实形态：它不是 ERP 里开一个“是否签核”开关就结束的配置项，而是一条从 Tiptop 数据表、抛转作业、XML 生成，到 Easyflow 表单、存储、流程、回写状态的完整链路。下面这份集成文档拆自 Tiptop 与 Easyflow 的新单据集成体例，适合正在做 ERP 单据电子签核、二次开发或实施交付的人。按这条链路走，新单据接入的每一步都有据可查。

2. Tiptop 端改动：签核栏位、AWS 抛转模块与 XML 生成的三层准备

2.1 环境配置文件 .profile：三个变量决定通信地址

做 ERP 接口的人都有体会：业务不顺的时候，先查环境。Tiptop 和 Easyflow 的交互走的是 Appserver，Tiptop for Browser 版装好之后，必须确认 startweb 已经把 Appserver 拉起来。这一步不满足，后面做的抛转作业、表单关联都不会触发。

确认 Appserver 存活后，改 Tiptop 账号根目录下的 .profile。里面有一组 Easyflow 相关的环境变量，核心是三个，缺一不可：EFSITEIP、EFSITENAME、EFSOAP。我一般会先在浏览器里打开 EFSOAP 地址，能出现 WSDL 描述页再往下走，这一步能排除一半的“抛转无响应”玄学问题。

#EasyFlow Server IP EFSITEIP=192.168.0.250; export EFSITEIP #EasyFlow Server Name EFSITENAME=EF2KWeb; export EFSITENAME #EasyFlow SOAP Location EFSOAP=http://192.168.0.250/EF2KGateWay/EF2KGateWay.WSDL; export EFSOAP

三个变量分别指向 Easyflow 服务器的 IP、站点名和 SOAP 网关地址，具体值要跟实际服务器配置一致。IP 是内网地址，WSDL 路径不能写错大小写。另一个容易漏的点是 Easyflow 服务器上必须安装过 Tiptop&Easyflow 集成包，这个包没装，Tiptop 调服务时连网关都找不到，日志里只会报连接失败。环境准备完成后再进数据库层，顺序不要乱。

2.2 数据库七个栏位：没有这七个字段，后面全是坑

接下来检查作业对应的数据表，确认签核相关栏位是否齐全。这里不要凭记忆，直接用数据库工具看表结构。以请购单单头档 pmk_file 为例，需要的是七个：

这里有个很实际的坑：前两个栏位每支作业都必须维护，后四个非关键栏位在简单签核场景下可能用不到，但表里仍要有。缺了任何一个，aws 抛转作业组 SQL 时就会报错。单身档通常不含签核字段，别去单身表里找这七个。创建缺失字段时按客制规范来写，命名不要乱编。

签核状态取值也要记牢：0 开立，1 已核准，6 结案，9 作废，S 送签中，R 送签退回，W 抽单。如果出现其他字符，一般是作业内部特殊选项，比如 2 表示转采购单。判断一张单据走到哪一步，看的就是这个字段的值。

2.3 aws_efcfg 维护：单头、单身与参照字段的选择逻辑

Tiptop 里有一个专门做集成的 aws 模块，目录结构与普通模块一样。4gl 目录下的程序分两类：一类是公共模块，以函数形式封装了与 Easyflow 集成所需的底层操作和服务，包括 aws_efcfg、aws_efsrv、aws_efcli、aws_efstat、aws_xml、aws_efgw 等；另一类是抛转模块，与各支作业一一对应，比如 aws_aapt110.4gl 对应 aapt110 请购作业，aws_asfi301.4gl 对应 asfi301 工单作业，数量跟需要签核的单据数一致。做新单据集成时，先确认是否存在对应的 aws_xxx.4gl，不存在就等 aws_efcfg 生成。

aws_efcfg 是这个环节的入口，它是一个维护窗体。操作顺序是：先在界面上维护单据基本信息，然后点按钮维护单头和单身栏位。单头界面左边输入要通过 XML 传递的单头表字段，右边参照字段用来做 JOIN 替换。举例：客户信息通常要传客户名称 occ02，而不是客户编码 oga04。做法是左边填 oga04，参照字段填 occ02，生成抛转程序时自动 JOIN occ_file，组 XML 时用 occ02 的值替代 oga04 的位置。单身栏位的维护逻辑相同，界面操作方式也一样。

维护完成后，点“产生范式程序”，aws/4gl 目录下会自动生成一支 aws_xxx.4gl，预生成好框架代码，在此基础改，而不是从零写。界面上的“传送栏位资讯”按钮能把单头单身栏位自动生成 Easyflow 端的 Columnset.xml 文件，但实际项目里我不建议用：它会完全按 Tiptop 数据库设置重建文件，而文件与实际数据表很难保证完全一致，容易把原有表单配置覆盖坏，Columnset.xml 宁可手工维护。这个小节很多人会踩，先记住结论。

2.4 抛转作业 aws_xxx.4gl：sr、SQL、XML 的对应与改写

自动生成的 aws_xxx.4gl 描述了一个函数 aws_efcli_cf()，各模块结构一致：先声明一个 RECORD sr 存中间信息，再组一条 SQL 取出抛转资料并赋值到 sr，然后循环按 sr 记录拼 XML 字符串。默认情况下 sr、SQL、XML 三者保持一致，但实际项目经常要改，典型场景有两类：一是字段需要加工后才能传，原 SQL 取出的值不能直接放进 XML，先定义中间变量转换，再把中间变量写进 XML；二是字段数量有差异，某个栏位不需要传给 Easyflow，或数据库取不到某个栏位，这时 sr 与 XML 的对应关系就要拆开。

下面这段是抛转作业里常见的加工逻辑：客户状态码要转成文字提示，地址栏位要把三行拼成一段。

CASE WHEN sr.oga00 = '1' THEN CALL cl_getmsg('aws-003', g_lang) RETURNING g_msg WHEN sr.oga00 = '2' THEN CALL cl_getmsg('aws-004', g_lang) RETURNING g_msg WHEN sr.oga00 = '3' THEN CALL cl_getmsg('aws-005', g_lang) RETURNING g_msg END CASE LET l_oga00 = g_msg CALL s_addr(sr.oga01, sr.oga04, sr.oga044) RETURNING l_oap.oap041, l_oap.oap042, l_oap.oap043 LET sr.addr = l_oap.oap041 CLIPPED, ' ', l_oap.oap042 CLIPPED, ' ', l_oap.oap043 CLIPPED

l_oga00 是中间变量，cl_getmsg 按代码取多语言消息；s_addr 把地址栏位拼成一段文本然后回填 sr.addr。这种改动在 XML 组装段能看到对应位置。

LET g_strXMLInput = g_strXMLInput CLIPPED, " <oga00>", l_oga00 CLIPPED, "</oga00>", ASCII 10, " <oaydesc>", sr.oaydesc CLIPPED, "</oaydesc>", ASCII 10, " <oga04>", sr.occ02 CLIPPED, "</oga04>", ASCII 10, " <oga08>", l_oga08 CLIPPED, "</oga08>", ASCII 10, " <oga24>", l_oga24 CLIPPED, "</oga24>", ASCII 10, " <addr>", sr.addr CLIPPED, "</addr>", ASCII 10, " </head>", ASCII 10

CLIPPED 去掉首尾空格，ASCII 10 输出换行，保证 XML 有可读结构。这里能看到前面为什么要用中间变量：l_oga00 是转换后的文字，sr.occ02 是参照字段替换后的客户名称，sr.addr 是拼好的完整地址。改完这段要对照 Easyflow 端 ColumnSet.xml 的字段名逐一检查，名字对不上，回写必然失败。记住一个原则：XML 栏位顺序可以与 Tiptop 抛转的字符串不完全相同，但名称必须完全对应。

2.5 标准作业 4GL 与 PER 档：加函数、拦审核、补图标

抛转作业只是服务端，标准作业也要改，否则审核按钮不会触发抛转。以 axmt620 出货单作业为例，需要增加一个 xxx_ef() 函数，核心代码可以直接从同类签核作业（比如请购单 apmt420）拷贝同名函数，再按单据修改参数。下面是函数核心部分：

IF aws_efcli(l_title, g_oga.oga01[1,3], g_oga.oga01, '', '', '', '', '') THEN LET g_success = 'Y' LET g_oga.ta_ogaefstat = 'S' LET g_oga.ogaconf = 'Y' CALL cl_set_field_pic(g_oga.ogaconf, g_chr2, g_oga.ogapost, g_chr3, g_chr, "") DISPLAY BY NAME g_oga.ta_ogaefstat, g_oga.ogaconf CALL cs_ogasta('oga', g_oga.ta_ogaefstat, g_oga.ogaconf, g_oga.ta_ogamksg) RETURNING g_sta DISPLAY g_sta TO FORMONLY.desc2 UPDATE oga_file SET ta_ogaefstat = g_oga.ta_ogaefstat, ogaconf = g_oga.ogaconf WHERE oga01 = g_oga.oga01 COMMIT WORK ELSE LET g_success = 'N' END IF

aws_efcli 是公共模块中负责实际发送和接收的调用，传界面单据信息；成功就把 g_success 置 Y，签核状态设成 S 送签中，审核状态设成 Y 已审核。cl_set_field_pic 根据状态设置界面图标，一个“确”一个“核”；cs_ogasta 生成中文状态提示，S 返回“送签中”。只有抛转成功的分支才更新数据表并提交。

然后改原有审核函数，在最关键的位置插拦截逻辑：在完成所有判断但未开始事务性更新之前。

IF g_success = 'Y' THEN IF g_oga.ta_ogamksg = 'Y' AND g_oga.ogaconf = 'N' THEN CALL t600_ef() IF g_success = 'N' THEN ROLLBACK WORK END IF RETURN END IF END IF

这里判断单据需要签核且审核状态未确认时，调用新函数把单据送签，然后 RETURN，不再执行原审核代码。这是会明显改变用户操作流程的改动：原审核代码被绕过。最稳的做法是把原审核代码复制一份放到新 Action（比如 confirm_ef）里，供签核完成后的确认操作使用，而不是直接删掉。送签退回的单据要再走一次确认，靠的就是这个动作。

配套改动还包括：PER 档增加签核状态栏位显示；有客制栏位时运行 p_perlang 维护显示；p_link 增加对 aws 的链接，新增作业还要维护 p_zz；p_ze 维护新增提示信息；取消审核、作废和相关事务性操作都要增加签核状态判断，需要签核且未核准的单据不允许作废。改作业时最省力的路径是仿照 apmt420 请购单作业，它是一支标准的签核作业，函数、Action、图标显示都能直接参照。

3. Easyflow 端落地：表单目录、ColumnSet 与流程关联的四个关键环节

3.1 复制表单目录与批量改名：TT_SO1 到 TT_WO1 的套路

Tiptop 端准备完，进入 Easyflow 端。Easyflow 的表单信息放在安装目录下的 ASP\CHT\Forms。新单据表单不要从零建，找一个已有的 Tiptop 单据目录整份复制。比如把 TT_SO1 复制成 TT_WO1，然后进入新目录，把所有文件名里的 TT_SO1 替换成 TT_WO1。

实际操作按三步走：一是打开 3 个 Init 结尾的 ASP 文件（TT_WO1_Approve_Init.ASP、TT_WO1_Create_Init.ASP、TT_WO1_Display_Init.ASP）和 Grid.ASP；二是做全局替换，把字符串“TT_SO1”替换为“TT_WO1”；三是核对表单文件名与单据代号是否完全一致，大小写也不能含糊。常见做法是先用系统复制命令整目录复制，再用文本编辑器做批量替换。注意不要漏掉 Grid.ASP，单身表格靠它渲染，漏了会出现表单打开后单身区域空白或直接报错。

3.2 Forms.ASP 控件布局：id 命名的两条规则不能乱

表单外观在 Forms.ASP 里维护。建议使用可视化网页编辑工具操作，但真正的关键不是美观，是控件 ID。一组标签、一组控件，两条命名规则必须遵守：标签的 ID 命名规则是栏位名加 _1，例如 sfb01_1；控件的 ID 命名规则是栏位名加 _2，例如 sfb01_2。Easyflow 解析 XML 时按栏位名自动匹配，把数据填充到对应 _2 控件里。

这两组 ID 千万不能弄反。弄反了，标签控件拿到值、输入控件拿到空值，表单在收件箱里打开就是一片空白。一般控件用多行文本框，日期用选择框，其他统一文本框。单身表格采用 OCX 嵌入方式，不需要单独维护控件 ID，数据表定义对了，TT_WO1_Grid.ASP 会自动按 ColumnSet 渲染。布局调整时尽量与 Tiptop 表单字段顺序接近，签核人打开表单找对应信息会快很多。

3.3 SQL Server 数据表与 ColumnSet.xml：与抛转 XML 完全对应

Easyflow 端数据存在 SQL Server。以原有表单名对应的数据表为基础，复制生成新表，再修改栏位名称。我在项目里的做法是直接用 SQL Server 的导入导出功能复制表结构和少量测试数据，然后按新单据字段重命名，省去手工建表的时间。

接下来改两个文件，都在 EF2Kweb\Packages\tiptop 目录下。第一个是 EF2Kweb.XML，增加新单据 ID，复制一个现有单据项目改；第二个是 ColumnSet.xml，增加 Program 段，里面填写的 XML 内容必须与 Tiptop 抛转作业 aws_xxx.4gl 输出的 XML 字段完全对应。

xxxuser 这条是血泪经验：它不显示在电子表单上，但 Easyflow 需要用它解析填单人并启动流程。漏了这个字段，单据抛转成功但流程起不来，或者收件人永远是错的。ColumnSet.xml 我建议手工维护，不要用 aws_efcfg 里的“传送栏位资讯”按钮自动生成，原因前面说过：自动重建会拿数据库结构覆盖现有文件，改动范围不可控，容易把其他表单一起搞坏。

3.4 表单开放、审批流程与集成向导的最后三步

文件配好后，再回 Easyflow 界面。路径是：电子表单模块 → 管理程序清单 → 流程基本数据 → 表单性质维护操作。查询到新表单后，进入表单性质设置，重点看两项：显示否要设成 N，生效日不要漏设；如果表单永久生效，失效日留空即可。这两项没设对，表单在权限树里根本不会出现。然后滚动到表单最下方，新建权限文件并给相关人员授权，不加权限，表单依旧无法显示。完成保存后，左侧清单里就能看到新增的表单。

接着设置审批流程：电子表单模块 → 管理程序清单 → 自动向导 → 流程设定向导，选择刚建的表单，新增一关审批并设置审批人。审批人设置后，从 Tiptop 抛转过来的单据会进入该审批人的收件箱，该审批人完成后流程结束，回写 Tiptop。

最后建立表单关联：自动向导 → 易拓集成向导 → 新增表单关联。选择 Tiptop 程序代号，系统会自动列出有抛转机制的所有作业代号；再选工厂代号，之后会自动列出该作业下已在单据性质设置中勾选需签核的单据类别；最后选对应的 Easyflow 表单代号，新增关联。到这一步，Tiptop 的单据类别和 Easyflow 表单才在逻辑上对接起来。前面任何一环漏了，审核时都不会有反应。

4. 集成测试与排查：状态回写失败、表单不显示的五个高频坑

4.1 测试路径：从开立到送签中的完整走单

配置完成后的验证路径，建议按顺序走一遍，确认每个状态点。以工单作业 asfi301 为例，新增一张工单，单别选在单据性质设置中已勾选签核的单别，保存后检查：审核状态为 N，签核状态为 0，提示信息“开立”。点审核按钮，提示是否确认，选是。抛转成功后，界面会显示送签状态。

测试状态流转顺序整理下来就是：签核状态 0 开立；点审核后签核状态 S 送签中；审批人在 Easyflow 收件箱看到表单，核准后 Tiptop 签核状态变 1；若流程退签，状态 R 送签退回；单据作废后状态 9。我一般会用两套环境做测试，一套配置干净的测试库，一套跟正式一致的环境，用干净库能避免历史脏数据掩盖问题。抛转成功的信息会给出单据号和 XML 摘要，确认这些信息里没有空字段，再进 Easyflow 查表单。

4.2 五个高频问题：现象、原因、解决

问题一：Easyflow 左侧表单清单里看不到新表单

现象：Tiptop 端审核已提示抛转成功，但 Easyflow 管理界面左侧找不到新单据表单。

原因：最常在表单性质维护时没正确设“显示否”或生效日，也可能是没有新建权限文件并授权。

解决：进入表单性质维护操作，确认“显示否”为 N，生效日设为当天或更早；表单若永久生效，失效日留空。保存后再到表单最下方新建权限文件并勾选授权范围。权限树有时有缓存，退出管理程序重新登录一次再看。

问题二：单据抛转成功但审批人收件箱为空

现象：Tiptop 审核后提示抛转成功，指定的审批人收件箱里没有表单。

原因：多数是 ColumnSet.xml 里漏了 xxxuser 栏位，或者易拓集成向导里表单关联未建立；还有一种情况是表单关联里选了错误的工厂或单别。

解决：先打开 ColumnSet.xml 检查 Program 段是否包含 xxxuser 字段；再到易拓集成向导确认新增关联里 Tiptop 程序代号、工厂代号、单据类别、Easyflow 表单代号四项全部对应。关联错了，Easyflow 接收后分发不到正确填单人。

问题三：Easyflow 签核完成后 Tiptop 状态不更新

现象：审批人在 Easyflow 核准，流程显示已结束，但 Tiptop 作业里签核状态仍是 S。

原因：回写链路断了。常见是 EFSOAP 地址不通或 WSDL 路径错误，也可能是 Tiptop 端 Appserver 未启动；还有情况是 XML 字段名与 ColumnSet.xml 不完全一致，回写时找不到目标栏位。

解决：先在浏览器打开的确认 EFSOAP 地址可达；再确认 .profile 中 EFSITEIP、EFSITENAME、EFSOAP 三个变量与实际环境匹配；最后对比 aws_xxx.4gl 拼出的 XML 字段和 ColumnSet.xml 字段，逐一对齐，不要只看个数，名字差一个字符都会回写失败。

问题四：客户名称显示出客户编码

现象：Easyflow 表单上客户栏位显示的是代码，不是名称。

原因：Tiptop 抛转作业组 XML 时没有按参照字段处理，直接把 oga04 客户编码传过去了。

解决：回到 aws_efcfg，在单头栏位维护里左边填 oga04，参照字段填 occ02，重新生成 aws_xxx.4gl 并编译。如果项目里不想重新生成，也可以直接改抛转作业的 SQL，把客户资料表 JOIN 进来，再用 occ02 替代 oga04 的值。参照字段替换在单据集成里是常用操作，不止客户栏位，供应商、品名、仓库名称都可以这样处理。

问题五：审核后原审核代码不执行

现象：单据走了 Easyflow 签核，但原来审核时该做的业务处理没有执行，比如库存没更新、相关记录没生成。

原因：审核函数里插入拦截代码后，一旦需要签核就直接 RETURN，跳过了原有事务逻辑。

解决：不要把原有审核代码移动到被拦截的位置。正确做法是把原有审核代码复制一份到新 Action（如 confirm_ef），在签核状态为核准 1 时才允许执行；不走签核流程的单据仍走原审核代码。这样两条路径都保留，退回的单据也能重新走确认动作，对程序本身影响最小。

5. 一个实用技巧：把抛转 XML 抓下来，等于拿到了排错的后悔药

前面几条链路走完，最后说一个排错技巧：抛转的 XML 怎么抓。很多集成问题到最后双方扯皮，Tiptop 说发了，Easyflow 说没收到，最后发现是字段名对不上或者多了一个空白字符。所以我在做新单据集成时，习惯先在 aws_efcli_cf() 函数里临时加一段日志代码，把生成的 XML 写到应用服务器的一个文本文件里。

# 临时调试用，上线前删除 CALL cl_write_log('/tmp/aws_send_' || sr.oga01 || '.xml', g_strXMLInput)

把 g_strXMLInput 完整写盘，然后拿文件内容跟 ColumnSet.xml 做一个纯文本对比。字段名、大小写、顺序有没有问题，一眼就能看出来。生产环境不需要保留这段日志，正式上线前删掉，避免日志文件堆积。如果项目用的 Tiptop 版本已经提供 aws_eflog.4gl，也可以直接调用它来写日志，不必自己造轮子。

抓 XML 不是只做一次，单据字段只要有增删，就要重新抓一次对比。我的习惯是，每次改完 aws_xxx.4gl，编译后先跑一笔测试单，把 XML 落盘，再跟 ColumnSet.xml 逐字段核对，核对完才交给 Easyflow 顾问联调。从第一次做 Tiptop 与 OA 接口被字段字符折腾到半夜之后，我每次集成新单据都强制走一遍这个动作，省下来的排查时间远超写日志那几行代码的功夫。希望帮到你。

本文还有配套的精品资源，点击获取