configuring-exports

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Exports

配置导出

An export is the data source in a Celigo integration. It connects to an external system and pulls data into the pipeline. Exports serve two roles:

Source -- the starting point that fetches the primary batch of records
Lookup -- a mid-flow enrichment step (
```
isLookup: true
```
) that fetches additional data per-record during processing

Both roles are used across flows, APIs, and tools.

Beyond fetching data, exports also handle post-retrieval processing before records enter the pipeline:

Output filter -- expression-based filtering to skip records that don't match criteria
Transform -- Transformation 2.0 expression rules to reshape/flatten response data before mapping
preSavePage hook -- JavaScript processing on the full page of records before they enter the pipeline
One-to-many -- when used as a lookup, fan out child records from a parent. Set
```
oneToMany: true
```
and
```
pathToMany
```
to the child array path so each child triggers a separate lookup. Once fanned out, the array element itself is the record -- see One-to-many fan-out
Response mapping -- when used as a lookup, extract fields from the lookup response back into the record. Configured on the flow's
```
pageProcessors[]
```
entry, but planned when building the lookup export. The response contains a
```
data
```
array and an
```
errors
```
array. Use
```
data[0].fieldName
```
when you expect a single result (e.g., fetching one order by ID); use
```
data[*].fieldName
```
when multiple results are expected. Response mapping uses Transformation 1.0 syntax (extract/generate pairs), not the newer expression-based transforms
postResponseMap hook -- JavaScript processing after response mapping merges the lookup response back into the record. Configured on the flow's
```
pageProcessors[]
```
entry, but planned when building the lookup export

导出是Celigo集成中的数据源。它连接到外部系统并将数据拉取到处理流程中。导出承担两种角色：

源——获取首批记录的起始步骤
查找——流程中间的数据增强步骤（
```
isLookup: true
```
），在处理期间为每条记录获取额外数据

这两种角色可用于各类流程、API和工具中。

除了获取数据外，导出还会在记录进入处理流程前进行获取后的处理：

输出过滤器——基于表达式的过滤规则，跳过不符合条件的记录
转换——使用Transformation 2.0表达式规则，在映射前重塑/扁平化响应数据
preSavePage钩子——在记录进入处理流程前，对整页记录执行JavaScript处理
一对多——作为查找使用时，从父记录中展开子记录。设置
```
oneToMany: true
```
并将
```
pathToMany
```
指定为子数组路径，使每个子记录触发单独的查找。展开后，数组元素本身即为记录——详见一对多展开
响应映射——作为查找使用时，从查找响应中提取字段并合并回原记录。配置在流程的
```
pageProcessors[]
```
项中，但需在构建查找导出时规划。响应包含
```
data
```
数组和
```
errors
```
数组。预期单个结果时使用
```
data[0].fieldName
```
（例如，通过ID获取单个订单）；预期多个结果时使用
```
data[*].fieldName
```
。响应映射使用Transformation 1.0语法（提取/生成对），而非较新的基于表达式的转换
postResponseMap钩子——响应映射将查找响应合并回原记录后，执行JavaScript处理。配置在流程的
```
pageProcessors[]
```
项中，但需在构建查找导出时规划

Export Execution Pipeline

导出执行流程

When a flow runs, each export executes this pipeline in strict order:

API request / query / file read -- fetches raw data from the external system
Response parsing --
```
resourcePath
```
extracts the record array from the response body or file (e.g.,
```
http.response.resourcePath
```
for HTTP,
```
file.json.resourcePath
```
for JSON files, XPath for XML)
Transformation (optional) --
```
transform
```
reshapes individual records after extraction (Transformation 2.0)
Output filter (optional) -- discards records that don't match filter expression rules
preSavePage hook (optional) -- JavaScript processing on the full page of records

Key distinction:

resourcePath

tells the export WHERE to find records in the response. Transforms reshape WHAT each record looks like after extraction. When a user says "extract records from X" or "treat each X as a separate record", that's almost always a

resourcePath

change, not a transform. Use transforms when you need to flatten nested objects, rename fields, or restructure individual records.

当流程运行时，每个导出都会严格按照以下顺序执行流程：

API请求/查询/文件读取——从外部系统获取原始数据
响应解析——
```
resourcePath
```
从响应体或文件中提取记录数组（例如，HTTP使用
```
http.response.resourcePath
```
，JSON文件使用
```
file.json.resourcePath
```
，XML使用XPath）
转换（可选）——
```
transform
```
在提取后重塑单个记录（Transformation 2.0）
输出过滤器（可选）——丢弃不符合过滤表达式规则的记录
preSavePage钩子（可选）——对整页记录执行JavaScript处理

关键区别：

resourcePath

告知导出在响应中的何处查找记录。转换则用于重塑提取后每条记录的内容。当用户说“从X中提取记录”或“将每个X视为单独记录”时，这几乎总是需要修改

resourcePath

，而非转换。仅当需要扁平化嵌套对象、重命名字段或重构单个记录时，才使用转换。

Three Categories of Export

导出的三类类型

Not all exports work the same way. Before building, understand which category you need:

并非所有导出的工作方式都相同。在构建前，需明确你需要的类型：

Listeners

监听器

Receive data pushed to Celigo from an external system. No polling, no scheduling -- the source system sends data when events happen.

```
WebhookExport
```
-- inbound HTTP listener (no connection required)
```
AS2Export
```
-- AS2 EDI file reception
Distributed exports (
```
type: "distributed"
```
) -- real-time event-driven push for NetSuite (via SuiteScript) and Salesforce (via streaming API). The platform installs listeners in the source system that fire when records change.
Change data capture (
```
type: "stream"
```
) -- MongoDB change streams that tail the oplog for real-time record changes.

When to use: The source system supports outbound webhooks, push notifications, or change data capture and you want real-time processing.

接收外部系统推送到Celigo的数据。无需轮询、无需调度——源系统在事件发生时发送数据。

```
WebhookExport
```
——入站HTTP监听器（无需连接）
```
AS2Export
```
——AS2 EDI文件接收
分布式导出（
```
type: "distributed"
```
）——NetSuite（通过SuiteScript）和Salesforce（通过流API）的实时事件驱动推送。平台会在源系统中安装监听器，当记录变更时触发。
变更数据捕获（
```
type: "stream"
```
）——MongoDB变更流，通过监听oplog获取实时记录变更。

**适用场景：**源系统支持出站Webhook、推送通知或变更数据捕获，且你需要实时处理。

File Transfers

文件传输

Read files from a remote location, then either parse them into records or transfer them as blobs.

```
FTPExport
```
/
```
S3Export
```
/
```
FileSystemExport
```
-- fetch files from FTP/SFTP, S3, or local filesystem
```
HTTPExport
```
with
```
http.type: "file"
```
-- fetch files over HTTP from cloud storage APIs (Google Drive, Box, Dropbox, Azure Blob Storage). The HTTP connector handles auth; the
```
file{}
```
config handles parsing.
```
NetSuiteExport
```
with
```
netsuite.type: "file"
```
-- fetch and parse files (CSV, JSON, XLSX, XML, EDI) from the NetSuite file cabinet
Parsed mode (
```
file.output: "records"
```
) -- CSV, XML, JSON, XLSX, EDI files are parsed into individual records
Blob mode (
```
type: "blob"
```
) -- binary files transferred as-is without parsing. Supported on HTTPExport, NetSuiteExport, SalesforceExport, FTPExport, and S3Export.

When to use: The source system drops files (CSV, EDI, XML, etc.) into a directory, bucket, file cabinet, or cloud storage rather than exposing a record-based API.

从远程位置读取文件，然后将其解析为记录或作为二进制大对象传输。

```
FTPExport
```
/
```
S3Export
```
/
```
FileSystemExport
```
——从FTP/SFTP、S3或本地文件系统获取文件
```
HTTPExport
```
搭配
```
http.type: "file"
```
——通过HTTP从云存储API（Google Drive、Box、Dropbox、Azure Blob Storage）获取文件。HTTP连接器处理认证；
```
file{}
```
配置处理解析。
```
NetSuiteExport
```
搭配
```
netsuite.type: "file"
```
——从NetSuite文件柜获取并解析文件（CSV、JSON、XLSX、XML、EDI）
解析模式（
```
file.output: "records"
```
）——CSV、XML、JSON、XLSX、EDI文件被解析为单个记录
二进制模式（
```
type: "blob"
```
）——二进制文件按原样传输，不进行解析。支持
```
HTTPExport
```
、
```
NetSuiteExport
```
、
```
SalesforceExport
```
、
```
FTPExport
```
和
```
S3Export
```
。

**适用场景：**源系统将文件（CSV、EDI、XML等）存入目录、存储桶、文件柜或云存储，而非提供基于记录的API。

Record-Based Exports

基于记录的导出

Actively fetch batches of records from an API or database on a schedule.

```
HTTPExport
```
-- REST/GraphQL APIs
```
NetSuiteExport
```
-- saved searches, restlets, SuiteQL
```
SalesforceExport
```
-- SOQL/Bulk queries
```
RDBMSExport
```
-- SQL SELECT queries
```
MongodbExport
```
,
```
JDBCExport
```
,
```
DynamodbExport
```
-- other databases
```
WrapperExport
```
-- custom stack (Walmart, BigCommerce)

When to use: You need to poll an API or query a database for records on a schedule (full fetch or delta/incremental).

按计划主动从API或数据库获取批量记录。

```
HTTPExport
```
——REST/GraphQL API
```
NetSuiteExport
```
——已保存搜索、Restlet、SuiteQL
```
SalesforceExport
```
——SOQL/批量查询
```
RDBMSExport
```
——SQL SELECT查询
```
MongodbExport
```
、
```
JDBCExport
```
、
```
DynamodbExport
```
——其他数据库
```
WrapperExport
```
——自定义栈（Walmart、BigCommerce）

**适用场景：**你需要按计划轮询API或查询数据库以获取记录（全量获取或增量获取）。

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

Your data comes from...	Use adaptorType	Category	Read schema
REST or GraphQL API	`HTTPExport`	Record-based	http.yml
Files over HTTP (Google Drive, Box, Dropbox, Azure Blob)	`HTTPExport` with `http.type: "file"`	File transfer	http.yml + file.yml
NetSuite (any method)	`NetSuiteExport`	Record-based	netsuite.yml
Salesforce objects	`SalesforceExport`	Record-based	salesforce.yml
SQL database	`RDBMSExport`	Record-based	rdbms.yml
MongoDB	`MongodbExport`	Record-based	mongodb.yml
JDBC database	`JDBCExport`	Record-based	jdbc.yml
DynamoDB	`DynamodbExport`	Record-based	dynamodb.yml
Files on FTP/SFTP	`FTPExport`	File transfer	ftp.yml + file.yml
Files on S3	`S3Export`	File transfer	s3.yml + file.yml
Webhooks / push events	`WebhookExport`	Listener	webhook.yml
AS2 EDI messages	`AS2Export`	Listener	as2.yml
Manual file upload	`SimpleExport`	File transfer	simple.yml
Local filesystem	`FileSystemExport`	File transfer	filesystem.yml + file.yml
Pre-built stack connector	`WrapperExport`	Record-based	wrapper.yml

Raw HTTP is the fallback, not the default. Pick the most specific match, in order:

Native adaptor -- if the application has its own row (NetSuite, Salesforce, databases, FTP/S3), use it. Do not build an
```
HTTPExport
```
against that app's REST API.
Pre-built HTTP connector -- for any other REST/GraphQL app, check the 550+ connector catalog before writing HTTP config (see Check for a pre-built connector). The step is still an
```
HTTPExport
```
, but it runs on a connector-backed connection and takes its endpoint config from the connector.
Manual HTTP -- hand-write the config from public API docs only when no connector exists or it doesn't cover the endpoint you need.

adaptorType

is case-sensitive:

HTTPExport

, not

httpExport

数据来源...	使用的adaptorType	类别	参考Schema
REST或GraphQL API	`HTTPExport`	基于记录	http.yml
HTTP协议传输的文件（Google Drive、Box、Dropbox、Azure Blob）	`HTTPExport` 搭配 `http.type: "file"`	文件传输	http.yml + file.yml
NetSuite（任意方式）	`NetSuiteExport`	基于记录	netsuite.yml
Salesforce对象	`SalesforceExport`	基于记录	salesforce.yml
SQL数据库	`RDBMSExport`	基于记录	rdbms.yml
MongoDB	`MongodbExport`	基于记录	mongodb.yml
JDBC数据库	`JDBCExport`	基于记录	jdbc.yml
DynamoDB	`DynamodbExport`	基于记录	dynamodb.yml
FTP/SFTP上的文件	`FTPExport`	文件传输	ftp.yml + file.yml
S3上的文件	`S3Export`	文件传输	s3.yml + file.yml
Webhook/推送事件	`WebhookExport`	监听器	webhook.yml
AS2 EDI消息	`AS2Export`	监听器	as2.yml
手动文件上传	`SimpleExport`	文件传输	simple.yml
本地文件系统	`FileSystemExport`	文件传输	filesystem.yml + file.yml
预构建栈连接器	`WrapperExport`	基于记录	wrapper.yml

**原生HTTP是 fallback 选项，而非默认选项。**按以下顺序选择最匹配的适配器：

原生适配器——如果应用有对应的行（NetSuite、Salesforce、数据库、FTP/S3），请使用它。不要针对该应用的REST API构建
```
HTTPExport
```
。
预构建HTTP连接器——对于其他REST/GraphQL应用，在编写HTTP配置前先查看550+连接器目录（详见检查预构建连接器）。该步骤仍为
```
HTTPExport
```
，但运行在连接器支持的连接上，并从连接器获取端点配置。
手动HTTP配置——仅当不存在连接器或连接器未覆盖你需要的端点时，才根据公开API文档手动编写配置。

adaptorType

区分大小写：

HTTPExport

，而非

httpExport

。

Minimum Required Fields

必填字段

Every export needs at minimum:

```
name
```
-- human-readable label
```
adaptorType
```
-- from the matrix above
```
_connectionId
```
-- except
```
WebhookExport
```
and
```
SimpleExport
```

Adaptor config block --

http{}

netsuite{}

ftp{}

salesforce{}

rdbms{}

, etc.

每个导出至少需要以下字段：

```
name
```
——人类可读的标签
```
adaptorType
```
——来自上述矩阵
```
_connectionId
```
——
```
WebhookExport
```
和
```
SimpleExport
```
除外

适配器配置块——

http{}

、

netsuite{}

、

ftp{}

、

salesforce{}

、

rdbms{}

等

Which Schemas to Read

需参考的Schema

Always: request.yml (base fields for all exports)
Plus: the adaptor-specific file from the matrix above (e.g.,
```
http.yml
```
for HTTPExport)
If file-based: also file.yml (CSV, XML, JSON, XLSX, EDI parsing config)
If delta/incremental: check delta.yml or Handlebars URI pattern (
```
{{{lastExportDateTime}}}
```
)
If cloning: clone-request.yml, clone-response.yml

必看：request.yml（所有导出的基础字段）
**附加：**上述矩阵中的适配器特定文件（例如，
```
HTTPExport
```
参考
```
http.yml
```
）
**如果是文件导出：**还需参考file.yml（CSV、XML、JSON、XLSX、EDI解析配置）
**如果是增量同步：**查看delta.yml或Handlebars URI模式（
```
{{{lastExportDateTime}}}
```
）
如果是克隆：clone-request.yml、clone-response.yml

Schema Index

Schema索引

All schemas are in references/schemas/:

Base fields (all exports): request.yml
Response shape: response.yml
Adaptor-specific config:
- http.yml -- HTTP/REST/GraphQL
- netsuite.yml -- NetSuite (restlet, saved search, SuiteQL, file cabinet)
- salesforce.yml -- Salesforce (SOQL, bulk)
- ftp.yml -- FTP/SFTP
- s3.yml -- Amazon S3
- rdbms.yml -- SQL databases
- mongodb.yml -- MongoDB
- jdbc.yml -- JDBC databases
- dynamodb.yml -- DynamoDB
- as2.yml -- AS2 EDI
- wrapper.yml -- custom stack connectors
- filesystem.yml -- local filesystem
- simple.yml -- data loader / manual upload
File parsing: file.yml (CSV, XML, JSON, XLSX, EDI)
Operational modes: delta.yml, webhook.yml, distributed.yml, once.yml
Mock output: mock-output.yml
Clone: clone-request.yml, clone-response.yml

所有Schema都在references/schemas/目录下：

基础字段（所有导出）：request.yml
响应格式：response.yml
适配器特定配置：
- http.yml——HTTP/REST/GraphQL
- netsuite.yml——NetSuite（Restlet、已保存搜索、SuiteQL、文件柜）
- salesforce.yml——Salesforce（SOQL、批量）
- ftp.yml——FTP/SFTP
- s3.yml——Amazon S3
- rdbms.yml——SQL数据库
- mongodb.yml——MongoDB
- jdbc.yml——JDBC数据库
- dynamodb.yml——DynamoDB
- as2.yml——AS2 EDI
- wrapper.yml——自定义栈连接器
- filesystem.yml——本地文件系统
- simple.yml——数据加载器/手动上传
文件解析：file.yml（CSV、XML、JSON、XLSX、EDI）
运行模式：delta.yml、webhook.yml、distributed.yml、once.yml
模拟输出：mock-output.yml
克隆：clone-request.yml、clone-response.yml

Related Skills

How to Build an Export

如何构建导出

1. Identify the target application

1. 确定目标应用

What system are you pulling data from? This determines everything -- adaptor type, connection type, and configuration shape.

你要从哪个系统拉取数据？这决定了所有内容——适配器类型、连接类型和配置格式。

2. Check for existing patterns

2. 检查现有模式

Before building from scratch, look at what already exists:

bash

undefined

在从头构建之前，先查看已有的资源：

bash

undefined

Search across the entire account for related resources

在整个账户中搜索相关资源

celigo account search "<keyword>"

Show what an existing export uses (connection) and what uses it (flows)

查看现有导出使用的连接以及哪些流程使用了该导出

celigo account dependencies export <id>

Find orphaned exports not referenced by any flow

查找未被任何流程引用的孤立导出

celigo account lint

Check if a similar export already exists in the account

检查账户中是否已存在类似的导出

celigo exports list | grep -i "<application-name>"

Search the marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

celigo templates marketplace

Preview a template to see its export configuration

预览模板以查看其导出配置

celigo templates preview <id> --model Export celigo templates preview <id> --summary


The account index auto-refreshes when stale (>4 hours). Force a fresh snapshot with `celigo account snapshot`.

Existing exports in the account are the best reference -- they show proven patterns for that specific customer's setup. Marketplace templates may provide a complete pre-built integration you can install rather than building from scratch.

celigo templates preview <id> --model Export celigo templates preview <id> --summary


账户索引在过期（>4小时）时会自动刷新。使用`celigo account snapshot`强制生成新的快照。

账户中的现有导出是最佳参考——它们展示了针对特定客户设置的已验证模式。市场模板可能提供完整的预构建集成，你可以直接安装而非从头构建。

3. Check for a pre-built connector

3. 检查预构建连接器

Always run this check before writing any HTTP config. Celigo maintains 550+ HTTP connector definitions and 590+ trading partner connectors. These provide pre-configured auth, base URLs, and endpoint definitions for common applications. Connectors are set on the connection, not the export -- but they determine what the export can do. Hand-write a manual

HTTPExport

from public API docs only when this search comes up empty or the connector doesn't cover the endpoint you need.

bash

undefined

在编写任何HTTP配置前务必执行此检查。Celigo维护了550+ HTTP连接器定义和590+交易伙伴连接器。这些连接器为常见应用提供了预配置的认证、基础URL和端点定义。连接器设置在连接上，而非导出上——但它们决定了导出能执行的操作。仅当搜索结果为空或连接器未覆盖你需要的端点时，才根据公开API文档手动编写

HTTPExport

配置。

bash

undefined

Search HTTP connectors (REST APIs: Shopify, Stripe, HubSpot, etc.)

搜索HTTP连接器（REST API：Shopify、Stripe、HubSpot等）

celigo http-connectors list | grep -i "<application-name>" celigo http-connectors get <id> --full # see endpoints, resources, auth config

celigo http-connectors list | grep -i "<application-name>" celigo http-connectors get <id> --full # 查看端点、资源、认证配置

Drill into the endpoints the connector defines for exports

深入查看连接器为导出定义的端点

celigo http-connectors catalog <id> --resource-type export --published-only celigo http-connectors endpoint-detail <id> --resource-type export --resource-id <rid> --endpoint-id <epid>

Search trading partner connectors (EDI, AS2, VAN)

搜索交易伙伴连接器（EDI、AS2、VAN）

celigo tp-connectors list


If an HTTP connector exists for your target app, create the connection from it (`http._httpConnectorId` -- see [configuring-connections > Check for a pre-built connector and global iClient](../configuring-connections/SKILL.md#4-check-for-a-pre-built-connector-and-global-iclient)) and take the export's `relativeURI`, method, pagination, and response paths from the connector's endpoint metadata rather than reconstructing them from public API docs. The connector-reference fields on the export itself (`http._httpConnectorEndpointId`, `http._httpConnectorVersionId`, `http._httpConnectorResourceId`) are read-only -- the platform sets them; what you control is the connection and the endpoint config you copy from the connector.

If a trading partner connector exists (EDI/AS2), reference it on the export via `ftp._tpConnectorId` (FTP exports) or `as2._tpConnectorId` (AS2 exports). You may also need to set `_ediProfileId` on the export for EDI document validation.

celigo tp-connectors list


如果目标应用存在HTTP连接器，请基于它创建连接（`http._httpConnectorId`——详见[configuring-connections > 检查预构建连接器和全局iClient](../configuring-connections/SKILL.md#4-check-for-a-pre-built-connector-and-global-iclient)），并从连接器的端点元数据中获取导出的`relativeURI`、方法、分页和响应路径，而非根据公开API文档重新构建。导出本身的连接器参考字段（`http._httpConnectorEndpointId`、`http._httpConnectorVersionId`、`http._httpConnectorResourceId`）是只读的——由平台设置；你需要控制的是连接以及从连接器复制的端点配置。

如果存在交易伙伴连接器（EDI/AS2），通过`ftp._tpConnectorId`（FTP导出）或`as2._tpConnectorId`（AS2导出）在导出中引用它。你可能还需要在导出上设置`_ediProfileId`以进行EDI文档验证。

4. Query metadata for the target system

4. 查询目标系统的元数据

For NetSuite, Salesforce, and RDBMS connections, you can discover available record types and fields directly from the live system:

bash

undefined

对于NetSuite、Salesforce和RDBMS连接，你可以直接从实时系统中发现可用的记录类型和字段：

bash

undefined

List available record types / sObjects / tables

列出可用的记录类型/sObjects/表

NetSuite also returns saved searches alongside record types

NetSuite还会返回已保存搜索和记录类型

celigo metadata types <connectionId>

List fields for a specific entity type

列出特定实体类型的字段

celigo metadata fields <connectionId> <entityType>


This tells you what data is available to export before you write any configuration.

- **NetSuite:** `metadata types` returns both record types and saved searches (with IDs you need for `netsuite.restlet.searchId`). `metadata fields` returns field IDs, names, types, and group — including sublist fields you'll need for `mapping.lists[].generate` on the import side.
- **Salesforce:** `metadata types` returns sObjects with queryable/createable flags. `metadata fields` returns fields, types, and relationship names — use these to discover child objects for `distributed.relatedLists[]` and relationship field names for cross-object queries.
- **RDBMS:** `metadata types` returns table names. `metadata fields` returns column names and types for a given table — use these when writing SQL queries or building field mappings.

celigo metadata fields <connectionId> <entityType>


这能让你在编写任何配置前了解可导出的数据。

- **NetSuite：**`metadata types`返回记录类型和已保存搜索（包含`netsuite.restlet.searchId`所需的ID）。`metadata fields`返回字段ID、名称、类型和分组——包括导入端`mapping.lists[].generate`所需的子列表字段。
- **Salesforce：**`metadata types`返回带有可查询/可创建标记的sObjects。`metadata fields`返回字段、类型和关系名称——用于发现`distributed.relatedLists[]`的子对象以及跨对象查询的关系字段名称。
- **RDBMS：**`metadata types`返回表名。`metadata fields`返回给定表的列名和类型——用于编写SQL查询或构建字段映射。

5. Determine the category

5. 确定导出类型

Is this a listener (real-time push from the source), a file transfer (fetch and parse/transfer files), or a record-based export (poll an API or query a database)? This narrows which adaptor types and modes apply.

这是监听器（源系统实时推送）、文件传输（获取并解析/传输文件）还是基于记录的导出（轮询API或查询数据库）？这会缩小适用的适配器类型和模式范围。

6. Choose the right adaptor type

6. 选择合适的适配器类型

Use the Adaptor Decision Matrix in Quick Reference above to select the correct

adaptorType

for your target system.

使用上述快速参考中的适配器决策矩阵为目标系统选择正确的

adaptorType

。

7. Build the export JSON

7. 构建导出JSON

Use the Schema Index and Which Schemas to Read in Quick Reference above. Read

request.yml

for base fields, then the adaptor-specific schema, plus

file.yml

if file-based and

delta.yml

if incremental.

使用上述快速参考中的Schema索引和需参考的Schema。先查看

request.yml

获取基础字段，再查看适配器特定的Schema，如果是文件导出还需查看

file.yml

，如果是增量同步则查看

delta.yml

。

Export Design Decisions

导出设计决策

A few design choices recur when building exports. Each has a defensible default once the framing is clear.

构建导出时会遇到一些常见的设计选择。一旦明确场景，每个选择都有合理的默认值。

Delta vs one-time vs full sync

增量同步 vs 一次性同步 vs 全量同步

The export's

type

field selects the sync behavior:

Delta (
```
type: "delta"
```
) -- pulls only records created or modified since the last successful run. The default for ongoing scheduled syncs when the source exposes a usable "last modified" timestamp. Non-HTTP adaptors set the timestamp field via
```
delta.dateField
```
; HTTP exports instead embed
```
{{{lastExportDateTime}}}
```
in the
```
relativeURI
```
or body. See delta.yml.
One-time (
```
type: "once"
```
) -- processes each record exactly once via a tracking flag: each run selects records where
```
once.booleanField
```
is
```
false
```
, then sets it to
```
true
```
after a page succeeds so later runs skip them. Use for backfills and migrations, or when the source has no reliable timestamp but its records can carry a processed flag. See once.yml.
Full (neither
```
delta
```
nor
```
once
```
mode) -- re-pulls the entire dataset every run. Use when the source has no usable modification timestamp, the dataset is small enough that re-pulling is cheap, or business logic requires a fresh snapshot each run.

When the request is vague ("sync customers"), confirm which kind of sync is intended before building. Delta is a reasonable default when the source exposes a timestamp field; full is reasonable for small static datasets.

导出的

type

字段选择同步行为：

增量（
```
type: "delta"
```
）——仅拉取自上次成功运行以来创建或修改的记录。当源系统提供可用的“最后修改”时间戳时，这是持续计划同步的默认选项。非HTTP适配器通过
```
delta.dateField
```
设置时间戳字段；HTTP导出则在
```
relativeURI
```
或请求体中嵌入
```
{{{lastExportDateTime}}}
```
。详见delta.yml。
一次性（
```
type: "once"
```
）——通过跟踪标记确保每条记录仅处理一次：每次运行选择
```
once.booleanField
```
为
```
false
```
的记录，在页面处理成功后将其设置为
```
true
```
，以便后续运行跳过这些记录。适用于回填和迁移，或源系统无可靠时间戳但记录可携带处理标记的场景。详见once.yml。
全量（既非
```
delta
```
也非
```
once
```
模式）——每次运行重新拉取整个数据集。适用于源系统无可用修改时间戳、数据集足够小以至于重新拉取成本低，或业务逻辑要求每次运行获取最新快照的场景。

当需求模糊时（例如“同步客户”），在构建前确认所需的同步类型。当源系统提供时间戳字段时，增量同步是合理的默认选项；对于小型静态数据集，全量同步是合理的选择。

Listener/webhook vs scheduled export

监听器/Webhook vs 计划导出

Both are starting steps (see Three Categories of Export); the choice is driven by what the source supports and the latency budget, not preference:

Reach for a listener (
```
WebhookExport
```
, or NetSuite/Salesforce
```
type: "distributed"
```
) when the source pushes events and the flow needs to react quickly ("when X happens, do Y").
Reach for a scheduled export when the source has no push mechanism, or when batch timing at off-peak hours is acceptable.

NetSuite and Salesforce support both for many record types. Mixing them on one flow is a common, good pattern -- a listener handles low-latency reactions while a scheduled export runs as a safety net for backfills, end-of-day reconciliation, and catching up after a webhook outage.

两者都是起始步骤（详见导出的三类类型）；选择取决于源系统支持的功能和延迟要求，而非偏好：

当源系统支持推送事件且流程需要快速响应时（“当X发生时，执行Y”），选择监听器（
```
WebhookExport
```
，或NetSuite/Salesforce的
```
type: "distributed"
```
）。
当源系统无推送机制，或可接受在非高峰时段批量处理时，选择计划导出。

NetSuite和Salesforce的许多记录类型同时支持这两种方式。在一个流程中混合使用它们是常见且良好的模式——监听器处理低延迟响应，而计划导出作为回填、日终对账和Webhook故障后追补的安全网。

Lookup export vs separate scheduled export

查找导出 vs 单独的计划导出

The distinguishing question is when the data is needed:

A lookup export (
```
isLookup: true
```
) runs per in-flight record, mid-pipeline, keyed off the upstream record -- fetching the customer for a specific order, or inventory for a specific SKU.
A scheduled export runs once per flow run as a starting point, producing the first batch of records the flow processes.

If the request is "for each X, look up Y", it's a lookup. If it's "every hour, pull all Y", it's a scheduled export.

区分的关键在于数据的需求时机：

查找导出（
```
isLookup: true
```
）针对流程中的每条记录运行，在流程中间根据上游记录的键获取数据——例如，为特定订单查找客户，或为特定SKU查找库存。
计划导出在每次流程运行时作为起始步骤运行一次，生成流程处理的首批记录。

如果需求是“为每个X查找Y”，则使用查找导出。如果需求是“每小时拉取所有Y”，则使用计划导出。

One-to-many fan-out -- the array element IS the record

一对多展开——数组元素即为记录

With

oneToMany: true

and

pathToMany

set to a child array path, each element of that array triggers its own lookup. Once fanned out, the element becomes the record: templates reference the element's own fields as

{{record.variantId}}

-- not

{{variantId}}

, and not

{{record.lineItems.variantId}}

. The array wrapper is gone; you are inside one element.

Three consequences worth knowing before you debug the wrong thing:

The build-time preview warning is expected. Previewing a fanned-out lookup in isolation reports "
```
<field>
```
not defined in the model" because no upstream record is bound yet. That is not a broken template -- don't "fix" a correct
```
{{record.X}}
```
reference because of it.
Response mapping merges per element automatically. To get looked-up values back onto each element, author a normal top-level
```
fields
```
response mapping; Celigo merges each result into its corresponding fanned-out element.
Two anti-patterns. Don't target the array with a
```
lists
```
entry (that nests a new array inside each element), and don't attempt the per-element merge in
```
postResponseMap
```
(it sees the page of parent records, not per-element results).

设置

oneToMany: true

并将

pathToMany

指定为子数组路径后，该数组的每个元素都会触发单独的查找。展开后，元素本身即为记录：模板引用元素自身的字段为

{{record.variantId}}

——而非

{{variantId}}

，也非

{{record.lineItems.variantId}}

。数组包装已消失；你操作的是单个元素。

在调试前需了解三个重要影响：

**构建时预览警告是正常现象。**单独预览展开后的查找会提示“
```
<field>
```
未在模型中定义”，因为此时尚未绑定上游记录。这并非模板错误——不要因此修改正确的
```
{{record.X}}
```
引用。
**响应映射会自动按元素合并。**要将查找值合并到每个元素中，编写常规的顶层
```
fields
```
响应映射即可；Celigo会将每个结果合并到对应的展开元素中。
**两种反模式。**不要用
```
lists
```
项指向数组（这会在每个元素中嵌套新数组），也不要尝试在
```
postResponseMap
```
中进行按元素合并（它看到的是父记录页面，而非按元素的结果）。

Source-side transform vs destination-side mapping

源端转换 vs 目标端映射

Both reshape data, but in opposite directions:

A transform on a source export reshapes records as they enter the flow -- flattening nested responses, or aligning multiple sources to a common shape (see Export Execution Pipeline).
A mapping on a downstream import reshapes records as they leave the flow toward a destination.

Don't add a transform to "match a destination" -- that's the destination import mapping's job. Transforms are for entry reshaping; mappings are for exit reshaping.

两者都会重塑数据，但方向相反：

源导出的转换在记录进入流程时重塑数据——扁平化嵌套响应，或使多个源的数据对齐为通用格式（详见导出执行流程）。
下游导入的映射在记录离开流程前往目标系统时重塑数据。

不要为“匹配目标系统”添加转换——这是目标导入映射的职责。转换用于入口数据重塑；映射用于出口数据重塑。

Async APIs (submit, poll, fetch)

异步API（提交、轮询、获取）

Most APIs return data in the same call and need none of this. Some APIs only acknowledge a request (an HTTP 202, a job ticket, a feed or document id) and process it in the background -- Amazon SP-API feeds, large report generators, bulk extract and file-conversion jobs. For those, attach an async helper to the export via

http._asyncHelperId

. The helper teaches the step the submit-poll-fetch pattern; it is part of the export, not something managed on its own, and bundles three pieces:

A status export (required) -- run on each poll to ask "is it done yet?". Configure the status path to read in the response, the case-sensitive in-progress / done / done-without-data / error value lists (taken from the API's docs), and the initial wait and poll wait intervals in minutes.
A result export (optional, usually present) -- fetches the final payload once status reports done.
Initial-submission handling -- where to find the job ticket in the first acknowledgement: "same as status" when the acknowledgement is itself shaped like a status response, otherwise a resource path (plus transform rules for non-JSON acknowledgements, e.g. Amazon's XML).

Two constraints shape the design: the status and result exports must be ordinary synchronous exports (an async helper cannot nest another), and the async-configured step cannot carry its own transform, output filter, or preSavePage hook -- put any reshaping or filtering on the dedicated result export instead. The same pattern applies symmetrically to imports writing to asynchronous destinations (

_asyncHelperId

on the import).

Reach for an async helper only when the API genuinely forces the fire-and-check-back shape. Adding one to a synchronous API is pure overhead -- extra polling plus a status and result export to maintain.

大多数API会在同一调用中返回数据，无需额外处理。部分API仅确认请求（HTTP 202、工单、Feed或文档ID）并在后台处理——例如Amazon SP-API Feed、大型报表生成器、批量提取和文件转换任务。对于这类API，通过

http._asyncHelperId

将异步助手附加到导出。助手会告知步骤提交-轮询-获取的模式；它是导出的一部分，而非独立管理的资源，包含三个部分：

状态导出（必填）——每次轮询时运行，询问“处理完成了吗？”。配置状态路径以读取响应，区分大小写的进行中/完成/无数据完成/错误值列表（取自API文档），以及初始等待和轮询等待间隔（分钟）。
结果导出（可选，通常存在）——当状态报告完成时获取最终负载。
初始提交处理——在首次确认中查找工单的位置：当确认本身的格式与状态响应相同时，使用“与状态相同”；否则使用资源路径（加上针对非JSON确认的转换规则，例如Amazon的XML）。

设计受两个约束：状态和结果导出必须是普通的同步导出（异步助手不能嵌套另一个异步助手），且配置了异步的步骤不能携带自己的转换、输出过滤器或preSavePage钩子——将任何重塑或过滤逻辑放在专用的结果导出中。相同模式对称适用于写入异步目标的导入（在导入上设置

_asyncHelperId

）。

仅当API确实要求先触发再检查的模式时，才使用异步助手。为同步API添加异步助手纯粹是额外开销——额外的轮询加上需要维护的状态和结果导出。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD

CRUD操作

celigo exports list celigo exports get <id> celigo exports create < export.json celigo exports update <id> < export.json celigo exports set <id> key=value [key2=value2 ...] celigo exports delete <id>

Invoke (test-run an export, see what data comes back)

调用（测试运行导出，查看返回的数据）

celigo exports invoke [id] [--all]

Clone and connection management

克隆和连接管理

echo '{"connectionMap":{"oldConnId":"newConnId"}}' | celigo exports clone <id> celigo exports replace-connection <id> <newConnectionId>

Discovery

发现

celigo account search "<keyword>" celigo templates marketplace celigo templates preview <id> --model Export celigo templates preview <id> --summary celigo http-connectors list celigo http-connectors catalog <id> --resource-type export --published-only celigo http-connectors endpoint-detail <id> --resource-type export --resource-id <rid> --endpoint-id <epid> celigo tp-connectors list celigo metadata types <connectionId> celigo metadata fields <connectionId> <entityType>

Debug

调试

celigo exports enable-debug <id> [--duration <minutes>] celigo exports disable-debug <id>


<!-- TIER:3 -->

celigo exports enable-debug <id> [--duration <minutes>] celigo exports disable-debug <id>


<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Before creating or updating an export, verify:

adaptorType
is exact -- case-sensitive, matches the Adaptor Decision Matrix (e.g.,
```
HTTPExport
```
, not
```
httpExport
```
or
```
HttpExport
```
)
Pre-built connector was checked -- for HTTP exports,
```
celigo http-connectors list
```
found no connector for the app (or the connector lacks the endpoint) before any hand-written
```
relativeURI
```
_connectionId
is valid -- points to an existing, online connection of the correct type. Not needed for
```
WebhookExport
```
or
```
SimpleExport
```
Adaptor config block is present --
```
http{}
```
,
```
netsuite{}
```
,
```
ftp{}
```
, etc. matches the
```
adaptorType
```
resourcePath
or query is correct -- wrong path silently returns 0 records with no error
Pagination is configured -- for HTTP exports, set
```
http.paging
```
if the API returns paginated results
Delta/incremental is configured -- if using delta, check
```
delta.dateField
```
or Handlebars
```
{{{lastExportDateTime}}}
```
in the URI
File parsing matches the format -- if file-based,
```
file.type
```
matches the actual file format (csv, json, xml, xlsx, edi)

mockOutput
format is correct --

{ "page_of_records": [{ "record": {...} }] }

, not a plain array

No
rest:
block --
```
rest:
```
creates a legacy RESTExport. Use only
```
http:
```
for new exports
Output filter syntax is valid -- if using an output filter expression, test it against sample data
Lookup config is complete -- if
```
isLookup: true
```
, ensure response mapping is planned for the flow's
```
pageProcessors[]
```
entry

在创建或更新导出前，验证以下内容：

adaptorType
完全匹配——区分大小写，与适配器决策矩阵一致（例如
```
HTTPExport
```
，而非
```
httpExport
```
或
```
HttpExport
```
）
已检查预构建连接器——对于HTTP导出，在编写任何手动
```
relativeURI
```
前，
```
celigo http-connectors list
```
未找到应用对应的连接器（或连接器缺少所需端点）
_connectionId
有效——指向现有且在线的正确类型连接。
```
WebhookExport
```
和
```
SimpleExport
```
无需此项
存在适配器配置块——
```
http{}
```
、
```
netsuite{}
```
、
```
ftp{}
```
等与
```
adaptorType
```
匹配
resourcePath
或查询正确——错误的路径会静默返回0条记录且无错误
已配置分页——对于HTTP导出，如果API返回分页结果，需设置
```
http.paging
```
已配置增量同步——如果使用增量同步，检查
```
delta.dateField
```
或URI中的Handlebars
```
{{{lastExportDateTime}}}
```
文件解析与格式匹配——如果是文件导出，
```
file.type
```
与实际文件格式匹配（csv、json、xml、xlsx、edi）

mockOutput
格式正确——格式为

{ "page_of_records": [{ "record": {...} }] }

，而非普通数组

无
rest:
块——
```
rest:
```
会创建旧版RESTExport。新导出仅使用
```
http:
```
输出过滤器语法有效——如果使用输出过滤器表达式，需针对样本数据测试
查找配置完整——如果
```
isLookup: true
```
，需确保流程的
```
pageProcessors[]
```
项中已规划响应映射

Gotchas

常见陷阱

PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this.
Including a
rest:
block creates a legacy RESTExport. Use only
```
http:
```
for new exports.
Wrong
resourcePath
produces 0 records with no error. First thing to check when an export succeeds but returns nothing.

mockOutput
format is
{ "page_of_records": [{ "record": {...} }] }
. Not a plain array.

HTTP delta exports use Handlebars (

{{{lastExportDateTime}}}

relativeURI

), not

delta.dateField

NetSuite saved searches need
netsuite.restlet.searchId
. Use

celigo metadata types <connectionId>

to find the search ID.

File exports require the
file{}
block. Without it, file-based exports return raw bytes instead of parsed records.
Webhook exports have no
_connectionId
. Setting one causes validation errors.
Distributed exports require
type: "distributed"
on the export AND
distributed: true
on the connection.
type: "once"
needs a dedicated, writeable tracking flag.
```
once.booleanField
```
must be writeable by the export's connection, and no other process may update the same field -- a shared flag causes records to be skipped.
An async-helper export cannot carry its own transform, output filter, or preSavePage hook. Build that processing into the helper's result export instead. The status and result exports must themselves be plain synchronous exports -- an async helper cannot nest another. See Async APIs (submit, poll, fetch).

**PUT会删除未指定的字段。**始终先GET，修改后再PUT。
```
set
```
命令会处理此问题。
**包含
```
rest:
```
块会创建旧版RESTExport。**新导出仅使用
```
http:
```
**错误的
```
resourcePath
```
会返回0条记录且无错误。**当导出成功但未返回任何数据时，首先检查此项。

mockOutput

格式为

{ "page_of_records": [{ "record": {...} }] }

。**而非普通数组。

HTTP增量导出使用Handlebars（
```
relativeURI
```
中的
```
{{{lastExportDateTime}}}
```
），而非
```
delta.dateField
```
。

**NetSuite已保存搜索需要

netsuite.restlet.searchId

。**使用

celigo metadata types <connectionId>

查找搜索ID。

**文件导出需要
```
file{}
```
块。**没有它，文件导出会返回原始字节而非解析后的记录。
**Webhook导出无
```
_connectionId
```
。**设置此项会导致验证错误。
分布式导出需要在导出上设置
type: "distributed"
，且在连接上设置
distributed: true
。
type: "once"
需要专用的可写入跟踪标记。
```
once.booleanField
```
必须可被导出的连接写入，且其他进程不得更新同一字段——共享标记会导致记录被跳过。
**配置了异步助手的导出不能携带自己的转换、输出过滤器或preSavePage钩子。**将这些处理逻辑构建到助手的结果导出中。状态和结果导出本身必须是普通的同步导出——异步助手不能嵌套另一个异步助手。详见异步API（提交、轮询、获取）。

Common Errors

常见错误

Error	Likely Cause	Fix
`404 Not Found` on export invoke	Wrong `relativeURI` or `resourcePath`	Verify the endpoint path against the API docs; check for missing path parameters
`401 Unauthorized`	Connection credentials expired or invalid	Run `celigo connections ping <connId>` ; re-authorize OAuth connections
`0 records exported` (no error)	Wrong `resourcePath` , empty date range, or overly restrictive filter	Check `resourcePath` , widen delta window, test without output filter
`Cannot read property of undefined` in preSavePage	Script assumes a field exists that is missing from some records	Add null checks: `if (record.field)` before access
`mockOutput is invalid`	Wrong format -- used array instead of object	Use `{ "page_of_records": [{ "record": {...} }] }`
`Invalid adaptorType`	Case mismatch or typo	Use exact casing from the Adaptor Decision Matrix
`Connection is offline`	Connection failed health check	Fix credentials, re-authorize, then `celigo connections ping <id>`
`Rate limit exceeded` / `429`	Too many concurrent requests to the source API	Lower `concurrencyLevel` on the connection; add retry config
`Timeout` on large exports	Query returns too much data or API is slow	Add pagination, narrow the date range, or increase timeout settings
`File parsing error`	`file.type` doesn't match actual file format, or delimiter/encoding mismatch	Verify `file.type` , check `file.csv.columnDelimiter` , ensure correct encoding

错误	可能原因	修复方法
导出调用时出现 `404 Not Found`	`relativeURI` 或 `resourcePath` 错误	根据API文档验证端点路径；检查是否缺少路径参数
`401 Unauthorized`	连接凭证过期或无效	运行 `celigo connections ping <connId>` ；重新授权OAuth连接
`0 records exported` （无错误）	`resourcePath` 错误、日期范围为空或过滤器过于严格	检查 `resourcePath` 、扩大增量窗口、移除输出过滤器测试
preSavePage中出现 `Cannot read property of undefined`	脚本假设存在某些记录中缺少的字段	添加空值检查：访问前先判断 `if (record.field)`
`mockOutput is invalid`	格式错误——使用了数组而非对象	使用 `{ "page_of_records": [{ "record": {...} }] }` 格式
`Invalid adaptorType`	大小写不匹配或拼写错误	使用适配器决策矩阵中的精确大小写
`Connection is offline`	连接健康检查失败	修复凭证、重新授权，然后运行 `celigo connections ping <id>`
`Rate limit exceeded` / `429`	对源API的并发请求过多	降低连接的 `concurrencyLevel` ；添加重试配置
大型导出出现 `Timeout`	查询返回数据过多或API响应缓慢	添加分页、缩小日期范围或增加超时设置
`File parsing error`	`file.type` 与实际文件格式不匹配，或分隔符/编码不匹配	验证 `file.type` 、检查 `file.csv.columnDelimiter` 、确保编码正确

configuring-exports

Original

Translation

Configuring Exports

配置导出

Export Execution Pipeline

导出执行流程

Three Categories of Export

导出的三类类型

Listeners

监听器

File Transfers

文件传输

Record-Based Exports

基于记录的导出

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

Minimum Required Fields

必填字段

Which Schemas to Read

需参考的Schema

Schema Index

Schema索引

Related Skills

相关技能

How to Build an Export

如何构建导出

1. Identify the target application

1. 确定目标应用

2. Check for existing patterns

2. 检查现有模式

Search across the entire account for related resources

在整个账户中搜索相关资源

Show what an existing export uses (connection) and what uses it (flows)

查看现有导出使用的连接以及哪些流程使用了该导出

Find orphaned exports not referenced by any flow

查找未被任何流程引用的孤立导出

Check if a similar export already exists in the account

检查账户中是否已存在类似的导出

Search the marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

Preview a template to see its export configuration

预览模板以查看其导出配置

3. Check for a pre-built connector

3. 检查预构建连接器

Search HTTP connectors (REST APIs: Shopify, Stripe, HubSpot, etc.)

搜索HTTP连接器（REST API：Shopify、Stripe、HubSpot等）

Drill into the endpoints the connector defines for exports

深入查看连接器为导出定义的端点

Search trading partner connectors (EDI, AS2, VAN)

搜索交易伙伴连接器（EDI、AS2、VAN）

4. Query metadata for the target system

4. 查询目标系统的元数据

List available record types / sObjects / tables

列出可用的记录类型/sObjects/表

NetSuite also returns saved searches alongside record types

NetSuite还会返回已保存搜索和记录类型

List fields for a specific entity type

列出特定实体类型的字段

5. Determine the category

5. 确定导出类型

6. Choose the right adaptor type

6. 选择合适的适配器类型

7. Build the export JSON

7. 构建导出JSON

Export Design Decisions

导出设计决策

Delta vs one-time vs full sync

增量同步 vs 一次性同步 vs 全量同步

Listener/webhook vs scheduled export

监听器/Webhook vs 计划导出

Lookup export vs separate scheduled export

查找导出 vs 单独的计划导出

One-to-many fan-out -- the array element IS the record

一对多展开——数组元素即为记录

Source-side transform vs destination-side mapping

源端转换 vs 目标端映射

Async APIs (submit, poll, fetch)