Back to Details

managing-integrations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- TIER:1 -->
<!-- TIER:1 -->

Managing Integrations

管理集成

An integration is a first-class Celigo resource that represents a named group of related resources -- flows, APIs, Tools, registered connections, scripts, settings, notification subscriptions, aliases, and revision history. It is the organizational layer that says "this body of automation goes together," typically because it serves a specific business purpose (the "Shopify-NetSuite integration", the "customer-onboarding integration"). The actual work is done by the resources inside; the integration coordinates how they are managed, deployed, and evolved.
Users may call integrations tiles, workspaces, or integration folders -- treat these as equivalent vocabulary for the same resource type.
Concerns when managing integrations:
  • Organization and access -- grouping related work so it can be named, permissioned, and reported on as a unit. The integration boundary is the permission boundary.
  • Plain vs Integration App -- customer-built integrations you own end to end, vs template-driven apps installed from the Marketplace.
  • Hierarchy -- parent/child integrations for multi-store, multi-tenant, or per-environment splits.
  • Lifecycle and promotion -- cloning across environments and running the ILM workflow (snapshots, pulls, reverts) to evolve integrations safely.
  • Composition -- what lives inside, and how to move a resource from one integration to another.
  • Per-integration knobs -- notifications, aliases, analytics, and settings that live on the integration record itself.
集成是Celigo的一等资源，代表一组命名的相关资源集合——包括flows、API、Tools、已注册连接、脚本、设置、通知订阅、别名和版本历史。它是一个组织层，用于定义“这套自动化体系属于同一范畴”，通常是因为它们服务于特定业务目标（例如“Shopify-NetSuite集成”“客户入职集成”）。实际工作由内部资源完成，集成则负责协调这些资源的管理、部署和演进方式。
用户可能会将集成称为磁贴（tiles）、工作区（workspaces）或集成文件夹（integration folders）——这些都是同一资源类型的等价表述。
管理集成时需关注的要点：
  • 组织与权限——将相关工作分组，使其可作为一个单元进行命名、设置权限和生成报告。集成边界即为权限边界。
  • 普通集成与Integration Apps——由客户从头构建、完全自主掌控的集成，与从Marketplace安装的模板驱动型应用的对比。
  • 层级结构——适用于多店铺、多租户或分环境场景的父子集成结构。
  • 生命周期与推广——跨环境克隆，以及运行ILM工作流（快照、拉取、回滚）以安全演进集成。
  • 组成结构——集成包含哪些资源，以及如何将资源从一个集成迁移到另一个集成。
  • 集成专属配置——集成记录本身附带的通知、别名、分析和设置功能。

What Lives Inside an Integration

集成包含的资源

An integration is a container for the resources that do the work:
  • Flows -- the body of the integration's automation; each is enabled/disabled independently.
  • APIs -- HTTP endpoints the integration exposes to external callers.
  • Tools -- reusable processing blocks invoked by flows, APIs, and AI agents.
  • Registered connections -- connections attached to the integration's connection list (registration is organizational, not binding -- see Gotchas).
  • Scripts -- JavaScript attached to the integration or its resources.
  • Settings and custom forms -- the integration record holds the settings values; a custom form controls their shape.
Integration listings surface computed fields useful for "which of my integrations have problems": 
numFlows
, 
numError
(open errors across all flows), 
numRegisteredConnections
, 
numOfflineConnections
, and 
lastErrorAt
(ISO timestamp of the most recent error). Rank by 
numError
/ 
numOfflineConnections
to triage.
集成是承载实际工作资源的容器，包含：
  • Flows——集成自动化体系的核心；每个flow可独立启用/禁用。
  • APIs——集成对外暴露的HTTP端点。
  • Tools——可被flows、APIs和AI agents调用的可复用处理模块。
  • 已注册连接——添加到集成连接列表的连接（注册仅为组织标记，并非绑定关系，详见注意事项）。
  • 脚本——附加到集成或其资源的JavaScript代码。
  • 设置与自定义表单——集成记录存储设置的值，自定义表单控制设置的结构。
集成列表会展示便于排查问题的计算字段：
numFlows
（flow数量）、
numError
（所有flow中的未处理错误数）、
numRegisteredConnections
（已注册连接数）、
numOfflineConnections
（离线连接数）和
lastErrorAt
（最近一次错误的ISO时间戳）。可按
numError
/
numOfflineConnections
排序来优先处理问题。

Plain Integrations vs Integration Apps

普通集成与Integration Apps

Two flavors share the integration resource shape but behave differently:
  • Plain integrations are built from scratch by the customer, who owns the structure entirely. Adding, removing, or modifying inner resources is normal CRUD, and cloning preserves the full structure.
  • Integration Apps (IAs) are template-driven integrations, typically installed from the Marketplace. IA resources carry a 
    _connectorId
    ; the template controls which flows exist, what settings are exposed, and how children are organized. Customer edits are bounded by the template, and the app can ship upgrades that propagate from the template author to every installed instance. Adding a flow to an IA may be limited to a "Custom flows" area.
Marketplace install and template-upgrade operations are a separate concern from managing the integration record.
两种类型共享集成资源结构，但行为不同：
  • 普通集成：由客户从头构建，完全掌控其结构。添加、移除或修改内部资源属于常规CRUD操作，克隆会保留完整结构。
  • Integration Apps（IAs）：模板驱动型集成，通常从Marketplace安装。IA资源带有
    _connectorId
    ，模板控制flow的存在、暴露的设置以及子集成的组织方式。客户的编辑受模板限制，应用可推送由模板作者发布的升级，同步到所有已安装实例。向IA添加flow可能仅局限于“自定义flows”区域。
Marketplace安装和模板升级操作属于独立范畴，与集成记录管理无关。

Parent / Child Integrations

父子集成

Some integrations support children: a parent integration with multiple child integrations underneath it. This shows up most often in multi-store / multi-tenant setups (one IA supporting several Shopify stores or business units, each a child) and in per-environment splits inside a single IA.
Children inherit structure from the parent (the flows, the settings schema, the connection requirements) but carry their own configuration values (the actual connections, settings values, and per-child flow customizations). Integration listings return both parent and child entries, so the full tree is visible.
Child integrations are generally available only when the parent is an Integration App. For a plain integration, use sibling integrations or per-flow naming instead (e.g. 
Order sync -- Store A
, 
Order sync -- Store B
).
部分集成支持子集成：一个父集成下包含多个子集成。这种结构最常见于多店铺/多租户场景（一个IA支持多个Shopify店铺或业务单元，每个对应一个子集成），以及单个IA内的分环境拆分场景。
子集成继承父集成的结构（flows、设置 schema、连接要求），但拥有独立的配置值（实际连接、设置值、子集成专属的flow自定义项）。集成列表会同时返回父集成和子集成条目，完整层级结构可见。
子集成通常仅在父集成是Integration Apps时可用。对于普通集成，可使用同级集成或flow命名区分（例如
Order sync -- Store A
、
Order sync -- Store B
）。

Quick Reference

快速参考

Add-to-Existing vs New Integration

添加到现有集成 vs 创建新集成

Default: add to an existing integration. Spawning a new one per flow defeats the purpose of grouping. Reach for a new integration when:
SituationChoice
A different group of people must manage or monitor it (contractor scope, partner visibility, ops vs IT split)New integration -- the boundary is the access boundary
The work is conceptually separate (different business problem, audience, lifecycle)New integration
Installing from a Marketplace templateNew integration (IAs come as their own integration)
An existing integration is at its scale ceiling (rare)New integration
Same team, same access needs, related workAdd to existing
默认选择：添加到现有集成。每个flow单独创建新集成会失去分组的意义。在以下场景选择创建新集成：
场景选择
需由不同团队管理或监控（承包商范围、合作方可见性、运营与IT分工）创建新集成——边界即为权限边界
工作在概念上独立（不同业务问题、受众、生命周期）创建新集成
从Marketplace模板安装创建新集成（IAs以独立集成形式安装）
现有集成已达规模上限（罕见）创建新集成
同一团队、相同权限需求、相关工作添加到现有集成

Clone Decision Matrix

克隆决策矩阵

IntentClone typeNotes
"A copy to play with" / backup before risky changesSame-environment cloneParallel copy in the same environment
"Develop changes in sandbox" / "clone to prod"Cross-environment cloneEntry point to the ILM workflow
Copy but keep future changes in syncClone (preserves clone-family lineage)Enables pulls between the two
Copy with no intention of keeping in syncDuplicate from scratchLoses lineage; ILM unavailable
Cross-environment clones remap connections via a connection map at clone time -- see the Reference Index.
意图克隆类型说明
“创建副本用于测试” / 风险变更前备份同环境克隆在同一环境中创建并行副本
“在沙箱中开发变更” / “克隆到生产环境”跨环境克隆ILM工作流的入口
创建副本并保持未来变更同步克隆（保留克隆家族谱系）支持两者间的拉取操作
创建副本且无需保持同步从头复制丢失谱系；无法使用ILM
跨环境克隆会在克隆时通过连接映射重映射连接——详见参考索引。

Moving a Resource -- Three Tiers

资源迁移——三个层级

TierResourcesHow it changes integration
Owned (movable)flows, APIs, ToolsMove re-homes it: swaps 
_integrationId
, preserves 
_id
/history/errors (flows also clear 
_flowGroupingId
)
Registered (not owned)connections, lookup cachesRegister/deregister to the integration's list (can belong to several at once)
Inherited (move the parent)exports, imports, AI agents, guardrailsNo per-step move -- move the parent flow/API/Tool
Integration-App resources (
_connectorId
) cannot be freely moved. Whole-integration relocation across accounts is the separate Integration transfer operation.
层级资源集成变更方式
自有（可迁移）flows、APIs、Tools迁移会重新归属资源：替换
_integrationId
，保留
_id
/历史/错误（flows还会清除
_flowGroupingId
）
已注册（非自有）连接、查找缓存在集成列表中注册/注销（可同时归属多个集成）
继承（需迁移父资源）exports、imports、AI agents、防护规则无法单独迁移——需迁移父flow/API/Tool
Integration Apps资源（带有
_connectorId
）无法自由迁移。跨账户迁移整个集成属于独立的集成转移操作。

Minimum Required Fields

必填字段

Creating an integration requires at minimum:
  • name
    -- the display name; name it after the business purpose, not a single operation.
  • description
    (optional) -- helpful context for the team.
Integration Apps are not created this way -- they are installed from the Marketplace.
创建集成至少需要：
  • name
    ——显示名称；应根据业务目标命名，而非单一操作。
  • description
    （可选）——为团队提供有用背景信息。
Integration Apps无法通过此方式创建——需从Marketplace安装。

Reference Index

参考索引

Deep ILM detail lives in references/lifecycle-management.md:
  • Clone family & linked vs standalone clones -- why a pull can report "no changes to pull"
  • Revisions -- 
    snapshot
    / 
    pull
    / 
    revert
    semantics, diffs, and auto-snapshots
  • Ignore fields -- per-resource-type fields (
    flow.*
    , 
    export.*
    , 
    import.*
    , 
    connection.*
    ) that stay per-environment
  • Connection remap on clone -- the connection-map object and why a post-clone update cannot remap
  • Move vs clone vs transfer -- owned / registered / inherited resource tiers
ILM详细内容请查阅references/lifecycle-management.md：
  • 克隆家族与关联/独立克隆——拉取操作显示“无变更可拉取”的原因
  • 版本控制——
    snapshot
    /
    pull
    /
    revert
    的语义、差异对比和自动快照
  • 忽略字段——各资源类型（
    flow.*
    、
    export.*
    、
    import.*
    、
    connection.*
    ）中保留在本地环境的字段
  • 克隆时的连接重映射——连接映射对象，以及为何克隆后更新无法重映射连接
  • 迁移 vs 克隆 vs 转移——自有/已注册/继承资源的层级

Related Skills

相关技能

  • building-flows > How to Build a Flow -- flows are the body of an integration's automation
  • configuring-connections > Quick Reference -- connections are registered to integrations and remapped on cross-environment clone
  • building-apis > Quick Reference -- APIs live inside integrations
  • building-tools > Tool Concepts -- Tools live inside integrations
  • managing-users > Access Strategy Decision Matrix -- the integration boundary is the permission boundary; grant manage/monitor per integration
  • troubleshooting-flows > Diagnostic Workflow -- diagnosing the errors that roll up into 
    numError
  • using-marketplace-templates -- Integration Apps install from the Marketplace as their own integration; templates seed a new one
<!-- TIER:2 -->
  • building-flows > 如何构建Flow——flows是集成自动化体系的核心
  • configuring-connections > 快速参考——连接注册到集成，跨环境克隆时会重映射
  • building-apis > 快速参考——APIs存在于集成内部
  • building-tools > Tool概念——Tools存在于集成内部
  • managing-users > 权限策略决策矩阵——集成边界即为权限边界；可按集成授予管理/监控权限
  • troubleshooting-flows > 诊断工作流——排查汇总到
    numError
    的错误
  • using-marketplace-templates——Integration Apps从Marketplace安装为独立集成；模板会生成新集成
<!-- TIER:2 -->

How to Manage Integrations

如何管理集成

1. Discover existing integrations

1. 发现现有集成

Before creating anything, understand the current state:
bash
undefined
创建任何资源前，先了解当前状态：
bash
undefined

List all integrations (includes parent and child entries)

列出所有集成（包含父集成和子集成条目）

celigo integrations list
celigo integrations list

Inspect one integration's record

查看单个集成的记录

celigo integrations get <id>
celigo integrations get <id>

Find related work by keyword across the account

按关键词在账户内查找相关工作

celigo account search "<keyword>"

Review the computed fields (`numFlows`, `numError`, `numRegisteredConnections`, `numOfflineConnections`, `lastErrorAt`) to spot integrations that need attention.
celigo account search "<keyword>"

查看计算字段（`numFlows`、`numError`、`numRegisteredConnections`、`numOfflineConnections`、`lastErrorAt`），找出需要关注的集成。

2. Decide: add to an existing integration or create a new one

2. 决策：添加到现有集成还是创建新集成

Use the Add-to-Existing vs New Integration matrix. The key question is almost always about access: do the people who will manage or monitor this work differ from the people who already have access to an existing integration? If yes, it needs its own integration so Custom permissions can be granted independently. If no, add it to the existing one.
参考添加到现有集成 vs 创建新集成矩阵。核心问题通常与权限相关：*管理或监控此项工作的人员，是否与现有集成的权限人员不同？*如果是，则需要创建新集成，以便独立设置自定义权限；如果否，则添加到现有集成。

3. Create an integration

3. 创建集成

bash
undefined
bash
undefined

Create from a JSON body (minimum: a descriptive name)

通过JSON内容创建（至少包含描述性名称）

echo '{"name":"Shopify-NetSuite"}' | celigo integrations create
echo '{"name":"Shopify-NetSuite"}' | celigo integrations create

Or edit a file and pipe it in

或编辑文件后传入

celigo integrations create < integration.json

Name it after the business purpose, not a single operation. Integration Apps are **not** created here -- install them from the Marketplace instead.
celigo integrations create < integration.json

根据业务目标命名，而非单一操作。Integration Apps**无法**通过此方式创建——需从Marketplace安装。

4. Organize the resources inside

4. 组织内部资源

Build the inner resources bottom-up (connections, then exports/imports, then flows/APIs/Tools) using their own skills. To change which integration a resource belongs to:
  • Flows / APIs / Tools -- these are owned and can be moved (the move preserves the resource's 
    _id
    , history, and errors while swapping 
    _integrationId
    ). Moving is done in the Celigo UI or via the public API -- not via 
    celigo integrations update
    , which only mutates the parent record.
  • Connections / lookup caches -- these are registered, not owned. "Move a connection" means register it to the target integration and deregister from the source (see 
    configuring-connections
    ).
  • Exports / imports / AI agents / guardrails -- these inherit their integration from the parent flow/API/Tool; move the parent instead.
自底向上构建内部资源（连接，然后是exports/imports，最后是flows/APIs/Tools），使用对应技能。如需变更资源所属集成：
  • Flows / APIs / Tools——这些是自有资源，可进行迁移（迁移会保留资源的
    _id
    、历史和错误，仅替换
    _integrationId
    ）。迁移需在Celigo UI或通过公开API完成——无法通过
    celigo integrations update
    操作，该操作仅修改父集成记录。
  • 连接 / 查找缓存——这些是已注册资源，非自有。“迁移连接”指将其注册到目标集成，并从源集成注销（详见
    configuring-connections
    ）。
  • Exports / imports / AI agents / 防护规则——这些资源继承其父flow/API/Tool的集成归属；需迁移父资源。

5. Clone across environments (and remap connections)

5. 跨环境克隆（并重映射连接）

To develop safely or promote work, clone the integration into another environment. Cloning copies the integration record, its flows, APIs, Tools, registered connections, scripts, and settings, and joins the copy to the original's clone family.
  • A cross-environment clone is the entry point to ILM.
  • Cloning cancels in-progress jobs on the original integration's connections -- schedule accordingly.
  • Remap connections to the target environment at clone time using a connection map (
    {"<oldConnectionId>": "<newConnectionId>"}
    ). This is the only place the binding change can happen -- see the Reference Index.
Cloning and connection remap are performed in the Celigo UI or via the public API. (The flow-level equivalent, 
celigo flows clone
, is documented in 
building-flows
and uses the same 
connectionMap
.)
如需安全开发或推广工作，可将集成克隆到另一个环境。克隆会复制集成记录、其flows、APIs、Tools、已注册连接、脚本和设置，并将副本加入原集成的克隆家族。
  • 跨环境克隆是ILM的入口。
  • 克隆会取消原集成连接上的进行中任务——需合理安排时间。
  • 克隆时需通过连接映射（
    {"<oldConnectionId>": "<newConnectionId>"}
    ）将连接重映射到目标环境。这是唯一可变更绑定关系的时机——详见参考索引。
克隆和连接重映射需在Celigo UI或通过公开API完成。（flow级别的等价操作
celigo flows clone
记录在
building-flows
中，使用相同的
connectionMap
。）

6. Promote with ILM (snapshot, pull, revert)

6. 通过ILM推广（快照、拉取、回滚）

Run the git-style ILM workflow to evolve integrations across environments:
  1. Snapshot the production integration before big changes (a known-good state to revert to).
  2. Develop in the cross-environment clone.
  3. Pull the changes from the clone back into production; auto-snapshots bookend the merge, and conflicts stop the pull for manual resolution.
  4. Revert to a prior revision if a pull introduced a regression.
Configure ignore fields first so environment-specific values (URLs, sandbox vs prod IDs) do not cross during a pull. These operations run in the Celigo UI's Revisions tab or via the public API. See references/lifecycle-management.md for full semantics.
运行类Git的ILM工作流，跨环境演进集成：
  1. 快照：重大变更前对生产集成进行快照（创建可回滚的已知良好状态）。
  2. 开发：在跨环境克隆中开发变更。
  3. 拉取：将变更从克隆拉取到生产环境；自动快照会记录合并前后状态，冲突会暂停拉取以进行手动解决。
  4. 回滚：如果拉取引入了问题，回滚到之前的版本。
需先配置忽略字段，确保环境特定值（URL、沙箱与生产ID）不会在拉取时同步。这些操作需在Celigo UI的**版本控制（Revisions）**标签页或通过公开API完成。完整语义请查阅references/lifecycle-management.md。

7. Configure per-integration knobs

7. 配置集成专属功能

These features live on the integration record and are managed in the Celigo UI or via the public API:
  • Notifications -- subscribe users (the current user or anyone by email) to all flow errors, specific flow errors, or offline-connection alerts for the integration.
  • Aliases -- stable, portable names mapping to a resource 
    _id
    . Use them when scripts must reference resources by name, because 
    _id
    s change when an integration is cloned to a new environment but aliases can stay stable.
  • Analytics -- flow execution metrics (success / error / ignored / resolved record counts, average processing time) roll up at the integration level, aggregated across the integration or grouped per flow or per step.
这些功能属于集成记录，需在Celigo UI或通过公开API管理：
  • 通知——订阅用户（当前用户或指定邮箱用户）接收集成的所有flow错误、特定flow错误或离线连接警报。
  • 别名——稳定、可移植的名称，映射到资源
    _id
    。当脚本需要按名称引用资源时使用，因为集成克隆到新环境时
    _id
    会变更，但别名可保持稳定。
  • 分析——flow执行指标（成功/错误/忽略/已处理记录数、平均处理时间）会汇总到集成层级，可按集成、flow或步骤分组查看。

8. Delete an integration

8. 删除集成

bash
celigo integrations delete <id>
Deleting removes the integration and is destructive -- confirm nothing is still running and that the resources inside are no longer needed. Prefer moving resources out first if any should be kept.
bash
celigo integrations delete <id>
删除集成是破坏性操作——需确认没有正在运行的任务，且内部资源不再需要。如需保留部分资源，建议先迁移再删除。

CLI Commands

CLI命令

bash
undefined
bash
undefined

CRUD

CRUD操作

celigo integrations list celigo integrations get <id> celigo integrations create < integration.json celigo integrations update <id> < integration.json celigo integrations delete <id>
celigo integrations list celigo integrations get <id> celigo integrations create < integration.json celigo integrations update <id> < integration.json celigo integrations delete <id>

Discovery

发现资源

celigo account search "<keyword>" # Find integrations and related resources by name/keyword

**UI / API alternatives.** The CRUD CLI mutates only the integration record. Operations that touch the integration's *inside* resources or lifecycle are performed in the Celigo UI or via the public API, not the CRUD CLI:

- **Clone** (same- or cross-environment) and connection remap
- **ILM**: snapshots, pulls, reverts, and ignore-field configuration (Revisions tab)
- **Move** a flow/API/Tool between integrations
- **Register / deregister** connections and lookup caches
- **Notifications**, **aliases**, and **analytics**
- **Integration transfer** across accounts, and **Marketplace** install/upgrade for Integration Apps

<!-- TIER:3 -->
celigo account search "<keyword>" # 按名称/关键词查找集成及相关资源

**UI / API替代方案**：CRUD CLI仅修改集成记录。涉及集成内部资源或生命周期的操作需在Celigo UI或通过公开API完成，无法通过CRUD CLI执行：

- **克隆**（同环境或跨环境）和连接重映射
- **ILM**：快照、拉取、回滚和忽略字段配置（版本控制标签页）
- 在集成间**迁移**flow/API/Tool
- **注册/注销**连接和查找缓存
- **通知**、**别名**和**分析**
- 跨账户的**集成转移**，以及Integration Apps的Marketplace安装/升级

<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Before creating, cloning, or promoting an integration, verify:
  • Chose add-to-existing vs new integration based on the access boundary (who manages/monitors the work)
  • New integration has a clear 
    name
    describing the business purpose, not a single operation
  • For a cross-environment clone, the connection map covers every source 
    _connectionId
    that must point at a target-environment connection
  • For ILM promotion, the source clone is lifecycle-linked (created via the UI clone flow), not standalone
  • Ignore fields cover environment-specific values before pulling between environments
  • Took a pre-deploy snapshot of the receiving integration before a risky pull
  • Used move (preserves 
    _id
    /history), not clone, when the same resource should change integrations
  • Confirmed nothing critical is running before cloning (in-progress jobs on the original's connections are canceled) or deleting
创建、克隆或推广集成前，请验证：
  • 根据权限边界（谁管理/监控工作）选择添加到现有集成或创建新集成
  • 新集成的
    name
    清晰描述业务目标，而非单一操作
  • 跨环境克隆时，连接映射覆盖所有需指向目标环境的源
    _connectionId
  • ILM推广时，源克隆是生命周期关联的（通过UI克隆流程创建），而非独立克隆
  • 跨环境拉取前，忽略字段已覆盖环境特定值
  • 风险拉取前，对接收集成进行了部署前快照
  • 同一资源变更集成时使用迁移（保留
    _id
    /历史），而非克隆
  • 克隆（原集成连接的进行中任务会被取消）或删除前，确认无关键任务在运行

Gotchas

注意事项

  1. A standalone clone silently breaks ILM. A clone created outside the UI clone flow (e.g. a plain public-API copy) is in the clone family but not lifecycle-linked: snapshots are refused, and pulls report 
    Everything up to date -- no changes to pull
    even with real edits. Check for a standalone source before debugging a "no changes" pull. It cannot be linked after the fact -- recreate it via the UI clone flow.
  2. Connection remap only happens at clone time. Use the connection map (
    {"<oldConnectionId>": "<newConnectionId>"}
    ) during the clone. Updating the integration afterward cannot remap connections on the inner flows/exports/imports -- 
    celigo integrations update
    only mutates the parent record.
  3. Registration is not binding. Registering a connection to an integration is an organizational tag (visibility in the connection list). The 
    _connectionId
    on an export/import is what actually binds a connection to work. Register/deregister never changes which connections the inner resources use.
  4. Cloning cancels in-progress jobs on the original integration's connections during the operation. Schedule clones when the integration is idle.
  5. Pulls only work between directly related, lifecycle-linked family members -- a parent and a direct child, not across unrelated branches of the clone family.
  6. Ignore fields only affect field-level updates to existing resources. Resource creation and deletion during a pull are never suppressed by the ignore list.
  7. Move preserves the resource; clone creates a new one. A move keeps the same 
    _id
    , history, and errors and just swaps 
    _integrationId
    (flows also clear 
    _flowGroupingId
    ). If the user says "move," "reassign," or "relocate," do not clone.
  8. Integration-App resources are template-controlled. Resources carrying a 
    _connectorId
    cannot be freely moved or restructured; their shape and upgrades come from the connector/template author. Custom additions may be limited to a "Custom flows" area.
  9. Integration transfer (across accounts) is distinct from a resource move (within an account) and from a clone (a copy). Do not conflate them.
  10. PUT/update erases omitted fields. When editing an integration record, GET first, modify, then update so you do not drop existing fields.
  11. Child integrations require an Integration App parent. Plain integrations do not get children -- use sibling integrations or per-flow naming to distinguish multi-store/multi-tenant work.
  1. 独立克隆会静默破坏ILM：通过UI克隆流程外创建的克隆（例如直接通过公开API复制）虽属于克隆家族，但未关联生命周期：无法创建快照，即使存在实际编辑，拉取操作仍会显示
    Everything up to date -- no changes to pull
    。排查“无变更”拉取问题前，先检查源克隆是否为独立克隆。独立克隆无法事后关联——需通过UI克隆流程重新创建。
  2. 连接重映射仅在克隆时生效：克隆时需使用连接映射（
    {"<oldConnectionId>": "<newConnectionId>"}
    ）。克隆后更新集成无法重映射内部flows/exports/imports的连接——
    celigo integrations update
    仅修改父集成记录。
  3. 注册并非绑定关系：将连接注册到集成只是组织标记（在连接列表中可见）。exports/imports上的
    _connectionId
    才是实际绑定连接到工作的标识。注册/注销操作不会改变内部资源使用的连接。
  4. 克隆会取消原集成连接上的进行中任务：需在集成空闲时安排克隆。
  5. 拉取仅在直接关联的生命周期克隆家族成员间生效——父集成与直接子集成，而非克隆家族的无关分支。
  6. 忽略字段仅影响现有资源的字段级更新：拉取时的资源创建和删除操作不会被忽略列表抑制。
  7. 迁移保留资源；克隆创建新资源：迁移会保留相同的
    _id
    、历史和错误，仅替换
    _integrationId
    （flows还会清除
    _flowGroupingId
    ）。如果用户要求“迁移”“重新分配”或“转移”，请勿使用克隆。
  8. Integration Apps资源受模板控制：带有
    _connectorId
    的资源无法自由迁移或重构；其结构和升级由连接器/模板作者提供。自定义添加可能仅局限于“自定义flows”区域。
  9. 跨账户集成转移是独立操作：与账户内资源迁移、克隆（复制）不同，请勿混淆。
  10. PUT/更新操作会清除未提交的字段：编辑集成记录时，需先GET获取记录，修改后再更新，避免丢失现有字段。
  11. 子集成需要Integration Apps作为父集成：普通集成不支持子集成——需使用同级集成或flow命名区分多店铺/多租户工作。

Common Errors

常见错误

Error / SymptomLikely CauseFix
Pull reports 
Everything up to date -- no changes to pull
(but edits exist)		Source clone is standalone, not lifecycle-linkedRecreate the clone through the Celigo UI clone flow; standalone clones cannot be linked after the fact
clone must be linked to source integration
on snapshot		Snapshot attempted on a standalone cloneUse a lifecycle-linked clone (created via the UI clone flow)
Pull stops with conflictsBoth sides changed the same fieldsResolve manually in the Celigo UI Revisions tab
Cloned flows still point at the source environment's connectionsConnection map not supplied (or wrong IDs) at clone timeRe-clone with a connection map linking each old 
_connectionId
to the target-environment connection
Environment-specific values overwritten by a pullThose field paths are not in the integration's ignore fieldsAdd the paths (e.g. 
connection.*
, 
export.*
) to ignore fields, then re-pull
Cannot move a flow/API/Tool into an integrationResource is Integration-App-owned (
_connectorId
set)		IA resources are managed by the connector; use a Custom-flows area or a plain integration
403 Forbidden
on integration edit		Token lacks manage/admin access to that integrationUse a token with manage or admin access (see 
managing-users
)
404 Not Found
on integration get/update		Wrong integration 
_id
, or it was deleted		Verify the ID with 
celigo integrations list
Integration listing is missing integrations you expectToken has Custom access and only sees granted integrationsUse an admin/owner token, or grant Custom access to those integrations (see 
managing-users
)
错误/症状可能原因修复方法
拉取显示
Everything up to date -- no changes to pull
（但存在编辑）		源克隆是独立克隆，未关联生命周期通过Celigo UI克隆流程重新创建克隆；独立克隆无法事后关联
快照时显示
clone must be linked to source integration
尝试对独立克隆创建快照使用生命周期关联的克隆（通过UI克隆流程创建）
拉取因冲突停止双方修改了相同字段在Celigo UI的**版本控制（Revisions）**标签页手动解决冲突
克隆后的flows仍指向源环境的连接克隆时未提供连接映射（或ID错误）使用连接映射重新克隆，将每个旧
_connectionId
关联到目标环境的连接
拉取覆盖了环境特定值这些字段路径未添加到集成的忽略字段将路径（例如
connection.*
、
export.*
）添加到忽略字段，重新拉取
无法将flow/API/Tool迁移到集成资源属于Integration Apps（已设置
_connectorId
）		IA资源由连接器管理；使用自定义flows区域或普通集成
编辑集成时显示
403 Forbidden
令牌缺少该集成的管理/管理员权限使用拥有管理或管理员权限的令牌（详见
managing-users
）
获取/更新集成时显示
404 Not Found
集成
_id
错误，或已被删除		通过
celigo integrations list
验证ID
集成列表缺少预期的集成令牌拥有自定义权限，仅能查看已授权的集成使用管理员/所有者令牌，或为这些集成授予自定义权限（详见
managing-users
）