@uipath/data-fabric-tool 1.198.0 → 1.199.0-preview.104

package/src/commands/entities.ts

@@ -6,6 +6,8 @@ import {
     OutputFormatter,
     processContext,
     RESULTS,
+    runChecks,
+    type ValidationError,
 } from "@uipath/common";
 import type {
     EntityCreateFieldOptions,
@@ -20,6 +22,15 @@ import { type Command, Option } from "commander";
 import { readJsonInput } from "../utils/input";
 import { fail, requireDestructiveConfirmation } from "../utils/output";
 import { connectOrFail } from "../utils/sdk-client";
+import {
+    findInvalidFieldConstraints,
+    findInvalidFieldName,
+    findIsUniqueInUpdateFields,
+    findMissingComplexFieldExtras,
+    findReferenceFolderKeyOnChoiceSet,
+    findUiBrokenFieldType,
+    validateName,
+} from "../utils/validate";
 
 interface ListOptions {
     tenant?: string;
@@ -145,13 +156,14 @@ const ENTITIES_DELETE_EXAMPLES: CommandExample[] = [
 const ENTITIES_CREATE_EXAMPLES: CommandExample[] = [
     {
         Description:
-            "Create an entity with choice-set, relationship, and file fields. " +
+            "Create an entity with choice-set, relationship, file, and large-text fields. " +
             "CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE require 'choiceSetId' (from 'df choice-sets list'). " +
             "RELATIONSHIP requires 'referenceEntityId' (UUID of the target entity, from 'df entities list') and 'referenceFieldId' (UUID of the field on the target entity, from 'df entities get <target-id>'). " +
             "Note: a RELATIONSHIP column on a record always stores the target record's UUID 'Id' (regardless of which 'referenceFieldId' configured the join) — see 'df records insert' for how to write the value. " +
-            "FILE fields take only 'fieldName' and 'type' — the server auto-wires the internal attachment reference; populate them later with 'uip df files upload <entity-id> <record-id> <field-name> --file <path>'.",
+            "FILE fields take only 'fieldName' and 'type' — the server auto-wires the internal attachment reference; populate them later with 'uip df files upload <entity-id> <record-id> <field-name> --file <path>'. " +
+            "MULTILINE_MAX holds very large text ('lengthLimit' = UTF-16 byte budget, 1-131072; default max ~65,536 chars). Not filterable/sortable; 'records list'/'query' return a size marker — full content via 'records get'. Tenant-gated by the 'MultilineMax' feature flag.",
         Command:
-            'uip df entities create Expense --body \'{"displayName":"Expense","fields":[{"fieldName":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"fieldName":"tags","type":"CHOICE_SET_MULTIPLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000002"},{"fieldName":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"fieldName":"receipt","type":"FILE"}]}\'',
+            'uip df entities create Expense --body \'{"displayName":"Expense","fields":[{"fieldName":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"fieldName":"tags","type":"CHOICE_SET_MULTIPLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000002"},{"fieldName":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"fieldName":"receipt","type":"FILE"},{"fieldName":"notes","type":"MULTILINE_MAX"}]}\'',
         Output: {
             Code: "EntityCreated",
             Data: { ID: "a1b2c3d4-0000-0000-0000-000000000004" },
@@ -204,6 +216,20 @@ function pickKnownUpdateKeys(
     return out as EntityUpdateByIdOptions;
 }
 
+// Run every check that applies to a `fields` / `addFields` payload:
+// name rules and UI-broken-type substitution. The SDK-enum type check
+// stays inline at the call site because it needs `hasInvalidFieldType`
+// (bound to the SDK enum, not portable to @uipath/common).
+function validateFieldsPayload(fields: unknown[]): ValidationError | null {
+    return runChecks([
+        () => findInvalidFieldName(fields),
+        () => findUiBrokenFieldType(fields),
+        () => findReferenceFolderKeyOnChoiceSet(fields),
+        () => findMissingComplexFieldExtras(fields),
+        () => findInvalidFieldConstraints(fields),
+    ]);
+}
+
 export const registerEntitiesCommand = (program: Command) => {
     const entities = program
         .command("entities")
@@ -408,6 +434,12 @@ export const registerEntitiesCommand = (program: Command) => {
                     );
                 }
 
+                const err = runChecks([
+                    () => validateName(name, "entity"),
+                    () => validateFieldsPayload(definition.fields as unknown[]),
+                ]);
+                if (err) return fail(err.message, err.instructions);
+
                 const sdk = await connectOrFail(options.tenant);
                 if (!sdk) return;
 
@@ -599,6 +631,12 @@ export const registerEntitiesCommand = (program: Command) => {
                         );
                     }
 
+                    const addErr = validateFieldsPayload(
+                        input.addFields as unknown[],
+                    );
+                    if (addErr)
+                        return fail(addErr.message, addErr.instructions);
+
                     const addNames = (
                         input.addFields as { fieldName: string }[]
                     ).map((f) => f.fieldName);
@@ -639,6 +677,12 @@ export const registerEntitiesCommand = (program: Command) => {
                             'Use \'df entities get <entityId>\' to find field IDs. Example: {"id":"<fieldId>","displayName":"Total Amount","isRequired":true}',
                         );
                     }
+
+                    const updateErr = findIsUniqueInUpdateFields(
+                        input.updateFields as unknown[],
+                    );
+                    if (updateErr)
+                        return fail(updateErr.message, updateErr.instructions);
                 }
 
                 const sdk = await connectOrFail(options.tenant);

package/src/commands/records.spec.ts

@@ -37,6 +37,9 @@ function buildProgram(): Command {
 function mockSdk(overrides: Record<string, unknown> = {}) {
     const sdk = {
         entities: {
+            // Default schema has no FILE fields — insert/update FILE-payload
+            // guard is a no-op unless a test overrides this.
+            getById: vi.fn().mockResolvedValue({ fields: [] }),
             getAllRecords: vi.fn().mockResolvedValue({
                 items: [],
                 totalCount: 0,
@@ -781,6 +784,66 @@ describe("records insert", () => {
         );
         expect(process.exitCode).toBe(1);
     });
+
+    it("skips FILE-payload validation when schema fetch fails and lets the SDK error surface", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getById).mockRejectedValue(
+            new Error("Entity not found"),
+        );
+        vi.mocked(sdk.entities.insertRecordById).mockRejectedValue(
+            new Error("Entity not found"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "missing-entity-id",
+            "--body",
+            '{"title":"Q1"}',
+        ]);
+
+        expect(sdk.entities.insertRecordById).toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error inserting record",
+            }),
+        );
+    });
+
+    it("rejects a FILE-typed key in the insert body", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.getById).mockResolvedValue({
+            fields: [
+                { name: "title", fieldDataType: { name: "STRING" } },
+                { name: "receipt", fieldDataType: { name: "FILE" } },
+            ],
+        } as never);
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '{"title":"Q1","receipt":"/tmp/r.pdf"}',
+        ]);
+
+        expect(sdk.entities.insertRecordById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("FILE-typed field 'receipt'"),
+                Instructions: expect.stringContaining("files upload"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
 });
 
 describe("records update", () => {
@@ -1408,8 +1471,8 @@ describe("records query", () => {
                 queryFilters: [
                     {
                         fieldName: "amount",
-                        operator: "GreaterThan",
-                        value: 100,
+                        operator: ">",
+                        value: "100",
                     },
                 ],
             },
@@ -1550,7 +1613,7 @@ describe("records query", () => {
                 queryFilters: [
                     {
                         fieldName: "status",
-                        operator: "Equals",
+                        operator: "=",
                         value: "Active",
                     },
                 ],
@@ -1953,6 +2016,59 @@ describe("records import", () => {
     });
 });
 
+describe("records query — filter validation", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("rejects an unsupported operator", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            '{"filterGroup":{"queryFilters":[{"fieldName":"Status","operator":"==","value":"Active"}]}}',
+        ]);
+
+        expect(sdk.entities.queryRecordsById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("unsupported operator '=='"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("rejects 'in' without a valueList", async () => {
+        const sdk = mockSdk();
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "query",
+            "entity-id",
+            "--body",
+            '{"filterGroup":{"queryFilters":[{"fieldName":"Status","operator":"in","value":"Active"}]}}',
+        ]);
+
+        expect(sdk.entities.queryRecordsById).not.toHaveBeenCalled();
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("requires 'valueList'"),
+            }),
+        );
+        expect(process.exitCode).toBe(1);
+    });
+});
+
 describe("records query — pagination", () => {
     beforeEach(() => {
         vi.resetAllMocks();

package/src/commands/records.ts

@@ -13,6 +13,60 @@ import { type Command, Option } from "commander";
 import { readFileBinary, readJsonInput } from "../utils/input";
 import { fail, requireDestructiveConfirmation } from "../utils/output";
 import { connectOrFail } from "../utils/sdk-client";
+import { findFilePayloadKeys, validateQueryFilter } from "../utils/validate";
+
+// Fetch the entity schema and return the set of FILE-typed field names.
+// One RTT — worth it: without this, `records insert/update` silently
+// strips FILE keys server-side and returns Success unchanged.
+//
+// On any fetch error, returns an empty set instead of surfacing the error.
+// The SDK write call that follows will hit the same failure and produce
+// the authoritative message ("Entity not found", auth issue, network,
+// etc.) — pre-empting it here would hide the real error behind a
+// misleading "validation" wrapper.
+async function loadFileFieldNames(
+    sdk: Awaited<ReturnType<typeof connectOrFail>>,
+    entityId: string,
+    folderKey?: string,
+): Promise<Set<string>> {
+    const names = new Set<string>();
+    if (!sdk) return names;
+    const [schemaErr, entity] = await catchError(
+        sdk.entities.getById(
+            entityId,
+            folderKey !== undefined ? { folderKey } : undefined,
+        ),
+    );
+    if (schemaErr) return names;
+    // Detect FILE fields by their data-type name. The `isAttachment` boolean
+    // exists on the SDK type but the server does not reliably set it (all
+    // fields — including FILE — come back with `IsAttachment: false`), so
+    // relying on it silently skipped the FILE check in live tests.
+    //
+    // The response also uses PascalCase at runtime while the SDK's TypeScript
+    // type declares camelCase — read both to survive that skew.
+    const rec = entity as unknown as {
+        fields?: Array<Record<string, unknown>>;
+        Fields?: Array<Record<string, unknown>>;
+    };
+    const fieldList = rec.fields ?? rec.Fields ?? [];
+    for (const f of fieldList) {
+        const dataType = (f.fieldDataType ?? f.FieldDataType) as
+            | { name?: string; Name?: string }
+            | undefined;
+        const typeName = dataType?.name ?? dataType?.Name;
+        const fieldName =
+            typeof f.name === "string"
+                ? f.name
+                : typeof f.Name === "string"
+                  ? f.Name
+                  : undefined;
+        if (typeName === "FILE" && fieldName !== undefined) {
+            names.add(fieldName);
+        }
+    }
+    return names;
+}
 
 interface ListOptions {
     tenant?: string;
@@ -72,7 +126,8 @@ interface BatchResult {
 
 const RECORDS_LIST_EXAMPLES: CommandExample[] = [
     {
-        Description: "List records in an entity.",
+        Description:
+            "List records in an entity. MULTILINE_MAX fields return a size marker (see 'notes' below) — full value via 'records get'.",
         Command:
             "uip df records list a1b2c3d4-0000-0000-0000-000000000001 --limit 2",
         Output: {
@@ -82,10 +137,12 @@ const RECORDS_LIST_EXAMPLES: CommandExample[] = [
                     {
                         Id: "b2c3d4e5-0000-0000-0000-000000000001",
                         amount: 1500,
+                        notes: "HasValue=true Length=20000",
                     },
                     {
                         Id: "b2c3d4e5-0000-0000-0000-000000000002",
                         amount: 2750,
+                        notes: null,
                     },
                 ],
                 totalCount: 2,
@@ -97,7 +154,8 @@ const RECORDS_LIST_EXAMPLES: CommandExample[] = [
 
 const RECORDS_GET_EXAMPLES: CommandExample[] = [
     {
-        Description: "Get a record by ID",
+        Description:
+            "Get a record by ID. Returns MULTILINE_MAX fields in full (see 'notes' below).",
         Command:
             "uip df records get a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001",
         Output: {
@@ -106,6 +164,7 @@ const RECORDS_GET_EXAMPLES: CommandExample[] = [
                 Id: "b2c3d4e5-0000-0000-0000-000000000001",
                 amount: 1500,
                 status: "Paid",
+                notes: "Customer disputed the Q1 late fee. Timeline of the case: … (the complete 20,000-character text, returned in full)",
             },
         },
     },
@@ -411,6 +470,14 @@ export const registerRecordsCommand = (program: Command) => {
                         ? { folderKey: options.folderKey }
                         : undefined;
 
+                const fileNames = await loadFileFieldNames(
+                    sdk,
+                    entityId,
+                    options.folderKey,
+                );
+                const fileErr = findFilePayloadKeys(recordsList, fileNames);
+                if (fileErr) return fail(fileErr.message, fileErr.instructions);
+
                 if (recordsList.length === 1) {
                     const [insertError, result] = await catchError(
                         sdk.entities.insertRecordById(
@@ -511,6 +578,14 @@ export const registerRecordsCommand = (program: Command) => {
                         ? { folderKey: options.folderKey }
                         : undefined;
 
+                const fileNames = await loadFileFieldNames(
+                    sdk,
+                    entityId,
+                    options.folderKey,
+                );
+                const fileErr = findFilePayloadKeys(recordsList, fileNames);
+                if (fileErr) return fail(fileErr.message, fileErr.instructions);
+
                 if (recordsList.length === 1) {
                     const record = recordsList[0];
                     const recordId =
@@ -685,6 +760,12 @@ export const registerRecordsCommand = (program: Command) => {
                         );
                     }
                     queryBody = parsed as Record<string, unknown>;
+
+                    const filterErr = validateQueryFilter(
+                        queryBody.filterGroup,
+                    );
+                    if (filterErr)
+                        return fail(filterErr.message, filterErr.instructions);
                 }
 
                 const sdk = await connectOrFail(options.tenant);

package/src/commands/roles.spec.ts

@@ -0,0 +1,153 @@
+import { Command } from "commander";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../utils/sdk-client", () => ({
+    createDataFabricClient: vi.fn(),
+    connectOrFail: vi.fn(),
+}));
+
+vi.mock("@uipath/common", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("@uipath/common")>();
+    return {
+        ...actual,
+        OutputFormatter: {
+            success: vi.fn(),
+            error: vi.fn(),
+        },
+    };
+});
+
+import { OutputFormatter } from "@uipath/common";
+import { connectOrFail } from "../utils/sdk-client";
+import { registerRolesCommand } from "./roles";
+
+function buildProgram(): Command {
+    const program = new Command();
+    program.name("test").exitOverride();
+    registerRolesCommand(program);
+    return program;
+}
+
+function mockSdk(overrides: Record<string, unknown> = {}) {
+    const sdk = {
+        entities: {
+            roles: {
+                getAll: vi.fn().mockResolvedValue([]),
+                ...overrides,
+            },
+        },
+    };
+    vi.mocked(connectOrFail).mockResolvedValue(sdk as never);
+    return sdk;
+}
+
+describe("roles", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        process.exitCode = undefined;
+    });
+
+    it("should register the roles command as hidden with a list subcommand", () => {
+        const program = buildProgram();
+        const cmd = program.commands.find((c) => c.name() === "roles");
+        expect(cmd).toBeDefined();
+        expect(program.commands.some((c) => c.name() === "roles")).toBe(true);
+        const subNames = cmd?.commands.map((c) => c.name()) ?? [];
+        expect(subNames).toContain("list");
+    });
+
+    it("should list roles with stats enabled by default", async () => {
+        const sdk = mockSdk();
+        const rawRoles = [
+            {
+                id: "c1d2e3f4-0000-0000-0000-000000000001",
+                name: "DataWriter",
+                type: "System",
+                directoryEntityCount: 3,
+            },
+        ];
+        vi.mocked(sdk.entities.roles.getAll).mockResolvedValue(
+            rawRoles as never,
+        );
+
+        const program = buildProgram();
+        await program.parseAsync(["node", "test", "roles", "list"]);
+
+        expect(sdk.entities.roles.getAll).toHaveBeenCalledWith({
+            stats: true,
+        });
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Success",
+                Code: "RoleList",
+                Data: rawRoles,
+            }),
+        );
+    });
+
+    it("should pass stats false with --no-stats", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "roles",
+            "list",
+            "--no-stats",
+        ]);
+
+        expect(sdk.entities.roles.getAll).toHaveBeenCalledWith({
+            stats: false,
+        });
+    });
+
+    it("should forward --folder-key", async () => {
+        const sdk = mockSdk();
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "roles",
+            "list",
+            "--folder-key",
+            "f-key-1",
+        ]);
+
+        expect(sdk.entities.roles.getAll).toHaveBeenCalledWith({
+            stats: true,
+            folderKey: "f-key-1",
+        });
+    });
+
+    it("should fail with exit 1 when the SDK call errors", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.roles.getAll).mockRejectedValue(
+            new Error("boom"),
+        );
+
+        const program = buildProgram();
+        await program.parseAsync(["node", "test", "roles", "list"]);
+
+        expect(OutputFormatter.error).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: "Error listing roles",
+            }),
+        );
+        expect(OutputFormatter.success).not.toHaveBeenCalled();
+        expect(process.exitCode).toBe(1);
+    });
+
+    it("should bail when SDK connection fails", async () => {
+        const sdk = mockSdk();
+        vi.mocked(connectOrFail).mockResolvedValue(undefined);
+
+        const program = buildProgram();
+        await program.parseAsync(["node", "test", "roles", "list"]);
+
+        expect(sdk.entities.roles.getAll).not.toHaveBeenCalled();
+        expect(OutputFormatter.success).not.toHaveBeenCalled();
+    });
+});

package/src/commands/roles.ts

@@ -0,0 +1,88 @@
+import {
+    type CommandExample,
+    catchError,
+    createHiddenDeprecatedTenantOption,
+    extractErrorMessage,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import type { Command } from "commander";
+import { fail } from "../utils/output";
+import { connectOrFail } from "../utils/sdk-client";
+
+interface ListOptions {
+    tenant?: string;
+    stats: boolean;
+    folderKey?: string;
+}
+
+const ROLES_LIST_EXAMPLES: CommandExample[] = [
+    {
+        Description: "List Data Fabric access roles.",
+        Command: "uip df roles list",
+        Output: {
+            Code: "RoleList",
+            Data: [
+                {
+                    Id: "c1d2e3f4-0000-0000-0000-000000000001",
+                    Name: "DataWriter",
+                    Type: "System",
+                    DirectoryEntityCount: 3,
+                },
+            ],
+        },
+    },
+];
+
+/**
+ * Internal manage-access surface — hidden from help output and not part of
+ * the documented `uip df` command set.
+ */
+export const registerRolesCommand = (program: Command) => {
+    const roles = program
+        .command("roles", { hidden: true })
+        .description("Manage Data Fabric access roles");
+
+    roles
+        .command("list")
+        .description("List Data Fabric access roles")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
+        .option(
+            "--no-stats",
+            "Skip role statistics (directory entity counts) in the response",
+        )
+        .option(
+            "--folder-key <key>",
+            "Folder key (GUID) for folder-scoped role requests",
+        )
+        .examples(ROLES_LIST_EXAMPLES)
+        .trackedAction(processContext, async (options: ListOptions) => {
+            const sdk = await connectOrFail(options.tenant);
+            if (!sdk) return;
+
+            const [listError, result] = await catchError(
+                sdk.entities.roles.getAll({
+                    stats: options.stats,
+                    ...(options.folderKey !== undefined && {
+                        folderKey: options.folderKey,
+                    }),
+                }),
+            );
+
+            if (listError) {
+                return fail(
+                    "Error listing roles",
+                    await extractErrorMessage(listError),
+                );
+            }
+
+            OutputFormatter.success({
+                Result: RESULTS.Success,
+                Code: "RoleList",
+                Data: result ?? [],
+            });
+        });
+};

package/src/tool.ts

@@ -4,9 +4,11 @@ import {
     registerChoiceSetsCommand,
     registerChoiceSetValuesCommand,
 } from "./commands/choice-sets";
+import { registerDirectoryCommand } from "./commands/directory";
 import { registerEntitiesCommand } from "./commands/entities";
 import { registerFilesCommand } from "./commands/files";
 import { registerRecordsCommand } from "./commands/records";
+import { registerRolesCommand } from "./commands/roles";
 
 export const metadata = {
     name: "data-fabric-tool",
@@ -22,4 +24,6 @@ export const registerCommands = async (program: Command): Promise<void> => {
     registerFilesCommand(program);
     registerChoiceSetsCommand(program);
     registerChoiceSetValuesCommand(program);
+    registerRolesCommand(program);
+    registerDirectoryCommand(program);
 };