@uipath/data-fabric-tool 1.0.1 → 1.1.0

package/src/commands/entities.ts

@@ -1,6 +1,7 @@
 import {
     type CommandExample,
     catchError,
+    createHiddenDeprecatedTenantOption,
     extractErrorMessage,
     OutputFormatter,
     processContext,
@@ -130,6 +131,22 @@ const ENTITIES_DELETE_EXAMPLES: CommandExample[] = [
     },
 ];
 
+const ENTITIES_CREATE_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "Create an entity with a choice-set field (single-select and multi-select) and a relationship to another entity. " +
+            "CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE require 'choiceSetId' (from 'df choice-sets list'). " +
+            "RELATIONSHIP requires 'referenceEntityName' (target entity) and 'referenceFieldName' (the field used to resolve joins on read; e.g. 'Id' or a unique key like 'Email'). " +
+            "Note: regardless of 'referenceFieldName', a relationship column on a record always stores the target record's UUID 'Id' — see 'df records insert' for how to write the value.",
+        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","referenceEntityName":"Employee","referenceFieldName":"Id","isRequired":true}]}\'',
+        Output: {
+            Code: "EntityCreated",
+            Data: { ID: "a1b2c3d4-0000-0000-0000-000000000004" },
+        },
+    },
+];
+
 const VALID_FIELD_TYPES = new Set(Object.values(EntityFieldDataType));
 const VALID_FIELD_TYPES_LIST = [...VALID_FIELD_TYPES].join(", ");
 
@@ -170,7 +187,9 @@ export const registerEntitiesCommand = (program: Command) => {
     entities
         .command("list")
         .description("List all Data Fabric entities")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "--native-only",
             "Show only native entities (exclude federated entities with external connections)",
@@ -237,7 +256,9 @@ export const registerEntitiesCommand = (program: Command) => {
         .command("get")
         .description("Get schema details of a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .examples(ENTITIES_GET_EXAMPLES)
         .trackedAction(
             processContext,
@@ -315,12 +336,15 @@ export const registerEntitiesCommand = (program: Command) => {
             "<name>",
             "Entity name (must start with a letter; letters, numbers, and underscores only)",
         )
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-f, --file <path>",
             "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled optional)",
         )
         .option("--body <json>", "Inline JSON entity definition")
+        .examples(ENTITIES_CREATE_EXAMPLES)
         .trackedAction(
             processContext,
             async (name: string, options: CreateOptions) => {
@@ -457,7 +481,9 @@ export const registerEntitiesCommand = (program: Command) => {
         .command("update")
         .description("Update schema or metadata of a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-f, --file <path>",
             "Path to JSON file with update options (addFields, updateFields, removeFields, displayName, description, isRbacEnabled)",
@@ -739,7 +765,9 @@ export const registerEntitiesCommand = (program: Command) => {
         .command("delete")
         .description("Delete a Data Fabric entity (irreversible)")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option("--confirm", "Acknowledge this is an irreversible operation")
         .option(
             "--reason <reason>",

package/src/commands/files.ts

@@ -1,6 +1,7 @@
 import {
     type CommandExample,
     catchError,
+    createHiddenDeprecatedTenantOption,
     extractErrorMessage,
     OutputFormatter,
     processContext,
@@ -86,7 +87,9 @@ export const registerFilesCommand = (program: Command) => {
         .argument("<entity-id>", "Entity ID")
         .argument("<record-id>", "Record ID")
         .argument("<field-name>", "Name of the file field (case-sensitive)")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option("-f, --file <path>", "Path to the file to upload")
         .examples(FILES_UPLOAD_EXAMPLES)
         .trackedAction(
@@ -179,7 +182,9 @@ export const registerFilesCommand = (program: Command) => {
         .argument("<entity-id>", "Entity ID")
         .argument("<record-id>", "Record ID")
         .argument("<field-name>", "Name of the file field (case-sensitive)")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "--destination <path>",
             "Output file path (defaults to <record-id>_<field-name>.bin)",
@@ -275,7 +280,9 @@ export const registerFilesCommand = (program: Command) => {
         .argument("<entity-id>", "Entity ID")
         .argument("<record-id>", "Record ID")
         .argument("<field-name>", "Name of the file field (case-sensitive)")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .examples(FILES_DELETE_EXAMPLES)
         .trackedAction(
             processContext,

package/src/commands/records.spec.ts

@@ -701,6 +701,75 @@ describe("records insert", () => {
         expect(process.exitCode).toBe(1);
     });
 
+    it("should pass choice-set NumberId integers and a relationship UUID through to the SDK on single insert", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordById).mockResolvedValue({
+            Id: "new-rec",
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '{"title":"Flight to NYC","amount":420.5,"opType":0,"multiOpType":[0,1],"assignee":"AEDE69C3-EFD1-4897-B216-019E1A7E9269","rel1":"B065E2A8-F33B-4721-8228-019DE0C593AF"}',
+        ]);
+
+        expect(sdk.entities.insertRecordById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.objectContaining({
+                opType: 0,
+                multiOpType: [0, 1],
+                assignee: "AEDE69C3-EFD1-4897-B216-019E1A7E9269",
+                rel1: "B065E2A8-F33B-4721-8228-019DE0C593AF",
+            }),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "RecordInserted" }),
+        );
+    });
+
+    it("should pass choice-set and relationship values through unchanged on batch insert", async () => {
+        const sdk = mockSdk();
+        vi.mocked(sdk.entities.insertRecordsById).mockResolvedValue({
+            successRecords: [{ Id: "rec-a" }, { Id: "rec-b" }],
+            failureRecords: [],
+        });
+
+        const program = buildProgram();
+        await program.parseAsync([
+            "node",
+            "test",
+            "records",
+            "insert",
+            "entity-id",
+            "--body",
+            '[{"opType":0,"multiOpType":[0],"assignee":"AEDE69C3-EFD1-4897-B216-019E1A7E9269"},{"opType":1,"multiOpType":[0,1],"assignee":"2481A9F6-E0F7-4996-8446-019E1A7E926A"}]',
+        ]);
+
+        expect(sdk.entities.insertRecordsById).toHaveBeenCalledWith(
+            "entity-id",
+            expect.arrayContaining([
+                expect.objectContaining({
+                    opType: 0,
+                    multiOpType: [0],
+                    assignee: "AEDE69C3-EFD1-4897-B216-019E1A7E9269",
+                }),
+                expect.objectContaining({
+                    opType: 1,
+                    multiOpType: [0, 1],
+                    assignee: "2481A9F6-E0F7-4996-8446-019E1A7E926A",
+                }),
+            ]),
+        );
+        expect(OutputFormatter.success).toHaveBeenCalledWith(
+            expect.objectContaining({ Code: "RecordsBatchInserted" }),
+        );
+    });
+
     it("should error on partial batch insert failure (FailureCount > 0)", async () => {
         const sdk = mockSdk();
         vi.mocked(sdk.entities.insertRecordsById).mockResolvedValue({

package/src/commands/records.ts

@@ -1,6 +1,7 @@
 import {
     type CommandExample,
     catchError,
+    createHiddenDeprecatedTenantOption,
     extractErrorMessage,
     OutputFormatter,
     processContext,
@@ -10,6 +11,7 @@ import { getFileSystem } from "@uipath/filesystem";
 import type { EntityRecord } from "@uipath/uipath-typescript";
 import type { Command } from "commander";
 import { readFileBinary, readJsonInput } from "../utils/input";
+import { extractCursorValue } from "../utils/pagination";
 import { createDataFabricClient } from "../utils/sdk-client";
 
 interface ListOptions {
@@ -113,6 +115,25 @@ const RECORDS_INSERT_EXAMPLES: CommandExample[] = [
             },
         },
     },
+    {
+        Description:
+            "Insert a record into an entity that has choice-set and relationship fields. " +
+            "CHOICE_SET_SINGLE → pass the choice value's 'NumberId' (integer, NOT the Name string — look it up via 'df choice-sets get <id>'). " +
+            "CHOICE_SET_MULTIPLE → pass an array of NumberId integers. " +
+            "RELATIONSHIP → always pass the target record's Id (UUID), even if the field was declared with a 'referenceFieldName' other than 'Id' (the referenceFieldName configures the join, not the stored value).",
+        Command:
+            'uip df records insert a1b2c3d4-0000-0000-0000-000000000004 --body \'{"category":0,"tags":[1,3],"submitter":"e1f2a3b4-0000-0000-0000-000000000001","amount":250}\'',
+        Output: {
+            Code: "RecordInserted",
+            Data: {
+                Id: "b2c3d4e5-0000-0000-0000-000000000020",
+                category: 0,
+                tags: [1, 3],
+                submitter: "e1f2a3b4-0000-0000-0000-000000000001",
+                amount: 250,
+            },
+        },
+    },
 ];
 
 const RECORDS_UPDATE_EXAMPLES: CommandExample[] = [
@@ -158,7 +179,9 @@ export const registerRecordsCommand = (program: Command) => {
         .command("list")
         .description("List records in a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-l, --limit <number>",
             "Number of records to return per page",
@@ -287,7 +310,9 @@ export const registerRecordsCommand = (program: Command) => {
         .description("Get a single record by ID")
         .argument("<id>", "Entity ID")
         .argument("<key>", "Record ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .examples(RECORDS_GET_EXAMPLES)
         .trackedAction(
             processContext,
@@ -343,7 +368,9 @@ export const registerRecordsCommand = (program: Command) => {
         .command("insert")
         .description("Insert records into a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-f, --file <path>",
             "Path to JSON file with record data (object or array of objects)",
@@ -449,7 +476,9 @@ export const registerRecordsCommand = (program: Command) => {
         .command("update")
         .description("Update records in a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-f, --file <path>",
             "Path to JSON file with record data (must include Id field)",
@@ -595,7 +624,9 @@ export const registerRecordsCommand = (program: Command) => {
                 "aggregates (function: COUNT/SUM/AVG/MIN/MAX, field, alias?), groupBy.",
         )
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option(
             "-f, --file <path>",
             "Path to JSON file with query options (filterGroup, selectedFields, sortOptions, aggregates, groupBy)",
@@ -766,7 +797,9 @@ export const registerRecordsCommand = (program: Command) => {
         .command("import")
         .description("Import records from a CSV file into a Data Fabric entity")
         .argument("<id>", "Entity ID")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .option("-f, --file <path>", "Path to the CSV file to import")
         .trackedAction(
             processContext,
@@ -855,7 +888,9 @@ export const registerRecordsCommand = (program: Command) => {
         .description("Delete records from a Data Fabric entity")
         .argument("<id>", "Entity ID")
         .argument("<key...>", "Record IDs to delete")
-        .option("-t, --tenant <tenant-name>", "Tenant name")
+        .addOption(
+            createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>"),
+        )
         .examples(RECORDS_DELETE_EXAMPLES)
         .trackedAction(
             processContext,
@@ -911,17 +946,6 @@ export const registerRecordsCommand = (program: Command) => {
         );
 };
 
-/** Normalises the SDK cursor to a plain string for CLI output.
- *  The SDK returns `PaginationCursor = { value: string }` but we want
- *  to expose just the string so the user can pass it directly to --cursor. */
-function extractCursorValue(cursor: unknown): string | undefined {
-    if (cursor === undefined || cursor === null) return undefined;
-    if (typeof cursor === "string") return cursor;
-    const c = cursor as Record<string, unknown>;
-    if (typeof c.value === "string") return c.value;
-    return undefined;
-}
-
 const isRecordObject = (value: unknown): value is Record<string, unknown> =>
     typeof value === "object" && value !== null && !Array.isArray(value);
 

package/src/index.ts

@@ -1,17 +1,12 @@
 #!/usr/bin/env bun
 import { Command } from "commander";
-import pkg from "../package.json" with { type: "json" };
-import { registerEntitiesCommand } from "./commands/entities";
-import { registerFilesCommand } from "./commands/files";
-import { registerRecordsCommand } from "./commands/records";
+import { metadata, registerCommands } from "./tool.js";
 
 const program = new Command();
 program
-    .name("data-fabric-tool")
-    .description("UiPath Data Fabric Tool - Standalone CLI")
-    .version(pkg.version);
+    .name(metadata.name)
+    .description(metadata.description)
+    .version(metadata.version);
 
-registerEntitiesCommand(program);
-registerRecordsCommand(program);
-registerFilesCommand(program);
+await registerCommands(program);
 await program.parseAsync(process.argv);

package/src/tool.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import pkg from "../package.json" with { type: "json" };
+import { registerChoiceSetsCommand } from "./commands/choice-sets";
 import { registerEntitiesCommand } from "./commands/entities";
 import { registerFilesCommand } from "./commands/files";
 import { registerRecordsCommand } from "./commands/records";
@@ -16,4 +17,5 @@ export const registerCommands = async (program: Command): Promise<void> => {
     registerEntitiesCommand(program);
     registerRecordsCommand(program);
     registerFilesCommand(program);
+    registerChoiceSetsCommand(program);
 };

package/src/utils/pagination.ts

@@ -0,0 +1,10 @@
+/** Normalises an SDK pagination cursor to a plain string for CLI output.
+ *  The SDK returns `PaginationCursor = { value: string }` but we want
+ *  to expose just the string so the user can pass it directly to --cursor. */
+export function extractCursorValue(cursor: unknown): string | undefined {
+    if (cursor === undefined || cursor === null) return undefined;
+    if (typeof cursor === "string") return cursor;
+    const c = cursor as Record<string, unknown>;
+    if (typeof c.value === "string") return c.value;
+    return undefined;
+}