JobBOSS² 集成指南：使用 SkyPlanner APS 进行生产排程
本指南面向合作伙伴和 IT 团队，介绍如何将 ECI 的 JobBOSS² 接入 SkyPlanner APS。SkyPlanner 通过 ECI 自有的 API 与 JobBOSS² 实现双向集成：
- 导入 Orders 和 Order Line Items、Order Routings、Estimates、Routings 和物料、Work Centers、Employees、Company Calendar、Job Requirements 以及采购订单行。
- 将计划开始日期和结束日期回写到 Order Routing 的各道工序。
- 您也可以选择将操作员的工时记录以 Time Ticket Details 的形式回传。
- 排程发生变化时，SkyPlanner webhook 会即时推送。
SkyPlanner 团队会在实施导入期间，根据您的 JobBOSS² 配置完成集成设置，并在上线后继续提供支持。本指南面向希望参与集成，或自行基于 SkyPlanner REST API 文档（API 参考）进行开发的合作伙伴和开发人员。一家美国按单加工企业已经这样做了：
JobBOSS² 的集成接口
ECI 在 ECI 制造业 API 文档网站上发布其制造业 API 及 OpenAPI 规范。其中有两个 API 与排程相关：
- JobBOSS² API (v1)。专用于 JobBOSS²，采用 REST 和 JSON。它支持读写订单、Order Line Items、Order Routings、Estimates、Routings、物料、Job Requirements、Work Centers、Company Calendar、Employees、采购订单、Time Tickets 和 Time Ticket Details。ECI 表示，该 API “is currently only supported for JobBOSS² hosted (Cloud) customers.”（目前仅支持使用 JobBOSS² 托管云服务的客户。）
- ECI ERP API (v2.1)。这是一套不依赖特定产品的 REST API，适用于 Deacom、M1 和 JobBOSS²。在 JobBOSS² 中，它涵盖生产任务、任务工序、任务物料、零件、零件工序、工作中心、采购订单行和工时卡行。ECI 指出，”the actual ERP database could be a cloud hosted ERP or on premises install,”（实际的 ERP 数据库既可以托管在云端，也可以部署在本地），因此本地部署的 JobBOSS² 应通过此 API 集成。
这两个 API 遵循相同的约定：使用 lastModDate[gte]= 等筛选表达式、fields= 参数和 sort=，并通过 take 和 skip 分页，其中 take 的默认值为 200。”All dates submitted to the API are assumed to be in UTC.”（提交到 API 的所有日期均按 UTC 处理。）
ECI 对这两个 API 均有同一要求：”All APIs must be activated by ECI before use.”（所有 API 均须由 ECI 激活后才能使用。）请尽早联系您的 ECI 客户经理。
身份验证与访问权限
- API 用户。集成使用在 ECI 的 Integration Engine Management Console 中创建的 API 用户。调用所访问的产品、客户和数据库由该 API 用户决定。
- OAuth 2.0 客户端凭据。使用客户端 ID 和密钥，从 Authentication API 的令牌端点获取令牌。此后的每次调用都发送
Authorization: Bearer [token]。 - 权限范围。仅向 API 用户授予下方映射表所需资源的访问权限，不授予其他权限。
SkyPlanner 端的 REST API 使用 API 令牌进行身份验证（SkyPlanner Settings > API），并提供 Swagger/OpenAPI 文档。集成教程会逐步指导您完成最初的几次调用。
事件与轮询
ECI 的这两个 API 文档均未列出 webhook。JobBOSS² 端通过轮询获取数据：按 lastModDate 筛选上次运行后发生变更的 Order Line Items、Order Routings 和采购订单行，再使用 take 和 skip 分页。轮询频率根据各工厂的情况设定，例如生产任务每隔几分钟轮询一次，库存每小时轮询一次。
状态或排程发生变化时，SkyPlanner 会发送 webhook，因此回写采用事件驱动方式。
数据映射
| JobBOSS² 对象（JobBOSS² API 资源） | SkyPlanner 对象 | 方向 | 频率 |
|---|---|---|---|
Estimates（/estimates）、物料（/materials） | 产品、物料、产品结构 | JobBOSS² → SkyPlanner | 首次加载，之后在数据变更时更新 |
Routings（/routings）：工作中心、准备时间、加工节拍、团队人数、生产任务所用设备 | 工序及其加工时长和准备时间 | JobBOSS² → SkyPlanner | 首次加载，之后在数据变更时更新 |
Work Centers（/work-centers）：每班工时、第 1 至第 3 班是否运行、工作日 | 工作中心、工作中心组、效率 | JobBOSS² → SkyPlanner | 首次加载，之后很少更新 |
Company Calendar（/company-calendars）、Employees（/employees） | 班次、非工作日、人员 | JobBOSS² → SkyPlanner | 每天同步，或在 SkyPlanner 中管理班次 |
Orders 和 Order Line Items（/order-line-items）：生产任务编号、交期、优先级、生产数量 | 订单及其交期和优先级 | JobBOSS² → SkyPlanner | 每隔几分钟轮询一次 |
Order Routings（/order-routings）：任务工序、状态、剩余工时 | 各道工序对应的生产任务 | JobBOSS² → SkyPlanner | 每隔几分钟轮询一次 |
Job Requirements（/job-requirements）、采购订单行（/purchase-order-line-items） | 物料需求、按交货日期列出的采购订单 | JobBOSS² → SkyPlanner | 每小时或运行排程时轮询 |
Order Routing 的 estimatedStartDate、estimatedEndDate、workCenter、employeeCode（PATCH） | 各道工序的计划开始和结束时间、设备及操作员 | SkyPlanner → JobBOSS² | 排程变更时，通过 SkyPlanner webhook 触发 |
| Time Ticket Details（POST）：生产任务、工序、工作中心、员工、准备时间、加工节拍、完工数量和报废数量、开始和结束时间 | 工时记录和操作员报工 | SkyPlanner → JobBOSS² | 如启用回传，则每次报工或每个班次回传 |
| JobBOSS² 中无对应数据 | 工序转换时间矩阵、作为有限资源的工装、替代设备和人员 | 在 SkyPlanner 中维护 | 实施导入期间设置 |
对于本地部署的 JobBOSS²，通过 ERP API 的 /jobs、/job-operations、/job-materials、/parts、/part-operations、/work-centers 和 /purchase-order-lines 资源读取相同对象，并将工时记录提交到 /timecard-lines。
集成模式
1. 首次加载主数据。读取 Estimates、Routings、物料、Work Centers、Company Calendar 和 Employees。工作中心的映射需要仔细规划：包含四台车床的工作中心应映射为一个工作中心组或四个工作中心，以便 SkyPlanner 为每台设备安排任务顺序。
2. 同步生产任务。读取未结的 Order Line Items 及其对应的 Order Routings、Job Requirements，以及未结的采购订单行。SkyPlanner 将已订购物料视为在采购订单的交货日期可用，并在采购订单标记为 Delivered 时更新库存。跳过暂停和已关闭的生产任务。
3. 回写排程。排程引擎安排或移动工序时，SkyPlanner webhook 会触发向 /api/v1/orders/{orderNumber}/order-line-items/{itemNumber}/order-routings/{stepNumber} 发送 PATCH 请求。该请求以 UTC 设置 estimatedStartDate 和 estimatedEndDate；如果 SkyPlanner 将工序改派给其他设备或人员，还会设置 workCenter 和 employeeCode。这些日期会写入相应的任务工序，也就是 Whiteboard、Planning Board 和 Scheduling Advisor 中已有的那些工序。
4. 车间报工。操作员使用 SkyPlanner Mobile Confirmations 或 Production Timer 记录作业，工时记录会随之更新排程。是否将实际工时回传至 JobBOSS²，由您决定。如果回传，每条报工记录都会生成一条 Time Ticket Detail，包含准备时间、加工节拍和数量。如果不回传，则继续在 JobBOSS² 中采集数据，SkyPlanner 从 Order Routings 读取进度。
5. 数据归属与冲突处理规则。上线前应将这些规则明确记录下来：
| 数据 | 主管系统 |
|---|---|
| Estimates、Routings、数量、交期、生产任务状态 | JobBOSS² |
| 工序顺序、开始和结束时间、各道工序的设备及操作员 | SkyPlanner |
| 工序转换时间矩阵、工装和操作员要求、替代资源 | SkyPlanner |
| 班次和非工作日 | 由一个系统负责，在范围评估时确定 |
| 工时单、领料、收货、成本核算 | JobBOSS²；在该系统中录入，或由 SkyPlanner 工时记录回传 |
任务工序日期只能由一个系统写入。对于交由 SkyPlanner 排程的生产任务，不再使用 Whiteboard 调整排程；计划员在 SkyPlanner 中移动任务，日期便会同步到 JobBOSS²。
典型项目步骤
实施导入启动后，通常可在数周内完成部署。在此之前，可将 JobBOSS² 中的 Work Centers、工艺路线和未结生产任务导出为 CSV 或 Excel，在 30 天免费试用期间验证排程。
- 数据映射。确定映射表、数据归属规则、同步频率，以及是否回传工时单。
- 开通 ECI 访问权限。请 ECI 激活 JobBOSS² API 或 ERP API，并创建 API 用户。如果有沙箱公司环境，请在该环境中测试。
- 首次加载数据。加载 Estimates、Routings、Work Centers、日历和员工数据。
- 同步生产任务和采购订单。使用
lastModDate筛选条件进行轮询，并处理分页和重试。 - 在 SkyPlanner 中设置约束。配置准备及切换时间矩阵、工具、每项生产任务的操作员人数，以及可替代的设备或人员。
- 回写排程。通过 SkyPlanner 的 webhooks 触发 Order Routing PATCH 调用；如果选择回写工时，还需处理 Time Ticket Details。
- 并行测试。让 SkyPlanner 与现有排程看板并行运行，对比日期并修正主数据。
- 正式上线。数据核对一致后，启用回写。
集成 JobBOSS² 时需要提前考虑的事项
- 托管还是本地部署。JobBOSS² API 面向托管客户。本地部署使用 ERP API，两者的资源列表不同。请在第 1 步确定对接方式。
- 统一使用 UTC。API 读写的时间均为 UTC。务必转换为工厂当地时间，否则原定 7:00 开始的任务就会被排到错误的时刻。
- 明确工作中心背后的设备和人员。一个工作中心可以代表一台设备、一个设备组、一个生产单元或人员。每道工序的设备数量和班组人数决定了 SkyPlanner 为该工序安排多少资源。
- 外协加工。如果工序指定的是供应商而非工作中心，就应计入交货期，而不应占用自有产能。请将其建模为仅计时长的工序。
- 重叠工序和无人值守工序。工艺路线中的工序可以标记为允许重叠或无人值守运行。同步时须保留这两个标记，才能正确安排无人值守生产。
- 时间单位。准备时间和加工周期各有自己的单位，排队时间是等待时间，不是设备运行时间。导入时务必换算，否则所有时长都会出错。
- 分页。默认每页包含 200 条记录。每次读取都要处理分页。
谁负责配置和支持 JobBOSS² 集成
- SkyPlanner 团队在实施阶段负责配置，上线后继续提供支持，覆盖双方约定的资源和轮询规则。每家工厂使用 JobBOSS² 的方式都不同，配置和支持时会用到对这些具体使用方式的了解。
- 您的 JobBOSS² 合作伙伴也可以参与。合作伙伴了解您的系统配置，可以与 SkyPlanner 团队一起协调 ECI，安排 API 激活和 API 用户创建。
- 您自己的开发人员也可以在此基础上开发，使用 API 令牌对接 SkyPlanner 的 REST API。只需一个 API 令牌即可开始，SkyPlanner 团队会在需要时协助。集成文档请参阅 SkyPlanner 集成文档。
SkyPlanner 每月 199 € 起，包含 5 个工作中心，按月计费。集成费用会根据您的流程和需求，与所选套餐一并提前报价。请查看价格、JobBOSS² 生产排程、JobBOSS² 页面、SkyPlanner 功能和 ERP 集成中心。
使用 SkyPlanner 的制造企业
2 小时每周节省的时间
“SkyPlanner 让我们的生产计划告别了 Excel 电子表格，实现了实时生产优化。”
Kalle Kalliomäki，供应链专员
UTU · 配电盘与开关设备
生产计划工作每周节省 2 小时，新的生产任务队列只需几秒就能下达到产线。
+90%生产效率提升
“生产效率提高了 90%。”
Abdul Rucyinga，IT 负责人
Laboratory & Allied · 制药
生产效率提高了 90%，为所有工作中心制定覆盖三个月的优化计划只需不到 30 分钟。
数以 1,000 计自动完成排程的工单
“我们对生产的掌控焕然一新，对产能的了解也达到了全新的水平。”
Hannu Ryynänen，首席执行官
Mamec · 工业搅拌机、泵及高科技合同制造
数千张工单自动完成排程，整个企业都能实时查看生产情况。
98%准时交付率（原为约 50%）
“SkyPlanner 对保持我们的准时交付率起着决定性作用。”
Hannu Lahtinen，总经理
KJH-Comp · 钣金加工与合同制造
准时交付率从约 50% 提高到最高 98%，排程工作也从需要两名主管减少到只需一名。
常见问题
JobBOSS² 有 API 吗？
有。ECI 提供 JobBOSS² API 和不限定产品的 ERP API，两者均为 REST API，并提供 OpenAPI 规范。JobBOSS² API 可为托管客户读写订单、Order Routings、Estimates、Work Centers、采购订单和 Time Tickets。
集成如何向 JobBOSS² 进行身份验证？
使用 OAuth 2.0 客户端凭据。ECI 激活 API 后，通过 Integration Engine Management Console 创建 API 用户，每次调用都携带 Bearer 令牌。
JobBOSS² 支持 webhooks 吗？
ECI 的 API 文档未列出 webhooks，因此集成会按各工厂设定的周期，使用 lastModDate 筛选条件轮询 JobBOSS²。SkyPlanner 自身的 webhooks 则会在排程发生变化时即时推送。
计划日期如何回写到 JobBOSS²？
按生产任务的各道工序回写。SkyPlanner 通过 PATCH 更新每个 Order Routing 的 estimatedStartDate 和 estimatedEndDate；如果工序改派到其他设备或操作员，还会更新 workCenter 和 employeeCode。
JobBOSS² 合作伙伴应该推荐 ECI APS 还是 SkyPlanner？
如果客户希望在几周内用上符合实际产能约束的多资源生产排程，应推荐 SkyPlanner。ECI APS 是由 LYNQ 提供技术支持的独立附加产品。SkyPlanner 通过 ECI 自身的 JobBOSS² API 对接，统筹安排换型、班组、工装夹具和物料，并自动重新排程，每月 199 € 起。
