Sage X3 集成指南：对接 SkyPlanner APS 生产排程
本指南介绍 Sage 合作伙伴和 IT 团队如何将 Sage X3 连接到 SkyPlanner APS，包括应使用哪些 X3 接口、数据由哪些对象承载，以及项目容易在哪些环节出问题。无论 X3 部署在云端还是本地，SkyPlanner 都能与其双向集成：
- 从 X3 导入工单、工序、工艺路线、工作中心、日历、库存及未结采购订单。
- 将工序的计划日期和工作中心回写至工单（GESMFG）。
- 将操作员的工时记录作为生产跟踪数据提交至 X3（GESMTK）。
- 排程发生变化时，SkyPlanner webhook 会即时推送。
在实施导入阶段，SkyPlanner 团队会根据您的 X3 环境配置集成，并在上线后继续提供支持。
如果您还在考虑 X3 是否需要按机器和人员的实际产能安排任务的生产排程工具，请先阅读Sage X3 是否支持生产排程？如需了解产品概况，请参阅适用于 Sage X3 的 SkyPlanner APS；如需了解其他 ERP，请访问ERP 集成中心。
SkyPlanner 在 X3 系统架构中的定位
Sage X3 的标准排程功能（FUNMAUTJ）根据工艺路线数据安排工序顺序，但每张工单都独立排程。Sage 英国支持指南对此有明确说明：它 “does not delay or stagger work orders based on overall resource load.”（不会根据资源的总体负荷推迟工单或将其错开安排。）按机器和人员实际产能进行生产排程，需要单独的功能层，Sage 提供两种选择：
- Production Scheduler（活动代码 POPS），仅支持本地部署。
- 通用 Finite scheduler 接口（活动代码 GFS），用于将云端或本地部署的 X3 连接到 Sage X3 Web Scheduling 或独立软件供应商的排程工具。
SkyPlanner 通过标准 X3 API 充当外部云端排程工具，因此在云端和本地 X3 上的工作方式相同。MRP（FUNMRP）仍负责生成工单建议和采购订单建议，SkyPlanner 则根据实际产能为已确认工单和计划工单安排顺序。
Sage X3 集成方式
集成路径取决于部署模式。Sage X3 云端既不向第三方应用开放应用文件系统，也不开放数据库，因此需要通过 API 或托管文件传输进行集成。本地部署还支持直接导入文件，以及使用 X3 数据库中的暂存表。
| 集成方式 | 说明 | 身份验证 | 适用场景 |
|---|---|---|---|
| GraphQL API (Sage X3 Web API) | Sage 将其称为 X3 API 的 “technology of choice”（首选技术）；持续演进，无需划分版本 | 使用 Connected application 的 Secret 对 JWT (HS256) 签名，Client ID 作为 iss，URL 作为 aud，并使用专用 Syracuse 用户 | 产品、站点、采购、库存；若已开放，也可访问制造节点 |
| REST api1 | 基于 representation 的 REST：.../api1/x3/$$prod/<FOLDER>.<ENTITY>?representation=<REP>.$query | Syracuse 身份验证 | GraphQL 尚未覆盖的实体 |
| SOAP 对象 Web 服务 | 在 Web services (GESAWE) 中发布的对象；字段对应对象的界面字段；支持读取、保存和修改 | Syracuse 连接池上的 OAuth2 身份验证 | 回写 Work order (GESMFG) 和 Production tracking (GESMTK) |
| SOAP Template Services | 通过 SOAP 调用 AOWSIMPORT 和 AOWSEXPORT，执行导入/导出模板 | OAuth2；X3 不允许 SOAP 使用基本身份验证 | 从中间件运行模板 |
| 导入/导出模板 | 按模板处理批量数据文件 | 文件系统（本地部署）或托管文件传输（云部署） | 初始数据加载、夜间批量同步 |
| Sync API (Cloud BI) | 仅限云部署，提供只读增量提取和 NDJSON 数据流；需通过您的 Sage ISV 代表申请 | Bearer 令牌及每个租户专属的 X-API-KEY | 在云端读取大量变更数据 |
本地部署使用 GraphQL 时，需要将 "bearer" 添加到 session.auth 数组中，该数组位于 nodelocal.js 文件中。Sage X3 SaaS 默认启用连接应用身份验证。在 Sage X3 Cloud 上，连接应用不能使用 admin 用户，需另行创建采用 Standard 身份验证的 Syracuse 用户。
各类数据流使用哪些接口
- 产品、站点、采购和库存：使用 GraphQL，与 Sage 官方示例一致。
- 工单、工序、工艺路线和工作中心：使用 REST api1 的 representation，或通过 AOWSEXPORT 运行导出模板。如果所用版本的 GraphQL schema 已开放制造领域（
xtremX3Manufacturing），集成也可通过该接口读取相同数据。 - 将工序日期和工作中心回写至 X3：调用 Work order（GESMFG）SOAP Web 服务的 modify 操作。备用方式是通过 AOWSIMPORT 使用导入模板。
- 生产跟踪：调用 Production tracking（GESMTK）SOAP Web 服务的 save 操作。
这套设计无需直接访问文件系统或数据库，因此同样适用于云端和本地部署的 X3。X3 中无需安装任何组件：集成使用连接应用、Syracuse 用户，以及在 GESAWE 中发布的 Web 服务。
事件处理：按轮询方式设计
Sage 公开的 X3 开发者文档未描述任何出站 webhook 或业务事件功能。2024 R1 新增的“Callback URL”设置用于 Mobile Automation 和 Web Scheduling 调用 SOAP Web 服务，并不是通用事件系统。应通过定时读取检测变更：可使用 GraphQL 查询、云端 Sync API 的时间戳游标，或定期通过模板导出数据。
数据映射：从 Sage X3 到 SkyPlanner
| Sage X3 对象（表、功能） | SkyPlanner 对象 | 方向 | 频率 |
|---|---|---|---|
| 产品，ITMMASTER | 产品 | X3 → SkyPlanner | 首次导入，之后定时同步 |
| 生产 BOM（GESBODP） | 多层产品结构、物料 | X3 → SkyPlanner | 首次导入，之后在变更时同步 |
| 工艺路线（GESROU）：OPENUM、工作中心 WST、SETTIM、OPETIM、时间单位 TIMUOMCOD | 工序及其准备时间和加工时间 | X3 → SkyPlanner | 首次导入，之后在变更时同步 |
| 工作中心（GESMWS、WORKSTATIO）：WST、WSTTYP、WSTNBR、EFF、SHR、带优先级的替代工作中心 | 工作中心、效率、替代工作中心 | X3 → SkyPlanner | 首次导入，之后很少同步 |
| 工作中心组（WCR） | 工作中心组 | X3 → SkyPlanner | 首次导入 |
| 每周工作结构（TWD）、工作时间表、产能变动表、DEFDIH | 班次、加班班次、缺勤 | X3 → SkyPlanner | 首次导入，之后在变更时同步 |
| 工单：MFGHEAD、MFGOPE，以及产品和物料 | 订单、物料、工序 | X3 → SkyPlanner | 每 5 至 15 分钟轮询 |
| 各站点库存 | 库存余额 | X3 → SkyPlanner | 轮询 |
| 采购订单（POH）：未结明细行、预计收货日期 | 待收物料及预计交货日期 | X3 → SkyPlanner | 每 5 至 15 分钟轮询 |
| GESMFG 的 Operations 选项卡：开始日期 OPESTR、结束日期 OPEEND、工作中心 | 排程确定的开始时间、结束时间及所选工作中心 | SkyPlanner → X3 | 排程变更时（webhook） |
| Production tracking（GESMTK）：工序工时、数量、物料跟踪、生产报工 | 工时记录、数量、物料用量 | SkyPlanner → X3 | 每次报工时（webhook） |
始终拉取已确认工单。如果计划员希望在甘特图上将计划工单显示为暂定负荷，也应拉取这些工单。MRP 计划建议在转换为工单之前仍保留在 MRP 中。
集成模式
1. 首次导入主数据。先导入工作中心和日历，再导入产品、BOM 和工艺路线，因为工艺路线会引用工作中心。
2. 订单同步。轮询 MFGHEAD 和 MFGOPE，获取新增和变更的工单。将每条 MFGOPE 明细映射为 SkyPlanner 中的一道工序，并根据其 WST 代码分配到相应工作中心。按相同周期同步未结采购订单。SkyPlanner 将已订购物料视为在采购订单交货日期可用，并在采购订单标记为 Delivered 时更新库存。这样，物料检查就能同时涵盖现有库存和待收物料。
3. 排程回写。排程发生变化时，会触发 SkyPlanner 的 webhook。集成程序调用 Work order 对象（GESMFG）的 modify 操作，该对象在 GESAWE 中发布为 SOAP Web 服务。对于每道发生变更的工序，更新其 Start（OPESTR）、End（OPEEND）和工作中心。批量更新时，通过 AOWSIMPORT 使用工单导入模板传入相同字段。只回写日期和工作中心，绝不回写数量、BOM 明细行或工艺路线。
4. 设备选择与回写。如果工作中心采用一一对应的映射，引擎从备选设备中选定的设备会作为工序的工作中心回写，使 X3 记录实际执行生产任务的设备。如果 X3 中的一个工作中心代表一组设备，操作员的任务队列中会显示具体设备；回写至 X3 的则是该设备组的工作中心和排程日期。
5. 车间报工。操作员通过 Mobile Confirmations 或 Production Timer 记录作业。集成程序使用 Production tracking 对象（GESMTK）的 save 操作提交每次报工：将工序工时和数量写入工序跟踪；如果您也在其中跟踪物料消耗，则一并提交。X3 只允许对状态为 Firm 的工单进行生产跟踪，且组件必须可用，除非在产品站点设置中选中了 Release if shortage（MFGSHTCOD）。
6. 确保同步可靠。每次提交生产跟踪数据时，以 SkyPlanner 工时记录 ID 作为唯一键，并保存由此生成的 X3 跟踪编号，确保重复收到 webhook 时不会重复提交。下次轮询时，将 X3 中已关闭或取消的工单从排程中移除。对于被拒绝的调用，记录 X3 返回的错误消息，不要盲目重试。X3 无法访问时，将变更放入队列，待其恢复后按顺序提交。
7. 明确数据管理权责。X3 负责定义生产什么：产品、数量、BOM、工艺路线和站点。SkyPlanner 负责确定何时、何处生产：顺序、工作中心以及开始和结束时间。应约定计划员不再使用 Planning workbench 重新排程，也不再对 SkyPlanner 管理的订单运行 FUNMAUTJ，否则这些修改会在下次回写时被覆盖。
典型项目步骤
实施通常在导入工作启动后数周内完成。Sage X3 项目包含以下步骤：
- 用您自己的数据试用。使用 X3 导出模板或 Excel，导出工作中心、工艺路线和未结工单的快照，再以 CSV 格式导入。调整班次、效率和优先级，直到甘特图与实际情况相符。
- 主数据映射。将 GESMWS 工作中心映射为 SkyPlanner 工作中心，将 GESROU 工序映射为 SkyPlanner 工序，并将时间单位和每周工作结构映射到班次。在此过程中，修正工艺路线工序未分配工作中心、日期缺少工作时间表、时间单位错误等问题。
- 首次导入。先导入产品、生产 BOM、工艺路线和工作中心，再导入日历。
- 同步订单和采购订单。配置已连接的应用、Syracuse 用户、GraphQL 查询或模板导出，以及用于读取工单、库存和未结采购订单的轮询任务。
- 回写排程。在 GESAWE 中发布 Work order SOAP Web 服务，并配置错误处理和日志记录。
- 车间报工。通过 Production tracking (GESMTK) Web 服务，将 Mobile Confirmations 的报工记录提交到 X3。
- 与现行计划并行测试。计划员对比两套计划后再切换。
- 上线。对于由 SkyPlanner 管理的订单，关闭 X3 中的手动重排功能。
Sage X3 集成中的常见问题
- 计划建议不是工单。MRP 建议只有转换为计划工单或确定工单后，才会生成 MFGOPE 工序行。因此，应对转换后的工单排程，而不是对建议排程。
- 日历缺项。工作日未配置时段表时，系统会采用 DEFDIH 默认方案。如果当天既没有时段表，也没有默认方案，就会产生错误的日期和负荷。导出日历前，请为每个周结构中的所有工作日配置时段表。
- 负荷时段数据未更新。产能或日历变更后，必须重新排程并运行 Recalculate loads (FUNMIWL)，X3 中现有的各时段负荷才会调整。不要用 Loads inquiry (CONSMWK) 中的过期数据核验 SkyPlanner。
- No. of resources 表示作业人数。WSTNBR 表示一道工序在工作中心所需的资源数量，例如人工工作中心需要三人。应将其映射到 SkyPlanner 工作中心的操作员人数，以便将多人同时安排到同一项生产任务上。使用过 GFS 高级接口的工厂按 Sage 要求将该值设为 1，因此需要核实实际作业人数存储在哪里。
- 工艺路线中未指定工作中心的工序无法安排到工作中心上。映射环节会标记这些工序。
- 时间单位和替代工作中心。工艺路线中的工时有各自的时间单位 (TIMUOMCOD)，替代工作中心则带有优先级。两者都必须明确映射，并在每次 X3 升级后重新检查映射。
- 订单被锁定。如果工厂还使用过 Production Scheduler，提交到该系统的订单会处于 Being optimized 状态，必须先将其从排程中移除 (PSOPTFREE)，才能修改。请在切换前解除这些订单的锁定。
Sage X3 集成由谁配置
配置工作包括将您的文件夹、工艺路线规则、工作中心结构及定制开发内容映射到 SkyPlanner。还需配置 X3 未作为可排程数据保存的约束：换型时间矩阵、工装、操作员人数和替代资源。
- SkyPlanner 团队在实施导入阶段负责配置，并在上线后提供支持。每家工厂使用 X3 的方式都不同，这些经验正是在此发挥作用。团队会连接您部署在云端或本地的 X3 端点，在映射环节验证主数据，并记录 X3 拒绝的请求以便跟进。集成从第一天起就有明确的负责人，您无需配备内部集成开发人员。
- 您的 Sage 合作伙伴也可以参与。合作伙伴了解您的文件夹、活动代码和定制开发内容，可以与 SkyPlanner 团队一起审核已连接的应用、Syracuse 用户及 GESAWE 中发布的服务。
- 您的开发人员可以在此基础上继续开发。SkyPlanner 的 REST API 可读写订单、产品、物料、工艺步骤和工时记录，采用 JWT 身份验证，并提供 Swagger/OpenAPI 文档（API 参考）。只需一个 API 密钥即可开始，集成教程会指导您完成最初的调用。SkyPlanner 团队会在需要时提供协助。SkyPlanner 文档涵盖产品和物料以及采购订单。在 Laboratory & Allied，内部 IT 团队在 SkyPlanner 的协助下，主要依靠自身力量完成了 SkyPlanner 与 SAP Business One 的对接。
X3 团队为何选择 SkyPlanner 承担排程
如果您希望几周内就能上线，请选择 SkyPlanner，无需等待长达数月的 APS 项目完成。
如果您希望在集成完成前就开始排程，请选择 SkyPlanner。
配置 X3 数据读取和回写的同时，计划员可在试用期间通过 CSV 导入数据进行排程。集成运行后，便会接替文件导入。
如果您希望集成架构保持轻量，请选择 SkyPlanner。
Webhook 实时推送排程和状态变更，因此中间件只需轮询 X3 端。Arcturus AI 引擎可在几秒内生成排程，生产发生变化时，Autopilot 会自动重新排程。
如果您需要用 X3 数据建立符合实际生产约束的模型，请选择 SkyPlanner。
作业人数会转换为同一工作中心上的多名操作员，替代工作中心则转换为备选机器。换型时间矩阵会根据产品先后顺序计入换型时间。工装按有限资源处理，因此一台机器正在使用的夹具绝不会同时安排给另一台机器。
如果您希望从车间现场开始跟踪生产，请选择 SkyPlanner。
操作员可在手机或平板电脑上使用 Mobile Confirmations、Production Timer 和 Quick Log Mode 记录作业。这些工时记录也会作为生产跟踪数据提交到 X3。
制造企业对 SkyPlanner 的评价
2 小时每周节省的时间
“SkyPlanner 让我们的生产计划从 Excel 表格迈向了实时生产优化。”
Kalle Kalliomäki，供应链专员
UTU · 配电柜和开关设备
生产计划工作每周节省 2 小时，新作业队列几秒内即可下达到产线。
+90%生产效率提升
“生产效率提高了 90%。”
Abdul Rucyinga，IT 负责人
Laboratory & Allied · 制药
生产效率提高了 90%，为所有工作中心编制覆盖三个月的优化计划，用时不到 30 分钟。
98%准时交付率，原为约 50%
“SkyPlanner 对保持我们的准时交付率起着决定性作用。”
Hannu Lahtinen，总经理
KJH-Comp · 钣金加工与代工制造
准时交付率从约 50% 提升至最高 98%，排程如今只需一名主管，而不再需要两名。
99.2%准时交付率
“SkyPlanner 让生产瓶颈清晰可见，也让生产管理更加清楚有序。”
Toni Tuori，生产经理
Piristeel · 屋面安全设施与雨水系统
今年准时交付率达到 99.2%，排程工作每天最多节省四小时。
常见问题
SkyPlanner APS 如何与 Sage X3 集成？
通过 GraphQL、REST api1、SOAP Web 服务和模板进行双向集成。工单、工艺路线和工作中心导入 SkyPlanner，计划工序日期和已记录工时则回传 X3，并在排程变更时由 Webhook 推送。SkyPlanner 团队可在实施导入阶段完成配置，您的 Sage X3 合作伙伴或开发人员也可基于 SkyPlanner REST API 进行开发。
工序日期如何回写到 Sage X3？
通过 Work order 对象 (GESMFG) 回写，该对象在 Web services 功能 (GESAWE) 中发布为 SOAP Web 服务。其 modify 操作会更新每道工序的 Start (OPESTR)、End (OPEEND) 和工作中心。批量更新时，通过 AOWSIMPORT 运行工单导入模板。工时和数量则通过 Production tracking 对象 (GESMTK) 提交。
应该使用 GraphQL 还是 SOAP Web 服务？
两者都用，各取所长。GraphQL 是 Sage 推荐的 API，可读取云端和本地部署中的产品、工厂、采购及库存数据。SOAP 对象 Web 服务用于写入排程和生产跟踪数据，SOAP Template Services 则运行导入和导出模板，完成批量数据加载。
如何避免重复提交或变更丢失？
以 SkyPlanner 工时记录 ID 作为每次 Production tracking 提交的唯一键，并保存 X3 返回的跟踪编号，以便识别并跳过重复的 Webhook。X3 无法访问时，将变更放入队列，待其恢复后按顺序提交。对于被拒绝的请求，例如向非 Firm 状态的工单提交生产跟踪数据，应连同 X3 错误消息一起记录。
使用 SkyPlanner 需要启用 POPS 或 GFS 活动代码吗？
不需要。这些代码用于启用 Sage 自带的 Production Scheduler，以及连接 Web Scheduling 的通用接口。SkyPlanner 通过 GraphQL、REST api1 或模板读取工单，再通过 Work order 和 Production tracking SOAP Web 服务回写数据。
SkyPlanner 如何获取 Sage X3 中的新工单？
集成通过 GraphQL、REST api1 或模板导出，以较短的轮询间隔读取 X3 数据；云端则可使用 Sync API。反向传输时，SkyPlanner 的 webhook 会在排程发生变化时即时推送变更。
