@uipath/data-fabric-tool 1.0.1 → 1.1.0

package/src/commands/choice-sets.ts

@@ -0,0 +1,286 @@
+import {
+    type CommandExample,
+    catchError,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import type { Command } from "commander";
+import { extractCursorValue } from "../utils/pagination";
+import { createDataFabricClient } from "../utils/sdk-client";
+
+interface ListOptions {
+    tenant?: string;
+}
+
+interface GetOptions {
+    tenant?: string;
+    limit?: string;
+    offset?: string;
+    cursor?: string;
+}
+
+const CHOICE_SETS_LIST_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "List all Data Fabric choice sets. The returned 'ID' is the value to pass as 'choiceSetId' on a CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE entity field, or to 'df choice-sets get <id>'.",
+        Command: "uip df choice-sets list",
+        Output: {
+            Code: "ChoiceSetList",
+            Data: [
+                {
+                    ID: "c1d2e3f4-0000-0000-0000-000000000001",
+                    Name: "ExpenseTypes",
+                    DisplayName: "Expense Types",
+                    Description: "Categories of expenses",
+                    FolderId: "f1000000-0000-0000-0000-000000000001",
+                    CreatedBy: "u1000000-0000-0000-0000-000000000001",
+                    UpdatedBy: "u1000000-0000-0000-0000-000000000001",
+                    CreatedTime: "2026-01-01T00:00:00Z",
+                    UpdatedTime: "2026-01-02T00:00:00Z",
+                },
+            ],
+        },
+    },
+];
+
+const CHOICE_SETS_GET_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "Get values for a choice set. The 'NumberId' on each value is the integer to pass when inserting or updating a record into a CHOICE_SET_SINGLE field (or in an array for CHOICE_SET_MULTIPLE).",
+        Command:
+            "uip df choice-sets get c1d2e3f4-0000-0000-0000-000000000001 --limit 2",
+        Output: {
+            Code: "ChoiceSetValues",
+            Data: {
+                TotalCount: 2,
+                Values: [
+                    {
+                        Id: "v1000000-0000-0000-0000-000000000001",
+                        Name: "travel",
+                        DisplayName: "Travel",
+                        NumberId: 1,
+                    },
+                    {
+                        Id: "v1000000-0000-0000-0000-000000000002",
+                        Name: "meals",
+                        DisplayName: "Meals",
+                        NumberId: 2,
+                    },
+                ],
+                HasNextPage: false,
+            },
+        },
+    },
+];
+
+export const registerChoiceSetsCommand = (program: Command) => {
+    const choiceSets = program
+        .command("choice-sets")
+        .description(
+            "Browse Data Fabric choice sets. Read-only: choice sets are authored in the Data Fabric web UI and cannot be created, updated, or deleted from the CLI. " +
+                "Use 'list' to find a choice set's ID (used as 'choiceSetId' on CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE entity fields), and 'get' to inspect its values.",
+        );
+
+    choiceSets
+        .command("list")
+        .description("List all Data Fabric choice sets")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .examples(CHOICE_SETS_LIST_EXAMPLES)
+        .trackedAction(processContext, async (options: ListOptions) => {
+            const [clientError, sdk] = await catchError(
+                createDataFabricClient(options.tenant),
+            );
+
+            if (clientError) {
+                OutputFormatter.error({
+                    Result: RESULTS.Failure,
+                    Message: "Error connecting to Data Fabric",
+                    Instructions: await extractErrorMessage(clientError),
+                });
+                processContext.exit(1);
+                return;
+            }
+
+            const [listError, result] = await catchError(
+                sdk.entities.choicesets.getAll(),
+            );
+
+            if (listError) {
+                OutputFormatter.error({
+                    Result: RESULTS.Failure,
+                    Message: "Error listing choice sets",
+                    Instructions: await extractErrorMessage(listError),
+                });
+                processContext.exit(1);
+                return;
+            }
+
+            const items = (result ?? []).map((cs) => ({
+                ID: (cs as { id?: string }).id,
+                Name: cs.name,
+                DisplayName: cs.displayName || cs.name,
+                Description: cs.description || "",
+                FolderId: cs.folderId,
+                CreatedBy: cs.createdBy,
+                UpdatedBy: cs.updatedBy,
+                CreatedTime: cs.createdTime,
+                UpdatedTime: cs.updatedTime,
+            }));
+
+            OutputFormatter.success({
+                Result: RESULTS.Success,
+                Code: "ChoiceSetList",
+                Data: items,
+            });
+        });
+
+    choiceSets
+        .command("get")
+        .description("Get values for a Data Fabric choice set")
+        .argument("<choice-set-id>", "Choice set ID")
+        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .option(
+            "-l, --limit <number>",
+            "Number of values to return per page",
+            "50",
+        )
+        .option(
+            "-o, --offset <number>",
+            "Start from the page containing this record index (rounded down to the nearest page boundary; mutually exclusive with --cursor)",
+        )
+        .option(
+            "--cursor <cursor>",
+            "Pagination cursor from a previous response to fetch the next page",
+        )
+        .examples(CHOICE_SETS_GET_EXAMPLES)
+        .trackedAction(
+            processContext,
+            async (choiceSetId: string, options: GetOptions) => {
+                const pageSize = Number(options.limit ?? "50");
+                if (Number.isNaN(pageSize) || pageSize < 1) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Invalid --limit value",
+                        Instructions: "Provide a positive integer for --limit.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                if (
+                    options.cursor !== undefined &&
+                    options.offset !== undefined
+                ) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "--offset and --cursor are mutually exclusive",
+                        Instructions:
+                            "Use --offset to jump to a position by record count, or --cursor to continue from a previous response.",
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                let jumpToPage: number | undefined;
+                if (options.offset !== undefined) {
+                    const offsetValue = Number(options.offset);
+                    if (Number.isNaN(offsetValue) || offsetValue < 0) {
+                        OutputFormatter.error({
+                            Result: RESULTS.Failure,
+                            Message: "Invalid --offset value",
+                            Instructions:
+                                "Provide a non-negative integer for --offset.",
+                        });
+                        processContext.exit(1);
+                        return;
+                    }
+                    jumpToPage = Math.floor(offsetValue / pageSize) + 1;
+                }
+
+                const [clientError, sdk] = await catchError(
+                    createDataFabricClient(options.tenant),
+                );
+
+                if (clientError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: "Error connecting to Data Fabric",
+                        Instructions: await extractErrorMessage(clientError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                const paginationOptions =
+                    options.cursor !== undefined
+                        ? { pageSize, cursor: { value: options.cursor } }
+                        : jumpToPage !== undefined
+                          ? { pageSize, jumpToPage }
+                          : { pageSize };
+
+                const [getError, result] = await catchError(
+                    sdk.entities.choicesets.getById(
+                        choiceSetId,
+                        paginationOptions,
+                    ),
+                );
+
+                if (getError) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `Error getting choice set '${choiceSetId}'`,
+                        Instructions: await extractErrorMessage(getError),
+                    });
+                    processContext.exit(1);
+                    return;
+                }
+
+                type ChoiceSetValue = {
+                    id?: string;
+                    name?: string;
+                    displayName?: string;
+                    numberId?: number;
+                    createdTime?: string;
+                    updatedTime?: string;
+                };
+                const response = result as unknown as {
+                    items?: ChoiceSetValue[];
+                    totalCount?: number;
+                    hasNextPage?: boolean;
+                    nextCursor?: unknown;
+                    currentPage?: number;
+                    totalPages?: number;
+                };
+                const values = (response.items ?? []).map((v) => ({
+                    Id: v.id,
+                    Name: v.name,
+                    DisplayName: v.displayName || v.name,
+                    NumberId: v.numberId,
+                    CreatedTime: v.createdTime,
+                    UpdatedTime: v.updatedTime,
+                }));
+                const nextCursor = extractCursorValue(response.nextCursor);
+
+                OutputFormatter.success({
+                    Result: RESULTS.Success,
+                    Code: "ChoiceSetValues",
+                    Data: {
+                        TotalCount: response.totalCount ?? values.length,
+                        Values: values,
+                        HasNextPage: response.hasNextPage ?? false,
+                        ...(nextCursor !== undefined && {
+                            NextCursor: nextCursor,
+                        }),
+                        ...(response.currentPage !== undefined && {
+                            CurrentPage: response.currentPage,
+                        }),
+                        ...(response.totalPages !== undefined && {
+                            TotalPages: response.totalPages,
+                        }),
+                    },
+                });
+            },
+        );
+};

package/src/commands/entities.spec.ts

@@ -465,6 +465,128 @@ describe("entities create", () => {
         );
     });
 
+    it("should create entity with a CHOICE_SET_SINGLE field carrying choiceSetId", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue(
+            "entity-choice-single",
+        );
+        const fields = [
+            {
+                fieldName: "opType",
+                type: "CHOICE_SET_SINGLE",
+                choiceSetId: "9db00b66-9952-f111-8ef3-6045bd07956d",
+                isRequired: true,
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ fields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "CliTestExpense",
+            "--body",
+            JSON.stringify({ fields }),
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "CliTestExpense",
+            expect.arrayContaining([
+                expect.objectContaining({
+                    fieldName: "opType",
+                    type: "CHOICE_SET_SINGLE",
+                    choiceSetId: "9db00b66-9952-f111-8ef3-6045bd07956d",
+                }),
+            ]),
+            undefined,
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityCreated" }),
+        );
+    });
+
+    it("should create entity with a CHOICE_SET_MULTIPLE field carrying choiceSetId", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue("entity-choice-multi");
+        const fields = [
+            {
+                fieldName: "multiOpType",
+                type: "CHOICE_SET_MULTIPLE",
+                choiceSetId: "9db00b66-9952-f111-8ef3-6045bd07956d",
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ fields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "CliTestExpense",
+            "--body",
+            JSON.stringify({ fields }),
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "CliTestExpense",
+            expect.arrayContaining([
+                expect.objectContaining({
+                    fieldName: "multiOpType",
+                    type: "CHOICE_SET_MULTIPLE",
+                    choiceSetId: "9db00b66-9952-f111-8ef3-6045bd07956d",
+                }),
+            ]),
+            undefined,
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityCreated" }),
+        );
+    });
+
+    it("should create entity with a RELATIONSHIP field carrying referenceEntityName and referenceFieldName", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.create).mockResolvedValue("entity-rel");
+        const fields = [
+            {
+                fieldName: "rel1",
+                type: "RELATIONSHIP",
+                referenceEntityName: "CodeEvalTestEntity",
+                referenceFieldName: "Email",
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ fields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "create",
+            "CliTestExpense",
+            "--body",
+            JSON.stringify({ fields }),
+        ]);
+
+        expect(sdk.entities.create).toHaveBeenCalledWith(
+            "CliTestExpense",
+            expect.arrayContaining([
+                expect.objectContaining({
+                    fieldName: "rel1",
+                    type: "RELATIONSHIP",
+                    referenceEntityName: "CodeEvalTestEntity",
+                    referenceFieldName: "Email",
+                }),
+            ]),
+            undefined,
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityCreated" }),
+        );
+    });
+
     it("should error when no --body or --file provided", async () => {
         vi.mocked(readJsonInput).mockRejectedValue(
             new Error("Provide entity definition via --file or --body."),
@@ -684,6 +806,69 @@ describe("entities update", () => {
         );
     });
 
+    it("should update entity by adding a RELATIONSHIP field with referenceFieldName=Email", async () => {
+        const sdk = mockSdk();
+        const addFields = [
+            {
+                fieldName: "rel1",
+                type: "RELATIONSHIP",
+                referenceEntityName: "CodeEvalTestEntity",
+                referenceFieldName: "Email",
+            },
+        ];
+        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(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityUpdated" }),
+        );
+    });
+
+    it("should update entity by adding a CHOICE_SET_MULTIPLE field with choiceSetId", async () => {
+        const sdk = mockSdk();
+        const addFields = [
+            {
+                fieldName: "multiOpType",
+                type: "CHOICE_SET_MULTIPLE",
+                choiceSetId: "9db00b66-9952-f111-8ef3-6045bd07956d",
+            },
+        ];
+        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(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityUpdated" }),
+        );
+    });
+
     it("should update entity by modifying existing fields (updateFields)", async () => {
         const sdk = mockSdk();
         vi.mocked(readJsonInput).mockResolvedValue({
@@ -727,6 +912,182 @@ describe("entities update", () => {
         );
     });
 
+    it("should update displayName on a CHOICE_SET_SINGLE field via updateFields", async () => {
+        const sdk = mockSdk();
+        const updateFields = [
+            {
+                id: "f9ccd648-ac52-f111-8ef3-6045bd07956d",
+                displayName: "Operator Type",
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ updateFields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            JSON.stringify({ updateFields }),
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ updateFields }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityUpdated" }),
+        );
+    });
+
+    it("should update displayName and isRequired on a CHOICE_SET_MULTIPLE field via updateFields", async () => {
+        const sdk = mockSdk();
+        const updateFields = [
+            {
+                id: "8750af08-b252-f111-8ef3-6045bd07956d",
+                displayName: "Multi Operator Types",
+                isRequired: true,
+            },
+        ];
+        vi.mocked(readJsonInput).mockResolvedValue({ updateFields });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            JSON.stringify({ updateFields }),
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({ updateFields }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "EntityUpdated" }),
+        );
+    });
+
+    it("should remove a CHOICE_SET_SINGLE field via removeFields with --confirm and --reason", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            removeFields: [{ fieldName: "opType" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"removeFields":[{"fieldName":"opType"}]}',
+            "--confirm",
+            "--reason",
+            "dropping single-select choice-set field",
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                removeFields: [{ fieldName: "opType" }],
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "EntityUpdated",
+                Data: expect.objectContaining({
+                    RemovedFields: ["opType"],
+                    Reason: "dropping single-select choice-set field",
+                }),
+            }),
+        );
+    });
+
+    it("should remove a CHOICE_SET_MULTIPLE field via removeFields with --confirm and --reason", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            removeFields: [{ fieldName: "multiOpType" }],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"removeFields":[{"fieldName":"multiOpType"}]}',
+            "--confirm",
+            "--reason",
+            "dropping multi-select choice-set field",
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                removeFields: [{ fieldName: "multiOpType" }],
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    RemovedFields: ["multiOpType"],
+                    Reason: "dropping multi-select choice-set field",
+                }),
+            }),
+        );
+    });
+
+    it("should remove both choice-set fields in a single removeFields call", async () => {
+        const sdk = mockSdk();
+        vi.mocked(readJsonInput).mockResolvedValue({
+            removeFields: [
+                { fieldName: "opType" },
+                { fieldName: "multiOpType" },
+            ],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "entities",
+            "update",
+            "entity-id",
+            "--body",
+            '{"removeFields":[{"fieldName":"opType"},{"fieldName":"multiOpType"}]}',
+            "--confirm",
+            "--reason",
+            "dropping all choice-set fields",
+        ]);
+
+        expect(sdk.entities.updateById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                removeFields: [
+                    { fieldName: "opType" },
+                    { fieldName: "multiOpType" },
+                ],
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Data: expect.objectContaining({
+                    RemovedFields: ["opType", "multiOpType"],
+                }),
+            }),
+        );
+    });
+
     it("should update entity metadata only (displayName and description)", async () => {
         const sdk = mockSdk();
         vi.mocked(readJsonInput).mockResolvedValue({