configuring-imports

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Imports

配置导入

An import is the data destination in a Celigo integration. It takes records from an upstream step and writes them to an external system -- REST APIs, databases, ERPs, file servers, or AI models. Every import is bound to exactly one connection and one adaptor type.

Imports handle six concerns:

Field mapping -- transforming source fields into the destination system's expected format (including value resolution via static maps and lookup tables). Uses Mapper 2.0 (
```
mappings[]
```
array) by default; NetSuite and Salesforce imports only support Mapper 1.0 (
```
mapping.fields[]
```
/
```
mapping.lists[]
```
)
Operation logic -- create, update, upsert, delete, attach/detach
Hooks -- JavaScript pre/post processing at various pipeline stages (preMap, postMap, postSubmit). File-based imports that generate files from records also support postAggregate
One-to-many -- fan out child records from a parent. Set
```
oneToMany: true
```
and
```
pathToMany
```
to the child array path (e.g.,
```
"lineItems"
```
) when one source record should create multiple import operations
Response mapping -- extract fields from the import's API response back into the record for downstream steps. Configured on the flow's
```
pageProcessors[]
```
entry, but planned when building the import. The response is available via
```
_json
```
(the raw API response) and
```
errors
```
. Use
```
_json.fieldName
```
to extract from the response (e.g.,
```
_json.id
```
for a created record's ID,
```
_json.output.1.content.0.text
```
for OpenAI responses). 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 response back into the record. Configured on the flow's
```
pageProcessors[]
```
entry, but planned when building the import. Use to transform or enrich the merged record before downstream steps

Imports are used across flows, APIs, and tools.

导入是Celigo集成中的数据目标。它将上游步骤的记录写入外部系统——REST APIs、数据库、ERP、文件服务器或AI模型。每个导入都绑定到恰好一个连接和一种适配器类型。

导入需处理六个核心事项：

字段映射——将源字段转换为目标系统预期的格式（包括通过静态映射和查找表解析值）。默认使用Mapper 2.0（
```
mappings[]
```
数组）；仅NetSuite和Salesforce导入支持Mapper 1.0（
```
mapping.fields[]
```
/
```
mapping.lists[]
```
）
操作逻辑——创建、更新、Upsert、删除、附加/分离
Hooks——在管道各阶段执行JavaScript预处理/后处理（preMap、postMap、postSubmit）。从记录生成文件的基于文件的导入还支持postAggregate
一对多——从父记录展开子记录。当一条源记录需要创建多个导入操作时，设置
```
oneToMany: true
```
并将
```
pathToMany
```
指定为子数组路径（例如
```
"lineItems"
```
）
响应映射——从导入的API响应中提取字段并返回到记录中，供下游步骤使用。在流的
```
pageProcessors[]
```
条目上配置，但需在构建导入时规划。可通过
```
_json
```
（原始API响应）和
```
errors
```
访问响应。使用
```
_json.fieldName
```
提取响应中的字段（例如
```
_json.id
```
获取创建记录的ID，
```
_json.output.1.content.0.text
```
获取OpenAI响应）。响应映射使用Transformation 1.0语法（提取/生成对），而非较新的基于表达式的转换
postResponseMap hook——响应映射将响应合并到记录后执行JavaScript处理。在流的
```
pageProcessors[]
```
条目上配置，但需在构建导入时规划。用于在下游步骤之前转换或丰富合并后的记录

导入可在流、API和工具中通用。

Import Execution Pipeline

导入执行管道

When records arrive at an import step, this pipeline executes in strict order:

Input filter (optional) -- discards records before any processing (configured as an expression on the flow's
```
pageProcessors[]
```
entry)
preMap hook (optional) -- JavaScript processing before field mapping
Field mapping -- Mapper 2.0 or 1.0 maps source fields to destination fields, including lookups and hardcoded values
postMap hook (optional) -- JavaScript processing after field mapping, before submission
Submit to destination -- writes the mapped record to the external system
postSubmit hook (optional) -- JavaScript processing after the destination responds (access response data, log results, trigger side effects)
Response mapping (optional) -- carries data from the destination response back into the record for downstream steps. Configured on the flow's
```
pageProcessors[]
```
entry, not on the import itself
postResponseMap hook (optional) -- JavaScript processing after response mapping merges response data back into the record

Key distinction: Response mapping lives on the flow's

pageProcessors[]

entry, not on the import resource. When building an import that needs to pass data downstream, plan the response mapping at flow design time.

当记录到达导入步骤时，将严格按以下顺序执行此管道：

输入过滤器（可选）——在任何处理前丢弃记录（在流的
```
pageProcessors[]
```
条目上配置为表达式）
preMap hook（可选）——字段映射前的JavaScript处理
字段映射——Mapper 2.0或1.0将源字段映射到目标字段，包括查找和硬编码值
postMap hook（可选）——字段映射后、提交前的JavaScript处理
提交到目标系统——将映射后的记录写入外部系统
postSubmit hook（可选）——目标系统响应后的JavaScript处理（访问响应数据、记录结果、触发副作用）
响应映射（可选）——将目标系统响应中的数据带回记录，供下游步骤使用。在流的
```
pageProcessors[]
```
条目上配置，而非导入本身
postResponseMap hook（可选）——响应映射将响应数据合并到记录后的JavaScript处理

**关键区别：**响应映射位于流的

pageProcessors[]

条目上，而非导入资源中。当构建需要向下游传递数据的导入时，需在流设计阶段规划响应映射。

Categories of Import

导入类别

Record-Based Imports

基于记录的导入

Submit structured records to APIs, databases, or ERPs. The vast majority of imports.

```
NetSuiteDistributedImport
```
-- high-performance SuiteApp writes (add, update, addupdate, delete, attach, detach)
```
HTTPImport
```
-- REST/GraphQL APIs (POST, PUT, PATCH, DELETE). Supports connector-assisted (
```
formType: "assistant"
```
) and GraphQL (
```
graph_ql
```
) modes
```
SalesforceImport
```
-- Salesforce CRUD via SOAP, REST, Bulk, or Composite Record API
```
RDBMSImport
```
-- SQL databases (Snowflake, PostgreSQL, MySQL, SQL Server, Oracle). Uses
```
per_record
```
,
```
bulk_insert
```
, or
```
bulk_load
```
query types
```
MongodbImport
```
,
```
DynamodbImport
```
,
```
JDBCImport
```
-- other databases

将结构化记录提交到API、数据库或ERP。这是绝大多数导入类型。

```
NetSuiteDistributedImport
```
——高性能SuiteApp写入（添加、更新、addupdate、删除、附加、分离）
```
HTTPImport
```
——REST/GraphQL APIs（POST、PUT、PATCH、DELETE）。支持连接器辅助（
```
formType: "assistant"
```
）和GraphQL（
```
graph_ql
```
）模式
```
SalesforceImport
```
——通过SOAP、REST、Bulk或Composite Record API实现Salesforce CRUD操作
```
RDBMSImport
```
——SQL数据库（Snowflake、PostgreSQL、MySQL、SQL Server、Oracle）。支持
```
per_record
```
、
```
bulk_insert
```
或
```
bulk_load
```
查询类型
```
MongodbImport
```
、
```
DynamodbImport
```
、
```
JDBCImport
```
——其他数据库类型

File-Based Imports

基于文件的导入

Write or upload files to remote storage. Require the

file{}

configuration block. Two modes:

Record-to-file -- aggregates incoming records into a file (CSV, JSON, XML, XLSX). The
```
file{}
```
block defines the output format.
Blob passthrough -- transfers a binary blob as-is from an upstream export. Set the
```
blobKeyPath
```
field to the path in the record that contains the blob key.

Adaptor types:

```
HTTPImport
```
with
```
http.type: "file"
```
-- upload files over HTTP to cloud storage APIs (Google Drive, Box, Dropbox, Azure Blob Storage)
```
FTPImport
```
-- CSV, XML, JSON, XLSX, EDI files to FTP/SFTP
```
S3Import
```
-- objects to Amazon S3
```
AS2Import
```
-- AS2 EDI file transmission
```
FileSystemImport
```
-- local/on-premise filesystem writes

将文件写入或上传到远程存储。需要

file{}

配置块。分为两种模式：

记录转文件——将传入的记录聚合为文件（CSV、JSON、XML、XLSX）。
```
file{}
```
块定义输出格式。
Blob直通——将二进制Blob按原样从上游导出传递。设置
```
blobKeyPath
```
字段为记录中包含Blob键的路径。

适配器类型：

```
HTTPImport
```
搭配
```
http.type: "file"
```
——通过HTTP将文件上传到云存储API（Google Drive、Box、Dropbox、Azure Blob Storage）
```
FTPImport
```
——将CSV、XML、JSON、XLSX、EDI文件上传到FTP/SFTP
```
S3Import
```
——将对象上传到Amazon S3
```
AS2Import
```
——AS2 EDI文件传输
```
FileSystemImport
```
——写入本地/本地部署文件系统

AI Imports

AI导入

Invoke AI models for classification, extraction, or safety checks. No

_connectionId

required unless using BYOK.

```
AiAgentImport
```
-- OpenAI or Gemini model invocations with structured output, tool use, and reasoning
```
GuardrailImport
```
-- PII detection, content moderation, or custom AI-based validation

调用AI模型进行分类、提取或安全检查。除非使用BYOK，否则无需

_connectionId

。

```
AiAgentImport
```
——调用OpenAI或Gemini模型，支持结构化输出、工具调用和推理
```
GuardrailImport
```
——PII检测、内容审核或基于AI的自定义验证

Stack and Tool Imports

堆栈与工具导入

```
WrapperImport
```
-- custom pre-built stack connectors (Walmart, BigCommerce)
```
ToolImport
```
-- invoke a Celigo Tool resource

```
WrapperImport
```
——自定义预构建堆栈连接器（Walmart、BigCommerce）
```
ToolImport
```
——调用Celigo Tool资源

Import Matching (create / update / upsert)

导入匹配（创建/更新/Upsert）

The core decision on most record-based imports is the operation -- what happens to each record at the destination. Create requires no match key; update and delete require one; upsert checks first and does whichever applies. Users describe the intent in business terms ("look up the customer and update them", "match by email and upsert", "skip the ones that already exist") that resolve into five behaviors:

Always create -- every record is submitted as new. No matching, no checks.
Create only if missing -- match-check first; submit as create if not found, skip silently if found.
Update only if exists -- match-check first; submit as update if found, skip silently if not.
Update only if exists, fail if missing -- strict variant; no-match records error out instead of skipping.
Upsert -- submit a create when no match is found, an update when matched. The catch-all, and the right default when the user is vague.

When matching applies, decide four things: the matching behavior, the match key field(s) (

email

external_id

customer.id

-- required for anything other than always-create), the on-match action (update, skip, fail), and the on-no-match action (create, skip, fail).

How a destination implements matching is adaptor-specific -- there is no single "matching mode" field. A destination might expose: a native upsert keyed off an external ID (Salesforce upsert, NetSuite upsert, RDBMS

ON CONFLICT

); a distinct

addupdate

operation that handles both paths in one call; an

ignoreExisting

flag paired with a lookup that probes before writing; two separate create and update endpoints with no upsert variant (see composite imports below); or a lookup endpoint plus separate create and update endpoints, where the lookup runs pre-write to drive the create-vs-update decision. Some destinations have no matching concept at all -- writing a CSV to FTP, sending an email, posting to a webhook -- so every record goes out as-is.

Prefer import-level matching over a separate lookup step. Imports natively support this pre-write check, so a single import that does the matching and the write together means fewer steps, fewer round-trips, and no glue logic to maintain. A standalone lookup earns its place only when the looked-up data has a consumer beyond the write -- a router branching on something other than "does this exist", an AI agent reasoning over the result, or multiple downstream steps reading different fields. If the only consumer is the destination call itself, the work belongs inside the import.

大多数基于记录的导入的核心决策是操作——每条记录在目标系统中的处理方式。创建无需匹配键；更新和删除需要一个匹配键；Upsert会先检查，然后执行相应操作。用户用业务术语描述意图（"查找客户并更新"、"按电子邮件匹配并Upsert"、"跳过已存在的记录"），这些意图可归结为五种行为：

始终创建——每条记录都作为新记录提交。无匹配、无检查。
仅当不存在时创建——先进行匹配检查；如果未找到则提交创建，如果已找到则静默跳过。
仅当存在时更新——先进行匹配检查；如果已找到则提交更新，如果未找到则静默跳过。
仅当存在时更新，不存在则报错——严格变体；未匹配的记录会报错而非跳过。
Upsert——未找到匹配时提交创建，找到匹配时提交更新。这是通用选项，当用户意图不明确时的默认选择。

当需要匹配时，需确定四件事：匹配行为、匹配键字段（

email

、

external_id

、

customer.id

——除始终创建外均必填）、匹配时操作（更新、跳过、报错）和未匹配时操作（创建、跳过、报错）。

目标系统实现匹配的方式因适配器而异——没有统一的"匹配模式"字段。目标系统可能提供：基于外部ID的原生Upsert（Salesforce Upsert、NetSuite Upsert、RDBMS

ON CONFLICT

）；单独的

addupdate

操作，一次调用处理两种路径；搭配查找的

ignoreExisting

标志，在写入前探测；无Upsert变体的单独创建和更新端点（见下文复合导入）；或查找端点加单独的创建和更新端点，其中查找在写入前运行，以决定执行创建还是更新。有些目标系统根本没有匹配概念——将CSV写入FTP、发送电子邮件、发送到Webhook——所以每条记录都按原样输出。

优先选择导入级匹配，而非单独的查找步骤。导入原生支持写入前检查，因此单个导入同时完成匹配和写入意味着更少的步骤、更少的往返，且无需维护粘合逻辑。仅当查找的数据有写入之外的消费者时，才需要独立查找步骤——例如基于"是否存在"之外的条件分支的路由器、对结果进行推理的AI Agent，或读取不同字段的多个下游步骤。如果唯一的消费者是目标调用本身，那么这项工作应在导入内部完成。

Composite (two-endpoint) imports

复合（双端点）导入

When an HTTP destination has no native upsert but exposes separate create and update endpoints, a composite import pins both endpoints on a single import node, role-tagged create and update. The runtime picks per record via a match-key check -- the same way a native upsert would -- so the flow stays one step. Prefer this over two separate imports driven by an upstream lookup or router; reach for separate imports only when the create and update paths must diverge beyond endpoint selection (different mappings, different downstream consumers, or different hook chains).

当HTTP目标系统没有原生Upsert但提供单独的创建和更新端点时，复合导入会将两个端点绑定到单个导入节点，分别标记为创建和更新角色。运行时会通过匹配键检查为每条记录选择相应端点——与原生Upsert的方式相同——因此流只需一步。优先选择这种方式，而非通过上游查找或路由器驱动的两个单独导入；仅当创建和更新路径必须超出端点选择的差异（不同映射、不同下游消费者或不同Hook链）时，才使用单独的导入。

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

Your data goes to...	Use adaptorType	Category	Read schema
REST or GraphQL API	`HTTPImport`	Record-based	http.yml
NetSuite (any method)	`NetSuiteDistributedImport`	Record-based	netsuitedistributed.yml
Salesforce objects	`SalesforceImport`	Record-based	salesforce.yml
SQL database (Snowflake, PostgreSQL, etc.)	`RDBMSImport`	Record-based	rdbms.yml
MongoDB	`MongodbImport`	Record-based	mongodb.yml
DynamoDB	`DynamodbImport`	Record-based	dynamodb.yml
JDBC database (non-built-in)	`JDBCImport`	Record-based	jdbc.yml
Files over HTTP (Google Drive, Box, Dropbox, Azure Blob)	`HTTPImport` with `http.type: "file"`	File-based	http.yml
Files to FTP/SFTP	`FTPImport`	File-based	ftp.yml
Files to S3	`S3Import`	File-based	s3.yml
AS2 EDI transmission	`AS2Import`	File-based	as2.yml
Local filesystem	`FileSystemImport`	File-based	filesystem.yml
OpenAI / Gemini	`AiAgentImport`	AI	aiagent.yml
PII detection / content moderation	`GuardrailImport`	AI	guardrail.yml
Celigo Tool	`ToolImport`	Tool	wrapper.yml
Pre-built stack connector	`WrapperImport`	Stack	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
```
HTTPImport
```
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
```
HTTPImport
```
, 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 operation you need.

adaptorType

is case-sensitive:

NetSuiteDistributedImport

, not

netsuitedistributedimport

数据目标系统...	使用adaptorType	类别	读取schema
REST或GraphQL API	`HTTPImport`	基于记录	http.yml
NetSuite（任何方法）	`NetSuiteDistributedImport`	基于记录	netsuitedistributed.yml
Salesforce对象	`SalesforceImport`	基于记录	salesforce.yml
SQL数据库（Snowflake、PostgreSQL等）	`RDBMSImport`	基于记录	rdbms.yml
MongoDB	`MongodbImport`	基于记录	mongodb.yml
DynamoDB	`DynamodbImport`	基于记录	dynamodb.yml
JDBC数据库（非内置）	`JDBCImport`	基于记录	jdbc.yml
HTTP文件上传（Google Drive、Box、Dropbox、Azure Blob）	`HTTPImport` 搭配 `http.type: "file"`	基于文件	http.yml
文件上传到FTP/SFTP	`FTPImport`	基于文件	ftp.yml
文件上传到S3	`S3Import`	基于文件	s3.yml
AS2 EDI传输	`AS2Import`	基于文件	as2.yml
本地文件系统	`FileSystemImport`	基于文件	filesystem.yml
OpenAI / Gemini	`AiAgentImport`	AI	aiagent.yml
PII检测 / 内容审核	`GuardrailImport`	AI	guardrail.yml
Celigo工具	`ToolImport`	工具	wrapper.yml
预构建堆栈连接器	`WrapperImport`	堆栈	wrapper.yml

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

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

adaptorType

区分大小写：

NetSuiteDistributedImport

，而非

netsuitedistributedimport

。

Minimum Required Fields

最小必填字段

Every import needs at minimum:

name

adaptorType

_connectionId

(except AiAgentImport/GuardrailImport without BYOK), and the adaptor config block (

http{}

netsuite_da{}

salesforce{}

, etc.).

每个导入至少需要：

name

、

adaptorType

、

_connectionId

（除非AiAgentImport/GuardrailImport不使用BYOK），以及适配器配置块（

http{}

、

netsuite_da{}

、

salesforce{}

等）。

Which Schemas to Read

需读取的Schema

Always: request.yml (base fields)
Plus: the adaptor-specific file from the decision matrix
If file-based: also file.yml
If cloning: clone-request.yml, clone-response.yml

必选：request.yml（基础字段）
附加：决策矩阵中的适配器特定文件
如果是基于文件的导入：还需file.yml
如果是克隆：clone-request.yml、clone-response.yml

Schema Index

Schema索引

All schemas are in references/schemas/:

Base fields (all imports): request.yml
Response shape: response.yml
Adaptor-specific config:
- http.yml -- HTTP/REST/GraphQL (methods, URIs, headers, response parsing, upsert via existingExtract)
- netsuitedistributed.yml -- NetSuite SuiteApp (operation, recordType, internalIdLookup, mapping, lookups)
- netsuite.yml -- NetSuite legacy
- salesforce.yml -- Salesforce (sObjectType, operation, api, idLookup)
- rdbms.yml -- SQL databases (queryType, query, bulkInsert, bulkLoad)
- ftp.yml -- FTP/SFTP
- s3.yml -- Amazon S3
- mongodb.yml -- MongoDB (method, collection, filter, upsert)
- dynamodb.yml -- DynamoDB
- jdbc.yml -- JDBC databases
- as2.yml -- AS2 EDI
- wrapper.yml -- custom stack connectors
- filesystem.yml -- local filesystem
AI config:
- aiagent.yml -- AI agent (provider, model, instructions, tools, structured output)
- guardrail.yml -- guardrails (PII, moderation, AI-agent validation)
File output: file.yml (CSV, XML, JSON, XLSX config for file-based imports)
Clone: clone-request.yml, clone-response.yml

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

所有导入的基础字段： request.yml
响应格式： response.yml
适配器特定配置：
- http.yml——HTTP/REST/GraphQL（方法、URI、 headers、响应解析、通过existingExtract实现Upsert）
- netsuitedistributed.yml——NetSuite SuiteApp（操作、recordType、internalIdLookup、映射、查找）
- netsuite.yml——NetSuite旧版
- salesforce.yml——Salesforce（sObjectType、操作、api、idLookup）
- rdbms.yml——SQL数据库（queryType、query、bulkInsert、bulkLoad）
- ftp.yml——FTP/SFTP
- s3.yml——Amazon S3
- mongodb.yml——MongoDB（方法、collection、filter、upsert）
- dynamodb.yml——DynamoDB
- jdbc.yml——JDBC数据库
- as2.yml——AS2 EDI
- wrapper.yml——自定义堆栈连接器
- filesystem.yml——本地文件系统
AI配置：
- aiagent.yml——AI Agent（提供商、模型、指令、工具、结构化输出）
- guardrail.yml——防护机制（PII、审核、AI Agent验证）
文件输出： file.yml（基于文件的导入的CSV、XML、JSON、XLSX配置）
克隆： clone-request.yml、clone-response.yml

Related Skills

How to Build an Import

如何构建导入

1. Identify the target application

1. 确定目标应用

What system are you writing data to? This determines 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 your account (fast, uses local index)

搜索你的账户（快速，使用本地索引）

celigo account search "<keyword>"

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

查看现有导入使用的连接以及使用该导入的流

celigo account dependencies import <id>

Find orphaned imports not referenced by any flow

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

celigo account lint

Search marketplace templates

搜索市场模板

celigo templates marketplace

Extract just imports from a template

从模板中仅提取导入

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


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

celigo templates preview <id> --model Import 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 connectors with pre-configured auth, endpoints, and resources. Hand-write a manual

HTTPImport

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

bash

undefined

**在编写任何HTTP配置之前务必执行此检查。**Celigo维护了550+个HTTP连接器，包含预配置的认证、端点和资源。仅当搜索结果为空或连接器不支持所需操作时，才根据公开API文档手动编写

HTTPImport

配置。

bash

undefined

Search HTTP connectors

搜索HTTP连接器

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 imports

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

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

Search trading partner connectors (EDI, AS2)

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

celigo tp-connectors list


If a connector exists, 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 import's `relativeURI`, method, and body/response shapes from the connector's endpoint metadata rather than reconstructing them from public API docs. The connector-reference fields on the import 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.

celigo tp-connectors list


如果存在连接器，请从连接器创建连接（`http._httpConnectorId`——见[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)），并从连接器的端点元数据中获取导入的`relativeURI`、方法和请求体/响应格式，而非从公开API文档重新构建。导入本身的连接器引用字段（`http._httpConnectorEndpointId`、`http._httpConnectorVersionId`、`http._httpConnectorResourceId`）是只读的——由平台设置；你需要控制的是连接以及从连接器复制的端点配置。

4. Query metadata for the target system

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

For NetSuite, Salesforce, and RDBMS connections, discover available record types and fields:

bash

celigo metadata types <connectionId>          # List record types / sObjects / tables
celigo metadata fields <connectionId> <type>  # List fields for an entity type

NetSuite:
```
metadata fields
```
returns field IDs, types, and groups — use the IDs for
```
mapping.fields[].generate
```
and
```
mapping.lists[].fields[].generate
```
. Sublist names (e.g.,
```
"item"
```
,
```
"addressbook"
```
) appear as groups, which map to
```
mapping.lists[].generate
```
. Lookup field IDs here are the
```
searchField
```
/
```
resultField
```
values for
```
netsuite_da.lookups[]
```
.
Salesforce:
```
metadata fields
```
returns field API names, types, and relationship info. Use field API names for
```
salesforce.sObjectType
```
lookups and for discovering which fields are createable/updateable.
RDBMS:
```
metadata fields
```
returns column names and types for a table — use these to write SQL queries (see
```
writing-sql
```
) and verify column names before building
```
bulkInsert.tableName
```
or
```
bulkLoad.tableName
```
.

对于NetSuite、Salesforce和RDBMS连接，发现可用的记录类型和字段：

bash

celigo metadata types <connectionId>          # 列出记录类型 / sObjects / 表
celigo metadata fields <connectionId> <type>  # 列出实体类型的字段

NetSuite：
```
metadata fields
```
返回字段ID、类型和分组——使用ID作为
```
mapping.fields[].generate
```
和
```
mapping.lists[].fields[].generate
```
的值。子列表名称（例如
```
"item"
```
、
```
"addressbook"
```
）显示为分组，对应
```
mapping.lists[].generate
```
。此处的查找字段ID是
```
netsuite_da.lookups[]
```
的
```
searchField
```
/
```
resultField
```
值。
Salesforce：
```
metadata fields
```
返回字段API名称、类型和关系信息。使用字段API名称进行
```
salesforce.sObjectType
```
查找，以及发现哪些字段可创建/更新。
RDBMS：
```
metadata fields
```
返回表的列名和类型——使用这些信息编写SQL查询（见
```
writing-sql
```
），并在构建
```
bulkInsert.tableName
```
或
```
bulkLoad.tableName
```
之前验证列名。

5. Determine the category

5. 确定导入类别

Is this a record-based import (submit records to an API/database/ERP), a file-based import (write files to storage), or an AI import (invoke a model)?

这是基于记录的导入（将记录提交到API/数据库/ERP）、基于文件的导入（将文件写入存储）还是AI导入（调用模型）？

6. Choose the right adaptor type

6. 选择正确的适配器类型

Refer to the Adaptor Decision Matrix in the Quick Reference above.

参考上述快速参考中的适配器决策矩阵。

7. Build the import JSON

7. 构建导入JSON

Reference the Schema Index for the exact fields needed. Use the Which Schemas to Read decision rule to determine which files to consult.

参考Schema索引获取所需的精确字段。使用需读取的Schema决策规则确定要查阅的文件。

File Uploads over HTTP (multipart/form-data)

HTTP文件上传（multipart/form-data）

Some destination APIs accept files only as

multipart/form-data

POSTs (Jira attachments, QuickBooks attachables, OpenAI file uploads). This is an

HTTPImport

in file-transfer mode (

http.type: "file"

) and works nothing like a JSON record write. Four pieces have to line up:

Where the bytes come from. The import never carries the file itself. A preceding blob export or blob lookup pulls the file into blob storage, and that step's response mapping puts the reference onto the record -- the idiom is
```
{"extract": "data.0.blobKey", "generate": "blobKey"}
```
. The record then carries a
```
blobKey
```
(a storage pointer, not content).
The media type. The connection's media type (or the import's request media type override) is
```
multipart/form-data
```
; success/error response media types usually override to JSON so replies parse normally.
The request body. Not raw MIME and not a normal handlebars payload -- a JSON array of parts, each
```
{name, value, type}
```
plus optional
```
filename
```
(include the extension) and
```
mime-headers
```
. The file part is
```
"type": "attachment"
```
with
```
"value": "{{blob}}"
```
--
```
{{blob}}
```
is the only accepted value for an attachment (anything else 422s). Fields the API wants alongside the file ride as
```
"type": "inline"
```
parts; an inline part whose value is a JSON object must be serialized. One file reference per import.
blobKeyPath
(Advanced settings) -- the JSON path in the record where the blobKey lives (
```
blobKey
```
, or
```
file.blobKey
```
if nested). At send time the platform follows it into blob storage and streams the real bytes into the attachment part.

The platform assembles the final MIME body itself -- it generates the

boundary

(never hardcode one), writes each part's

Content-Disposition

, and substitutes the attachment part with the raw file bytes. The parts array is a build recipe, not the payload.

Not every multipart API is form-data. Some upload endpoints expect

multipart/related

instead (e.g. Google Drive's

/upload/drive/v3/files?uploadType=multipart

), and the parts-array machinery does NOT apply. There the request body is the literal MIME document: explicit boundary, a JSON metadata part, and a content part referencing

{{blob}}

(double braces). Check which flavor the destination API documents before building -- mixing them produces an import that saves cleanly and fails at runtime.

某些目标API仅接受

multipart/form-data

POST请求上传文件（Jira附件、QuickBooks可附加项、OpenAI文件上传）。这是文件传输模式下的

HTTPImport

（

http.type: "file"

），与JSON记录写入完全不同。需确保四个部分匹配：

字节来源——导入本身不携带文件。前置的Blob导出或Blob查找将文件拉入Blob存储，该步骤的响应映射将引用放到记录上——惯用写法是
```
{"extract": "data.0.blobKey", "generate": "blobKey"}
```
。记录随后携带
```
blobKey
```
（存储指针，而非内容）。
媒体类型——连接的媒体类型（或导入的请求媒体类型覆盖）为
```
multipart/form-data
```
；成功/错误响应媒体类型通常覆盖为JSON，以便正常解析回复。
请求体——不是原始MIME，也不是普通handlebars payload——而是JSON数组形式的部件，每个部件包含
```
{name, value, type}
```
，可选
```
filename
```
（包含扩展名）和
```
mime-headers
```
。文件部件为
```
"type": "attachment"
```
且
```
"value": "{{blob}}"
```
——
```
{{blob}}
```
是附件唯一接受的值（任何其他值都会返回422错误）。API所需的附加字段作为
```
"type": "inline"
```
部件传递；值为JSON对象的inline部件必须序列化。每个导入仅支持一个文件引用。
blobKeyPath
（高级设置）——记录中
```
blobKey
```
所在的JSON路径（
```
blobKey
```
，如果嵌套则为
```
file.blobKey
```
）。发送时，平台会跟随该路径进入Blob存储，并将真实字节流式传输到附件部件中。

平台会自行组装最终的MIME请求体——它会生成

boundary

（切勿硬编码），写入每个部件的

Content-Disposition

，并将附件部件替换为原始文件字节。部件数组是构建配方，而非实际payload。

**并非所有multipart API都是form-data。**某些上传端点需要

multipart/related

（例如Google Drive的

/upload/drive/v3/files?uploadType=multipart

），此时部件数组机制不适用。请求体是字面MIME文档：显式边界、JSON元数据部件和引用

{{blob}}

的内容部件（双大括号）。在构建前检查目标API文档指定的类型——混合使用会导致导入保存正常但运行时失败。

Async Destinations (submit, poll, confirm)

异步目标系统（提交、轮询、确认）

Some destination APIs only acknowledge a write (an HTTP 202, a job ticket) and finish it in the background -- bulk loads, file ingestion, document conversion. Attach an async helper to the import (

http._asyncHelperId

) so the step submits, polls a status export until the external work completes, and only then resolves. The mechanics and constraints (a status export with done/error value lists and poll intervals; no transform, output filter, or hook on the async-configured step; helpers cannot nest) are identical to the export side -- see configuring-exports > Async APIs (submit, poll, fetch). Only add one when the API genuinely cannot confirm the write synchronously.

某些目标API仅确认写入（HTTP 202、作业工单）并在后台完成处理——批量加载、文件 ingestion、文档转换。为导入附加异步助手（

http._asyncHelperId

），使步骤先提交，然后轮询状态导出直到外部工作完成，之后再完成解析。其机制和约束（状态导出包含完成/错误值列表和轮询间隔；配置异步的步骤无转换、输出过滤器或Hook；助手不能嵌套）与导出端完全相同——见configuring-exports > Async APIs (submit, poll, fetch)。仅当API确实无法同步确认写入时才添加。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD

CRUD操作

celigo imports list celigo imports get <id> celigo imports create < import.json celigo imports update <id> < import.json celigo imports set <id> key=value [key2=value2 ...] celigo imports delete <id> [-y]

Invoke (test submission without creating a job)

调用（无需创建作业即可测试提交）

echo '[{"name":"test"}]' | celigo imports invoke <id>

Clone and connection management

克隆和连接管理

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

Discovery

发现

celigo templates marketplace celigo http-connectors list celigo http-connectors catalog <id> --resource-type import --published-only celigo http-connectors endpoint-detail <id> --resource-type import --resource-id <rid> --endpoint-id <epid> celigo tp-connectors list celigo metadata types <connectionId> celigo metadata fields <connectionId> <entityType>

Debug

调试

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


<!-- TIER:3 -->

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


<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Required (all imports)

所有导入必填项

```
name
```
is set
```
adaptorType
```
exact case matches connection type (request.yml > adaptorType)
```
_connectionId
```
references a valid, online connection (skip for AI imports without BYOK)
Adaptor config block name matches adaptorType (
```
http{}
```
for HTTPImport,
```
netsuite_da{}
```
for NetSuiteDistributedImport, etc.)

设置了
```
name
```
```
adaptorType
```
大小写与连接类型完全匹配（request.yml > adaptorType）
```
_connectionId
```
引用了有效的在线连接（不使用BYOK的AI导入可跳过）
适配器配置块名称与adaptorType匹配（
```
HTTPImport
```
对应
```
http{}
```
，
```
NetSuiteDistributedImport
```
对应
```
netsuite_da{}
```
等）

Adaptor-specific

适配器特定项

HTTP: pre-built connector was checked (
```
celigo http-connectors list
```
) -- hand-written config only because no connector covers the app or operation
HTTP:
```
http.method
```
and
```
http.relativeURI
```
are set (http.yml)
NetSuite:
```
netsuite_da.operation
```
and
```
netsuite_da.recordType
```
are set (netsuitedistributed.yml)

RDBMS:

rdbms.queryType

per_record

bulk_insert

-- NOT legacy

insert

update

(rdbms.yml)

Salesforce:

salesforce.sObjectType

and

salesforce.operation

are set (salesforce.yml)

HTTP：已检查预构建连接器（
```
celigo http-connectors list
```
）——仅当连接器不支持该应用或操作时才手动编写配置
HTTP：设置了
```
http.method
```
和
```
http.relativeURI
```
（http.yml）
NetSuite：设置了
```
netsuite_da.operation
```
和
```
netsuite_da.recordType
```
（netsuitedistributed.yml）

RDBMS：

rdbms.queryType

为

per_record

或

bulk_insert

——而非旧版

insert

update

（rdbms.yml）

Salesforce：设置了
```
salesforce.sObjectType
```
和
```
salesforce.operation
```
（salesforce.yml）

Cross-resource consistency

跨资源一致性

Connection
```
type
```
matches the import's
```
adaptorType
```
If response mapping needed: configured on the flow's
```
pageProcessors[]
```
entry, not on the import itself
If one-to-many:
```
oneToMany: true
```
and
```
pathToMany
```
is set to the child array path
If using Mapper 1.0 (NetSuite/Salesforce):
```
mapping.fields[]
```
/
```
mapping.lists[]
```
, not
```
mappings[]
```

连接
```
type
```
与导入的
```
adaptorType
```
匹配
如果需要响应映射：在流的
```
pageProcessors[]
```
条目上配置，而非导入本身
如果是一对多：设置了
```
oneToMany: true
```
且
```
pathToMany
```
指定为子数组路径
如果使用Mapper 1.0（NetSuite/Salesforce）：使用
```
mapping.fields[]
```
/
```
mapping.lists[]
```
，而非
```
mappings[]
```

Gotchas

注意事项

PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this.
Including a
rest:
block creates a legacy RESTImport. Use only
```
http:
```
for new imports.
Input filter skips that import, not the record. Filtered records skip the current import step but continue to subsequent steps in the flow. They aren't dropped -- check
```
numIgnore
```
on the job if records seem to bypass a step.
Multipart file parts only accept
{{blob}}
. In a
```
multipart/form-data
```
parts array, the file part must be
```
"type": "attachment"
```
with
```
"value": "{{blob}}"
```
-- any other value 422s. Never hardcode the MIME
```
boundary
```
; the platform generates it. Fields the API wants alongside the file ride as
```
"type": "inline"
```
parts.
bodyKey
/
blobKey
in logs is an artifact, not a payload field. Audit and debug logs never show the assembled multipart body -- an internal storage pointer appears where the body would be. But if the destination actually received the literal string
```
bodyKey
```
or
```
blobKey
```
, the file part is misconfigured (an
```
inline
```
part where an
```
attachment
```
belongs, or a
```
blobKeyPath
```
that doesn't resolve).

**PUT会清除未包含的字段。**务必先GET，修改后再PUT。
```
set
```
命令可处理此问题。
**包含
```
rest:
```
块会创建旧版RESTImport。**新导入仅使用
```
http:
```
。
**输入过滤器跳过的是该导入步骤，而非记录。**被过滤的记录会跳过当前导入步骤，但会继续流中的后续步骤。它们不会被丢弃——如果记录似乎绕过了某个步骤，请检查作业的
```
numIgnore
```
。
**Multipart文件部件仅接受
```
{{blob}}
```
。**在
```
multipart/form-data
```
部件数组中，文件部件必须为
```
"type": "attachment"
```
且
```
"value": "{{blob}}"
```
——任何其他值都会返回422错误。切勿硬编码MIME
```
boundary
```
；平台会自动生成。API所需的附加字段作为
```
"type": "inline"
```
部件传递。
**日志中的
```
bodyKey
```
/
```
blobKey
```
是 artifact，而非payload字段。**审计和调试日志永远不会显示组装后的multipart请求体——内部存储指针会出现在请求体的位置。但如果目标系统实际收到了字符串
```
bodyKey
```
或
```
blobKey
```
，则表示文件部件配置错误（应该是
```
attachment
```
部件却用了
```
inline
```
，或者
```
blobKeyPath
```
无法解析）。

Common Errors

常见错误

Error	Cause	Fix
422 `adaptorType invalid`	Wrong case	Use exact case from decision matrix: `HTTPImport` , `NetSuiteDistributedImport` , etc.
422 `_connectionId required`	Missing connection	Set `_connectionId` to a valid connection ID
422 `queryType invalid`	Legacy Snowflake value	Use `per_record` or `bulk_insert` , not `insert` / `update`
422 `distributed required`	Missing NetSuite flag	Use `NetSuiteDistributedImport` with `distributed: true` on connection
422 `mapping invalid`	Wrong mapper version	NetSuite/Salesforce use Mapper 1.0 ( `mapping.fields[]` ), not Mapper 2.0 ( `mappings[]` )
422 attachment `value` invalid	Multipart file part is not `{{blob}}`	Set the file part to `"type": "attachment"` , `"value": "{{blob}}"` ; let the platform generate the `boundary`

错误	原因	修复方法
422 `adaptorType invalid`	大小写错误	使用决策矩阵中的精确大小写： `HTTPImport` 、 `NetSuiteDistributedImport` 等
422 `_connectionId required`	缺少连接	将 `_connectionId` 设置为有效的连接ID
422 `queryType invalid`	使用了Snowflake旧版值	使用 `per_record` 或 `bulk_insert` ，而非 `insert` / `update`
422 `distributed required`	缺少NetSuite标志	使用 `NetSuiteDistributedImport` 并在连接上设置 `distributed: true`
422 `mapping invalid`	映射器版本错误	NetSuite/Salesforce使用Mapper 1.0（ `mapping.fields[]` ），而非Mapper 2.0（ `mappings[]` ）
422 attachment `value` invalid	Multipart文件部件不是 `{{blob}}`	将文件部件设置为 `"type": "attachment"` 、 `"value": "{{blob}}"` ；让平台生成 `boundary`

configuring-imports

Original

Translation

Configuring Imports

配置导入

Import Execution Pipeline

导入执行管道

Categories of Import

导入类别

Record-Based Imports

基于记录的导入

File-Based Imports

基于文件的导入

AI Imports

AI导入

Stack and Tool Imports

堆栈与工具导入

Import Matching (create / update / upsert)

导入匹配（创建/更新/Upsert）

Composite (two-endpoint) imports

复合（双端点）导入

Quick Reference

快速参考

Adaptor Decision Matrix

适配器决策矩阵

Minimum Required Fields

最小必填字段

Which Schemas to Read

需读取的Schema

Schema Index

Schema索引

Related Skills

相关技能

How to Build an Import

如何构建导入

1. Identify the target application

1. 确定目标应用

2. Check for existing patterns

2. 检查现有模式

Search your account (fast, uses local index)

搜索你的账户（快速，使用本地索引）

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

查看现有导入使用的连接以及使用该导入的流

Find orphaned imports not referenced by any flow

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

Search marketplace templates

搜索市场模板

Extract just imports from a template

从模板中仅提取导入

3. Check for a pre-built connector

3. 检查预构建连接器

Search HTTP connectors

搜索HTTP连接器

Drill into the endpoints the connector defines for imports

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

Search trading partner connectors (EDI, AS2)

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

4. Query metadata for the target system

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

5. Determine the category

5. 确定导入类别

6. Choose the right adaptor type

6. 选择正确的适配器类型

7. Build the import JSON

7. 构建导入JSON

File Uploads over HTTP (multipart/form-data)

HTTP文件上传（multipart/form-data）

Async Destinations (submit, poll, confirm)

异步目标系统（提交、轮询、确认）

CLI Commands

CLI命令

CRUD

CRUD操作

Invoke (test submission without creating a job)

调用（无需创建作业即可测试提交）

Clone and connection management

克隆和连接管理

Discovery

发现

Debug