feat(data-fabric): add folderKey support to entities.getAll and ChoiceSets surface

[AditiGoyalUipath]

Summary

• entities.getAll now accepts an optional folderKey. The Data Fabric entity list filter is exclusive: omitting folderKey returns only tenant entities; passing folderKey returns only entities in that folder. Verified against alpha.
• ChoiceSets surface (8 methods) now threads folderKey through every public method and sends X-UIPATH-FolderKey. Two endpoints — insertValueById and updateValueById — hard-fail with 400 "Entity not found at tenant level" on folder-scoped choice sets without the header. Confirmed against alpha.
• Internal ChoiceSetService.resolveChoiceSetName now scopes its getAll lookup by the supplied folderKey, fixing a path that previously threw NotFoundError for folder-scoped choice sets before the API call was even reached.
• JSDoc @example blocks updated on every Entities method that already supported folderKey but didn't show it (getAllRecords, getRecordById, insertRecord*, updateRecord*, deleteRecordsById, queryRecordsById).

Behavior table — verified against alpha

Endpoint	No header	With X-UIPATH-FolderKey	Header required?
Entities.getAll	tenant entities only	folder entities only (disjoint set)	Filters list
ChoiceSets.getAll	tenant only	folder only (disjoint set)	Filters list
ChoiceSets.insertValueById	400 "not found at tenant level"	200	Required
ChoiceSets.updateValueById	400 "not found at tenant level"	200	Required
Other Entities/ChoiceSets by-ID endpoints	200	200	Optional (SDK still sends for uniformity)

Test plan

• npm run typecheck clean
• npm run lint 0 warnings / 0 errors
• npm run test:unit — 1728/1728 passing (updated 10 assertions to expect the new { headers: {} } shape on the calls that gained the third arg)
• Added integration test: entities.getAll folder filter — runs whenever INTEGRATION_TEST_FOLDER_KEY is set; throws (not silent-skips) if missing
• Added describe.skip('Folder-scoped operations') block to choicesets.integration.test.ts covering create/list/value-CRUD/delete with folderKey — skipped for the same DataFabric.Schema.Write OAuth scope reason that gates the existing tenant-scope value-CRUD block
• Manually re-run integration suite with INTEGRATION_TEST_FOLDER_KEY set against a tenant that has folder-scoped DF entities

🤖 Generated with Claude Code

[claude]

This test covers getAll() with no options ({ headers: {} }), but there's no test for getAll({ folderKey: '...' }) verifying the X-UIPATH-FolderKey header is set. Every other Entities method that gained folderKey support already has a matching "should pass folderKey via X-UIPATH-FolderKey header" test (e.g. getById at line 129, getAllRecords at line 488). getAll should follow the same pattern:

it('should pass X-UIPATH-FolderKey header when folderKey is provided', async () => {
  mockApiClient.get.mockResolvedValue([]);
  await entityService.getAll({ folderKey: ENTITY_TEST_CONSTANTS.FIELD_ID });
  expect(mockApiClient.get).toHaveBeenCalledWith(
    DATA_FABRIC_ENDPOINTS.ENTITY.GET_ALL,
    { headers: { 'X-UIPATH-FolderKey': ENTITY_TEST_CONSTANTS.FIELD_ID } },
  );
});

[claude]

Review findings

Two missing unit tests for the new folderKey header path:

1. tests/unit/services/data-fabric/choicesets.test.ts (line 84) — getAll, getById, deleteById, insertValueById, updateValueById, and deleteValuesById all gained folderKey support but only the no-folderKey case ({ headers: {} }) is tested. Missing companion tests for when folderKey is supplied.

2. tests/unit/services/data-fabric/entities.test.ts (line 342) — getAll({ folderKey }) has no unit test verifying the X-UIPATH-FolderKey header is set, unlike every other Entities method that gained folderKey support (each of those has a dedicated header test).

Everything else (implementation, type definitions, JSDoc, integration tests structure) looks correct.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Review findings

One new finding this run:

tests/integration/shared/data-fabric/entities.integration.test.ts (line 131) — magic UUID string '00000000-0000-0000-0000-000000000000' should use the DATA_FABRIC_TENANT_FOLDER_ID constant instead, matching the production code that performs the identical comparison. Suggestion posted inline.

Everything else — implementation, type definitions, JSDoc, and all unit test coverage for the folderKey header paths — looks correct.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Review findings

One new finding this run:

src/services/data-fabric/entities.ts (lines 1229–1230) — entityType: 'ChoiceSet' and entityTypeId: 1 are raw string/number literals inlined in the buildReferenceMeta method body. Per conventions: "Use enums for fixed value sets — NEVER leave raw strings/numbers" and "NEVER define static lookup tables or inline regex literals inside method bodies". Both should be extracted to module-level constants. Suggestion posted inline.

[claude]

Review findings

One new finding this run:

tests/unit/services/data-fabric/entities.test.ts (lines 2212–2213) — the referenceChoiceSet assertion hardcodes entityType: "ChoiceSet" and entityTypeId: 1 as raw literals instead of using EntityType.ChoiceSet and ENTITY_TYPE_IDS[EntityType.ChoiceSet]. Per conventions, enum-backed values must use the enum constant — raw strings/numbers drift silently if the enum or mapping ever changes. Suggestion posted inline.

[claude]

Review findings

One new finding this run:

src/models/data-fabric/entities.types.ts (line 313) — the referenceFolderKey JSDoc references DATA_FABRIC_TENANT_FOLDER_ID, an internal endpoint constant that isn't exported through the public API barrel. Per conventions: "NEVER expose internal implementation details in user-facing JSDoc." Replace with the literal value '00000000-0000-0000-0000-000000000000' so the docs are self-contained. Suggestion posted inline.

[claude]

JSDoc first-line is out of sync with EntityServiceModel. This PR changed the model's summary to "Gets entities in the system" (entities.models.ts:56) but left the implementation unchanged at "Gets all entities in the system". Per conventions: "Keep JSDoc on service class methods in sync with {Entity}ServiceModel — both the models file and the service implementation file must have identical JSDoc for each public method."

Suggested change

	* Gets all entities in the system
	* Gets entities in the system

[claude]

Review findings

One new finding this run:

src/services/data-fabric/entities.ts:507 — the getAll implementation JSDoc first-line says "Gets all entities in the system" but this PR updated EntityServiceModel (in entities.models.ts:56) to "Gets entities in the system". The two are now out of sync. Per conventions: "both the models file and the service implementation file must have identical JSDoc for each public method." Suggestion posted inline.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[vnaren23]

folderKey is preferred over includeFolderChoiceSets

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Review findings

One new finding this run:

src/models/data-fabric/choicesets.types.ts:60 — includeFolderChoiceSets is missing the @experimental tag. The parallel EntityGetAllOptions.includeFolderEntities (entities.types.ts:336) has it; both are described as in-preview features throughout this PR — the tag should be consistent across both options types. Suggestion posted inline.

[claude]

Review findings

One new finding this run:

src/models/data-fabric/choicesets.types.ts (line 2) — choicesets.types.ts imports EntityFolderScopedOptions directly from entities.types.ts. Per conventions, this is a cross-service type import within the same domain (analogous to cases.models importing from processes.types within maestro), which creates hidden coupling that breaks when type ownership shifts. EntityFolderScopedOptions should be extracted to a shared data-fabric.types.ts file and imported from there by both services. Suggestion posted inline.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Review findings

One new finding this run:

src/models/data-fabric/entities.models.ts:61 — entities.getAll({ includeFolderEntities: true }) switches to the /api/v2/Entity endpoint, which the code comments in entities.ts and data-fabric.ts explicitly label "requires OR.Users scope". But docs/oauth-scopes.md was not updated — it still only lists DataFabric.Schema.Read for getAll() with no mention of the conditional OR.Users requirement. Per CLAUDE.md, scope docs must always be kept in sync. Suggestion posted inline.

[claude]

Review findings

One new finding this run:

src/models/data-fabric/entities.internal-types.ts:33 — entityType?: string in the new ReferenceEntityPayload interface should use EntityType?. The EntityType enum already covers all possible values (Entity, ChoiceSet, InternalEntity, SystemEntity), and the service's buildReferenceMeta call site correctly uses EntityType.ChoiceSet — but the interface type allows any string, losing type safety and autocomplete. Suggestion posted inline.

[claude]

Review findings

Unresolved thread:

• docs/oauth-scopes.md — Reopened thread PRRT_kwDOOpObr86Jkw43: getAll({ includeFolderEntities: true }) switches to the /api/v2/Entity endpoint which requires OR.Users in addition to DataFabric.Schema.Read, but the oauth-scopes.md table still only has the base getAll() row with DataFabric.Schema.Read. The previously resolved suggestion to add the conditional row was not applied.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
99.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud