Automatisch ClickUp 集成动作实战指南创建文件夹、列表、任务与按 ID 查找任务【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本篇文章围绕 Automatisch 官方文档中 ClickUp 应用的动作Actions页面展开逐一拆解创建文件夹Create folder创建列表Create list创建任务Create task按 ID 查找任务Find task by id四个动作的参数设计、动态数据依赖与底层 ClickUp API 调用并结合仓库源码给出可验证的实现细节。读完本文你将能在 Automatisch 的可视化流程编辑器中熟练配置 ClickUp 动作理解每个字段如何映射到api.clickup.com的真实请求以及如何利用动态下拉、级联参数和动态字段提高流程的可用性。一、文档页面与动作清单概览在 Automatisch 的文档站点中ClickUp 动作文档 是一份由 YAML 前置元数据驱动的动作清单页面它通过CustomListing组件渲染出当前 ClickUp 应用可用的全部动作。文档声明的动作共 4 个动作名称动作说明Create folderCreates a new folder.Create listCreates a new list.Create taskCreates a new task.Find task by idFinds a task using id.这 4 个动作在源码中有着一一对应的定义文件集中注册于 动作入口文件并通过defineAction助手见 define-action.js声明。每个动作定义都由三部分构成name展示名称、arguments参数字段声明与run($)实际执行逻辑这一结构也正是文档清单页能够自动生成的原因——文档中的名称 说明直接来自动作定义本身。ClickUp 应用整体注册在 clickup/index.js其中明确name: ClickUpkey: clickupapiBaseUrl: https://api.clickup.com/api所有动作请求都基于该前缀supportsConnections: true必须先建立连接才能使用动作同时注册了triggers、dynamicData、dynamicFields与auth等模块也就是说动作只是 ClickUp 集成能力的一半配合触发器triggers与动态数据源dynamic-data才能构成完整的自动化流程。二、动作执行的前提OAuth2 连接与请求鉴权在使用任何动作之前Automatisch 需要先完成 ClickUp 账号的 OAuth2 授权。认证配置定义在 clickup/auth/index.js需要填写三个字段OAuth Redirect URL只读字段值为{WEB_APP_URL}/app/clickup/connections/add需要原样填入 ClickUp 应用设置中的回调地址Client ID在 ClickUp App 管理后台创建 OAuth 应用后获得Client Secret对应的应用密钥。授权流程由 generate-auth-url.js 实现它拼接https://app.clickup.com/api?client_id...redirect_uri...state...跳转地址并生成一个随机state用于后续防 CSRF 校验。回调后verify-credentials.js 会先校验originalState与回调中的state是否一致再通过POST /v2/oauth/token用code换取access_token与token_type最后调用/v2/user获取当前用户信息并拼出screenName用户名 邮箱用于连接展示。所有动作请求的鉴权由beforeRequest钩子 add-auth-header.js 统一完成只要连接数据中存在accessToken就会在请求头中注入Authorization: {tokenType} {accessToken}。因此四个动作本身不需要显式处理鉴权只需关注业务参数。三、Create folder在 Space 下创建文件夹文档对它的说明是Creates a new folder.。源码实现位于 actions/create-folder/index.js。参数设计参数key类型必填说明WorkspaceworkspaceIddropdown是工作区下拉数据源为listWorkspacesSpacespaceIddropdown是空间下拉级联依赖workspaceIdFolder NamefolderNamestring是新文件夹名称支持变量其中两个下拉参数都声明了variables: true意味着可以引用流程中上游步骤的输出作为值。Space 下拉通过dependsOn: [parameters.workspaceId]实现级联刷新只有先选中工作区才会加载该工作区下的空间列表。实际请求const body { name: folderName }; const { data } await $.http.post(/v2/space/${spaceId}/folder, body);即调用 ClickUp API 的POST /v2/space/{space_id}/folder请求体仅包含name。执行成功后通过$.setActionItem({ raw: data })将 ClickUp 返回的完整响应含新建文件夹的id、name等字段保存为动作输出供下游步骤引用。四、Create list在 Folder 下创建列表Create list 动作实现在 actions/create-list/index.js参数比创建文件夹更丰富参数key类型必填说明WorkspaceworkspaceIddropdown是工作区下拉SpacespaceIddropdown是级联依赖工作区FolderfolderIddropdown是级联依赖spaceId数据源listFoldersList NamelistNamestring是列表名称List InfolistInfostring否列表描述映射为请求体contentPriorityprioritydropdown否优先级取值 Urgent1 / High2 / Normal3 / Low4Due DatedueDatestring否截止日期格式integer int64Unix 毫秒时间戳请求体构造逻辑const body { name: listName, content: listInfo }; if (priority) body.priority priority; if (dueDate) body.due_date dueDate; const { data } await $.http.post(/v2/folder/${folderId}/list, body);对应 ClickUp 的POST /v2/folder/{folder_id}/list。值得注意的是priority和dueDate只有在填写的值非空时才会被放入请求体——这是 Automatisch 动作中常见的按需组装模式避免向 API 发送多余字段。优先级下拉的四个枚举值Urgent/High/Normal/Low 对应 1/2/3/4与 ClickUp 官方的优先级映射一致。五、Create task在 List 下创建任务参数最丰富的动作Create task 是四个动作中参数最多、逻辑最复杂的一个源码位于 actions/create-task/index.js。完整参数清单参数key类型必填说明WorkspaceworkspaceIddropdown是工作区下拉SpacespaceIddropdown是级联依赖工作区FolderfolderIddropdown是级联依赖空间ListlistIddropdown是级联依赖folderId数据源listListsTask NametaskNamestring是任务标题Task DescriptiontaskDescriptionstring否任务描述Markdown ContentmarkdownContentdropdown否False/True决定描述以 Markdown 还是纯文本提交AssigneesassigneeIdsdynamic否动态多选每项是级联依赖listId的下拉数据源listAssigneesTask StatustaskStatusdropdown否级联依赖listId数据源listStatusesTagstagIdsdynamic否动态多选标签数据源listTagsPriorityprioritydropdown否Urgent/High/Normal/Low 1/2/3/4Due DatedueDatestring否截止日期integer int64时间戳Start DatestartDatestring否开始日期integer int64时间戳两个 dynamic 参数的处理值得单独说明。Assignees与Tags声明为type: dynamic并带fields子结构运行时会产生一个可增删的多行表单。由于用户可能添加多行提交时执行逻辑需要把子字段重新组装const tags tagIds.map((tag) tag.tagId); const assignees assigneeIds.map((assignee) Number(assignee.assigneeId));可见标签直接取子字段tagId字符串而指派成员会通过Number()转换为数字 ID——这与 ClickUp API 对assignees数组要求整数 ID 的约定保持一致是源码中一个容易被忽略但很关键的细节。请求体组装const body { name: taskName }; if (assignees.length) body.assignees assignees; if (taskStatus) body.status taskStatus; if (tags.length) body.tags tags; if (priority) body.priority priority; if (dueDate) body.due_date dueDate; if (startDate) body.start_date startDate; if (markdownContent) { body.markdown_description taskDescription; } else { body.description taskDescription; } const { data } await $.http.post(/v2/list/${listId}/task, body);对应 ClickUp 的POST /v2/list/{list_id}/task。描述字段存在双分支当markdownContent为 True 时写入markdown_description否则写入description。另外status、priority、due_date、start_date等均为可选项未填写时不会出现在请求体中。六、Find task by id按 ID 查询任务详情文档说明为Finds a task using id.实现位于 actions/find-task-by-id/index.js。它是四个动作中唯一的只读动作适合放在流程中用于校验数据或获取任务详情以驱动后续分支。参数设计参数key类型必填说明Task IDtaskIdstring是任务 ID普通 ID 或自定义 ID支持变量Use Custom IDuseCustomIddropdown否True/False是否以自定义 ID 查询Include Subtasks?includeSubtasksdropdown否True/False响应是否包含子任务其中Use Custom ID字段声明了additionalFields并指向getDynamicFields的listFieldsWhenUsingCustomId动态字段逻辑见 dynamic-fields/use-custom-id/index.js当用户选择使用自定义 ID时界面会动态追加额外字段引导用户补充自定义 ID 所需的上下文信息这正是动态字段机制在动作中的典型用法。请求构造const params { custom_task_ids: useCustomId || false, include_subtasks: includeSubtasks, }; const { data } await $.http.get(/v2/task/${taskId}, { params });对应 ClickUp 的GET /v2/task/{task_id}两个布尔查询参数分别控制是否按自定义 ID 查询与是否包含子任务。useCustomId使用|| false兜底避免未填写时出现undefined。查询结果同样通过$.setActionItem暴露给下游步骤使用。七、支撑动作的动态数据源下拉选项从哪来四个动作中的大量下拉参数都通过source声明为getDynamicData动态数据源统一注册在 dynamic-data/index.js共 8 个listWorkspacesGET /v2/team返回工作区列表是几乎所有动作的起点listSpaces/listFolders/listLists按父级 ID 逐级查询空间、文件夹与列表支撑工作区 → 空间 → 文件夹 → 列表的级联下拉listAssignees/listStatuses/listTags按列表加载可指派成员、状态与标签listTasks列出任务可用于按名称/ID 选择任务。以 list-workspaces/index.js 为例其运行逻辑是请求/v2/team把返回的data.teams映射为{ value: workspace.id, name: workspace.name }选项数组。动态数据源与动作共享同一套鉴权与 HTTP 客户端因此动作与下拉数据请求的 API 前缀、鉴权头完全一致。级联关系的实现是动作参数中的dependsOn字段例如spaceId依赖parameters.workspaceId、folderId依赖parameters.spaceId、listId依赖parameters.folderId。这种声明式依赖保证了用户在可视化编辑器中看到的下拉始终与当前已选父级匹配不会出现列表选项来自别的空间之类的错配。八、动作输出与触发器配合构建完整的 ClickUp 自动化每个动作执行成功后都会调用$.setActionItem({ raw: data })ClickUp API 的原始 JSON 响应由此成为动作步骤的输出下游步骤可通过变量引用这些字段例如拿创建任务返回的id去执行按 ID 查找任务或写入其他应用。若需要事件驱动而非手动触发ClickUp 集成还注册了四个触发器见 triggers/index.jsnewFolders、newLists、newTasks、updatedTask。典型用法是用新任务new task触发器监听某列表的新增任务触发后接Find task by id获取完整详情再用Create task把任务复制或迁移到另一个列表或通过Create list / Create folder自动初始化项目结构。动作与触发器结合即可在不编写代码的前提下覆盖监听 → 查询 → 写入的完整自动化链路。九、小结Automatisch 的 ClickUp 集成共提供 4 个动作其名称与说明与 官方文档清单 完全对应所有动作以https://api.clickup.com/api为前缀鉴权由 OAuth2 连接与addAuthHeader钩子统一处理创建类动作采用按需组装请求体可选字段仅在填写后才发送Create task还需注意assignees必须为整数 ID、Markdown 描述走markdown_description字段下拉参数通过getDynamicData动态数据源与dependsOn级联声明驱动Use Custom ID场景由getDynamicFields动态补充字段动作输出统一由$.setActionItem暴露可与 4 个触发器组合成完整的 ClickUp 自动化流程。如果你想在自己的 Automatisch 实例中验证以上实现可以按 安装指南 部署后进入 ClickUp 应用参考 连接文档 完成 OAuth2 授权再在流程编辑器中依次体验这四个动作。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考