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

.github/workflows/pr-checks.yml

@@ -66,6 +66,7 @@ jobs:
           echo "data_fabric_test_entity_id=${{ secrets.UIPATH_DATA_FABRIC_TEST_ENTITY_ID_DEV || secrets.UIPATH_DATA_FABRIC_TEST_ENTITY_ID }}" >> $GITHUB_OUTPUT
           echo "data_fabric_test_choiceset_id=${{ secrets.UIPATH_DATA_FABRIC_TEST_CHOICESET_ID_DEV || secrets.UIPATH_DATA_FABRIC_TEST_CHOICESET_ID }}" >> $GITHUB_OUTPUT
           echo "data_fabric_test_attachment_field=${{ secrets.UIPATH_DATA_FABRIC_TEST_ATTACHMENT_FIELD_DEV || secrets.UIPATH_DATA_FABRIC_TEST_ATTACHMENT_FIELD }}" >> $GITHUB_OUTPUT
+          echo "data_fabric_test_folder_entity_id=${{ secrets.UIPATH_DATA_FABRIC_TEST_FOLDER_ENTITY_ID_DEV || secrets.UIPATH_DATA_FABRIC_TEST_FOLDER_ENTITY_ID }}" >> $GITHUB_OUTPUT
           echo "orchestrator_attachment_id=${{ secrets.UIPATH_ORCHESTRATOR_ATTACHMENT_ID_DEV || secrets.UIPATH_ORCHESTRATOR_ATTACHMENT_ID }}" >> $GITHUB_OUTPUT
           echo "jobs_test_folder_id=${{ secrets.UIPATH_JOBS_TEST_FOLDER_ID_DEV || secrets.UIPATH_JOBS_TEST_FOLDER_ID }}" >> $GITHUB_OUTPUT
           echo "traces_test_trace_id=${{ secrets.UIPATH_TRACES_TEST_TRACE_ID_DEV || secrets.UIPATH_TRACES_TEST_TRACE_ID }}" >> $GITHUB_OUTPUT
@@ -88,6 +89,7 @@ jobs:
           DATA_FABRIC_TEST_ENTITY_ID=${{ steps.config.outputs.data_fabric_test_entity_id }}
           DATA_FABRIC_TEST_CHOICESET_ID=${{ steps.config.outputs.data_fabric_test_choiceset_id }}
           DATA_FABRIC_TEST_ATTACHMENT_FIELD=${{ steps.config.outputs.data_fabric_test_attachment_field }}
+          DATA_FABRIC_TEST_FOLDER_ENTITY_ID=${{ steps.config.outputs.data_fabric_test_folder_entity_id }}
           ORCHESTRATOR_TEST_PROCESS_KEY=${{ steps.config.outputs.orchestrator_test_process_key }}
           ORCHESTRATOR_ATTACHMENT_ID=${{ steps.config.outputs.orchestrator_attachment_id }}
           JOBS_TEST_FOLDER_ID=${{ steps.config.outputs.jobs_test_folder_id }}

src/models/data-fabric/choicesets.models.ts

@@ -1,12 +1,16 @@
 import {
+  ChoiceSetGetAllOptions,
   ChoiceSetGetAllResponse,
   ChoiceSetGetResponse,
   ChoiceSetGetByIdOptions,
   ChoiceSetCreateOptions,
   ChoiceSetUpdateOptions,
+  ChoiceSetDeleteByIdOptions,
   ChoiceSetValueInsertOptions,
   ChoiceSetValueInsertResponse,
-  ChoiceSetValueUpdateResponse
+  ChoiceSetValueUpdateOptions,
+  ChoiceSetValueUpdateResponse,
+  ChoiceSetValueDeleteOptions,
 } from './choicesets.types';
 import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '../../utils/pagination/types';
 
@@ -28,33 +32,32 @@ import { PaginatedResponse, NonPaginatedResponse, HasPaginationOptions } from '.
  */
 export interface ChoiceSetServiceModel {
   /**
-   * Gets all choice sets in the org
+   * Gets choice sets in the tenant.
    *
+   * Three call modes:
+   * - `getAll()` — default. Returns only tenant-level choice sets.
+   * - `getAll({ folderKey: "<uuid>" })` — preferred for folder-scoped data. Returns only choice sets in that folder.
+   * - `getAll({ includeFolderChoiceSets: true })` — returns tenant-level **and** folder-level choice sets together. `folderKey` is preferred over `includeFolderChoiceSets` when both are set.
+   *
+   * @param options - Optional {@link ChoiceSetGetAllOptions} (`folderKey` to list a single folder's choice sets — preferred when scoping to a folder; `includeFolderChoiceSets: true` to list tenant + folder choice sets together) The `folderKey` property is **experimental**.
    * @returns Promise resolving to an array of choice set metadata
    * {@link ChoiceSetGetAllResponse}
    * @example
    * ```typescript
-   * // Get all choice sets
-   * const allChoiceSets = await choicesets.getAll();
+   * // Tenant-only (default)
+   * const tenantChoiceSets = await choicesets.getAll();
    *
-   * // Iterate through choice sets
-   * allChoiceSets.forEach(choiceSet => {
-   *   console.log(`ChoiceSet: ${choiceSet.displayName} (${choiceSet.name})`);
-   *   console.log(`Description: ${choiceSet.description}`);
-   *   console.log(`Created by: ${choiceSet.createdBy}`);
-   * });
+   * // A single folder's choice sets (preferred when targeting a specific folder)
+   * const folderChoiceSets = await choicesets.getAll({ folderKey: "<folderKey>" });
    *
-   * // Find a specific choice set by name
-   * const expenseTypes = allChoiceSets.find(cs => cs.name === 'ExpenseTypes');
+   * // Tenant + folder choice sets together
+   * const allChoiceSets = await choicesets.getAll({ includeFolderChoiceSets: true });
    *
-   * // Check choice set details
-   * if (expenseTypes) {
-   *   console.log(`Last updated: ${expenseTypes.updatedTime}`);
-   *   console.log(`Updated by: ${expenseTypes.updatedBy}`);
-   * }
+   * // Find a specific choice set by name
+   * const expenseTypes = tenantChoiceSets.find(cs => cs.name === 'ExpenseTypes');
    * ```
    */
-  getAll(): Promise<ChoiceSetGetAllResponse[]>;
+  getAll(options?: ChoiceSetGetAllOptions): Promise<ChoiceSetGetAllResponse[]>;
 
   /**
    * Gets choice set values by choice set ID with optional pagination
@@ -64,7 +67,7 @@ export interface ChoiceSetServiceModel {
    * - A PaginatedResponse with navigation cursors (when any pagination parameter is provided)
    *
    * @param choiceSetId - UUID of the choice set
-   * @param options - Pagination options
+   * @param options - Pagination options and optional `folderKey` (omit for tenant-level choice sets) The `folderKey` property is **experimental**.
    * @returns Promise resolving to choice set values or paginated result
    * {@link ChoiceSetGetResponse}
    * @example
@@ -89,6 +92,9 @@ export interface ChoiceSetServiceModel {
    * if (page1.hasNextPage) {
    *   const page2 = await choicesets.getById(choiceSetId, { cursor: page1.nextCursor });
    * }
+   *
+   * // Folder-scoped choice set
+   * const folderValues = await choicesets.getById(choiceSetId, { folderKey: "<folderKey>" });
    * ```
    */
   getById<T extends ChoiceSetGetByIdOptions = ChoiceSetGetByIdOptions>(
@@ -106,7 +112,7 @@ export interface ChoiceSetServiceModel {
    * @param name - Choice set name. Must start with a
    *   letter, may contain only letters, numbers, and underscores, length
    *   3–100 characters (e.g., `"expenseTypes"`).
-   * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions})
+   * @param options - Optional choice-set-level settings ({@link ChoiceSetCreateOptions}) The `folderKey` property is **experimental**.
    * @returns Promise resolving to the UUID of the created choice set
    *
    * @example
@@ -131,7 +137,7 @@ export interface ChoiceSetServiceModel {
    * the call throws `ValidationError` if both are omitted.
    *
    * @param choiceSetId - UUID of the choice set to update
-   * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions})
+   * @param options - Metadata fields to change ({@link ChoiceSetUpdateOptions}) The `folderKey` property is **experimental**.
    * @returns Promise resolving when the update is complete
    *
    * @example
@@ -153,6 +159,7 @@ export interface ChoiceSetServiceModel {
    * Deletes a Data Fabric choice set and all its values.
    *
    * @param choiceSetId - UUID of the choice set to delete
+   * @param options - Optional {@link ChoiceSetDeleteByIdOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level The `folderKey` property is **experimental**.
    * @returns Promise resolving when the choice set is deleted
    *
    * @example
@@ -162,17 +169,20 @@ export interface ChoiceSetServiceModel {
    * const expenseTypes = allChoiceSets.find(cs => cs.name === 'expense_types');
    *
    * await choicesets.deleteById(expenseTypes.id);
+   *
+   * // Folder-scoped choice set
+   * await choicesets.deleteById(expenseTypes.id, { folderKey: "<folderKey>" });
    * ```
    * @internal
    */
-  deleteById(choiceSetId: string): Promise<void>;
+  deleteById(choiceSetId: string, options?: ChoiceSetDeleteByIdOptions): Promise<void>;
 
   /**
    * Inserts a single value into a choice set.
    *
    * @param choiceSetId - UUID of the parent choice set
    * @param name - Identifier name of the new value (e.g., `"TRAVEL"`)
-   * @param options - Optional fields ({@link ChoiceSetValueInsertOptions})
+   * @param options - Optional fields ({@link ChoiceSetValueInsertOptions}) The `folderKey` property is **experimental**.
    * @returns Promise resolving to the inserted value ({@link ChoiceSetValueInsertResponse})
    *
    * @example
@@ -185,6 +195,12 @@ export interface ChoiceSetServiceModel {
    *   displayName: 'Travel',
    * });
    * console.log(inserted.id);
+   *
+   * // Folder-scoped choice set: folderKey is required on the wire
+   * await choicesets.insertValueById(expenseTypes.id, 'TRAVEL', {
+   *   displayName: 'Travel',
+   *   folderKey: "<folderKey>",
+   * });
    * ```
    * @internal
    */
@@ -203,6 +219,7 @@ export interface ChoiceSetServiceModel {
    * @param choiceSetId - UUID of the parent choice set
    * @param valueId - UUID of the value to update
    * @param displayName - New human-readable display name for the value
+   * @param options - Optional {@link ChoiceSetValueUpdateOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level. The `folderKey` property is **experimental**.
    * @returns Promise resolving to the updated value ({@link ChoiceSetValueUpdateResponse})
    *
    * @example
@@ -214,20 +231,27 @@ export interface ChoiceSetServiceModel {
    * const travel = values.items.find(v => v.name === 'TRAVEL');
    *
    * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel');
+   *
+   * // Folder-scoped choice set: folderKey is required on the wire
+   * await choicesets.updateValueById(expenseTypes.id, travel.id, 'Business Travel', {
+   *   folderKey: "<folderKey>",
+   * });
    * ```
    * @internal
    */
   updateValueById(
     choiceSetId: string,
     valueId: string,
     displayName: string,
+    options?: ChoiceSetValueUpdateOptions,
   ): Promise<ChoiceSetValueUpdateResponse>;
 
   /**
    * Deletes one or more values from a choice set.
    *
    * @param choiceSetId - UUID of the parent choice set
    * @param valueIds - Array of value UUIDs to delete
+   * @param options - Optional {@link ChoiceSetValueDeleteOptions} — pass `folderKey` for folder-scoped choice sets; omit for tenant-level The `folderKey` property is **experimental**.
    * @returns Promise resolving when the values are deleted
    *
    * @example
@@ -237,9 +261,12 @@ export interface ChoiceSetServiceModel {
    * const idsToDelete = values.items.slice(0, 2).map(v => v.id);
    *
    * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete);
+   *
+   * // Folder-scoped choice set
+   * await choicesets.deleteValuesById('<choiceSetId>', idsToDelete, { folderKey: "<folderKey>" });
    * ```
    * @internal
    */
-  deleteValuesById(choiceSetId: string, valueIds: string[]): Promise<void>;
+  deleteValuesById(choiceSetId: string, valueIds: string[], options?: ChoiceSetValueDeleteOptions): Promise<void>;
 }
 

src/models/data-fabric/choicesets.types.ts

@@ -1,4 +1,5 @@
 import { PaginationOptions } from '../../utils/pagination/types';
+import { EntityFolderScopedOptions } from './data-fabric.types';
 
 /**
  * ChoiceSet Get All Response
@@ -49,44 +50,59 @@ export interface ChoiceSetGetResponse {
   recordOwner?: string;
 }
 
+export interface ChoiceSetGetAllOptions extends EntityFolderScopedOptions {
+  /**
+   * When `true`, also returns folder-level choice sets alongside tenant ones.
+   * Omit (or `false`, the default) to return only tenant-level choice sets.
+   * Ignored when `folderKey` is provided — `folderKey` is preferred over `includeFolderChoiceSets` when both are set.
+   *
+   * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+   */
+  includeFolderChoiceSets?: boolean;
+}
+
 /**
  * Options for getting choice set values by choice set ID
  */
-export type ChoiceSetGetByIdOptions = PaginationOptions;
+export type ChoiceSetGetByIdOptions = PaginationOptions & EntityFolderScopedOptions;
 
 /**
  * Options for creating a new choice set
  */
-export interface ChoiceSetCreateOptions {
+export interface ChoiceSetCreateOptions extends EntityFolderScopedOptions {
   /** Human-readable display name */
   displayName?: string;
   /** Optional choice set description */
   description?: string;
-  /** UUID of the folder to place the choice set in (defaults to the tenant-level folder) */
-  folderKey?: string;
 }
 
 /**
  * Options for updating an existing choice set's metadata
  */
-export interface ChoiceSetUpdateOptions {
+export interface ChoiceSetUpdateOptions extends EntityFolderScopedOptions {
   /** New display name for the choice set */
   displayName?: string;
   /** New description for the choice set */
   description?: string;
 }
 
+export interface ChoiceSetDeleteByIdOptions extends EntityFolderScopedOptions {}
+
 /**
  * Optional fields when inserting a single value into a choice set.
  *
  * The required `name` identifier is passed as a positional argument to
  * `insertValueById`.
  */
-export interface ChoiceSetValueInsertOptions {
+export interface ChoiceSetValueInsertOptions extends EntityFolderScopedOptions {
   /** Human-readable display name */
   displayName?: string;
 }
 
+export interface ChoiceSetValueUpdateOptions extends EntityFolderScopedOptions {}
+
+export interface ChoiceSetValueDeleteOptions extends EntityFolderScopedOptions {}
+
 /**
  * Response returned after inserting a choice-set value — the full value object.
  */

src/models/data-fabric/data-fabric.types.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared types for the Data Fabric domain — used by both Entities and ChoiceSets.
+ * Lives here (not in either service's `*.types.ts`) to avoid cross-domain coupling
+ * between sibling services.
+ */
+
+/**
+ * Common shape for every folder-scoped Data Fabric operation.
+ * Forwarded on the wire as the `X-UIPATH-FolderKey` header.
+ */
+export interface EntityFolderScopedOptions {
+  /**
+   * Key identifying the folder the entity belongs to. Omit for tenant-level entities.
+   *
+   * @experimental Folder-scoped Data Fabric is in preview — the contract may change.
+   */
+  folderKey?: string;
+}

src/models/data-fabric/entities.constants.ts

@@ -1,4 +1,4 @@
-import { EntityFieldDataType, FieldDisplayType } from "./entities.types";
+import { EntityFieldDataType, EntityType, FieldDisplayType } from "./entities.types";
 import {
   EntitySchemaFieldMapping,
   SqlFieldType,
@@ -7,6 +7,15 @@ import {
 } from "./entities.internal-types";
 export { SqlFieldType } from "./entities.internal-types";
 
+/**
+ * Numeric type IDs that pair with {@link EntityType} on reference payloads
+ * (entityType + entityTypeId travel together in `referenceEntity` /
+ * `referenceChoiceSet` bodies on cross-folder schema upserts).
+ */
+export const ENTITY_TYPE_IDS = {
+  [EntityType.ChoiceSet]: 1,
+} as const;
+
 /**
  * Maps fields for Entities
  */

src/models/data-fabric/entities.internal-types.ts

@@ -1,4 +1,4 @@
-import { FieldDisplayType, EntityRecord, ReferenceType, SqlType } from './entities.types';
+import { EntityType, FieldDisplayType, EntityRecord, ReferenceType, SqlType } from './entities.types';
 
 /**
  * Write-side payload shape for creating a new field in a schema upsert call.
@@ -20,10 +20,25 @@ export interface FieldSchemaPayload {
   defaultValue?: string;
   choiceSetId?: string;
   referenceType?: ReferenceType;
-  referenceEntity?: { id: string };
+  referenceEntity?: ReferenceEntityPayload;
+  referenceChoiceSet?: ReferenceEntityPayload;
   referenceField?: { id: string };
 }
 
+/** Body embedded in `referenceEntity` / `referenceChoiceSet` on cross-folder field payloads. */
+export interface ReferenceEntityPayload {
+  id: string;
+  name?: string;
+  folderId?: string;
+  entityType?: EntityType;
+  entityTypeId?: number;
+}
+
+export interface ResolvedReferenceMeta {
+  referenceEntity?: ReferenceEntityPayload;
+  referenceChoiceSet?: ReferenceEntityPayload;
+}
+
 /**
  * Shape of each entry in EntitySchemaFieldTypeMap — internal only.
  */