@uipath/data-fabric-tool 1.196.0 → 1.197.0-preview.59

package/src/commands/entities.spec.ts

@@ -518,6 +518,48 @@ describe("entities create", () => {
         );
     });
 
+    it("should preserve per-field referenceFolderKey on a cross-folder RELATIONSHIP", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue("entity-xfolder-rel");
+        const fields = [
+            {
+                fieldName: "order",
+                type: "RELATIONSHIP",
+                referenceEntityId: "a1b2c3d4-0000-0000-0000-000000000010",
+                referenceFieldId: "f1000000-0000-0000-0000-000000000100",
+                referenceFolderKey: "f1000000-0000-0000-0000-000000000060",
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ fields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "OrderLine",
+            "--body",
+            JSON.stringify({ fields }),
+            "--folder-key",
+            "f1000000-0000-0000-0000-000000000050",
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "OrderLine",
+            expect.arrayContaining([
+                expect.objectContaining({
+                    fieldName: "order",
+                    type: "RELATIONSHIP",
+                    referenceFolderKey: "f1000000-0000-0000-0000-000000000060",
+                }),
+            ]),
+            expect.objectContaining({
+                folderKey: "f1000000-0000-0000-0000-000000000050",
+            }),
+        );
+    });
+
     it("should error when no --body or --file provided", async () => {
         vi.mocked(readJsonInput).mockRejectedValue(
             new Error("Provide entity definition via --file or --body."),
@@ -763,6 +805,43 @@ describe("entities update", () => {
         );
     });
 
+    it("should preserve per-field referenceFolderKey when addFields includes a cross-folder RELATIONSHIP", async () => {
+        const sdk = mockSdk();
+        const addFields = [
+            {
+                fieldName: "order",
+                type: "RELATIONSHIP",
+                referenceEntityId: "a1b2c3d4-0000-0000-0000-000000000010",
+                referenceFieldId: "f1000000-0000-0000-0000-000000000100",
+                referenceFolderKey: "f1000000-0000-0000-0000-000000000060",
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ addFields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            JSON.stringify({ addFields }),
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                addFields: expect.arrayContaining([
+                    expect.objectContaining({
+                        referenceFolderKey:
+                            "f1000000-0000-0000-0000-000000000060",
+                    }),
+                ]),
+            }),
+        );
+    });
+
     it("should update entity by adding a CHOICE_SET_MULTIPLE field with choiceSetId", async () => {
         const sdk = mockSdk();
         const addFields = [
@@ -1772,6 +1851,7 @@ describe("entities delete", () => {
 
         expect(sdk.entities.deleteById).toHaveBeenCalledWith(
             "entity-to-delete",
+            undefined,
         );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({
@@ -1819,7 +1899,10 @@ describe("entities delete", () => {
             "cleanup",
         ]);
 
-        expect(sdk.entities.deleteById).toHaveBeenCalledWith("entity-id");
+        expect(sdk.entities.deleteById).toHaveBeenCalledWith(
+            "entity-id",
+            undefined,
+        );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({ Result: "Success" }),
         );
@@ -1920,3 +2003,171 @@ describe("entities delete", () => {
         expect(process.exitCode).toBe(1);
     });
 });
+
+describe("entities --folder-key forwarding", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should forward --folder-key to getById", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getById).mockResolvedValue({
+            id: "ent-1",
+            fields: [],
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "get",
+            "ent-1",
+            "--folder-key",
+            "folder-guid-1",
+        ]);
+
+        expect(sdk.entities.getById).toHaveBeenCalledWith("ent-1", {
+            folderKey: "folder-guid-1",
+        });
+    });
+
+    it("should forward --folder-key into create options", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue("new-entity-id");
+        vi.mocked(readJsonInput).mockResolvedValue({
+            fields: [{ fieldName: "title", type: "STRING" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "MyEntity",
+            "--body",
+            '{"fields":[{"fieldName":"title","type":"STRING"}]}',
+            "--folder-key",
+            "folder-guid-2",
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "MyEntity",
+            [{ fieldName: "title", type: "STRING" }],
+            expect.objectContaining({ folderKey: "folder-guid-2" }),
+        );
+    });
+
+    it("should forward --folder-key into updateById options", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            displayName: "Renamed",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "ent-1",
+            "--body",
+            '{"displayName":"Renamed"}',
+            "--folder-key",
+            "folder-guid-3",
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "ent-1",
+            expect.objectContaining({
+                displayName: "Renamed",
+                folderKey: "folder-guid-3",
+            }),
+        );
+    });
+
+    it("should forward --folder-key to deleteById", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "delete",
+            "ent-1",
+            "--confirm",
+            "--reason",
+            "cleanup",
+            "--folder-key",
+            "folder-guid-4",
+        ]);
+
+        expect(sdk.entities.deleteById).toHaveBeenCalledWith("ent-1", {
+            folderKey: "folder-guid-4",
+        });
+    });
+});
+
+describe("entities list --include-folders", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should call getAll with no options when neither --folder-key nor --include-folders is passed", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync(["node", "test", "entities", "list"]);
+        expect(sdk.entities.getAll).toHaveBeenCalledWith(undefined);
+    });
+
+    it("should forward --include-folders as includeFolderEntities: true", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "list",
+            "--include-folders",
+        ]);
+        expect(sdk.entities.getAll).toHaveBeenCalledWith({
+            includeFolderEntities: true,
+        });
+    });
+
+    it("should forward --folder-key as folderKey to getAll", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "list",
+            "--folder-key",
+            "folder-guid-1",
+        ]);
+        expect(sdk.entities.getAll).toHaveBeenCalledWith({
+            folderKey: "folder-guid-1",
+        });
+    });
+
+    it("should reject --folder-key combined with --include-folders", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "list",
+            "--folder-key",
+            "folder-guid-1",
+            "--include-folders",
+        ]);
+        expect(sdk.entities.getAll).not.toHaveBeenCalled();
+        expect(process.exitCode).toBe(1);
+    });
+});

package/src/commands/entities.ts

@@ -9,6 +9,7 @@ import {
 } from "@uipath/common";
 import type {
     EntityCreateFieldOptions,
+    EntityGetAllOptions,
     EntityServiceModel,
     EntityUpdateByIdOptions,
     ExternalSourceFields,
@@ -23,16 +24,20 @@ import { connectOrFail } from "../utils/sdk-client";
 interface ListOptions {
     tenant?: string;
     nativeOnly?: boolean;
+    folderKey?: string;
+    includeFolders?: boolean;
 }
 
 interface GetOptions {
     tenant?: string;
+    folderKey?: string;
 }
 
 interface CreateOptions {
     tenant?: string;
     file?: string;
     body?: string;
+    folderKey?: string;
 }
 
 interface UpdateEntityOptions {
@@ -42,6 +47,7 @@ interface UpdateEntityOptions {
     yes?: boolean;
     confirm?: boolean;
     reason?: string;
+    folderKey?: string;
 }
 
 interface DeleteOptions {
@@ -49,11 +55,14 @@ interface DeleteOptions {
     yes?: boolean;
     confirm?: boolean;
     reason?: string;
+    folderKey?: string;
 }
 
 const ENTITIES_LIST_EXAMPLES: CommandExample[] = [
     {
-        Description: "List Data Fabric entities.",
+        Description:
+            "List Data Fabric entities. Each entity includes the 'folderId' it lives in — pass that as '--folder-key' on follow-up commands targeting folder-scoped entities. " +
+            "Scope modes: omit both flags to see only tenant-level entities (the default); pass '--folder-key <uuid>' to see only that folder's entities; pass '--include-folders' to see tenant + folder entities together. '--folder-key' and '--include-folders' are mutually exclusive.",
         Command: "uip df entities list --native-only",
         Output: {
             Code: "EntityList",
@@ -64,6 +73,7 @@ const ENTITIES_LIST_EXAMPLES: CommandExample[] = [
                     displayName: "Invoice",
                     entityType: "Standard",
                     description: "Invoice records",
+                    folderId: "f1000000-0000-0000-0000-000000000001",
                     isRbacEnabled: false,
                     fields: [
                         {
@@ -146,6 +156,19 @@ const ENTITIES_CREATE_EXAMPLES: CommandExample[] = [
             Data: { ID: "a1b2c3d4-0000-0000-0000-000000000004" },
         },
     },
+    {
+        Description:
+            "Create a folder-scoped entity with cross-folder references. " +
+            "Pass '--folder-key' to place the new entity in a folder. " +
+            "Per-field 'referenceFolderKey' points a RELATIONSHIP, FILE, or CHOICE_SET_* field at a target that lives in a different folder (or at the tenant level when omitted). " +
+            "Get target entity/field IDs from 'df entities list --folder-key <key>' and 'df entities get <id> --folder-key <key>'; get choice-set IDs from 'df choice-sets list --folder-key <key>' (omit '--folder-key' for tenant-level choice sets).",
+        Command:
+            'uip df entities create OrderLine --folder-key f1000000-0000-0000-0000-000000000050 --body \'{"displayName":"Order Line","fields":[{"fieldName":"order","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","referenceFolderKey":"f1000000-0000-0000-0000-000000000060","isRequired":true},{"fieldName":"userType","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000077"}]}\'',
+        Output: {
+            Code: "EntityCreated",
+            Data: { ID: "a1b2c3d4-0000-0000-0000-000000000005" },
+        },
+    },
 ];
 
 const VALID_FIELD_TYPES = new Set(Object.values(EntityFieldDataType));
@@ -195,12 +218,43 @@ export const registerEntitiesCommand = (program: Command) => {
             "--native-only",
             "Show only native entities (exclude federated entities with external connections)",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) to scope the listing to a specific folder",
+        )
+        .option(
+            "--include-folders",
+            "List tenant-level entities together with entities from every folder you can see. Mutually exclusive with --folder-key.",
+        )
         .examples(ENTITIES_LIST_EXAMPLES)
         .trackedAction(processContext, async (options: ListOptions) => {
+            if (
+                options.folderKey !== undefined &&
+                options.includeFolders === true
+            ) {
+                return fail(
+                    "--folder-key and --include-folders are mutually exclusive",
+                    "Use --folder-key to list a single folder, or --include-folders to list tenant + folder entities together.",
+                );
+            }
+
             const sdk = await connectOrFail(options.tenant);
             if (!sdk) return;
 
-            const [listError, result] = await catchError(sdk.entities.getAll());
+            const listOpts: EntityGetAllOptions = {
+                ...(options.folderKey !== undefined && {
+                    folderKey: options.folderKey,
+                }),
+                ...(options.includeFolders === true && {
+                    includeFolderEntities: true,
+                }),
+            };
+
+            const [listError, result] = await catchError(
+                sdk.entities.getAll(
+                    Object.keys(listOpts).length > 0 ? listOpts : undefined,
+                ),
+            );
 
             if (listError) {
                 return fail(
@@ -231,6 +285,10 @@ export const registerEntitiesCommand = (program: Command) => {
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(ENTITIES_GET_EXAMPLES)
         .trackedAction(
             processContext,
@@ -239,7 +297,12 @@ export const registerEntitiesCommand = (program: Command) => {
                 if (!sdk) return;
 
                 const [getError, entity] = await catchError(
-                    sdk.entities.getById(id),
+                    sdk.entities.getById(
+                        id,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
+                    ),
                 );
 
                 if (getError) {
@@ -280,9 +343,10 @@ export const registerEntitiesCommand = (program: Command) => {
             "-f, --file <path>",
             "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled optional)",
         )
+        .option("--body <json>", "Inline JSON entity definition")
         .option(
-            "--body <json>",
-            "Inline JSON entity definition (use `-` to read from stdin)",
+            "--folder-key <key>",
+            "Folder key (GUID) of the target folder (for folder-scoped entities)",
         )
         .examples(ENTITIES_CREATE_EXAMPLES)
         .trackedAction(
@@ -356,6 +420,9 @@ export const registerEntitiesCommand = (program: Command) => {
                     ...(definition.isRbacEnabled !== undefined && {
                         isRbacEnabled: definition.isRbacEnabled as boolean,
                     }),
+                    ...(options.folderKey !== undefined && {
+                        folderKey: options.folderKey,
+                    }),
                 };
 
                 const entityService: EntityServiceModel = sdk.entities;
@@ -410,6 +477,10 @@ export const registerEntitiesCommand = (program: Command) => {
             "--reason <reason>",
             "Required when 'removeFields' is non-empty — echoed back in the response so the caller can log it",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .trackedAction(
             processContext,
             async (id: string, options: UpdateEntityOptions) => {
@@ -573,8 +644,14 @@ export const registerEntitiesCommand = (program: Command) => {
                 if (!sdk) return;
 
                 const entityService: EntityServiceModel = sdk.entities;
+                const updatePayload: EntityUpdateByIdOptions = {
+                    ...pickKnownUpdateKeys(input),
+                    ...(options.folderKey !== undefined && {
+                        folderKey: options.folderKey,
+                    }),
+                };
                 const [updateError] = await catchError(
-                    entityService.updateById(id, pickKnownUpdateKeys(input)),
+                    entityService.updateById(id, updatePayload),
                 );
 
                 if (updateError) {
@@ -613,6 +690,10 @@ export const registerEntitiesCommand = (program: Command) => {
             "--reason <reason>",
             "Reason for the deletion — echoed back in the response so the caller can log it",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(ENTITIES_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -629,7 +710,12 @@ export const registerEntitiesCommand = (program: Command) => {
 
                 const entityService: EntityServiceModel = sdk.entities;
                 const [deleteError] = await catchError(
-                    entityService.deleteById(id),
+                    entityService.deleteById(
+                        id,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
+                    ),
                 );
 
                 if (deleteError) {

package/src/commands/files.spec.ts

@@ -109,6 +109,7 @@ describe("files upload", () => {
             "record-1",
             "attachment",
             expect.any(File),
+            undefined,
         );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({
@@ -132,6 +133,7 @@ describe("files upload", () => {
             "record-1",
             "attachment",
             expect.objectContaining({ name: "upload" }),
+            undefined,
         );
     });
 
@@ -245,6 +247,7 @@ describe("files delete", () => {
             "entity-1",
             "record-1",
             "attachment",
+            undefined,
         );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({
@@ -266,6 +269,7 @@ describe("files delete", () => {
             "entity-1",
             "record-1",
             "attachment",
+            undefined,
         );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({ Result: "Success", Code: "FileDeleted" }),
@@ -370,3 +374,62 @@ describe("files download edge cases", () => {
         );
     });
 });
+
+describe("files --folder-key forwarding", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(OutputFormatter.success).mockReset();
+        vi.mocked(OutputFormatter.error).mockReset();
+    });
+
+    it("should forward --folder-key to uploadAttachment", async () => {
+        const sdk = mockSdk();
+        mockFs.readFile.mockResolvedValue(new Uint8Array([1, 2, 3]));
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files upload entity-1 record-1 attachment --file /tmp/report.pdf --folder-key folder-guid-1",
+        );
+        expect(sdk.entities.uploadAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+            expect.any(File),
+            { folderKey: "folder-guid-1" },
+        );
+    });
+
+    it("should forward --folder-key to downloadAttachment", async () => {
+        const blob = new Blob(["data"]);
+        const sdk = mockSdk({
+            downloadAttachment: vi.fn().mockResolvedValue(blob),
+        });
+        mockFs.writeFile.mockResolvedValue(undefined);
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files download entity-1 record-1 attachment --folder-key folder-guid-2",
+        );
+        expect(sdk.entities.downloadAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+            { folderKey: "folder-guid-2" },
+        );
+    });
+
+    it("should forward --folder-key to deleteAttachment", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await runCommand(
+            program,
+            "files delete entity-1 record-1 attachment --yes --reason cleanup --folder-key folder-guid-3",
+        );
+        expect(sdk.entities.deleteAttachment).toHaveBeenCalledWith(
+            "entity-1",
+            "record-1",
+            "attachment",
+            { folderKey: "folder-guid-3" },
+        );
+    });
+});

package/src/commands/files.ts

@@ -16,11 +16,13 @@ import { connectOrFail } from "../utils/sdk-client";
 interface UploadOptions {
     tenant?: string;
     file?: string;
+    folderKey?: string;
 }
 
 interface DownloadOptions {
     tenant?: string;
     destination?: string;
+    folderKey?: string;
 }
 
 interface DeleteOptions {
@@ -28,6 +30,7 @@ interface DeleteOptions {
     yes?: boolean;
     confirm?: boolean;
     reason?: string;
+    folderKey?: string;
 }
 
 const FILES_UPLOAD_EXAMPLES: CommandExample[] = [
@@ -95,6 +98,10 @@ export const registerFilesCommand = (program: Command) => {
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
         .option("-f, --file <path>", "Path to the file to upload")
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(FILES_UPLOAD_EXAMPLES)
         .trackedAction(
             processContext,
@@ -134,6 +141,9 @@ export const registerFilesCommand = (program: Command) => {
                             [fileContent as Uint8Array<ArrayBuffer>],
                             fileName,
                         ),
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
                     ),
                 );
 
@@ -170,6 +180,10 @@ export const registerFilesCommand = (program: Command) => {
             "--destination <path>",
             "Output file path (defaults to <record-id>_<field-name>.bin)",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(FILES_DOWNLOAD_EXAMPLES)
         .trackedAction(
             processContext,
@@ -187,6 +201,9 @@ export const registerFilesCommand = (program: Command) => {
                         entityId,
                         recordId,
                         fieldName,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
                     ),
                 );
 
@@ -252,6 +269,10 @@ export const registerFilesCommand = (program: Command) => {
             "--reason <reason>",
             "Reason for the deletion — echoed back in the response so the caller can log it",
         )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
+        )
         .examples(FILES_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -276,6 +297,9 @@ export const registerFilesCommand = (program: Command) => {
                         entityId,
                         recordId,
                         fieldName,
+                        options.folderKey !== undefined
+                            ? { folderKey: options.folderKey }
+                            : undefined,
                     ),
                 );