@uipath/data-fabric-tool 1.195.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 = [
@@ -1217,7 +1296,7 @@ describe("entities update", () => {
         expect(process.exitCode).toBe(1);
     });
 
-    it("should reject removeFields without --confirm", async () => {
+    it("should reject removeFields without confirmation: exit 1, SDK not called", async () => {
         const sdk = mockSdk();
         vi.mocked(readJsonInput).mockResolvedValue({
             removeFields: [{ fieldName: "oldField" }],
@@ -1237,15 +1316,36 @@ describe("entities update", () => {
         ]);
 
         expect(sdk.entities.updateById).not.toHaveBeenCalled();
-        expect(OutputFormatter.error).toHaveBeenCalledWith(
-            expect.objectContaining({
-                Result: "Failure",
-                Message: "Confirmation required for destructive operation",
-            }),
-        );
+        expect(OutputFormatter.success).not.toHaveBeenCalled();
         expect(process.exitCode).toBe(1);
     });
 
+    it("should accept removeFields with --yes (canonical flag)", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            removeFields: [{ fieldName: "oldField" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"removeFields":[{"fieldName":"oldField"}]}',
+            "--yes",
+            "--reason",
+            "drop legacy",
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalled();
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Success" }),
+        );
+    });
+
     it("should reject removeFields without --reason", async () => {
         const sdk = mockSdk();
         vi.mocked(readJsonInput).mockResolvedValue({
@@ -1751,6 +1851,7 @@ describe("entities delete", () => {
 
         expect(sdk.entities.deleteById).toHaveBeenCalledWith(
             "entity-to-delete",
+            undefined,
         );
         expect(OutputFormatter.success).toHaveBeenCalledWith(
             expect.objectContaining({
@@ -1764,7 +1865,7 @@ describe("entities delete", () => {
         );
     });
 
-    it("should error when --confirm is missing", async () => {
+    it("should error when confirmation is missing: exit 1, SDK not called", async () => {
         const sdk = mockSdk();
 
         const program = buildProgram();
@@ -1779,15 +1880,34 @@ describe("entities delete", () => {
         ]);
 
         expect(sdk.entities.deleteById).not.toHaveBeenCalled();
-        expect(OutputFormatter.error).toHaveBeenCalledWith(
-            expect.objectContaining({
-                Result: "Failure",
-                Message: "Confirmation required for destructive operation",
-            }),
-        );
+        expect(OutputFormatter.success).not.toHaveBeenCalled();
         expect(process.exitCode).toBe(1);
     });
 
+    it("should delete with --yes (canonical confirmation flag)", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "delete",
+            "entity-id",
+            "--yes",
+            "--reason",
+            "cleanup",
+        ]);
+
+        expect(sdk.entities.deleteById).toHaveBeenCalledWith(
+            "entity-id",
+            undefined,
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Result: "Success" }),
+        );
+    });
+
     it("should error when --reason is missing", async () => {
         const sdk = mockSdk();
 
@@ -1883,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,13 +9,14 @@ import {
 } from "@uipath/common";
 import type {
     EntityCreateFieldOptions,
+    EntityGetAllOptions,
     EntityServiceModel,
     EntityUpdateByIdOptions,
     ExternalSourceFields,
     RawEntityGetResponse,
 } from "@uipath/uipath-typescript";
 import { EntityFieldDataType } from "@uipath/uipath-typescript";
-import type { Command } from "commander";
+import { type Command, Option } from "commander";
 import { readJsonInput } from "../utils/input";
 import { fail, requireDestructiveConfirmation } from "../utils/output";
 import { connectOrFail } from "../utils/sdk-client";
@@ -23,35 +24,45 @@ 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 {
     tenant?: string;
     file?: string;
     body?: string;
+    yes?: boolean;
     confirm?: boolean;
     reason?: string;
+    folderKey?: string;
 }
 
 interface DeleteOptions {
     tenant?: string;
+    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",
@@ -62,6 +73,7 @@ const ENTITIES_LIST_EXAMPLES: CommandExample[] = [
                     displayName: "Invoice",
                     entityType: "Standard",
                     description: "Invoice records",
+                    folderId: "f1000000-0000-0000-0000-000000000001",
                     isRbacEnabled: false,
                     fields: [
                         {
@@ -144,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));
@@ -193,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(
@@ -229,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,
@@ -237,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) {
@@ -279,6 +344,10 @@ export const registerEntitiesCommand = (program: Command) => {
             "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled optional)",
         )
         .option("--body <json>", "Inline JSON entity definition")
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) of the target folder (for folder-scoped entities)",
+        )
         .examples(ENTITIES_CREATE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -351,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;
@@ -390,15 +462,25 @@ export const registerEntitiesCommand = (program: Command) => {
             "-f, --file <path>",
             "Path to JSON file with update options (addFields, updateFields, removeFields, displayName, description, isRbacEnabled)",
         )
-        .option("--body <json>", "Inline JSON update options")
         .option(
-            "--confirm",
+            "--body <json>",
+            "Inline JSON update options (use `-` to read from stdin)",
+        )
+        .option(
+            "-y, --yes",
             "Required when 'removeFields' is non-empty — acknowledges the field deletion is irreversible",
         )
+        .addOption(
+            new Option("--confirm", "Deprecated alias for --yes").hideHelp(),
+        )
         .option(
             "--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) => {
@@ -482,6 +564,7 @@ export const registerEntitiesCommand = (program: Command) => {
 
                     const reason = requireDestructiveConfirmation(
                         options,
+                        `remove fields from entity '${id}'`,
                         'Pass --reason "<text>" to record why fields are being removed.',
                     );
                     if (reason === null) return;
@@ -561,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) {
@@ -593,17 +682,25 @@ export const registerEntitiesCommand = (program: Command) => {
         .addOption(
             createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
         )
-        .option("--confirm", "Acknowledge this is an irreversible operation")
+        .option("-y, --yes", "Acknowledge this is an irreversible operation")
+        .addOption(
+            new Option("--confirm", "Deprecated alias for --yes").hideHelp(),
+        )
         .option(
             "--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,
             async (id: string, options: DeleteOptions) => {
                 const reason = requireDestructiveConfirmation(
                     options,
+                    `delete entity '${id}'`,
                     'Pass --reason "<text>" to record why the entity is being deleted.',
                 );
                 if (reason === null) return;
@@ -613,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) {