Solavel 文档
中文

集成

最后更新

项目的集成选项卡用于将一个项目连接到其他系统:

  • 外发 Webhook将项目事件(创建任务、冲刺开始、创建文档……)推送到您拥有的 HTTPS 端点,并附带签名,以便接收方验证其可信性。
  • 传入 Webhook 令牌允许外部系统(表单工具、GitHub、脚本)在项目中创建任务或评论。
  • 公共 API令牌通过 SolaProjects API 授予其他系统对项目任务和工时的有范围限制的读取或写入权限。
  • 原生服务提供商就绪状态会显示预置连接(Slack、Microsoft Teams、GitHub、GitLab、Google Calendar、Google Drive、OneDrive、Zapier / IFTTT)及各连接是否可用。

当项目需要与其他工具交互,例如向客户仪表板发布任务更新,或将网站咨询转换为任务时,请使用它。项目经理和管理员负责设置;通常每个项目与 IT 联系人一起设置一次。

有两个页面名为集成。本页介绍项目选项卡。侧边栏工作区部分的集成项目(/projects/settings/integrations)是组织的SolaCount 连接 — 请参阅下文组织 SolaCount 连接及预算与财务。

#哪里可以找到

侧边栏 项目区域 → 集成(位于自动化与人工智能之间)
URL /projects/{project}/integrations
命令面板 集成 · {project name},位于当前项目之下

由谁查看:

  • 套餐:集成功能属于高级套餐(企业套餐也包含)。较低套餐会隐藏此选项卡。付费套餐到期后,该选项卡会消失,也不再提供 Webhook,直到续费。
  • 角色:只有能够编辑项目的人员才能加载该选项卡(参见权限)。其他人会看到"我们无法加载集成。"以及重试。

#屏幕导览

#标题卡片

集成 — 外发 Webhook、传入令牌以及投递历史。

卡片 含义
传出 有效的出站 Webhook。
传入令牌 有效且未撤销的传入令牌。
最近交付记录 投递尝试列在最近投递中。
投递失败 其中失败的尝试次数(大于零时显示为红色)。

#外发 Webhook 卡片

将项目事件以 HMAC-SHA256 签名后 POST 到外部 HTTPS 端点。 在右上角点击 新建 Webhook。

每张 Webhook 卡片显示名称、端点 URL、状态徽标(启用、禁用或已归档)、每个已订阅事件的标签,以及{n} 次投递 · {n} 次失败。行操作(已归档的 Webhook 除外):编辑、测试、轮换密钥、归档。

空状态:没有外发 Webhook — 创建一个以将事件推送到外部系统。

#传入 Webhook 令牌卡片

允许外部系统通过携带密钥令牌的 POST 请求创建任务/评论。请在右上角点击新建令牌。

每张令牌卡片:名称、提供方(自定义或GitHub)· 上次使用 {date}或从未使用,徽标为启用、停用或已撤销。操作(已撤销令牌除外):轮换、撤销。

空状态:没有传入令牌 — 创建一个令牌以接收入站 Webhook。

#公共 API 卡片

为已记录的项目、任务和工时记录端点创建有范围限制的持有者令牌。 按钮:文档(在新标签页中打开 OpenAPI 参考)和 新建令牌。

每张令牌卡片:名称、最后使用 {date} / 从未使用、状态徽章,以及每项权限一个标签。操作:轮换、撤销。

空状态:没有 API 令牌 — 为公共 API 创建一个令牌。

#最近交付卡片

外发投递尝试及其结果。 带有计数的徽标。

列 含义
触发时机 交付日期。
Webhook Webhook 名称,或 已归档的 Webhook。
活动 事件类型,例如 task.status_changed。
状态 已送达(绿色)、待处理(琥珀色,等待或重试中)、失败(红色)、已跳过。
尝试 SolaProjects 已尝试的次数。
响应 您的端点返回的 HTTP 状态码;若未收到响应则为错误,或为—。
(按钮) 对任何未投递成功的投递重试。

空状态:尚无投递记录 — 事件触发或您发送测试后,投递尝试会显示在此处。

#原生提供商就绪卡片

针对特定服务商集成的连接状态和设置前提条件。 每个服务商一个磁贴:

服务商 功能
Slack 向 Slack 发送项目通知,并从 Slack 接收任务指令。
Microsoft Teams 向 Teams 频道发送项目通知并支持 Teams 操作。
GitHub 将代码库事件、问题、拉取请求和提交链接到项目任务。
GitLab 将 GitLab 合并请求、问题和流水线事件链接到项目任务。
Google Calendar 将项目里程碑和任务日期同步到 Google Calendar。
Google Drive 将项目文档附加或同步到 Google Drive 文件夹。
OneDrive 将项目文档附加或同步到 OneDrive 文件夹。
Zapier / IFTTT 向无代码平台开放 SolaProjects 的触发器和操作。

每个卡片显示状态(可用、待处理、已启用、失败)、功能,以及已检测到正式服务商配置。或本地模拟器可用;生产凭据属于激活设置。(该服务商尚未在您的组织正式启用)。还可能显示因缺少设置而受阻:…、激活说明:…、OAuth 回调待处理。、最后错误:…、最后一条消息或最后收到的事件。

#您可以发送的事件

在 webhook 表单中勾选一个或多个:

活动 发送时间
task.created 创建任务(包括通过传入的 Webhook 创建)。
task.updated 任务被编辑。
task.status_changed 任务状态发生变化。
task.completed 任务被标记为完成。
task.blocked 任务被标记为阻塞。
comment.created 添加了任务评论。
doc.created 已创建项目文档。
time_entry.created 已记录工时。
milestone.completed 里程碑已完成。
sprint.started / sprint.completed 冲刺开始/完成时。
share_link.created 已创建访客共享链接。
automation.run_failed / automation.rule_failed 自动化运行失败。
ai.suggestion_applied 已应用 AI 建议。

每个请求都是 JSON POST,带有请求头X-SolaProjects-Event(事件类型)、X-SolaProjects-Delivery(投递 ID)、X-SolaProjects-Signature(使用签名密钥对原始请求体计算的 HMAC-SHA256)以及User-Agent: SolaProjects-Webhooks/1.0。信任请求前请先验证签名。

重试。失败的投递会在约 1、5、15 和 60 分钟后自动重试;第五次尝试后,它将保持失败状态。使用重试可手动再次尝试。

#任务

#创建传出 webhook

  1. 打开项目 → 集成 → 新建 Webhook。

  2. 填写新建外发 Webhook:

    字段 必填 规则 / 默认设置 注释
    名称 是的 最多 160 个字符。 例如 客户仪表板。
    端点 URL (HTTPS) 是的 有效的 URL,最多 2,048 个字符,必须为公开的 HTTPS。 占位符 https://example.com/hooks/solaprojects。本地和专用网络地址会被拒绝:"请使用公共 HTTPS 端点。本地和专用网络 URL 已被阻止。"
    事件 是的 至少一项。 参见上方表格。
    活跃 — 默认勾选。 取消勾选可将其保存为 已禁用。
  3. 点击创建。您会看到传出 Webhook 已创建。及签名密钥对话框:“请立即保存 — 仅显示一次,之后无法再次获取。” 点击复制(已复制到剪贴板。),将密钥保存到接收系统,然后点击完成。

#编辑、测试、轮换和归档 Webhook

行动 步骤 结果
编辑 更改名称、URL、事件,或将启用 → 保存。 传出 Webhook 已更新。
测试 点击测试。 测试投递已排队。 一行记录会出现在 最近投递 中。
轮换密钥 确认 轮换密钥 ——“当前密钥将停止工作。请使用新密钥更新已连接的服务。” 密钥已轮换。 新密钥只显示一次。
存档 确认 归档 Webhook ——“此传出 Webhook 将停止推送项目事件。” Webhook 已归档。徽章显示已归档;不再投递;历史记录保留。

#创建传入 webhook 令牌

  1. 在 传入 Webhook 令牌 上点击 新建令牌。
  2. 名称(必填,最多 160 个字符)以及 提供方:自定义(默认)或 GitHub。
  3. 点击创建 → 入站令牌已创建。请复制仅显示一次的入站 Webhook 令牌:“将此作为入站 Webhook URL 中的令牌使用。仅显示一次。”

外部系统随后会发送 POST /api/projects/webhooks/incoming/{token},请求体为 JSON(每个发送方每分钟限 60 次请求):

服务商 正文 发生的事情
自定义 {"title": "...", "description": "...", "priority": "high"} 在 待办 中创建一个私人任务(优先级默认为 medium;标题最多 180 个字符)。响应中包含新的 task_key。
自定义 {"task_key": "ALN-14", "comment": "..."} 为该任务添加一条内部评论。
GitHub 签发或签发评论事件 问题会转为任务;若问题标题中包含任务编号(例如 ALN-14),其评论会成为该任务的评论。

其他任何请求都会被拒绝,并显示“Webhook rejected.”;已撤销或错误的令牌会得到相同的响应。任务和评论由创建该令牌的人员署名。

轮换会签发新令牌并立即撤销旧令牌(令牌已轮换。)。撤销会询问撤销令牌 — “使用此令牌的请求将不再具有访问权限。” → 令牌已撤销。

#创建公共 API 令牌

  1. 在 公共 API 上点击 新建令牌。

  2. 名称(必填,最多 120 个字符)以及 权限(至少一项;projects:read、tasks:read 和 time:read 已默认勾选):

    能力 允许
    projects:read 阅读此项目。
    tasks:read / tasks:write 读取 / 创建和更新任务。
    time:read / time:write 读取 / 创建工时记录。
  3. 创建 → API 令牌已创建。 复制 项目 API 令牌:“将此作为 /api/v1 的 Bearer 令牌使用。仅显示一次。”

通过 API 创建的任务会触发与应用内创建任务相同的自动化和 webhook。轮换 → 确认轮换令牌(“当前令牌将停止工作。请使用新令牌更新已连接的服务。”)→ API 令牌已轮换。撤销 → API 令牌已撤销。

#重试失败的发送

在最近交付中,点击该行的重试 → 已重试交付。稍后查看状态和响应。

#连接原生服务提供商

  1. 在提供商卡片上选择渠道(例如 Slack 的#projects),然后点击连接 → {Provider} 连接已开始。
  2. 在授权对话框中完成 {Provider} 授权,点击 完成回调(或 稍后)→ 原生集成已连接。
  3. 连接后,可使用发送测试({Provider} 测试消息已发送。)、刷新({Provider} 已刷新。)或断开连接({Provider} 已断开连接。)。

模拟器模式下的卡片还会显示 模拟事件 和 错误,用于在提供商正式上线前检查设置;它们不会连接真实服务。

#状态

对象 状态
外发 Webhook 启用、已禁用(取消勾选“启用”后保存)、已归档
发货 待处理、已送达、失败、已跳过
传入 / API 令牌 启用、停用、已撤销
原生提供商 可用、待处理、活动、失败

#权限

角色 打开该选项卡 创建 / 更改 webhooks、令牌、提供商
组织所有者 是的 是的
项目管理员 是的 是的
在此担任项目经理的项目经理 是的 是的
项目成员、项目查看者、访客 否 否

如果组织停用了集成编辑,标签页为只读(没有新建、行操作或重试)。更改被拒绝时会显示“集成编辑已停用或您没有权限。”;页面过时时会显示“请刷新后重试。”一次性对话框关闭后,密钥和令牌不会再次显示,即使所有者也无法查看。

#组织 SolaCount 连接

工作区侧栏的集成(/projects/settings/integrations)是另一个页面。它显示 SolaProjects 是否连接到 SolaCount(已连接、可连接、集成已暂停、已断开连接——保留历史记录等),并允许组织所有者或财务管理员连接、暂停、断开或检查连接。单个项目可在其设置选项卡中选择不使用财务集成(集成卡片 → 内部项目/财务已禁用)。参见预算与财务及 SolaProjects 概览。

#操作示例

#示例 1 — 询价转为任务(日常)

{User 1 name} 希望 {Showroom project name}(DEMO-FIT)的网站咨询能够转为任务。

  1. 新建令牌 → 名称 网站咨询,提供方 自定义 → 创建;她将令牌交给网站开发人员。
  2. 网站过账 {"title": "Quote request – reception desk", "priority": "high"}。
  3. 任务ALN-31 报价请求 – 前台出现在待办中,为私有,优先级为高。令牌卡显示上次使用 10 月 6 日。

#示例 2 — 客户仪表板数据推送出现故障(完整场景)

{User 2 name} 连接 {Organization name} 的站点仪表板。

步骤 行动 结果
1 新建 Webhook:站点仪表板,https://hooks.company.example.com/projects,事件 task.status_changed,task.completed,milestone.completed。 外发 Webhook 已创建。签名密钥已复制到仪表板。
2 测试。 测试投递已排队。;该行 已投递,响应 200。
3 {User 1 name} 将 ALN-12 移至已完成。 两次交付:task.status_changed和task.completed,均为已交付。
4 仪表板因维护而暂时不可用。 下一次交付显示待处理,然后显示失败,响应为 503;页眉中以红色显示失败交付 1;大约在 1、5、15、60 分钟后重试。
5 仪表板返回;{User 2 name} 点击 重试。 已重试投递。 → 已送达。
6 IT 怀疑密钥已泄露。{User 2 name} 点击轮换密钥并确认。 密钥已轮换。;新密钥只显示一次;IT 部门更新仪表板。

#连接方式

位置 链接
任务 传入令牌和 API 可创建任务和评论;任务变更会发送事件。
规划 里程碑完成以及冲刺开始/完成会发送事件。
自动化 在 SolaProjects 内操作;失败的运行可以作为事件发出。
访客共享链接 share_link.created 事件。
人工智能 ai.suggestion_applied 事件。
工时跟踪 time_entry.created 事件;时间 API 权限。
设置 按项目的 SolaCount 财务开关。

#提示与常见问题

问题 原因 解决方法
缺少标签页。 套餐低于 Premium 或已过期。 升级或续订。
使用公共 HTTPS 端点… URL 为 http、localhost 或私有地址。 请使用公开的 HTTPS 网址。
丢失了密钥或令牌。 仅显示一次。 轮换,并更新其他系统。
投递以 4xx 代码失败。 您的端点拒绝了该请求(通常是签名校验失败)。 请检查端点是否使用当前密钥。
Webhook 已拒绝。传入调用时。 令牌已撤销或错误,或请求正文中没有 title 或 task_key + comment。 检查令牌和请求体。
评论未从 GitHub 添加。 问题标题中没有任务键。 在问题标题中填写密钥(例如 ALN-14)。
API 返回访问被拒绝。 令牌缺少相应权限或已被撤销。 创建具有适当权限的令牌。
提供方显示 本地模拟器可用… 您的组织尚未正式启用。 请联系 Solavel 支持人员咨询激活事宜。