Qeasy Cloud
Get Started

Authoritative Field Manual for Kingdee Cloud Galaxy Organization (ORG_Organizations) Query Interface

· 钟家寿· Engineering Best Practices· 21 views· 4 min read
MySQLKingdee Cloud组织机构接口字段手册轻易云供应链集成主数据同步

What Problem This Interface Solves

The Kingdee Cloud Galaxy organization (ORG_Organizations) query interface is the master data foundation for supply chain integration. In multi-organization retail/distribution scenarios, the organization code is the root dimension for document attribution, permission isolation, and cross-system mapping. Through this interface, we synchronize organization master data from Kingdee to MySQL and other downstream systems, enabling multi-org architecture mapping, document attribution validation, and subsequent correlation of warehouses, purchasing organizations, and sales organizations. A typical scenario is establishing the correspondence between multi-store/multi-warehouse and Kingdee organizations.

Interface Capability Overview

  • Authentication: Standard Kingdee WebAPI authentication, typically using App ID + App Secret to obtain a Token before invocation.
  • Request Method: POST, calling the executeBillQuery universal query interface with FormId fixed as ORG_Organizations.
  • Response Structure: Standard Kingdee Result response, with the data array in Result.Results, each row containing field-name-to-value key-value pairs.
  • Pagination/Incremental Mode: Supports Limit/StartRow pagination; supports incremental filtering via FAuditDate>= to avoid full pulls.
  • Strategy Type: QUERY_ONLY, pure query, typically scheduled daily in the early hours.
  • Typical Schedule: 3 1 * * *, executing at 01:03 daily to pull the previous day's changes.

Typical Field Mappings

Field NameTypeMeaningPractical Notes
FOrgIDstringOrganization primary key, unique within KingdeeMust be configured as id in metadata; used for internal system reference and cross-system PK mapping
FNumberstringOrganization business codeConfigured as the number field in metadata; the unique identifier for business references and cross-system mapping
FNamestringOrganization display nameUsed for document display, dropdown selection, and name fuzzy-match queries
FAuditDatedatetimeAudit dateIncremental filter field; use FAuditDate>='2024-01-01' for incremental pulls
FOrgFunctionsarrayOrganization functions (sales, purchasing, inventory)Need split mapping when multiple functions exist
FIsBusinessOrgboolWhether a business organizationControls participation in business document flow
FParentOrgstringParent organizationRequired for building multi-level organization trees

How to Configure on Qeasy

On the Qeasy data integration platform, the Kingdee Cloud Galaxy query interface is typically encapsulated as a "Kingdee adapter." We only need to fill in the App ID, Secret, service address, and account set identifier in the data source configuration, select the executeBillQuery operation, and enter ORG_Organizations as the FormId. The platform automatically retrieves the form field metadata, and in the field mapper we can map FOrgID → organization_id, FNumber → organization_code, FName → organization_name to the MySQL target table with one click. For incremental strategies, Qeasy supports cursor variables based on FAuditDate; the platform persists the maximum timestamp from the previous run and automatically resumes from there next time. Scheduled tasks can be configured directly with cron, no need for a self-built scheduler.

Cross-Solution Practical Key Points

  1. Use FNumber rather than FOrgID as the cross-system primary key: FOrgID is Kingdee's internal PK; for cross-system references, use the business code FNumber to avoid reconciliation issues caused by PK changes after upgrades/migrations.
  2. Prefer FAuditDate as the incremental field: Organization master data changes infrequently, but any change (new organization, function adjustment) affects downstream document attribution; incremental sync is mandatory.
  3. Organization functions need split mapping: A single Kingdee organization can hold sales, purchasing, and inventory functions simultaneously; on the MySQL side, we recommend splitting into three relational tables to avoid query difficulties from multi-value single fields.
  4. Plan multi-org architecture in advance: In HQ/branch/subsidiary scenarios, keep the organization tree depth to 3-4 levels; if it exceeds 5 levels, consider flattening the structure.
  5. Use FName fuzzy match for dropdown queries: Frontend organization selectors typically search by name; the interface must support FName LIKE '%xxx%'.
  6. Serialize downstream dependencies: Strategies like WMS warehouse correspondence and online store management depend on organization codes; they must execute only after organization sync completes.

Pitfall Recap

  • Pitfall 1: Ignoring FAuditDate timezone. Kingdee's audit date defaults include timezone info; direct string comparison will miss data. The safe approach is to convert to UTC before comparison.
  • Pitfall 2: FNumber duplication. Some customers have dirty historical data causing duplicate codes; Kingdee allows records with different FOrgID but identical FNumber, which conflicts during cross-system mapping. Validate uniqueness before landing.
  • Pitfall 3: Organization function changes don't trigger downstream. Pure queries don't return change logs; function additions/removals can only be captured via FAuditDate increments—double-check the incremental field configuration.
  • Pitfall 4: Pagination Limit exceeds Kingdee threshold. Kingdee executeBillQuery typically caps single-call Limit at 2000; exceeding it throws errors. Qeasy's field mapper automatically splits by page, no manual intervention needed.
  • Pitfall 5: Multi-org switch causes document misalignment. The same business code may be reused across different account sets/environments; syncing without account-set isolation causes misalignment. Always append account-set filter conditions in FilterString.

When to Use

This interface is suitable for scenarios where Kingdee Cloud Galaxy serves as the master data source and needs to synchronize organization master data to downstream systems (MySQL, ERP, WMS), especially in multi-org, multi-account-set, multi-store/multi-warehouse supply chain integrations. In pure query scenarios, it can serve as the organization foundation, working in concert with other master data (warehouse, customer, vendor) sync strategies. It is not suitable for scenarios with frequent organization changes requiring real-time push; in those cases, switch to change-log interfaces or message push.

Original content. Please credit the source when reposting: https://www.qeasy.cloud/insights/engineering/hb-p2-026-841e

Comments