Epicor Kinetic 集成指南：使用 SkyPlanner APS 进行生产排程
本指南面向 Epicor 合作伙伴、IT 团队和技术采购人员，介绍如何配合 Epicor Kinetic，使用 SkyPlanner APS 进行生产排程，确保排程符合设备和人员的实际产能。SkyPlanner 通过 Kinetic 自身的 REST 服务与其双向集成：
- 导入生产任务、工序、资源和采购订单交付计划。
- 将工序的计划日期回写至生产任务。
- 将操作员的工时记录回传至 Kinetic，作为工时数据入账。
- 排程发生变化时，SkyPlanner 通过 webhook 实时推送。
SkyPlanner 团队会在实施导入阶段，根据您的 Kinetic 配置完成集成设置，并在上线后持续提供支持。本指南面向希望参与集成，或自行基于 SkyPlanner REST API 文档（API 参考）进行开发的合作伙伴和开发人员。
如果您尚不确定 Kinetic 自带的 Scheduling and Resource Management 或 APS 模块能否满足需求，请先阅读《Epicor Kinetic 支持生产排程吗？》。
Kinetic 提供的集成接口与技术
Epicor 表示：”All Kinetic services, including business objects, processes, reports, BAQs, and Epicor Functions, are accessible through REST endpoints.”（所有 Kinetic 服务，包括业务对象、流程、报表、BAQs 和 Epicor Functions，均可通过 REST 端点访问。）排程集成基于以下四项 Epicor 技术构建：
- Kinetic REST API v2 (OData v4)。业务对象以名为
Erp.BO.<Name>Svc的服务对外提供，常用路径为/api/v2/odata/{Company}/Erp.BO.{Svc}/{EntitySet}。REST v1 仍然可用，但已属于旧版，因此应基于 v2 开发。请在/api/help/v2/的 REST Help 中确认当前版本支持的实体集和方法。 - 通过 REST 访问 Business Activity Queries (BAQ)。BAQ 的访问路径为
/api/v2/odata/{Company}/BaqSvc/{BAQ}/Data。提取计划数据时，使用 BAQ 可以在一次调用中关联读取JobHead、JobOper、JobMtl、PartWhse和PORel，是实用的数据读取方式（社区示例）。 - Epicor Functions (EFx)。这类服务端函数可通过
/api/v2/efx/{Company}/{Library}/{Function}调用。Epicor 指出，这些函数“can be triggered from multiple entry points, including BPMs, REST services, schedules, and application events.”（可从多个入口触发，包括 BPM、REST 服务、定时任务和应用事件。） - BPM 指令。生产任务或工序发生变化时，会触发 Method Directives 和 Data Directives，并可调用函数向外推送数据。
对于文件交换，DMT 负责导入，BAQ 导出负责提取数据。Epicor 还提供 Epicor Automation Studio，并将其描述为 “a low-code app for integration-led automations”（一款通过集成实现自动化的低代码应用）。不要直接访问数据库：REST、BAQs 和函数在本地部署环境与 Kinetic Cloud 中的工作方式相同。
身份验证与访问范围
Kinetic REST v2 按集成分别控制访问权限。每项集成都有一个 API 密钥，并绑定一个访问范围，列明允许调用的服务和方法。Epicor 的表述是：”API keys, access scopes, and standard authentication methods control which services and methods are available to each integration.”（API 密钥、访问范围和标准身份验证方式共同控制每项集成可使用的服务和方法。）
除了提供 API 密钥，调用方还需以 Kinetic 用户身份登录。请使用专用的集成用户，且仅授予集成所需的权限。SkyPlanner 的 REST API 使用 JWT 身份验证，并提供 Swagger/OpenAPI 文档。
与 SkyPlanner 集成时，访问范围通常包括：
Erp.BO.JobEntrySvc(JobEntries, JobOpers, GetDatasetForTree)Erp.BO.ResourceGroupSvc和Erp.BO.ResourceSvcErp.BO.CapabilitySvcErp.BO.PartSvc(Parts, PartWhses)Erp.BO.EmpBasicSvcErp.BO.ScheduleEngineSvc(GetNewParamsForJob, MoveJobItem, ChangeResource)Erp.BO.LaborSvc(Labors, LaborDtls, StartActivity, EndActivityByEmp)- 您为集成发布的 BAQs 和 EFx 库
如果某个方法未纳入访问范围，错误会在运行时出现，而非配置时。请列出所有要调用的方法，监控 API 密钥的到期时间，并对 HTTP 错误设置告警，不要只关注空结果。
变更检测：BPM 指令、函数或轮询
Epicor 文档未提供通用的出站 webhook API，因此 Kinetic 的变更通过以下两种方式之一传递给 SkyPlanner：
- 事件驱动。
JobHead或JobOper上的 BPM Data Directive 调用 Epicor Function，由该函数将变更后的生产任务发送至 SkyPlanner REST API。 - 定时轮询。每隔几分钟或每小时运行一次按变更日期筛选的 BAQ。这种方式更便于维护和故障恢复。
反向传输时，SkyPlanner 通过 webhook 推送状态和排程变更。您的中间件或 EFx 端点接收这些变更，并将其写入 Kinetic。
数据映射
| Kinetic 实体 / 服务 | SkyPlanner 对象 | 数据流向 | 同步频率 |
|---|---|---|---|
Part, PartRev (Erp.BO.PartSvc/Parts) | 产品 | 从 Kinetic 到 SkyPlanner | 首次加载，之后定时同步 |
PartMtl（工艺方法）、JobMtl（生产任务） | 产品和订单的物料 | 从 Kinetic 到 SkyPlanner | 随生产任务同步 |
PartOpr（工艺方法）、JobOper（生产任务） | 工序 | 从 Kinetic 到 SkyPlanner | 随生产任务同步 |
ResourceGroup, Resource (ResourceGroupSvc, ResourceSvc) | 工作中心组、工作中心 | 从 Kinetic 到 SkyPlanner | 首次加载，变更时同步 |
Capability (CapabilitySvc) | 替代工作中心 | 从 Kinetic 到 SkyPlanner | 首次加载，变更时同步 |
| 资源和资源组日历 | 班次和例外安排 | 从 Kinetic 到 SkyPlanner | 首次加载，之后每周或变更时同步 |
EmpBasic (EmpBasicSvc) | 人员 | 从 Kinetic 到 SkyPlanner | 首次加载，变更时同步 |
JobHead (JobEntrySvc/JobEntries) | 订单 | 从 Kinetic 到 SkyPlanner | 通过 BPM + EFx 实时同步，或通过 BAQ 轮询 |
通过 BAQ 读取 PartWhse | 库存 | 从 Kinetic 到 SkyPlanner | 定时同步 |
采购订单：通过 BAQ 读取 POHeader、PODetail、PORel | 采购订单 / 待到货物料（预计交货日期） | 从 Kinetic 到 SkyPlanner | 定时同步，或在采购订单变更时通过 BPM + EFx 同步 |
| 每道工序的计划开始和结束时间 | JobOper 日期：在 EFx 中通过 ScheduleEngineSvc (MoveJobItem, ChangeResource) 写入 | 从 SkyPlanner 到 Kinetic | 排程变更时通过 webhook 同步 |
| 工时记录、数量、工序进度、原因 | Labors / LaborDtls：通过 LaborSvc 写入；原因代码：通过 Erp.BO.ReasonSvc 写入 | 从 SkyPlanner 到 Kinetic | 通过 webhook 实时同步 |
Epicor 将生产订单称为 Job。将每条 JobHead 映射为一个 SkyPlanner 订单，将每条 JobOper 映射为一道工序。保留生产任务编号、装配序号和工序序号，用作外部键。
集成方式
1. 首次加载主数据。读取零件、资源组、资源、能力、日历和员工数据。根据 Kinetic 资源建立 SkyPlanner 工作中心，根据资源组建立工作中心组。读取大量数据时，使用 $top 和 $skip 分页，或通过 BAQ 批量提取。
2. 同步订单。发送已下达且已确定的生产任务，以及对应的工序和物料。使用 GetDatasetForTree 或 BAQ 获取生产任务树，不要逐个实体读取。未确定的 MRP 生产任务应留在 Kinetic 中，待确定后再同步。读取库存的同时，同步未结采购订单的交货计划及其到期日期。SkyPlanner 将已订购的物料视为在交货日期可用，并在采购订单标记为 Delivered 时更新库存，因此排程会同时检查现有库存和采购待到货物料。
3. 回写排程。SkyPlanner 的 webhook 将每道工序的计划开始时间、结束时间和工作中心发送至 EFx 端点（/api/v2/efx/{Company}/{Library}/{Function}）。该函数通过 Kinetic 排程引擎写入数据；Job Entry 排程和排程看板也使用这一业务对象（社区示例）：
ScheduleEngine.GetNewParamsForJob为该生产任务构建排程引擎数据集。- 函数设置生产任务编号、装配序号、工序序号以及计划开始日期和时间，然后调用
ScheduleEngine.MoveJobItem。 - 如果 SkyPlanner 将工序安排在组内的其他资源上，
ScheduleEngine.ChangeResource会将工序移至该资源。仅调用MoveJobItem会保留该组的默认资源。 - 函数设置生产任务的排程锁（
JobHead.SchedLocked，即 Job Entry 中的 Lock 选项），使 Global Scheduling 保留 SkyPlanner 设定的日期。
将这些调用封装在一个 Epicor Function 中，可以保证每个生产任务的写入具有原子性，也便于添加自定义校验。如果工厂不希望使用自定义函数，也可以按相同顺序，通过 REST 直接调用 Erp.BO.ScheduleEngineSvc。切勿直接写入 ResourceTimeUsed 或 JobOper 的日期字段：这样会绕过引擎，导致排程看板上的资源分配与排程不一致。
4. 车间报工。操作员通过 Mobile Confirmations、Production Timer 或 Quick Log Mode 在 SkyPlanner 中记录作业。每条已结束的工时记录都通过 Erp.BO.LaborSvc 转为 Kinetic 中的工时数据：实时作业使用 StartActivity 和 EndActivityByEmp，事后补录则使用 Labors 和 Update。如果工厂要求审批，请将 submitForApproval 纳入流程和访问权限范围。
5. 数据归属与冲突处理规则。上线前应明确记录以下规则：
| 数据 | 主管系统 |
|---|---|
| 物料、制造方法、资源、日历、生产任务、MRP、库存、成本核算 | Kinetic |
| 数量与生产任务状态 | Kinetic |
| 工序顺序、计划日期、组内资源选择 | SkyPlanner |
由 SkyPlanner 排程的生产任务会设置排程锁，因此 Global Scheduling 不会更改这些任务的日期。对于不由 SkyPlanner 计划的资源，继续使用 Kinetic 排程。
键值、重试与数据核对
- 稳定的键值。每条记录都携带其 Kinetic 键值：工序使用生产任务编号、装配序号和工序序号；工时使用工时表头和明细键值。写入时按该键值执行更新或插入，因此重复消息只会更新记录，不会生成重复数据。
- 重试。向任一系统写入失败时都会重试，每个 SkyPlanner 工时记录 ID 只入账一次，因此重试不会导致工时重复计算。
- 数据核对。定时运行 BAQ，将未结生产任务、工序状态和数量与 SkyPlanner 比对，修正数据偏差。例如，消息传输期间，某项生产任务已在 Kinetic 中关闭。
- 数量变更与取消。Kinetic 中的数量发生变化时，会更新 SkyPlanner 中的订单及其工序。部分完工会减少剩余加工时间。在 Kinetic 中关闭或删除的生产任务，会在下次同步时从排程中移除。
项目包含哪些工作
实施通常会在导入工作启动后数周内完成。Kinetic 集成项目包括：
- 在任何开发工作开始前，使用以 CSV 或 Excel 格式导出的生产任务、工序和资源数据，进行 30 天试用。
- 配置 API 密钥、访问范围、专用集成用户，以及集成要读取的 BAQs。
- 主数据映射：将能力、资源组、资源、日历和员工映射至 SkyPlanner 的工作中心、组、班次和人员。
- 首次导入物料、制造方法（BOM 和工序）以及资源。
- 同步生产任务、采购订单（
PORel到期日期）以及PartWhse库存。 - 在 Epicor Function 中通过
ScheduleEngineSvc(MoveJobItem, ChangeResource) 回写工序的计划日期，并设置生产任务锁。 - 通过
LaborSvc将车间报工写入工时数据。 - 与现有 Kinetic 排程并行测试，然后上线。
Kinetic 集成中的常见陷阱
- 产能约束需要在多处设置。Finite 复选框位于资源设置中。排程遵守产能约束的时间范围需要在资源、资源组以及 Site Maintenance 的 Planning 选项卡中设置。每个排程工具也有各自的 Finite 复选框。在将 Kinetic 日期导入作为基准前，先确认这些日期是否确实在排程时考虑了产能约束。
- Capability 与 Resource Group、Resource 的选择关系。工序指定能力时，其资源组和资源字段留空。否则，工序会指定资源组，有时还会指定具体资源。集成必须读取相应字段，并自行确定满足该能力要求的资源。
- 日历中可能留有历史调整。资源日历和员工人数往往经过调整，以便让原生排程工具按预期运行。请将实际班次模式和真实人员映射到 SkyPlanner；对于需要团队作业的生产任务，让 SkyPlanner 分配多名操作员。
- 日期必须通过引擎更新，而不是直接执行 CRUD。仅通过
JobEntrySvc更新工序日期不会触发重新排程；一则论坛反馈显示，JobScheduling调用返回了 200 OK，生产任务却没有变化。请使用上述ScheduleEngine调用顺序。 - 数据管理决定排程结果。工序时间估计过于乐观、采购提前期缺失、生产任务未及时关闭，以及日历中遗漏停机时间，都会降低排程质量，无论使用原生还是外部排程工具（Bluesky ERP）。
谁来配置 Kinetic 集成
各工厂使用 Kinetic 的方式并不相同。基于能力的工艺路线、资源组日历、BAQ 设计、BPM 指令以及不同版本的回写方法，都会因工厂而异。正确配置这些内容，决定了排程人员是信任排程结果，还是不得不重新调整。
- SkyPlanner 团队在实施导入阶段完成配置，上线后持续提供支持。团队会映射您的资源、生产任务和采购订单交付计划，并配置 BAQ 读取、BPM 触发器和回写函数，将 SkyPlanner 的 REST API 和 webhook 与 Kinetic REST v2 对接。即使您的 BAQs、BPMs 或 Kinetic 版本发生变化，支持也会继续。
- 您的 Epicor 合作伙伴。已有 BAQs、BPMs 和 Epicor Functions 开发经验的合作伙伴，可以使用同一套有文档支持的 SkyPlanner REST API，读取和写入订单、产品、物料、工序和工时记录。
- 您的内部开发人员。具备 Kinetic REST 经验的内部团队可以直接开发；如果已使用 Automation Studio，也可以在其中开发。只需一个 SkyPlanner API 密钥即可开始（集成教程），SkyPlanner 团队会在需要时提供协助。产品文档公开发布在 SkyPlanner 文档中。
同样的 API 与 webhook 集成方式已在对接其他 ERP 的生产环境中运行，例如 UTU。在 Laboratory & Allied，内部 IT 团队在 SkyPlanner 的协助下，基本自主完成了 SAP Business One 集成。
无论选择哪种方式，第一步都相同：先导入 CSV 数据进行30 天免费试用，验证排程效果，再开发集成。价格每月 199 € 起，包含 5 个工作中心，按月计费，可随时取消。集成费用会根据您的流程和需求，连同订阅方案提前报价，让您在开始前了解全部费用。
为什么选择这一方案，而不是购买 Kinetic APS 许可
对于技术采购人员，比较的重点是项目范围和见效时间。以下情况适合选择 SkyPlanner：
- 希望控制集成范围。从 Kinetic 导出生产任务、工序、资源和物料，再回传计划日期和工时。上述数据映射就是全部集成范围。
- 两次排程运行之间也需响应变化。Arcturus 在数秒内生成符合实际产能的生产排程，生产发生变化时，Autopilot 会自动重新排程。SkyPlanner 的 webhook 会推送每项变更，因此无需运行 Global Scheduling，Kinetic 即可获得新的日期。
- 车间报工应写入 Kinetic 的工时数据。操作员使用手机或平板，通过 Mobile Confirmations、Production Timer 和 Quick Log Mode 记录作业；通过
LaborSvc写入工时也是同一集成的一部分。 - 采购物料决定任务何时开工。库存和未结采购订单交付计划都会纳入排程，让工序按物料实际预计到位的时间开工。
- 约束条件不止两个。同一任务需要多名操作员、工具在别处使用时不可占用，以及备选工作中心和人员，都能在同一份排程中处理。准备时间矩阵用于安排换产顺序，集成会将结果回写。
- 先验证效果，再快速实施。试用时可通过 BAQ 导出数据，查看您自己的排程，最多支持 20 个工作中心，无需信用卡。实施通常会在导入工作启动后数周内完成。
制造企业对 SkyPlanner 的评价
2 小时每周节省
“SkyPlanner 让我们的生产计划告别了 Excel 电子表格，实现了实时生产优化。”
Kalle Kalliomäki，供应链专员
UTU · 配电盘与开关设备
每周可节省 2 小时的生产计划编制时间，新的作业队列只需几秒即可下达到产线。
+90%生产效率提升
“生产效率提高了 90%。”
Abdul Rucyinga，IT 负责人
Laboratory & Allied · 制药
生产效率提高了 90%，为所有工作中心编制覆盖三个月的优化计划，用时不到 30 分钟。
1,000s份工单自动完成排程
“我们对生产的管控方式焕然一新，对产能的了解也达到了全新水平。”
Hannu Ryynänen，首席执行官
Mamec · 工业搅拌机、泵及高科技产品代工
数千份工单自动完成排程，全公司都能实时掌握生产情况。
99.2%准时交付率
“SkyPlanner 让生产瓶颈一目了然，生产管理也更加清晰。”
Toni Tuori，生产经理
Piristeel · 屋顶安全设施与雨水系统
今年的准时交付率达到了 99.2%，每天在排程上最多可节省四小时的工作时间。
常见问题
SkyPlanner APS 如何与 Epicor Kinetic 集成？
通过 Kinetic REST v2、BAQs 和 Epicor Functions 实现双向集成。生产任务、工序、资源和采购订单下达明细传入 SkyPlanner，计划工序日期和工时数据则回传至 Kinetic，排程变更通过 webhook 实时推送。SkyPlanner 团队会在实施启动阶段根据您的 Kinetic 配置完成集成配置，您的 Epicor 合作伙伴或开发人员也可以使用同一套 REST API。
排程集成应使用哪个 Kinetic API？
使用 REST v2。通过 JobEntrySvc 访问生产任务和工序，通过 ResourceGroupSvc、ResourceSvc 和 CapabilitySvc 访问产能数据，通过 BAQ 批量读取数据，并通过 LaborSvc 回写作业记录。
Epicor Kinetic 支持 webhook 吗？
它不提供通用的出站 webhook API。事件驱动的推送通过 BPM 指令调用 Epicor Functions 来实现，也可以按设定的周期轮询 BAQ。
SkyPlanner 能否将排程日期回写到 Kinetic 的生产任务中？
可以。Epicor Function 先调用 ScheduleEngine.GetNewParamsForJob，再为每道工序调用 MoveJobItem，资源发生变更时还会调用 ChangeResource，最后锁定生产任务，使 Global Scheduling 保留这些日期。同样的调用也可以通过 REST 直接在 Erp.BO.ScheduleEngineSvc 上执行。
由谁维护集成？
SkyPlanner 团队在实施启动阶段完成集成配置，并在上线后提供支持；您的 BAQs、BPMs 或 Kinetic 版本发生变化时，也同样提供支持。
能否与本地部署的 Epicor Kinetic 集成？
可以。REST API、BAQs、BPMs 和 Epicor Functions 在本地部署与 Kinetic 云端的工作方式相同，因此一套集成设计即可适用于两种环境。
SkyPlanner APS 与 Epicor Kinetic 的集成需要多长时间？
实施通常在导入工作启动后数周内完成。范围包括上述数据映射、初始数据加载、生产任务与采购订单同步、排程回写及工时过账，并与您现有的排程并行测试。
