AD Current Settlement Ledger Query Sync Strategy: An End-to-End Implementation Tutorial
What This Strategy Solves
In a private deployment for a retail enterprise, the front-end business system generates a large volume of current settlement ledger data every day. This data needs to be pulled into the integration platform during the off-peak window, serving as input for downstream reconciliation, field mapping, and BI analytics. If teams rely on manual exports, timeliness suffers and period misalignment or missing channels become common. The AD current settlement ledger query strategy standardizes and automates conditional queries by period, entity, and channel, ensuring that daily ledger data lands on the integration platform on time and completely, forming the entry point of the data pipeline.
Data Flow and Field Mapping
The data flow is straightforward: source business system → integration platform. The source side calls a paginated query interface that supports filtering by page number, page size, period, entity, channel code, and platform customer name. The target side executes a "write no-op" on the integration platform; in practice, the data is landed in the platform's intermediate layer for downstream strategies to consume.
Key field reference:
| Meaning | Source Field | Type | Note |
|---|---|---|---|
| Page number | page | int | Default 1, used for paging |
| Page size | size | int | Default 100, controls batch size |
| Period | settlementDate | int | e.g., 202309, accounting period |
| Entity | companyName | string | Optional, multi-entity filter |
| Channel code | channelCode | string | Optional, channel filter |
| Platform customer | platCustomerName | string | Optional, customer-level filter |
The source id field acts as both a deduplication key and an idempotency key. With idCheck=true, Qeasy ensures the same record will not be written into the intermediate layer twice.
How to Configure in Qeasy
In Qeasy, this strategy is treated as a data entry point rather than an endpoint. Key configuration points:
- Source connection: Register the source business system's RESTful connection in the Qeasy data integration platform. The endpoint is the paginated query API with POST method. Period fields like
settlementDatemust use Qeasy's variable replacement instead of being hard-coded in the request body. - Pagination strategy: The source uses a standard page + size pattern. Qeasy's built-in paginator handles this; a page size of 100 is the empirical sweet spot, balancing throughput and source load.
- Target action: The target is a WebAPI "write no-op". The point is not the API itself but that Qeasy lands the response data into the intermediate layer table. Both
numberandidare set to 0, meaning no business document number is generated, only data is persisted. - Centralized encoding mapping: We recommend maintaining enumeration values such as period, entity, and channel in a unified mapping table within Qeasy rather than scattering them across strategies. This is one of the most common patterns Qeasy customers adopt—future business adjustments can be made in one place and take effect across the full pipeline.
Implementation Steps
In a real project, we typically roll out this query-style strategy in three phases:
Phase 1: Incremental start point Run a minimal viable pipeline first—pick a historical period (e.g., 202309), trigger it manually, and confirm the data lands correctly on the integration platform. This phase validates field mapping and pagination, not performance.
Phase 2: Full-volume trigger Once the minimal pipeline is stable, release the historical backfill using Qeasy's full-volume mechanism to bring in missing historical ledgers in one batch. Be cautious about source system rate limits. Pull a batch, pause, then pull the next—avoid triggering the partner's risk control.
Phase 3: Scheduling cadence
The source strategy crontab is set to 3 2 * * *, triggering daily at 02:03; the target action fires at 02:23. The 20-minute gap leaves enough window for source querying and transmission. Once stable in production, the cadence can be tuned to business volume—e.g., daily to weekly—based on the actual scenario.
Lessons Learned from the Field
Pitfall 1: Period field hard-coded
In an early implementation, the engineer hard-coded settlementDate in the request parameters, causing the same period to be pulled every day. The fix was switching to Qeasy variables plus scheduling parameters. The takeaway: any field carrying period semantics must be parameterized.
Pitfall 2: Page size set too large
The source returns full ledger details. When size was bumped above 1000, the source database showed clear query jitter. 100 is the empirically safe value—enough throughput for the off-peak window without burdening the source.
Pitfall 3: Misunderstanding of no-op semantics The target is a "write no-op". Customer ops once thought the strategy was failing because they could not see any obvious downstream action. This must be documented clearly during delivery: no-op does not mean nothing happened—it means data is landed into the intermediate layer for downstream strategies to consume.
Pitfall 4: idCheck and dedup ordering
When using the source id as an idempotency key, if Qeasy's dedup judgment runs before page merging, the same id across different pages can be mistakenly treated as two records. The safe approach is to confirm dedup runs after all pages are merged, not during streaming.
Applicable and Non-Applicable Scenarios
Applicable: Conditional pulls of ledger-style data by period, entity, and channel, where the goal is to aggregate data onto the integration platform first and then hand it off to downstream strategies. Typical examples include current settlement ledgers, online ledgers, and receivables ledgers.
Non-applicable: If the business requires real-time push (within minutes), or if the source system does not support stable backend paginated queries, the "early-morning batch + conditional query" model is not appropriate—use event-driven or CDC models instead.