@tenonhq/dovetail-servicenow 0.0.12 → 0.0.13

package/README.md

@@ -180,6 +180,10 @@ npx dove-sn view-action --sys-id <action_type_sys_id> --scope <scope_sys_id>
 # Copy a flow / subflow (creates an INACTIVE DRAFT) via the Designer's Copy endpoint
 npx dove-sn copy-flow --sys-id <sys_id> --name "My Copy"   # scope defaults to source's
 
+# Create a NEW flow (type=flow) from scratch and PUBLISH it (grafts a template's trigger+action)
+npx dove-sn create-flow --name "My Flow" --template <published_flow_sys_id> --scope <scope_sys_id> \
+  --trigger-table customer_contact --log-message "hello"            # add --dry-run to preview
+
 # Publish (compile the snapshot of) a flow / subflow after editing in the Designer
 npx dove-sn publish-flow --sys-id <sys_id>             # scope defaults to the flow's
 
@@ -196,6 +200,21 @@ npx dove-sn edit-flow --sys-id <sys_id> --from-json ops.json --apply --update-se
 `copy-flow` calls the Designer's own `POST /processflow/flow/{id}/copy` — a
 complete, faithful clone created as an **inactive draft**. (Don't publish +
 activate a copy of a triggered production flow unless you intend it to fire.)
+
+`create-flow` mints a **brand-new** flow (`sys_hub_flow`, `type=flow`) from scratch
+and **publishes** it: `POST /processflow/flow` initialises the envelope, the
+trigger + action graph is grafted from a published template flow (`--template`,
+ids remapped + values patched via `--trigger-table` / `--trigger-condition` /
+`--log-message`), a `versioning/create_version` bookmark is written, then the
+`/snapshot` POST compiles it. The result is a **published** flow — a published
+triggered flow can fire on its trigger, so do NOT graft a production send template
+you don't intend to fire (the `active` flag on the result reports whether it's
+live). The
+`POST /processflow/flow` create step is the crux: a Table-API / Dovetail
+`createRecord` insert never initialises the processflow envelope, so its snapshot
+POST silently no-ops (stays draft). Sequence reverse-engineered from Workflow
+Studio HARs and validated live (2026-06-02, tenonworkstudio). Exit `0` published
+or dry-run; `2` created-but-not-published.
 `test-flow` defaults to **validate** — a safe pre-flight (published? inputs match
 declared variables?) that never runs the flow; `--execute --confirm` runs it via
 the server-side FlowAPI runner (deploy `resources/runFlow.md` first).
@@ -258,7 +277,8 @@ Claude Code and agents: `create_view`, `set_list_layout`, `set_form_layout`,
 `set_related_lists`, `add_choices_to_field`, plus the Flow Designer tools
 `flow_view` (read a flow/subflow's step graph), `action_view` (read an action
 type's model), `flow_publish` (compile a flow/subflow snapshot), `flow_copy`
-(copy a flow as an inactive draft), `flow_test` (validate or run a flow), and
+(copy a flow as an inactive draft), `flow_create` (create a NEW flow from scratch +
+publish, grafting a template), `flow_test` (validate or run a flow), and
 `flow_edit` (patch a flow). It reads ServiceNow credentials from the same env
 vars as the CLI.
 

package/dist/cli.js

@@ -73,6 +73,7 @@ const readFlow_1 = require("./flowDesigner/readFlow");
 const readActionType_1 = require("./flowDesigner/readActionType");
 const publishFlow_1 = require("./flowDesigner/publishFlow");
 const copyFlow_1 = require("./flowDesigner/copyFlow");
+const createFlow_1 = require("./flowDesigner/createFlow");
 const editFlow_1 = require("./flowDesigner/editFlow");
 const testFlow_1 = require("./flowDesigner/testFlow");
 const flowDesigner_formatter_2 = require("./flowDesigner-formatter");
@@ -424,6 +425,79 @@ async function runCopyFlow(flags) {
         + ") — inactive draft. Publish with: dove-sn publish-flow --sys-id " + result.sysId + "\n");
     return 0;
 }
+/**
+ * dove-sn create-flow:
+ *   --name <name>           Required. Name for the new flow.
+ *   --template <sys_id>     Required. Published sys_hub_flow whose trigger+action graph is grafted.
+ *   --scope <sys_id>        Required. Target scope (sysparm_transaction_scope).
+ *   --internal-name <name>  Optional. internal_name (defaults to a slug of --name).
+ *   --description <text>    Optional.
+ *   --trigger-table <table> Optional. Patch the trigger's table input (e.g. customer_contact).
+ *   --trigger-condition <q> Optional. Patch the trigger's condition (encoded query).
+ *   --log-message <text>    Optional. Patch the action's message / short_description.
+ *   --dry-run               Optional. Print the plan + template graph counts; write nothing.
+ *   --json                  Optional. Emit the structured CreateFlowResult.
+ *
+ * Creates a NEW flow from scratch and PUBLISHES it: POST /processflow/flow mints an
+ * initialised envelope, the template's trigger+action graph is grafted on (ids remapped,
+ * values patched), then the snapshot is compiled. The result is a published flow — a
+ * published triggered flow can fire on its trigger, so do NOT graft a production send
+ * template you don't intend to fire (the result's `active` flag reports whether it's live).
+ *
+ * Exit codes: 0 published OR dry-run; 2 created-but-not-published (snapshot didn't compile).
+ */
+async function runCreateFlow(flags) {
+    var name = flags.name;
+    var templateSysId = flags.template || flags["template-sys-id"] || flags.templateSysId;
+    var scope = flags.scope || flags.scopeSysId;
+    if (!name || !templateSysId || !scope) {
+        process.stderr.write("create-flow: --name, --template <sys_id> and --scope <sys_id> are required\n");
+        return 1;
+    }
+    var params = {
+        client: (0, client_1.createClient)({}),
+        name: name,
+        templateSysId: templateSysId,
+        scopeSysId: scope
+    };
+    if (flags["internal-name"] || flags.internalName) {
+        params.internalName = flags["internal-name"] || flags.internalName;
+    }
+    if (flags.description) {
+        params.description = flags.description;
+    }
+    if (flags["trigger-table"] || flags.triggerTable) {
+        params.triggerTable = flags["trigger-table"] || flags.triggerTable;
+    }
+    if (flags["trigger-condition"] !== undefined || flags.triggerCondition !== undefined) {
+        params.triggerCondition = flags["trigger-condition"] !== undefined ? flags["trigger-condition"] : flags.triggerCondition;
+    }
+    if (flags["log-message"] || flags.logMessage) {
+        params.logMessage = flags["log-message"] || flags.logMessage;
+    }
+    if (flags["dry-run"] === "true") {
+        params.dryRun = true;
+    }
+    var result = await (0, createFlow_1.createFlow)(params);
+    if (flags.json === "true") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else if (result.status === "dry-run") {
+        process.stdout.write("[dry-run] would create '" + result.name + "' (internal " + result.internalName + ") in scope "
+            + result.scopeSysId + " — grafting " + result.graph.triggers + " trigger + "
+            + result.graph.actions + " action + " + result.graph.logic + " logic from template\n");
+    }
+    else {
+        process.stdout.write("[" + result.status + "] '" + result.name + "' sys_id " + result.sysId
+            + (result.snapshotSysId ? " — snapshot " + result.snapshotSysId : "")
+            + (result.active === undefined ? "" : result.active ? " — ACTIVE (will fire)" : " — inactive")
+            + "\n");
+    }
+    if (result.status === "not-published") {
+        return 2;
+    }
+    return 0;
+}
 /**
  * dove-sn test-flow:
  *   --sys-id <sys_id>   Required. sys_hub_flow sys_id (flow or subflow).
@@ -554,6 +628,10 @@ function printHelp() {
         "                     (--sys-id <sys_id> [--scope <sys_id>] [--json])\n" +
         "  copy-flow          Copy a flow/subflow (inactive draft) via the Designer Copy API\n" +
         "                     (--sys-id <sys_id> --name <name> [--scope <sys_id>] [--json])\n" +
+        "  create-flow        Create a NEW flow (type=flow) from scratch + publish (grafts a template)\n" +
+        "                     (--name <n> --template <sys_id> --scope <sys_id>\n" +
+        "                      [--trigger-table <t>] [--trigger-condition <q>] [--log-message <m>]\n" +
+        "                      [--internal-name <n>] [--description <d>] [--dry-run] [--json])\n" +
         "  test-flow          Validate (default) or run a flow/subflow\n" +
         "                     (--sys-id <sys_id> [--execute --confirm] [--inputs <json>] [--json])\n" +
         "  edit-flow          Patch a flow/subflow (rename, description, step inputs)\n" +
@@ -588,6 +666,9 @@ async function main() {
     if (parsed.command === "copy-flow") {
         return await runCopyFlow(parsed.flags);
     }
+    if (parsed.command === "create-flow") {
+        return await runCreateFlow(parsed.flags);
+    }
     if (parsed.command === "test-flow") {
         return await runTestFlow(parsed.flags);
     }

package/dist/flowDesigner/createFlow.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Create a whole Flow Designer FLOW (sys_hub_flow, type=flow) from scratch and
+ * publish it — headless, basic auth. The missing peer of copyFlow / publishFlow:
+ * copyFlow duplicates an existing flow; createFlow mints a NEW flow whose trigger
+ * + action graph is grafted from a template, then compiled.
+ *
+ * === CANONICAL SEQUENCE (reverse-engineered from Workflow Studio HARs, 2026-06-02) ===
+ * The Designer SPA holds the entire flow graph client-side and persists + compiles
+ * it in ONE shot at publish. There are NO incremental add-trigger / add-action REST
+ * calls — only version bookmarks. The proven, validated sequence is:
+ *
+ *   1. CREATE  POST /api/now/processflow/flow?param_only_properties=true&sysparm_transaction_scope={scope}
+ *        body = a small properties envelope. -> 200, result.data = a FULLY INITIALISED
+ *        empty model (server-minted id, internalName, flowCatalogVariableModelId,
+ *        version, authoredOnReleaseVersion). This initialisation is the piece a
+ *        Dovetail createRecord / Table API insert never produces — and without it the
+ *        snapshot POST silently no-ops (flow stays draft, no snapshot).
+ *   2. GRAFT   GET /api/now/processflow/flow/{template}?sysparm_transaction_scope={scope}
+ *        -> result.data carries the template's triggerInstances / actionInstances /
+ *        flowLogicInstances. Build the publish model = the NEW envelope with those arrays
+ *        grafted in, ids remapped (flowSysId -> new id; fresh id + uiUniqueIdentifier),
+ *        and values patched (trigger table/condition, action message inputs).
+ *   3. VERSION POST /api/now/processflow/versioning/create_version?...
+ *        body { item_sys_id: newFlow, type: "Activate/Publish", annotation: "", favorite: false }
+ *   4. PUBLISH POST /api/now/processflow/flow/{newFlow}/snapshot?...  body = the FLAT model
+ *        -> result.data.status="published", isPublished=true, latestSnapshot=<sys_id>.
+ *
+ * Validated live 2026-06-02 on tenonworkstudio (x_cadso_automate): flow
+ * aceb8e683395cb147b18bc534d5c7b5e published with a compiled snapshot
+ * (7ceb02a83395cb147b18bc534d5c7b03), 1 trigger in sys_hub_trigger_instance_v2,
+ * 1 action in sys_hub_action_instance_v2 — zero UI clicks.
+ *
+ * The clone inherits the template's trigger + action SHAPE; author a different
+ * shape by building that flow once in the Designer and pointing templateSysId at it.
+ */
+import type { ServiceNowClient } from "../client";
+export interface CreateFlowParams {
+    client: ServiceNowClient;
+    /** Name for the new flow. */
+    name: string;
+    /**
+     * sys_id of an existing published sys_hub_flow whose trigger + action graph is
+     * grafted onto the new flow. Required — the trigger/action shape comes from here.
+     */
+    templateSysId: string;
+    /** Target application scope sys_id (sysparm_transaction_scope). Required. */
+    scopeSysId: string;
+    /** internal_name; defaults to a slug of name. */
+    internalName?: string;
+    /** description on the new flow. */
+    description?: string;
+    /** Patch the trigger's `table` input (e.g. "customer_contact"). */
+    triggerTable?: string;
+    /** Patch the trigger's `condition` input (encoded query). Pass "" to clear. */
+    triggerCondition?: string;
+    /** Patch the action's `message` input (Log message) / short_description data. */
+    logMessage?: string;
+    /**
+     * When true, do everything up to but not including the writes and return the
+     * planned new name / internalName / template-graph counts. No network writes.
+     */
+    dryRun?: boolean;
+}
+export interface CreateFlowResult {
+    status: "published" | "dry-run" | "not-published";
+    /** sys_id of the new flow (empty on dry-run). */
+    sysId: string;
+    name: string;
+    internalName: string;
+    scopeSysId: string;
+    /** sys_id of the compiled snapshot, when published. */
+    snapshotSysId?: string;
+    /** Counts grafted from the template. */
+    graph: {
+        triggers: number;
+        actions: number;
+        logic: number;
+    };
+    /**
+     * Whether the published flow is ACTIVE (will fire on its trigger). Read back
+     * from the snapshot response when it reports it; `undefined` when the response
+     * doesn't carry an active flag (dry-run, or a server payload that omits it).
+     * Don't assume inactive on `undefined` — confirm against the flow record.
+     */
+    active?: boolean;
+    /** HTTP status of the snapshot POST (0 on dry-run). */
+    httpStatus: number;
+}
+/**
+ * Graft the template's graph onto the freshly-created envelope and patch values.
+ * Exported for unit testing the pure transform without any network.
+ */
+export declare function buildPublishModel(envelope: any, template: any, newFlow: string, params: CreateFlowParams): any;
+export declare function createFlow(params: CreateFlowParams): Promise<CreateFlowResult>;

package/dist/flowDesigner/createFlow.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Create a whole Flow Designer FLOW (sys_hub_flow, type=flow) from scratch and
+ * publish it — headless, basic auth. The missing peer of copyFlow / publishFlow:
+ * copyFlow duplicates an existing flow; createFlow mints a NEW flow whose trigger
+ * + action graph is grafted from a template, then compiled.
+ *
+ * === CANONICAL SEQUENCE (reverse-engineered from Workflow Studio HARs, 2026-06-02) ===
+ * The Designer SPA holds the entire flow graph client-side and persists + compiles
+ * it in ONE shot at publish. There are NO incremental add-trigger / add-action REST
+ * calls — only version bookmarks. The proven, validated sequence is:
+ *
+ *   1. CREATE  POST /api/now/processflow/flow?param_only_properties=true&sysparm_transaction_scope={scope}
+ *        body = a small properties envelope. -> 200, result.data = a FULLY INITIALISED
+ *        empty model (server-minted id, internalName, flowCatalogVariableModelId,
+ *        version, authoredOnReleaseVersion). This initialisation is the piece a
+ *        Dovetail createRecord / Table API insert never produces — and without it the
+ *        snapshot POST silently no-ops (flow stays draft, no snapshot).
+ *   2. GRAFT   GET /api/now/processflow/flow/{template}?sysparm_transaction_scope={scope}
+ *        -> result.data carries the template's triggerInstances / actionInstances /
+ *        flowLogicInstances. Build the publish model = the NEW envelope with those arrays
+ *        grafted in, ids remapped (flowSysId -> new id; fresh id + uiUniqueIdentifier),
+ *        and values patched (trigger table/condition, action message inputs).
+ *   3. VERSION POST /api/now/processflow/versioning/create_version?...
+ *        body { item_sys_id: newFlow, type: "Activate/Publish", annotation: "", favorite: false }
+ *   4. PUBLISH POST /api/now/processflow/flow/{newFlow}/snapshot?...  body = the FLAT model
+ *        -> result.data.status="published", isPublished=true, latestSnapshot=<sys_id>.
+ *
+ * Validated live 2026-06-02 on tenonworkstudio (x_cadso_automate): flow
+ * aceb8e683395cb147b18bc534d5c7b5e published with a compiled snapshot
+ * (7ceb02a83395cb147b18bc534d5c7b03), 1 trigger in sys_hub_trigger_instance_v2,
+ * 1 action in sys_hub_action_instance_v2 — zero UI clicks.
+ *
+ * The clone inherits the template's trigger + action SHAPE; author a different
+ * shape by building that flow once in the Designer and pointing templateSysId at it.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPublishModel = buildPublishModel;
+exports.createFlow = createFlow;
+const crypto = __importStar(require("crypto"));
+function newId() {
+    return crypto.randomBytes(16).toString("hex");
+}
+function uuid() {
+    return crypto.randomUUID();
+}
+function slug(s) {
+    // The first replace collapses every run of non-alphanumerics to a single "_",
+    // so consecutive underscores can never occur here — a single-char trim (no "+"
+    // quantifier) is sufficient and avoids the polynomial-backtracking pattern.
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+/** Normalize `{ result: { data } }` / `{ data }` / `{ result }` / bare to the model. */
+function unwrapModel(data) {
+    if (data && typeof data === "object" && data.result && typeof data.result === "object") {
+        if (data.result.data && typeof data.result.data === "object") {
+            return data.result.data;
+        }
+        return data.result;
+    }
+    if (data && typeof data === "object" && data.data && typeof data.data === "object") {
+        return data.data;
+    }
+    return data;
+}
+function flowGetPath(sysId, scopeSysId) {
+    return "/api/now/processflow/flow/" + encodeURIComponent(sysId)
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+function flowCreatePath(scopeSysId) {
+    return "/api/now/processflow/flow?param_only_properties=true"
+        + "&sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+function createVersionPath(scopeSysId) {
+    return "/api/now/processflow/versioning/create_version"
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+function snapshotPath(sysId, scopeSysId) {
+    return "/api/now/processflow/flow/" + encodeURIComponent(sysId) + "/snapshot"
+        + "?sysparm_transaction_scope=" + encodeURIComponent(scopeSysId);
+}
+function patchInputs(inst, kv) {
+    if (!inst || !Array.isArray(inst.inputs))
+        return;
+    for (var i = 0; i < inst.inputs.length; i += 1) {
+        var inp = inst.inputs[i];
+        if (Object.prototype.hasOwnProperty.call(kv, inp.name)) {
+            inp.value = kv[inp.name];
+            if (Object.prototype.hasOwnProperty.call(inp, "displayValue")) {
+                inp.displayValue = kv[inp.name];
+            }
+        }
+    }
+}
+function remapInstances(arr, newFlow) {
+    if (!Array.isArray(arr))
+        return [];
+    return arr.map(function (src) {
+        var inst = JSON.parse(JSON.stringify(src));
+        if (Object.prototype.hasOwnProperty.call(inst, "flowSysId"))
+            inst.flowSysId = newFlow;
+        if (Object.prototype.hasOwnProperty.call(inst, "id"))
+            inst.id = newId();
+        if (Object.prototype.hasOwnProperty.call(inst, "uiUniqueIdentifier"))
+            inst.uiUniqueIdentifier = uuid();
+        return inst;
+    });
+}
+/**
+ * Graft the template's graph onto the freshly-created envelope and patch values.
+ * Exported for unit testing the pure transform without any network.
+ */
+function buildPublishModel(envelope, template, newFlow, params) {
+    var M = JSON.parse(JSON.stringify(envelope));
+    M.id = newFlow;
+    M.status = "draft";
+    M.active = false;
+    M.latestSnapshot = "";
+    M.masterSnapshot = false;
+    M.masterSnapshotId = "";
+    M.isPublished = false;
+    M.snapshot = false;
+    M.jsonSnapshot = false;
+    M.deletedActions = [];
+    M.deletedTriggers = [];
+    M.deletedFlowLogicInstances = [];
+    M.triggerInstances = remapInstances(template.triggerInstances, newFlow);
+    M.actionInstances = remapInstances(template.actionInstances, newFlow);
+    M.flowLogicInstances = remapInstances(template.flowLogicInstances, newFlow);
+    M.subFlowInstances = remapInstances(template.subFlowInstances, newFlow);
+    var ti;
+    for (ti = 0; ti < M.triggerInstances.length; ti += 1) {
+        var kv = {};
+        if (params.triggerTable)
+            kv.table = params.triggerTable;
+        if (params.triggerCondition !== undefined)
+            kv.condition = params.triggerCondition;
+        patchInputs(M.triggerInstances[ti], kv);
+    }
+    var ai;
+    for (ai = 0; ai < M.actionInstances.length; ai += 1) {
+        var act = M.actionInstances[ai];
+        if (params.logMessage) {
+            patchInputs(act, { message: params.logMessage });
+            if (act.data && Object.prototype.hasOwnProperty.call(act.data, "values")) {
+                act.data.values = "short_description=" + params.logMessage;
+            }
+        }
+    }
+    return M;
+}
+function extractSnapshotSysId(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    var snap = body.latestSnapshot || body.masterSnapshot
+        || body.latest_snapshot || body.master_snapshot || body.snapshot;
+    if (snap && typeof snap === "object") {
+        return typeof snap.sys_id === "string" ? snap.sys_id : undefined;
+    }
+    if (typeof snap === "string" && snap.length >= 32)
+        return snap;
+    return undefined;
+}
+async function createFlow(params) {
+    var client = params.client;
+    if (!params.name || params.name.trim().length === 0) {
+        throw new Error("createFlow: name is required.");
+    }
+    if (!params.templateSysId) {
+        throw new Error("createFlow: templateSysId is required (the trigger/action shape is grafted from it).");
+    }
+    if (!params.scopeSysId) {
+        throw new Error("createFlow: scopeSysId is required.");
+    }
+    var internalName = params.internalName || slug(params.name);
+    // 1/2 (read): pull the template graph first — also validates the template exists.
+    var template = unwrapModel(await client.now.get(flowGetPath(params.templateSysId, params.scopeSysId)));
+    if (!template || !Array.isArray(template.triggerInstances) || template.triggerInstances.length === 0) {
+        throw new Error("createFlow: template flow " + params.templateSysId + " has no trigger to graft.");
+    }
+    var graph = {
+        triggers: (template.triggerInstances || []).length,
+        actions: (template.actionInstances || []).length,
+        logic: (template.flowLogicInstances || []).length,
+    };
+    if (params.dryRun) {
+        return {
+            status: "dry-run",
+            sysId: "",
+            name: params.name,
+            internalName: internalName,
+            scopeSysId: params.scopeSysId,
+            graph: graph,
+            httpStatus: 0,
+        };
+    }
+    // 1 (write): create the flow — server mints the initialised envelope.
+    var props = {
+        access: "public",
+        description: params.description || "",
+        flowPriority: "MEDIUM",
+        name: params.name,
+        protection: "",
+        runAs: "system",
+        runWithRoles: { value: "", displayValue: "" },
+        type: "flow",
+        active: false,
+        deleted: false,
+        security: { can_read: true, can_write: true },
+        scope: params.scopeSysId,
+        scopeName: "",
+        scopeDisplayName: "",
+        status: "draft",
+        userHasRolesAssignedToFlow: true,
+    };
+    var createResp = await client.now.post(flowCreatePath(params.scopeSysId), props);
+    var envelope = unwrapModel(createResp);
+    if (!envelope || typeof envelope.id !== "string" || envelope.id.length < 32) {
+        throw new Error("createFlow: create did not return an initialised flow id: "
+            + JSON.stringify(createResp).substring(0, 300));
+    }
+    var newFlow = envelope.id;
+    if (envelope.internalName)
+        internalName = envelope.internalName;
+    // 2: build the publish model.
+    var model = buildPublishModel(envelope, template, newFlow, params);
+    // 3: version bookmark (Activate/Publish). Best-effort — publish is the gate.
+    try {
+        await client.now.post(createVersionPath(params.scopeSysId), {
+            item_sys_id: newFlow,
+            type: "Activate/Publish",
+            annotation: "",
+            favorite: false,
+        });
+    }
+    catch (err) {
+        // non-fatal; the snapshot POST is what compiles.
+    }
+    // 4: publish (compile the snapshot). request() throws on non-2xx.
+    var snapResp = await client.now.post(snapshotPath(newFlow, params.scopeSysId), model);
+    var snapBody = unwrapModel(snapResp);
+    var publishedFlag = snapBody && (snapBody.isPublished === true || snapBody.status === "published");
+    var snapshotSysId = extractSnapshotSysId(snapBody);
+    var active = snapBody && typeof snapBody.active === "boolean" ? snapBody.active : undefined;
+    return {
+        status: publishedFlag || snapshotSysId ? "published" : "not-published",
+        sysId: newFlow,
+        name: params.name,
+        internalName: internalName,
+        scopeSysId: params.scopeSysId,
+        snapshotSysId: snapshotSysId,
+        graph: graph,
+        active: active,
+        httpStatus: 200,
+    };
+}

package/dist/flowDesigner/index.d.ts

@@ -24,6 +24,8 @@ export { publishFlow } from "./publishFlow";
 export type { PublishFlowParams, PublishFlowResult } from "./publishFlow";
 export { copyFlow } from "./copyFlow";
 export type { CopyFlowParams, CopyFlowResult } from "./copyFlow";
+export { createFlow, buildPublishModel } from "./createFlow";
+export type { CreateFlowParams, CreateFlowResult } from "./createFlow";
 export { editFlow } from "./editFlow";
 export type { EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch } from "./editFlow";
 export { testFlow, DEFAULT_RUN_FLOW_PATH } from "./testFlow";

package/dist/flowDesigner/index.js

@@ -6,7 +6,7 @@
  * functions land in Phase 1.C/D.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.SYSTEM_FIELDS_TO_STRIP = exports.assertSysId = exports.applyScope = exports.stripSystemFields = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = void 0;
 var listTemplates_1 = require("./listTemplates");
 Object.defineProperty(exports, "listTemplates", { enumerable: true, get: function () { return listTemplates_1.listTemplates; } });
 var verifyArtifact_1 = require("./verifyArtifact");
@@ -27,6 +27,9 @@ var publishFlow_1 = require("./publishFlow");
 Object.defineProperty(exports, "publishFlow", { enumerable: true, get: function () { return publishFlow_1.publishFlow; } });
 var copyFlow_1 = require("./copyFlow");
 Object.defineProperty(exports, "copyFlow", { enumerable: true, get: function () { return copyFlow_1.copyFlow; } });
+var createFlow_1 = require("./createFlow");
+Object.defineProperty(exports, "createFlow", { enumerable: true, get: function () { return createFlow_1.createFlow; } });
+Object.defineProperty(exports, "buildPublishModel", { enumerable: true, get: function () { return createFlow_1.buildPublishModel; } });
 var editFlow_1 = require("./editFlow");
 Object.defineProperty(exports, "editFlow", { enumerable: true, get: function () { return editFlow_1.editFlow; } });
 var testFlow_1 = require("./testFlow");

package/dist/index.d.ts

@@ -14,6 +14,6 @@ export { setFormLayout } from "./layout/formLayout";
 export { setRelatedLists } from "./layout/relatedLists";
 export { formatLayoutResult, formatCreateViewResult } from "./layout/formatter";
 export { sincPlugin } from "./plugin";
-export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, readFlow, readActionType, publishFlow, copyFlow, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
-export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult } from "./flowDesigner";
+export { listTemplates, verifyArtifact, cloneSubflow, cloneActionType, triggerPublication, publishActionType, readFlow, readActionType, publishFlow, copyFlow, createFlow, buildPublishModel, editFlow, testFlow, DEFAULT_RUN_FLOW_PATH, generateSysId, topoSort, executeWritePlan, WriteOrderError } from "./flowDesigner";
+export type { TemplateRef, ListTemplatesParams, FlowKind, VerifyExpect, VerifyFound, VerifyFailure, VerifyReport, VerifyArtifactParams, CloneSubflowParams, CloneSubflowResult, CloneActionTypeParams, CloneActionTypeResult, TriggerPublicationParams, TriggerPublicationResult, PublishActionTypeParams, PublishActionTypeResult, ReadFlowParams, ReadFlowResult, FlowStep, FlowVariable, ReadActionTypeParams, ReadActionTypeResult, ActionIo, PublishFlowParams, PublishFlowResult, CopyFlowParams, CopyFlowResult, CreateFlowParams, CreateFlowResult, EditFlowParams, EditFlowResult, EditFlowOps, StepInputPatch, TestFlowParams, TestFlowResult, WriteOp, WriteOpResult } from "./flowDesigner";
 export type { ServiceNowClientConfig, ChoiceValue, ChoiceType, AddChoicesParams, AddChoicesResult, ChoiceActionResult, DictionaryRecord, UpdateSetRecord, LayoutAction, LayoutRecordResult, LayoutResult, CreateViewParams, CreateViewResult, FormSectionSpec, SetFormLayoutParams, SetListLayoutParams, SetRelatedListsParams } from "./types";

package/dist/index.js

@@ -6,7 +6,7 @@
  * REST API so every change lands in the target update set and scope.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
+exports.WriteOrderError = exports.executeWritePlan = exports.topoSort = exports.generateSysId = exports.DEFAULT_RUN_FLOW_PATH = exports.testFlow = exports.editFlow = exports.buildPublishModel = exports.createFlow = exports.copyFlow = exports.publishFlow = exports.readActionType = exports.readFlow = exports.publishActionType = exports.triggerPublication = exports.cloneActionType = exports.cloneSubflow = exports.verifyArtifact = exports.listTemplates = exports.sincPlugin = exports.formatCreateViewResult = exports.formatLayoutResult = exports.setRelatedLists = exports.setFormLayout = exports.setListLayout = exports.createView = exports.formatAddChoicesResult = exports.addChoicesToField = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 var choices_1 = require("./choices");
@@ -37,6 +37,8 @@ Object.defineProperty(exports, "readFlow", { enumerable: true, get: function ()
 Object.defineProperty(exports, "readActionType", { enumerable: true, get: function () { return flowDesigner_1.readActionType; } });
 Object.defineProperty(exports, "publishFlow", { enumerable: true, get: function () { return flowDesigner_1.publishFlow; } });
 Object.defineProperty(exports, "copyFlow", { enumerable: true, get: function () { return flowDesigner_1.copyFlow; } });
+Object.defineProperty(exports, "createFlow", { enumerable: true, get: function () { return flowDesigner_1.createFlow; } });
+Object.defineProperty(exports, "buildPublishModel", { enumerable: true, get: function () { return flowDesigner_1.buildPublishModel; } });
 Object.defineProperty(exports, "editFlow", { enumerable: true, get: function () { return flowDesigner_1.editFlow; } });
 Object.defineProperty(exports, "testFlow", { enumerable: true, get: function () { return flowDesigner_1.testFlow; } });
 Object.defineProperty(exports, "DEFAULT_RUN_FLOW_PATH", { enumerable: true, get: function () { return flowDesigner_1.DEFAULT_RUN_FLOW_PATH; } });

package/dist/mcp/registry.d.ts

@@ -9,7 +9,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ServiceNowClient } from "../client";
-export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_test", "flow_edit"];
+export declare var TOOL_NAMES: readonly ["create_view", "set_list_layout", "set_form_layout", "set_related_lists", "add_choices_to_field", "flow_view", "action_view", "flow_publish", "flow_copy", "flow_create", "flow_test", "flow_edit"];
 export type ToolName = typeof TOOL_NAMES[number];
 export interface RegistryDeps {
     /** Optional client injection for tests; defaults to createClient({}). */

package/dist/mcp/registry.js

@@ -21,6 +21,7 @@ const readFlow_1 = require("../flowDesigner/readFlow");
 const readActionType_1 = require("../flowDesigner/readActionType");
 const publishFlow_1 = require("../flowDesigner/publishFlow");
 const copyFlow_1 = require("../flowDesigner/copyFlow");
+const createFlow_1 = require("../flowDesigner/createFlow");
 const editFlow_1 = require("../flowDesigner/editFlow");
 const testFlow_1 = require("../flowDesigner/testFlow");
 const schemas_1 = require("./schemas");
@@ -34,6 +35,7 @@ exports.TOOL_NAMES = [
     "action_view",
     "flow_publish",
     "flow_copy",
+    "flow_create",
     "flow_test",
     "flow_edit"
 ];
@@ -141,6 +143,35 @@ function buildDescriptors(deps = {}) {
                 return (0, copyFlow_1.copyFlow)({ client: client(), sourceSysId: p.sourceSysId, newName: p.newName, scopeSysId: p.scopeSysId });
             }
         },
+        {
+            name: "flow_create",
+            description: "Create a NEW ServiceNow Flow Designer flow (sys_hub_flow, type=flow) from scratch and "
+                + "PUBLISH it, headless. Mints a fresh flow via POST /processflow/flow, grafts the trigger + "
+                + "action graph from an existing published template flow (templateSysId), then compiles the "
+                + "snapshot — leaving a published flow (the result's `active` flag reports whether it will "
+                + "fire). Unlike flow_copy (which duplicates a flow), "
+                + "this creates a new flow you can re-point at a different trigger table / message. "
+                + "name + templateSysId + scopeSysId are required; triggerTable / triggerCondition / "
+                + "logMessage patch the grafted graph; dryRun:true returns the plan + template graph counts "
+                + "without writing. WARNING: a published triggered flow can fire on its trigger — do not graft "
+                + "a production send template you don't intend to fire.",
+            shape: schemas_1.createFlowSchema.shape,
+            handler: async function (args) {
+                var p = schemas_1.createFlowSchema.parse(args);
+                return (0, createFlow_1.createFlow)({
+                    client: client(),
+                    name: p.name,
+                    templateSysId: p.templateSysId,
+                    scopeSysId: p.scopeSysId,
+                    internalName: p.internalName,
+                    description: p.description,
+                    triggerTable: p.triggerTable,
+                    triggerCondition: p.triggerCondition,
+                    logMessage: p.logMessage,
+                    dryRun: p.dryRun
+                });
+            }
+        },
         {
             name: "flow_test",
             description: "Test or run a ServiceNow flow/subflow. mode='validate' (default) is a safe, read-only "

package/dist/mcp/schemas.d.ts

@@ -231,6 +231,37 @@ export declare var copyFlowSchema: z.ZodObject<{
     newName: string;
     scopeSysId?: string | undefined;
 }>;
+export declare var createFlowSchema: z.ZodObject<{
+    name: z.ZodString;
+    templateSysId: z.ZodString;
+    scopeSysId: z.ZodString;
+    internalName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    triggerTable: z.ZodOptional<z.ZodString>;
+    triggerCondition: z.ZodOptional<z.ZodString>;
+    logMessage: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    scopeSysId: string;
+    templateSysId: string;
+    description?: string | undefined;
+    dryRun?: boolean | undefined;
+    internalName?: string | undefined;
+    triggerTable?: string | undefined;
+    triggerCondition?: string | undefined;
+    logMessage?: string | undefined;
+}, {
+    name: string;
+    scopeSysId: string;
+    templateSysId: string;
+    description?: string | undefined;
+    dryRun?: boolean | undefined;
+    internalName?: string | undefined;
+    triggerTable?: string | undefined;
+    triggerCondition?: string | undefined;
+    logMessage?: string | undefined;
+}>;
 export declare var testFlowSchema: z.ZodObject<{
     sysId: z.ZodString;
     mode: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"validate">, z.ZodLiteral<"execute">]>>;

package/dist/mcp/schemas.js

@@ -4,7 +4,7 @@
  * own file so registry.ts stays focused on wiring.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
+exports.editFlowSchema = exports.stepInputPatchSchema = exports.testFlowSchema = exports.createFlowSchema = exports.copyFlowSchema = exports.publishFlowSchema = exports.viewActionSchema = exports.viewFlowSchema = exports.addChoicesToFieldSchema = exports.choiceValueSchema = exports.setRelatedListsSchema = exports.setFormLayoutSchema = exports.formSectionSchema = exports.setListLayoutSchema = exports.createViewSchema = void 0;
 const zod_1 = require("zod");
 exports.createViewSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
@@ -76,6 +76,17 @@ exports.copyFlowSchema = zod_1.z.object({
     newName: zod_1.z.string().min(1),
     scopeSysId: zod_1.z.string().optional()
 });
+exports.createFlowSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    templateSysId: zod_1.z.string().min(1),
+    scopeSysId: zod_1.z.string().min(1),
+    internalName: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    triggerTable: zod_1.z.string().optional(),
+    triggerCondition: zod_1.z.string().optional(),
+    logMessage: zod_1.z.string().optional(),
+    dryRun: zod_1.z.boolean().optional()
+});
 exports.testFlowSchema = zod_1.z.object({
     sysId: zod_1.z.string().min(1),
     mode: zod_1.z.union([zod_1.z.literal("validate"), zod_1.z.literal("execute")]).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-servicenow",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "engines": {
     "node": ">=22"
   },