getting-started

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Getting Started with Celigo Integrations

Celigo集成入门

Core Concepts

核心概念

Celigo integrations move data between external systems through a small set of resource types:

Connection -- credentials and configuration that authenticate to an external system (Salesforce, NetSuite, HTTP API, database, FTP, etc.)
Export -- data source step that fetches records from a connected system (or receives them via webhook)
Import -- data destination step that writes records to a connected system
Flow -- pipeline that connects exports to imports, with optional branching, transformation, and scripting
Integration -- named container that groups related flows, connections, and resources
Script -- JavaScript hook that runs at specific points in the data pipeline (preSavePage, preMap, postMap, postSubmit, postResponseMap)
API -- custom HTTP endpoint that exposes integration logic for synchronous external consumption
Tool -- reusable building block (input schema -> routers with lookups/imports -> output contract) callable from flows, APIs, AI agents, MCP servers, and other tools
AI agent -- LLM-powered pipeline step (stored as an import) that classifies, extracts, summarizes, or generates data mid-pipeline
Guardrail -- safety/compliance check (PII, moderation, AI evaluation) that flags records; the parent pipeline decides what happens to flagged records
Lookup cache -- account-level key-value store for fast in-memory reference lookups (cross-reference IDs, large translation tables, dedup markers)

Celigo集成通过少量资源类型在外部系统之间传输数据：

Connection —— 用于认证外部系统（Salesforce、NetSuite、HTTP API、数据库、FTP等）的凭证和配置
Export —— 从已连接系统获取记录（或通过webhook接收记录）的数据源步骤
Import —— 向已连接系统写入记录的数据目标步骤
Flow —— 连接Export与Import的管道，支持可选分支、转换和脚本
Integration —— 对相关Flow、Connection及资源进行分组的命名容器
Script —— 在数据管道特定节点运行的JavaScript钩子（preSavePage、preMap、postMap、postSubmit、postResponseMap）
API —— 暴露集成逻辑以供外部同步调用的自定义HTTP端点
Tool —— 可复用的构建模块（输入 schema -> 含查询/导入的路由器 -> 输出契约），可从Flow、API、AI agent、MCP服务器及其他Tool调用
AI agent —— 由LLM驱动的管道步骤（以Import形式存储），可在管道中对数据进行分类、提取、汇总或生成
Guardrail —— 安全/合规检查（PII、内容审核、AI评估），用于标记记录；父管道将决定标记记录的处理方式
Lookup cache —— 账户级键值存储，用于快速内存参考查询（交叉引用ID、大型转换表、去重标记）

How each surface is invoked

各类资源的触发方式

The three pipeline-carrying resources differ mainly in what starts them:

Resource	Started by	Schedule/listeners	Runtime controls
Flow	Itself -- cron schedule, listener/webhook, or another flow chaining into it	Yes	Yes ( `proceedOnFailure` , `skipRetries` , chaining, ...)
API	An external HTTP caller; the request IS the source record	No	No -- errors land on the fail response; retries are the caller's concern
Tool	A consumer -- flow step, AI agent, API, MCP server, or another tool	No	No -- the consumer decides error behavior

"Every night at 2 AM" or "when a webhook fires" always points at a flow. "Reachable from outside Celigo over HTTP" points at an API. "Reusable from multiple places inside Celigo" points at a tool (and a recipe needed both inside and outside is a tool exposed behind an API).

三种承载管道的资源主要区别在于触发方式：

资源类型	触发方式	调度/监听器	运行时控制
Flow	自身触发——定时调度（cron）、监听器/webhook，或由其他Flow链式触发	支持	支持（ `proceedOnFailure` 、 `skipRetries` 、链式触发等）
API	外部HTTP调用方；请求即为源记录	不支持	不支持——错误将返回失败响应；重试由调用方负责
Tool	消费者触发——Flow步骤、AI agent、API、MCP服务器或其他Tool	不支持	不支持——错误处理由消费者决定

“每天凌晨2点执行”或“webhook触发时执行”对应的是Flow。“可通过HTTP从Celigo外部访问”对应的是API。“可在Celigo内部多处复用”对应的是Tool（若需同时在内部和外部使用，则需将Tool通过API暴露）。

Build Order

构建顺序

Always build bottom-up. Resources reference each other, so dependencies must exist first:

1. Connection     (credentials for each system)
2. Export + Import (data source and destination steps, each referencing a connection)
3. Flow           (pipeline wiring exports to imports)

Never start by creating a flow -- its exports and imports must exist first, and those require connections.

At each layer, match the connector to the target application -- raw HTTP is the fallback, not the default. Use the application-specific adaptor when one exists (NetSuite, Salesforce, databases, FTP/S3); otherwise check for a pre-built HTTP connector (550+ apps:

celigo http-connectors list

); hand-write HTTP config only when neither covers the target. See configuring-connections and the adaptor decision matrices in configuring-exports / configuring-imports.

For APIs and tools, the same principle applies: build the connections, exports, and imports that the API/tool will use, then wire them into the API/tool definition.

始终采用自下而上的构建方式。资源之间存在引用关系，因此必须先创建依赖资源：

1. Connection     (每个系统的凭证)
2. Export + Import (数据源和数据目标步骤，均需引用Connection)
3. Flow           (连接Export与Import的管道)

切勿从创建Flow开始——它依赖的Export和Import必须先存在，而这些又需要Connection。

在每个层级，选择与目标应用匹配的连接器——原生HTTP仅作为备选方案，而非默认选择。若存在应用特定适配器（NetSuite、Salesforce、数据库、FTP/S3），则优先使用；否则查看是否有预构建的HTTP连接器（超过550个应用：

celigo http-connectors list

）；只有当两者都不适用时，才手动编写HTTP配置。详见configuring-connections以及configuring-exports/configuring-imports中的适配器决策矩阵。

对于API和Tool，同样遵循此原则：先构建API/Tool所需的Connection、Export和Import，再将它们接入API/Tool定义。

First Steps

初始步骤

0. Pick your surface: CLI or MCP

0. 选择操作界面：CLI或MCP

Skills in this pack show

celigo ...

CLI commands, but there are two equivalent ways to execute most operations:

The Celigo CLI -- what the command blocks in these skills show.
The Celigo Platform MCP server -- if your agent is connected to it, the same operations are MCP tools. Translate CLI blocks directly:
```
list_<type>
```
/
```
upsert_<type>
```
replace
```
celigo <type> list|get|create|update
```
,
```
delete_resource
```
replaces
```
celigo <type> delete
```
, and
```
run_flow
```
,
```
cancel_job
```
,
```
list_jobs
```
,
```
list_flow_errors
```
,
```
list_execution_logs
```
,
```
deploy_template
```
, and
```
get_schema
```
cover running, monitoring, deploying, and schema lookups. The MCP server also has tools with no CLI equivalent, such as
```
search_knowledge_base
```
and
```
triage_flow_errors
```
.

A few operations are CLI-only (no MCP tool): the local account index (

celigo account snapshot|search|dependencies|lint

), API-token management (

celigo accesstokens ...

), stacks, on-premise agents, and user management. For those, use the CLI, the integrator.io REST API, or the UI.

本技能包中的技能展示了

celigo ...

CLI命令，但大多数操作有两种等效执行方式：

Celigo CLI —— 技能中的命令块展示的内容。
Celigo平台MCP服务器 —— 若你的agent已连接到该服务器，相同操作可通过MCP工具执行。直接转换CLI块：
```
list_<type>
```
/
```
upsert_<type>
```
替代
```
celigo <type> list|get|create|update
```
，
```
delete_resource
```
替代
```
celigo <type> delete
```
，
```
run_flow
```
、
```
cancel_job
```
、
```
list_jobs
```
、
```
list_flow_errors
```
、
```
list_execution_logs
```
、
```
deploy_template
```
和
```
get_schema
```
覆盖运行、监控、部署和schema查询功能。MCP服务器还提供一些无CLI等效项的工具，例如
```
search_knowledge_base
```
和
```
triage_flow_errors
```
。

少数操作仅支持CLI（无MCP工具）：本地账户索引（

celigo account snapshot|search|dependencies|lint

）、API令牌管理（

celigo accesstokens ...

）、堆栈、本地代理和用户管理。对于这些操作，请使用CLI、integrator.io REST API或UI。

1. Configure the CLI

1. 配置CLI

bash

celigo config set api_token <your-token>       # Set your API bearer token
celigo config set base_url <url>               # Optional: override base URL for sandbox/EU
celigo config show                             # Verify configuration

The CLI accepts either token kind from Resources > API tokens as its bearer token: a personal access token (any user can generate one; inherits your own permissions; expires after 90 days by default) or an account API token (owner/admin-created, scopeable, long-lived -- prefer it for CI). See managing-api-tokens.

bash

celigo config set api_token <your-token>       # 设置API承载令牌
celigo config set base_url <url>               # 可选：覆盖沙箱/欧盟环境的基础URL
celigo config show                             # 验证配置

CLI接受Resources > API tokens中的任意一种令牌作为承载令牌：个人访问令牌（任何用户均可生成；继承你的权限；默认90天后过期）或账户API令牌（由所有者/管理员创建，可设置作用域，长期有效——CI场景优先使用）。详见managing-api-tokens。

2. Build the Account Index

2. 构建账户索引

The account index is a local snapshot of all resources in your Celigo account. It enables fast search, dependency analysis, and linting without repeated API calls.

bash

celigo account snapshot                        # Fetch all resources, build dependency graph
celigo account search <keyword>                # Find resources by name or keyword
celigo account dependencies <type> <id>        # Show what a resource uses and what uses it
celigo account lint                            # Find orphaned resources, offline connections, untriggered flows
celigo account stats                           # Resource counts by type

The index auto-refreshes when stale (default: 4 hours, configurable via

CELIGO_INDEX_STALE_HOURS

). Commands that depend on the index refresh it automatically unless

--no-refresh

is passed.

账户索引是Celigo账户中所有资源的本地快照。它支持快速搜索、依赖分析和代码检查，无需重复调用API。

bash

celigo account snapshot                        # 获取所有资源，构建依赖关系图
celigo account search <keyword>                # 按名称或关键词查找资源
celigo account dependencies <type> <id>        # 查看某资源的依赖项及被依赖项
celigo account lint                            # 查找孤立资源、离线Connection、未触发的Flow
celigo account stats                           # 按资源类型统计数量

索引会在过期时自动刷新（默认：4小时，可通过

CELIGO_INDEX_STALE_HOURS

配置）。依赖索引的命令会自动刷新索引，除非传入

--no-refresh

参数。

3. Discover Before Building

3. 构建前先发现现有资源

Before creating new resources, always check what already exists:

```
celigo account search "customer sync"
```
-- find existing flows, exports, imports by keyword
```
celigo account dependencies flow <id>
```
-- see the full resource tree for an existing flow
```
celigo account lint
```
-- identify orphaned exports/imports you might reuse

在创建新资源前，务必检查已有的资源：

```
celigo account search "customer sync"
```
—— 通过关键词查找现有Flow、Export、Import
```
celigo account dependencies flow <id>
```
—— 查看现有Flow的完整资源树
```
celigo account lint
```
—— 识别可复用的孤立Export/Import

Planning Discipline

规划原则

Before writing any JSON or CLI commands, answer these questions:

What kind of operation is this?

Modifying an existing resource's config (export settings, import mappings, scripts) -- work on the resource directly with
```
celigo <type> set
```
or
```
celigo <type> get
```
+ edit +
```
celigo <type> update
```
. Don't rebuild the flow
Modifying an existing flow's structure (add/remove steps, change schedule) -- GET the flow, modify the structure, PUT it back
Building something new where every step is clear -- build directly, bottom-up
Any ambiguity about what to build -- design first (see checklist below)

Design checklist (when ambiguity exists):

What source systems? What destination systems?
What data moves between them, in which direction?
How often? (cron schedule, webhook trigger, on-demand)
What happens when a step fails? (
```
proceedOnFailure
```
, error notifications)
Do downstream steps need data from upstream responses? (response mapping)
Is this a one-off or a reusable template? (abstract/instance flow)
Sandbox or production? (never mix --
```
sandbox: true
```
flows only use
```
sandbox: true
```
connections)

在编写任何JSON或CLI命令前，请先回答以下问题：

本次操作属于哪种类型？

修改现有资源的配置（Export设置、Import映射、Script）—— 使用
```
celigo <type> set
```
或
```
celigo <type> get
```
+ 编辑 +
```
celigo <type> update
```
直接操作资源。无需重建Flow
修改现有Flow的结构（添加/移除步骤、更改调度）—— 获取Flow，修改结构，再重新提交
构建步骤明确的新资源—— 直接自下而上构建
对构建内容存在疑问—— 先进行设计（见下方清单）

设计清单（存在疑问时）：

源系统是什么？目标系统是什么？
哪些数据在系统间传输，传输方向如何？
传输频率？（定时调度、webhook触发、按需执行）
步骤失败时如何处理？（
```
proceedOnFailure
```
、错误通知）
下游步骤是否需要上游响应的数据？（响应映射）
是一次性操作还是可复用模板？（抽象Flow/实例Flow）
沙箱环境还是生产环境？（切勿混用——
```
sandbox: true
```
的Flow只能使用
```
sandbox: true
```
的Connection）

Sandbox vs Production

沙箱环境 vs 生产环境

Celigo enforces strict separation:

A
```
sandbox: true
```
connection can only be used by
```
sandbox: true
```
flows
A production (non-sandbox) connection can only be used by production flows
Mixing sandbox and production resources will cause runtime errors

When testing, always create flows with

disabled: true

and verify before enabling.

Celigo强制执行严格的隔离规则：

```
sandbox: true
```
的Connection只能被
```
sandbox: true
```
的Flow使用
生产环境（非沙箱）的Connection只能被生产环境的Flow使用
混用沙箱和生产资源会导致运行时错误

测试时，始终创建

disabled: true

的Flow，验证通过后再启用。

Which Skill to Use

技能选择指南

Task	Skill	Key sections
Set up credentials for an external system	configuring-connections	Connection Type Decision Matrix, iClients
Fetch data from a system (export)	configuring-exports	Adaptor Decision Matrix, Export Execution Pipeline
Write data to a system (import)	configuring-imports	Adaptor Decision Matrix, Import Execution Pipeline
Wire exports to imports in a pipeline	building-flows	Flow Topologies, How to Build a Flow
Build a synchronous HTTP endpoint	building-apis	Builder vs Script mode, API Execution Pipeline
Build a reusable operation	building-tools	Tool Concepts, Tool Execution Pipeline
Map fields between source and destination	writing-mappings	Mapper 2.0 Workflow, Transformation 2.0
Write dynamic expressions in configs	writing-handlebars	Helper Catalog, Expression Patterns
Write JavaScript hooks	writing-scripts	Hook Point Decision Matrix
Set up EDI/B2B trading partner integrations	building-b2b	EDI Standards, Trading Partner Onboarding
Debug a failing flow	troubleshooting-flows	Error Diagnosis Framework, Diagnostic Workflow
Configure filters on exports or imports	configuring-filters	Expression Syntax, Filter Placement
Set up AI-powered import processing	configuring-ai-agents	Provider Decision Matrix
Add PII/moderation/policy checks	configuring-guardrails	Type Decision Matrix, Guardrails Flag, They Don't Enforce
Configure lookup caches	configuring-lookup-caches	How to Build a Lookup Cache
Expose tools via MCP for AI agents	building-mcp-servers	How to Build an MCP Server
Manage account users and access	managing-users	Access Strategy Decision Matrix
Organize flows/APIs in a container; clone or promote across environments	managing-integrations	Clone Decision Matrix, ILM Reference
Install a prebuilt Template or Integration App from the Marketplace	using-marketplace-templates	Templates vs Integration Apps
Create inbound API tokens for scripts, pipelines, or MCP servers	managing-api-tokens	Access Scope Decision Matrix
Run extension code on your own server or AWS Lambda	managing-stacks	Do You Need a Stack?, server vs lambda
Reach a private system behind your firewall	managing-on-premise-agents	Do You Need an On-Premise Agent?

任务	技能	核心章节
设置外部系统凭证	configuring-connections	连接类型决策矩阵、iClients
从系统获取数据（Export）	configuring-exports	适配器决策矩阵、Export执行管道
向系统写入数据（Import）	configuring-imports	适配器决策矩阵、Import执行管道
连接Export与Import构建管道	building-flows	Flow拓扑、Flow构建方法
构建同步HTTP端点	building-apis	构建器模式vs脚本模式、API执行管道
构建可复用操作	building-tools	Tool概念、Tool执行管道
源与目标之间的字段映射	writing-mappings	Mapper 2.0工作流、Transformation 2.0
在配置中编写动态表达式	writing-handlebars	助手函数目录、表达式模式
编写JavaScript钩子	writing-scripts	钩子节点决策矩阵
设置EDI/B2B贸易伙伴集成	building-b2b	EDI标准、贸易伙伴入驻
调试失败的Flow	troubleshooting-flows	错误诊断框架、诊断工作流
为Export或Import配置过滤器	configuring-filters	表达式语法、过滤器位置
设置AI驱动的Import处理	configuring-ai-agents	供应商决策矩阵
添加PII/内容审核/策略检查	configuring-guardrails	类型决策矩阵、Guardrails标记、不强制执行规则
配置Lookup cache	configuring-lookup-caches	Lookup cache构建方法
通过MCP向AI agent暴露Tool	building-mcp-servers	MCP服务器构建方法
管理账户用户与权限	managing-users	权限策略决策矩阵
在容器中组织Flow/API；跨环境克隆或推广	managing-integrations	克隆决策矩阵、ILM参考
从市场安装预构建模板或集成应用	using-marketplace-templates	模板vs集成应用
为脚本、管道或MCP服务器创建入站API令牌	managing-api-tokens	权限范围决策矩阵
在自有服务器或AWS Lambda上运行扩展代码	managing-stacks	是否需要堆栈？服务器vs Lambda
访问防火墙后的私有系统	managing-on-premise-agents	是否需要本地代理？

When No Skill Covers the Shape

无对应技能时的处理方式

The reference schemas shipped with these skills cover the high-stakes shapes where guessing corrupts data, not the whole API surface. When you need a field or resource no skill documents, use the live sources — in this order:

A real resource is ground truth.
```
celigo <type> get <id>
```
returns the exact wire shape; request bodies for
```
create
```
/
```
update
```
are exactly what GET returns. Copying a live resource beats any documentation.
The developer docs are agent-native and always current. Every API reference page is fetchable as markdown — append
```
.md
```
to any page URL (e.g.
```
https://developer.celigo.com/api/api-reference/flows.md
```
), start from the index at
```
https://developer.celigo.com/llms.txt
```
, or ask a direct question:
```
GET https://developer.celigo.com/readme.md?ask=<question>
```
.
Prefer a shipped schema when one exists — schemas under each skill's
```
references/
```
are synced from the API specs and reviewed before shipping, and their
```
x-celigo-ai-guidance
```
notes carry hazards the raw docs don't.

本技能包提供的参考schema仅覆盖可能导致数据损坏的关键结构，而非整个API表面。当需要技能未文档化的字段或资源时，请按以下顺序使用实时资源：

真实资源是最准确的参考。
```
celigo <type> get <id>
```
返回精确的接口结构；
```
create
```
/
```
update
```
的请求体与GET返回的结构完全一致。复制真实资源比任何文档都可靠。
开发者文档为原生agent文档，且始终保持最新。每个API参考页面均可获取为markdown格式——在页面URL后追加
```
.md
```
（例如
```
https://developer.celigo.com/api/api-reference/flows.md
```
），从索引
```
https://developer.celigo.com/llms.txt
```
开始，或直接提问：
```
GET https://developer.celigo.com/readme.md?ask=<question>
```
。
优先使用已提供的schema—— 每个技能
```
references/
```
下的schema均与API规范同步，并经过审核后发布，其
```
x-celigo-ai-guidance
```
注释包含原始文档未提及的风险提示。