<!-- TIER:1 -->
<!-- TIER:1 -->
Using Marketplace Templates
使用Marketplace Template
The Celigo Marketplace is a catalog of pre-built integration blueprints -- packaged flows, exports, imports, connections, and scripts you can browse, install, or reuse instead of building from scratch. Each listing is one of three kinds: a Template, an Integration App (IA), or an AI Agent. Most decisions come down to Templates vs Integration Apps.
Celigo Marketplace是预构建集成蓝图的目录——包含打包好的流程、导出、导入、连接和脚本，您可以浏览、安装或复用这些资源，无需从头构建。每个条目分为三类：Template、Integration App (IA)或AI Agent。大多数决策围绕Template与Integration App的选择展开。
Templates vs Integration Apps
Template与Integration App对比
Templates are open, customizable blueprints. Every flow, export, import, and script ships into your account as your own editable resource -- rename, restructure, or rewrite anything. The trade-off: templates receive no ongoing updates. A template is a starting point, not a maintained product; if the source application's API changes, you carry the fix.
Integration Apps (IAs) are vendor-maintained, structure-locked products. Their core flows, mappings, and logic are upgrade-protected so Celigo (or a partner) can ship updates without breaking your customizations. The trade-off: you configure only what the IA exposes (settings, mappings, endpoints) and can't rewrite the core -- in exchange you inherit bug fixes and new features over time.
Choosing wrong has opposite failure modes: pick a template when you needed an IA and you own the integration forever with no upstream fixes; pick an IA when you needed a template and you hit the locked-component ceiling the moment you must customize beyond what it exposes. When unsure, list both and compare.
AI Agents are a third listing type -- browse them in the marketplace to see what's available.
Template是开放、可定制的蓝图。每个流程、导出、导入和脚本都会作为您可编辑的资源导入到您的账户中——您可以重命名、重构或改写任何内容。缺点是：Template不接收持续更新。Template只是一个起点，而非维护型产品；如果源应用的API发生变化，您需要自行修复。
Integration App (IA)是由供应商维护、结构锁定的产品。其核心流程、映射和逻辑受升级保护，因此Celigo（或合作伙伴）可以推送更新而不会破坏您的自定义内容。缺点是：您只能配置IA公开的内容（设置、映射、端点），无法改写核心逻辑——但作为交换，您可以长期继承漏洞修复和新功能。
选择错误会导致相反的问题：当您需要IA却选择了Template，您将永久负责集成维护且无法获得上游修复；当您需要Template却选择了IA，一旦您必须进行超出其公开范围的自定义，就会遇到锁定组件的限制。不确定时，可同时列出两者进行对比。
AI Agent是第三种条目类型——您可以在市场中浏览查看可用的AI Agent。
Whole Install vs Single-Element Copy
完整安装与单个元素复制
Two distinct operations, separated by intent:
- Whole-template install creates a brand-new integration containing fresh copies of every resource in the blueprint. Intent: "set up the whole integration." This runs in the Celigo Marketplace UI installer on the listing's preview page.
- Single-element copy drops ONE element -- a flow, export, import, connection, or script -- plus everything it depends on, into an integration you already have. Intent: "borrow one piece."
Recognize intent from wording: "install the X template" / "set up X from a template" -> whole install; "copy the Y flow from the X template" / "I just want the customer export" -> single-element copy.
这是两种不同的操作，意图各不相同：
- 完整模板安装会创建一个全新的集成，包含蓝图中所有资源的全新副本。意图：“搭建完整集成”。此操作在条目预览页面的Celigo Marketplace UI安装程序中运行。
- 单个元素复制会将一个元素——流程、导出、导入、连接或脚本——及其所有依赖项，添加到您已有的集成中。意图：“借用单个组件”。
可通过措辞判断意图：“安装X模板”/“从模板搭建X”-> 完整安装；“从X模板复制Y流程”/“我只需要客户导出功能”-> 单个元素复制。
What Gets Copied vs Mapped
复制与映射的区别
When resources land in your account, they fall into two camps:
- Copied -- flows, exports, imports, scripts, lookup caches, and response mappings become fresh resources you own. There is no link back to the blueprint: editing them doesn't touch the source, and editing the source wouldn't touch them.
- Mapped -- connections are never copied. The blueprint's connection ids are placeholders; install and copy resolve each one to a real account connection -- reusing a match (same type + endpoint shape) or creating a new one. Connections are shared resources, so copying them would just duplicate credentials pointing at the same endpoint.
A single-element copy pulls the full dependency cascade: copying a flow brings its exports, imports, scripts, and lookup exports -- each dragging in its connection (mapped) and hook scripts -- so you get a runnable element, not a half-wired fragment.
资源导入到您的账户后分为两类：
- 复制——流程、导出、导入、脚本、查找缓存和响应映射会成为您拥有的全新资源。与蓝图无关联：编辑这些资源不会影响源蓝图，编辑源蓝图也不会影响它们。
- 映射——连接永远不会被复制。蓝图中的连接ID是占位符；安装和复制操作会将每个占位符解析为真实的账户连接——复用匹配的连接（相同类型+端点结构）或创建新连接。连接是共享资源，复制它们只会生成指向同一端点的重复凭据。
单个元素复制会提取完整的依赖链：复制流程会同时导入其导出、导入、脚本和查找导出——每个资源都会关联其映射的连接和钩子脚本，因此您得到的是可运行的完整元素，而非半连接的片段。
Templates vs Integration Apps
Template与Integration App对比
| Dimension | Templates | Integration Apps (IAs) |
|---|
| After install | Fully unlocked -- every resource is yours to edit | Structure-locked -- core flows/mappings/logic are upgrade-protected |
| Ongoing updates | None -- a starting point you maintain | Vendor-maintained -- receives bug fixes and new features |
| Customization | Rename, restructure, rewrite anything | Configure only what the IA exposes (settings, mappings, endpoints) |
| If the source API changes | You fix it yourself | The vendor ships the update |
| Best for | A fast start you'll own and adapt | A supported product you don't need to rewrite |
| Install path | Marketplace UI installer (preview page) | Marketplace UI installer (multi-step wizard) |
| Single-element copy | Supported -- pull one element into your integration | Installed as a whole product |
| 维度 | Template | Integration App (IA) |
|---|
| 安装后状态 | 完全解锁——所有资源均可由您编辑 | 结构锁定——核心流程/映射/逻辑受升级保护 |
| 持续更新 | 无——您需自行维护的起点 | 供应商维护——接收漏洞修复和新功能 |
| 自定义权限 | 可重命名、重构、改写任何内容 | 仅能配置IA公开的内容（设置、映射、端点） |
| 源API变更时 | 您需自行修复 | 供应商推送更新 |
| 最佳适用场景 | 快速启动后由您自行持有和调整的集成 | 无需改写核心逻辑的受支持产品 |
| 安装路径 | Marketplace UI安装程序（预览页面） | Marketplace UI安装程序（多步骤向导） |
| 单个元素复制 | 支持——将单个元素拉入您的集成 | 仅支持完整产品安装 |
Whole Install vs Single-Element Copy
完整安装与单个元素复制对比
| Whole-template install | Single-element copy |
|---|
| Result | Brand-new integration with fresh copies of everything | One element (+ its dependencies) added to an existing integration |
| Runs in | Celigo Marketplace UI installer | Marketplace UI (into a chosen integration) |
| Connections | Mapped during the installer | Mapped to existing or newly created connections |
| Use when | You want the entire integration | You want to borrow one piece |
| 完整模板安装 | 单个元素复制 |
|---|
| 结果 | 包含所有资源全新副本的全新集成 | 向现有集成添加一个元素（及其依赖项） |
| 运行环境 | Celigo Marketplace UI安装程序 | Marketplace UI（选择目标集成） |
| 连接处理 | 安装程序中完成映射 | 映射到现有连接或新建连接 |
| 使用场景 | 您需要完整的集成 | 您只需借用单个组件 |
Start From a Blueprint vs Build From Scratch
从蓝图开始 vs 从头构建
| Situation | Do this |
|---|
| A listing matches your source + destination and you want a fast start you'll own | Install a Template |
| You want a supported, auto-updated product and don't need to rewrite core logic | Install an Integration App |
| You only need one flow or step from an otherwise-unfit blueprint | Copy that single element into your integration |
| No listing matches, or requirements are highly custom | Build from scratch |
| 场景 | 操作建议 |
|---|
| 条目匹配您的源端+目标端，且您需要一个可自行持有的快速启动方案 | 安装Template |
| 您需要受支持、自动更新的产品，且无需改写核心逻辑 | 安装Integration App |
| 您只需要某个不匹配蓝图中的单个流程或步骤 | 将该单个元素复制到您的集成中 |
| 无匹配条目，或需求高度定制 | 从头构建 |
- getting-started > Build Order -- where installing from a blueprint fits versus building bottom-up
- managing-integrations -- a whole-template install lands as a new integration you then organize and promote
- configuring-connections > Quick Reference -- connections are mapped, not copied; verify or create the ones an install needs
- building-flows > How to Build a Flow -- edit or extend a flow after it lands in your account
- configuring-exports > Quick Reference -- exports pulled in by the dependency cascade
- configuring-imports > Quick Reference -- imports pulled in by the dependency cascade
- writing-scripts > Quick Reference -- hook scripts copied alongside flows and steps
<!-- TIER:2 -->
- getting-started > Build Order —— 从蓝图安装与自下而上构建的适配场景
- managing-integrations —— 完整模板安装会生成新集成，您可对其进行组织和推广
- configuring-connections > Quick Reference —— 连接采用映射而非复制；验证或创建安装所需的连接
- building-flows > How to Build a Flow —— 资源导入账户后编辑或扩展流程
- configuring-exports > Quick Reference —— 依赖链中导入的导出资源
- configuring-imports > Quick Reference —— 依赖链中导入的导入资源
- writing-scripts > Quick Reference —— 随流程和步骤一同复制的钩子脚本
<!-- TIER:2 -->
How to Use a Marketplace Template
如何使用Marketplace Template
1. Check what already exists
1. 检查现有资源
Before installing anything, search the account so you don't duplicate an integration or connection you already have.
bash
celigo account search "<keyword>"
安装任何内容前，先搜索账户，避免重复创建已有的集成或连接。
bash
celigo account search "<keyword>"
2. Browse the marketplace
2. 浏览Marketplace
List catalog entries and note whether each is a Template or an Integration App.
bash
celigo marketplace list
celigo marketplace list --type template
UI (primary): the Marketplace UI is the primary place to browse and install -- open the listing's preview page there.
列出目录条目，记录每个条目是Template还是Integration App。
bash
celigo marketplace list
celigo marketplace list --type template
UI（首选）： Marketplace UI是浏览和安装的主要平台——打开条目的预览页面即可操作。
3. Decide: Template, Integration App, or build from scratch
3. 决策：Template、Integration App还是从头构建
Use the
Quick Reference tables. Key questions:
- Do you need ongoing vendor updates (-> Integration App) or full control (-> Template)?
- Do you need the whole integration (-> install) or one piece (-> copy)?
- Does anything even match (-> otherwise build from scratch)?
- 您需要持续的供应商更新（-> Integration App）还是完全控制权（-> Template）？
- 您需要完整集成（-> 安装）还是单个组件（-> 复制）？
- 是否存在匹配的条目（-> 否则从头构建）？
4. Preview before you install
4. 安装前预览
Inspect the blueprint's contents and the connections it expects before committing.
bash
celigo templates preview <id> --summary
celigo templates preview <id> --model Connection
提交安装前，检查蓝图的内容和所需的连接。
bash
celigo templates preview <id> --summary
celigo templates preview <id> --model Connection
5. Install a whole template or Integration App
5. 安装完整Template或Integration App
Whole-template and IA installs run in the Celigo Marketplace UI installer on the listing's preview page. The installer walks the multi-step wizard: mapping or creating connections, accepting the license, selecting a plan, and configuration.
Programmatic whole-install is not reliable. The simple install API (
POST /v1/integrations/template/{id}
with a
body) succeeds only for simple single-integration templates; most published blueprints ship as multi-step installers and are rejected. Use the UI installer.
完整Template和IA安装在条目预览页面的Celigo Marketplace UI安装程序中运行。安装程序会引导您完成多步骤向导：映射或创建连接、接受许可、选择方案、配置设置。
程序化完整安装并不可靠。简单安装API（
POST /v1/integrations/template/{id}
并携带
请求体）仅适用于简单的单集成Template；大多数已发布的蓝图为多步骤安装程序，会被API拒绝。请使用UI安装程序。
6. Or copy a single element
6. 或复制单个元素
When you only need one piece, copy that element into an existing integration. The copy pulls the element's full dependency cascade and maps its connections to your account's connections -- reusing a match or creating a new one. Choose the target integration up front; if you don't, the element lands standalone.
Copying a flow may create a flow grouping on the target through Celigo's staged-changes review. Accept the staged change in the UI before the grouping is usable, then continue.
当您只需要单个组件时，将该元素复制到现有集成中。复制操作会提取元素的完整依赖链，并将其连接映射到您账户中的连接——复用匹配的连接或创建新连接。提前选择目标集成；如果未选择，元素将作为独立资源导入。
复制流程可能会通过Celigo的staged-changes审核在目标集成中创建流程分组。在分组可用前，需在UI中接受暂存变更，然后继续操作。
7. Map connections, satisfy settings, then enable
7. 映射连接、填充设置并启用
After resources land in your account:
- Verify each mapped connection points at the right account connection (see configuring-connections).
- Populate any settings references the blueprint expects (e.g.,
{{settings.integration.region}}
- Verify structure, confirm sandbox vs production matches your environment, then enable the flows. Everything installed or copied is now an ordinary editable resource (IA core components remain locked).
资源导入账户后：
- 验证每个映射的连接指向正确的账户连接（参考连接配置文档）。
- 填充蓝图所需的所有设置引用（例如
{{settings.integration.region}}
- 验证结构，确认沙箱与生产环境匹配您的环境，然后启用流程。所有安装或复制的资源现在都是可编辑的普通资源（IA核心组件仍保持锁定）。
Browse the marketplace catalog
浏览Marketplace目录
celigo marketplace list
celigo marketplace list --type template # only Templates
celigo marketplace list --type integration-app # only Integration Apps
celigo marketplace list
celigo marketplace list --type template # 仅列出Template
celigo marketplace list --type integration-app # 仅列出Integration App
Check the account before installing (avoid duplicates)
安装前检查账户（避免重复）
celigo account search "<keyword>"
celigo account search "<keyword>"
Preview a blueprint's contents and dependencies
预览蓝图内容和依赖项
celigo templates preview <id>
celigo templates preview <id> --summary
celigo templates preview <id> --model Connection # connections the blueprint expects
celigo templates preview <id>
celigo templates preview <id> --summary
celigo templates preview <id> --model Connection # 蓝图所需的连接
Whole-template / Integration App install -> run in the Celigo Marketplace UI installer
完整Template/Integration App安装 -> 在Celigo Marketplace UI安装程序中运行
(open the listing's preview page in the UI; programmatic whole-install is not
（在UI中打开条目预览页面；多步骤Template不支持程序化完整安装）
supported for multi-step templates)
Pre-Submit Checklist
提交前检查清单
Before installing a template or Integration App, or copying an element, verify:
安装Template或Integration App，或复制元素前，验证以下内容：
- Whole-template install runs in the Marketplace UI. The simple install API handles only simple single-integration templates; most published blueprints ship as multi-step installers and fail programmatically. Install from the preview page in the UI.
- Templates receive no ongoing updates. A template is a starting point you own and maintain -- if the source app's API changes, you fix it. Choose an Integration App when you need vendor-maintained updates.
- Integration Apps are structure-locked. Core flows, mappings, and logic can't be rewritten -- you configure only what the IA exposes. Picking an IA when you need deep customization leaves you at the locked-component ceiling.
- Connections are mapped, not copied. Install and copy resolve the blueprint's placeholder connection ids to real account connections -- reusing a matching one or creating a new one. You never get duplicate credentials pointing at the same endpoint.
- Copying one element brings its whole dependency closure. Copying a flow drags in its exports, imports, scripts, and lookups (and their connections and hooks). You get a runnable element, not a half-wired piece.
- After install, everything is yours. Installed and copied flows, exports, imports, and scripts are ordinary editable resources -- edit, delete, or run them like anything you built by hand. IA core components are the exception; they stay locked.
- Copying a flow may create a flow grouping via staged changes. If the target integration lacks a grouping by the same name, the copy creates it through Celigo's staged-changes review. Accept the staged change in the UI before it's usable, then continue.
- Settings references may not carry over. Template flows can reference integration or flow-grouping settings (e.g.,
{{settings.integration.region}}
- Marketplace access is plan-gated. Browsing, previewing, or installing may return on plans without marketplace access.
- Lookup cache data only travels when flagged. A lookup cache's data is included in a blueprint only when
includeDataInTemplatesAndCloning: true
- 完整模板安装需在Marketplace UI中运行。简单安装API仅支持简单的单集成Template；大多数已发布的蓝图为多步骤安装程序，程序化安装会失败。请从UI预览页面进行安装。
- Template不接收持续更新。Template是您自行持有和维护的起点——如果源应用的API发生变化，您需自行修复。需要供应商维护的更新时，请选择Integration App。
- Integration App是结构锁定的。核心流程、映射和逻辑无法改写——您只能配置IA公开的内容。当您需要深度自定义却选择了IA，会遇到锁定组件的限制。
- 连接采用映射而非复制。安装和复制操作会将蓝图中的占位符连接ID解析为真实的账户连接——复用匹配的连接或创建新连接。您永远不会得到指向同一端点的重复凭据。
- 复制单个元素会携带其完整依赖链。复制流程会同时导入其导出、导入、脚本和查找（及它们的连接和钩子）。您得到的是可运行的完整元素，而非半连接的片段。
- 安装后所有资源归您所有。安装或复制的流程、导出、导入和脚本都是可编辑的普通资源——您可以像手动构建的资源一样编辑、删除或运行它们。IA核心组件除外，它们仍保持锁定。
- 复制流程可能通过暂存变更创建流程分组。如果目标集成中没有同名分组，复制操作会通过Celigo的staged-changes审核创建分组。在分组可用前，需在UI中接受暂存变更，然后继续操作。
- 设置引用可能无法自动转移。Template流程可能引用集成或流程分组的设置（例如
{{settings.integration.region}}
- Marketplace访问受方案限制。浏览、预览或安装操作可能因账户或令牌无Marketplace访问权限而返回。
- 查找缓存数据仅在标记后才会转移。只有当
includeDataInTemplatesAndCloning: true
| Error | Cause | Fix |
|---|
Install step is invalid: invalid templateZip
| Tried to install a multi-step template via the simple install API | Install from the listing's preview page in the Marketplace UI |
| on marketplace list/preview/install | Marketplace access is plan-gated for the account or token | Use an account/plan with marketplace access, or contact your Celigo admin |
| Installed flow won't run -- missing setting | Blueprint referenced integration or flow-grouping settings that didn't come along | Populate the referenced values on the target integration or flow grouping |
| Copied flow's grouping not visible to follow-up calls | A new flow grouping was created via staged changes and not yet accepted | Accept the staged change in the UI, then continue the copy |
| Duplicate connection after install | Created a new connection instead of mapping an existing one | Re-map the install to your existing connection -- connections are meant to be shared, not duplicated |
| Installed resource can't be edited | It's an Integration App core component (upgrade-protected), not a template resource | Customize via the IA's exposed settings and mappings, or use a Template when you need full control |
| 错误 | 原因 | 修复方案 |
|---|
Install step is invalid: invalid templateZip
| 尝试通过简单安装API安装多步骤Template | 从Marketplace UI的条目预览页面进行安装 |
| 市场列表/预览/安装时返回 | 账户或令牌的方案无Marketplace访问权限 | 使用拥有Marketplace访问权限的账户/方案，或联系Celigo管理员 |
| 安装的流程无法运行——缺少设置 | 蓝图引用的集成或流程分组设置未一同导入 | 在目标集成或流程分组中填充引用的值 |
| 复制的流程分组无法被后续调用识别 | 通过暂存变更创建了新流程分组但未接受 | 在UI中接受暂存变更，然后继续复制操作 |
| 安装后出现重复连接 | 创建了新连接而非映射现有连接 | 将安装重新映射到您的现有连接——连接旨在共享，而非重复创建 |
| 安装的资源无法编辑 | 这是Integration App的核心组件（受升级保护），而非Template资源 | 通过IA公开的设置和映射进行自定义，或在需要完全控制权时使用Template |