feat(entities): migrate Data Fabric entities to v3 APIs + federated create

[niket0503]

Ports the TypeScript SDK's Data Fabric changes (uipath-typescript — v3 migration + federated entity support) to the Python SDK (uipath-platform).

What changed

Entity schema (create / reads):

• create_entity now targets the v3 upsert (POST /api/v3/entities) and supports federated entities: EntityCreateOptions.entity_class=Federated with external_fields (connector or native sources) and source_join_condition_details. Validates the class (rejects Case) and requires ≥1 source for Federated.
• retrieve, list_entities, delete_entity, update_entity_metadata → v3. list_entities now includes federated entities (the v1 list excludes them).
• retrieve_by_name and choice-set listing stay on v1 — the v3 by-name route returns a different (CompositeEntityMetadataResponse) shape, and choice-set listing is unchanged.

Records:

• Record CRUD (list/get/insert/update/delete + batches) → v3 (/api/v3/entities/entity/{id}/…), same HTTP methods/bodies.
• Query routing: joins stay on the v1 by-key endpoint (the v3 by-id query rejects joins); everything else — including binnings — uses the v3 by-id query, so federated entities are readable. Binning is gated by the same EnableBinningOnQuery feature flag the old v2 path used (confirmed in the backend), so the special v2 path was dropped.
• The federated SQL passthrough (query_entity_records → /api/v1/query/execute) is unchanged — it's the query-engine's own endpoint, not part of the entity v1→v3 surface.

New models (exported from uipath.platform.entities): EntityClass/EntityClassId, numeric DataDirectionType, JoinType.InnerJoin, Searchability/SearchabilityOperator/SearchabilityNamedSearch, EntityCreateExternalConnection/EntityCreateExternalObject/EntityCreateExternalFieldMapping/EntityCreateExternalField/EntityCreateExternalSource, NativeConnectionDetail, SourceJoinConditionDetail; EntityCreateOptions gains entity_class, external_fields, source_join_condition_details.

Note: the TS updateById (federated/native field deltas) is intentionally not ported in this PR — scoped to create + reads + query.

Testing

• Full uipath-platform suite passes; mypy and ruff clean. Added federated-create, binning→v3, and join→v1 routing tests; migrated existing mocks to v3.
• Validated live against alpha: native v3 round-trip (create→insert→query→list→delete) and a federated Salesforce Account create + live query round-trip through the SDK.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR ports Data Fabric entity and record operations in uipath-platform to the v3 API surface and adds federated entity create support, aligning the Python SDK with the TypeScript SDK’s Data Fabric updates.

Changes:

• Migrates entity schema operations (retrieve/list/create/delete/metadata update) to datafabric_/api/v3/entities, including v3 upsert-based create with federated entity payload support.
• Migrates record CRUD + batch endpoints to the v3 entity data endpoints, and updates query routing to use v3 by-id except when joins are present (joins route to the v1 by-key endpoint).
• Introduces new federated-create models/enums and expands the test suite/mocks to validate v3 routing and federated payload shapes.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/uipath-platform/tests/services/test_entities_service.py	Updates mocks/assertions to v3 endpoints; adds tests for federated create payload and query routing (binnings → v3, joins → v1).
packages/uipath-platform/src/uipath/platform/entities/entities.py	Adds federated-create models and enums; changes DataDirectionType to numeric wire representation; adds EntityClass and related mapping.
packages/uipath-platform/src/uipath/platform/entities/_entity_schema_service.py	Routes entity schema operations to v3; builds federated create/upsert payload including external sources and join-condition details.
packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py	Migrates record endpoints to v3 and updates structured query routing logic (joins → v1, otherwise → v3).
packages/uipath-platform/src/uipath/platform/entities/init.py	Re-exports new models/enums from uipath.platform.entities (with a noted missing export).

Suppressed comments (2)

packages/uipath-platform/src/uipath/platform/entities/init.py:71

• EntityClassId is not listed in __all__, so it still won't be exported when users do from uipath.platform.entities import * and tooling that relies on __all__ won't see it. Add it alongside EntityClass.

    "Entity",
    "EntityAggregate",
    "EntityAggregateFunction",
    "EntityBinning",
    "EntityClass",
    "EntityCreateExternalConnection",

packages/uipath-platform/tests/services/test_entities_service.py:2366

• This async test now uses the v3 query endpoint, but the name test_query_async_v1 suggests it exercises the v1 path. Renaming it to ..._v3 will keep the intent clear (especially now that joins intentionally route to v1).

            url=re.compile(
                rf"{base_url}{org}{tenant}/datafabric_/api/v3/entities/entity/{entity_key}/query"
            ),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[niket0503]

Addressed the Copilot review + version bump:

• Test names — renamed test_query_v1_with_filter_and_pagination → test_query_v3_by_id_with_filter_and_pagination and test_query_async_v1 → test_query_async_v3_by_id to match the endpoint under test. (test_query_with_joins_routes_to_v1 stays — it genuinely asserts the v1 by-key join route.)
• DataDirectionType back-compat — added _missing_ so the legacy string member names ("ReadOnly" / "ReadAndWrite", case-insensitive) are still accepted as input and normalise to the numeric members, while serializing the numeric wire form. Added a test locking this.
• EntityClassId export — added to __init__.py imports + __all__.
• Version bump — uipath-platform 0.2.12 → 0.2.13 (patch; matches the pattern of prior entities feature PRs and satisfies the dependency-bump check). No uipath bump needed — its uipath-platform>=0.2.4, <0.3.0 range still holds.

Full uipath-platform suite green, mypy/ruff clean (161 entity tests).

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.0% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →