Feishu Goods Mapping Table Sync to MySQL: A Single-Strategy Tutorial

What This Strategy Solves

In one of our retail projects, the operations team maintained a goods mapping table in Feishu Sheets, recording external product codes, names, and specifications alongside our internal product codes and names. Finance and supply chain data lived in MySQL, and downstream order, invoice, and pricing workflows all depended on this mapping. When the two sides drifted apart, orders stalled, invoices failed, and inventory no longer reconciled.

This strategy has a single goal: pull the Feishu mapping table on a schedule and write it into MySQL so that every downstream system uses one consistent set of internal product codes. It looks simple, but a poorly designed mapping causes silent divergence after three months — a classic pitfall.

Data Flow and Field Mapping

The flow is Feishu Sheets (source) → Qeasy (middleware) → MySQL (target). The source uses the Feishu open platform Sheets API, and the target uses MySQL batch execution (batchexecute).

Key field mapping:

The source is fetched in ascending id order; the target writes by id with idCheck enabled so primary-key conflicts surface immediately.

How to Configure in Qeasy

We built this pipeline on the Qeasy data integration platform. Key configuration points:

1. Source platform: choose Feishu, configure appId/appSecret (omitted here per data-handling rules), authorize the tenant space, and put the target spreadsheetToken into the path parameter slot.
2. Source API: use GET /open-apis/sheets/v2/spreadsheets/:spreadsheetToken/values/:range, set valueRenderOption to ToString and dateTimeRenderOption to FormattedString so dates and numbers are not corrupted during serialization.
3. Target platform: a MySQL data source. Use batchexecute, parameterize the INSERT SQL with {{field}} placeholders that reference source data.
4. Field mapping: in the mapping node, align Feishu columns with MySQL fields. Two patterns are common across our customers — keep mappings in a centralized mapping-config table so new columns are added by config change rather than strategy edits; or use a phased "header-then-body" rollout that stabilizes the header fields first and only then layers in the body.
5. Auto-fill response: enable autoFillResponse on the target side so the platform echoes back the affected fields for easier troubleshooting.

Implementation Steps

Implementation follows three phases: incremental starting point → full trigger → schedule cadence.

1. Incremental start: use the maximum id in the current Feishu mapping table as the starting point so the first run does not replay history.
2. Full trigger: on go-live, manually trigger a full run to backfill historical mappings; validate mapping and charset in a test database first.
3. Schedule cadence: the source crontab is 0 1 * * * and the target is 30 1 * * *, leaving a 30-minute buffer for network jitter and mapping exceptions. A common "incremental + full dual-track" pattern we have seen works well: run incremental daily, trigger a manual full reconciliation once a month to guarantee both sides match exactly.

Lessons Learned

1. Date and number formats: if Feishu returns date cells as timestamps by default, MySQL will treat them as dates in 1970. The safe approach is valueRenderOption=ToString and dateTimeRenderOption=FormattedString, landing strings in VARCHAR and letting the MySQL view layer handle type conversion.
2. Centralized mapping management: a common mistake is to hard-code mappings into the SQL template, forcing a strategy edit whenever a column is added. Keep mappings in a config table so operations can maintain them directly.
3. Do not disable idCheck carelessly: this strategy sets source idCheck off and target idCheck on. Turning off target idCheck lets primary-key conflicts fail silently, which is extremely painful to debug.
4. Crontab buffering: running source and target at the same sharp hour collides with Feishu rate limits and MySQL connection pool exhaustion. A 30-minute offset is the safe value validated across multiple customer environments.

When to Use and When Not to

This pattern fits mapping-table / master-data scenarios with under tens of thousands of rows, scheduled daily or hourly, with no real-time requirement. It is not suitable for high-concurrency real-time ordering paths, source structures that change frequently, or complex bidirectional sync; those scenarios call for event-driven architectures or dedicated reconciliation services.