snow-flow 10.0.197 → 10.0.199

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "10.0.197",
+  "version": "10.0.199",
   "name": "snow-flow",
   "description": "Snow-Flow - ServiceNow Multi-Agent Development Framework powered by AI",
   "license": "Elastic-2.0",

package/src/servicenow/servicenow-mcp-unified/tools/catalog/snow_order_catalog_item.ts

@@ -1,25 +1,37 @@
 /**
  * snow_order_catalog_item - Order catalog item
  *
- * Orders a catalog item programmatically, creating a request (RITM) with specified variable values.
+ * Orders a catalog item programmatically, creating a request (RITM) with
+ * specified variable values.
+ *
+ * Operation order (avoids race condition with flows):
+ *   1. Fetch variable definitions (item_option_new)
+ *   2. Create sc_request
+ *   3. Pre-create sc_item_option records in parallel (no RITM needed yet)
+ *   4. Short delay to ensure DB commit
+ *   5. Create sc_req_item (RITM) — flow triggers here with variables ready
+ *   6. Create sc_item_option_mtom links in parallel
+ *   7. Two PATCHs to trigger Business Rules that associate the flow context
+ *
+ * Based on contribution by @frodoyoraul (PR #83).
  */
 
 import { MCPToolDefinition, ServiceNowContext, ToolResult } from "../../shared/types.js"
 import { getAuthenticatedClient } from "../../shared/auth.js"
 import { createSuccessResult, createErrorResult } from "../../shared/error-handler.js"
 
+// Delay between sc_item_option creation and RITM insert to ensure DB commit
+const VARIABLE_COMMIT_DELAY_MS = 1000
+
 export const toolDefinition: MCPToolDefinition = {
   name: "snow_order_catalog_item",
   description: "Orders a catalog item programmatically, creating a request (RITM) with specified variable values.",
-  // Metadata for tool discovery (not sent to LLM)
   category: "itsm",
   subcategory: "service-catalog",
   use_cases: ["ordering", "automation", "ritm"],
   complexity: "intermediate",
   frequency: "high",
 
-  // Permission enforcement
-  // Classification: WRITE - Write operation based on name pattern
   permission: "write",
   allowedRoles: ["developer", "admin"],
   inputSchema: {
@@ -36,46 +48,89 @@ export const toolDefinition: MCPToolDefinition = {
   },
 }
 
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
 export async function execute(args: any, context: ServiceNowContext): Promise<ToolResult> {
   const { cat_item, requested_for, variables, quantity = 1, delivery_address, special_instructions } = args
 
   try {
     const client = await getAuthenticatedClient(context)
 
-    // Create service catalog request
+    // 1. Fetch variable definitions before creating the RITM
+    const varDefsResponse = await client.get("/api/now/table/item_option_new", {
+      params: {
+        sysparm_query: "cat_item=" + cat_item,
+        sysparm_fields: "sys_id,name",
+        sysparm_limit: 100,
+      },
+    })
+    const varDefs = varDefsResponse.data.result || []
+    const varMap = new Map<string, string>()
+    varDefs.forEach((def: any) => {
+      if (def.name) varMap.set(def.name, def.sys_id)
+    })
+
+    // 2. Create sc_request
     const requestData: any = {
       requested_for,
       opened_by: requested_for,
     }
-
     if (special_instructions) requestData.special_instructions = special_instructions
 
     const requestResponse = await client.post("/api/now/table/sc_request", requestData)
     const requestId = requestResponse.data.result.sys_id
 
-    // Create requested item (RITM)
+    // 3. Pre-create sc_item_option records in parallel (no RITM needed yet)
+    const varEntries = variables ? Object.entries(variables).filter(([name]) => varMap.has(name)) : []
+    const skippedVars = variables ? Object.keys(variables).filter((name) => !varMap.has(name)) : []
+
+    const optionSysIds: Array<{ optionSysId: string }> = await Promise.all(
+      varEntries.map(async ([varName, varValue]) => {
+        const defSysId = varMap.get(varName)!
+        const optResp = await client.post("/api/now/table/sc_item_option", {
+          item_option_new: defSysId,
+          value: varValue,
+        })
+        return { optionSysId: optResp.data.result.sys_id }
+      }),
+    )
+
+    // 4. Wait for sc_item_option records to be committed in DB
+    if (optionSysIds.length > 0) {
+      await sleep(VARIABLE_COMMIT_DELAY_MS)
+    }
+
+    // 5. Create sc_req_item (RITM) — flow triggers here with variables already ready
     const ritmData: any = {
       request: requestId,
       cat_item,
       requested_for,
       quantity,
     }
-
     if (delivery_address) ritmData.delivery_address = delivery_address
 
     const ritmResponse = await client.post("/api/now/table/sc_req_item", ritmData)
     const ritmId = ritmResponse.data.result.sys_id
     const ritmNumber = ritmResponse.data.result.number
 
-    // Set variable values if provided
-    if (variables) {
-      for (const [varName, varValue] of Object.entries(variables)) {
-        await client.post("/api/now/table/sc_item_option_mtom", {
+    // 6. Create sc_item_option_mtom links in parallel
+    await Promise.all(
+      optionSysIds.map(({ optionSysId }) =>
+        client.post("/api/now/table/sc_item_option_mtom", {
           request_item: ritmId,
-          name: varName,
-          value: varValue,
-        })
-      }
+          sc_item_option: optionSysId,
+        }),
+      ),
+    )
+
+    // 7. Two PATCHs to trigger Business Rules that associate the flow context.
+    //    sys_mod_count is auto-incremented by ServiceNow (the value we send is
+    //    ignored), but the PATCH itself is a real update that fires BR triggers.
+    //    Two updates are needed: the first associates the flow, the second
+    //    ensures the flow context is fully propagated.
+    if (optionSysIds.length > 0) {
+      await client.patch("/api/now/table/sc_req_item/" + ritmId, { sys_mod_count: "1" })
+      await client.patch("/api/now/table/sc_req_item/" + ritmId, { sys_mod_count: "1" })
     }
 
     return createSuccessResult(
@@ -85,6 +140,8 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
         ritm_id: ritmId,
         ritm_number: ritmNumber,
         quantity,
+        variables_processed: varEntries.length,
+        variables_skipped: skippedVars.length > 0 ? skippedVars : undefined,
       },
       {
         operation: "order_catalog_item",
@@ -97,5 +154,5 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
   }
 }
 
-export const version = "1.0.0"
-export const author = "Snow-Flow SDK Migration"
+export const version = "2.0.0"
+export const author = "Snow-Flow"

package/src/servicenow/servicenow-mcp-unified/tools/platform/snow_create_ui_policy.ts

@@ -8,6 +8,7 @@
 import { MCPToolDefinition, ServiceNowContext, ToolResult } from "../../shared/types.js"
 import { getAuthenticatedClient } from "../../shared/auth.js"
 import { createSuccessResult, createErrorResult } from "../../shared/error-handler.js"
+import { linkUiPolicyReference, verifyUiPolicyLink } from "../ui-policies/link-ui-policy.js"
 
 /**
  * Extract sys_id from API response - handles both string and object formats
@@ -129,6 +130,7 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
 
     // Create UI Policy Actions
     const createdActions = []
+    const unlinkableActions: string[] = []
     for (const action of actions) {
       const actionData: any = {
         ui_policy: policySysId,
@@ -140,10 +142,20 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
       }
 
       const actionResponse = await client.post("/api/now/table/sys_ui_policy_action", actionData)
-      createdActions.push(actionResponse.data.result)
+      const actionResult = actionResponse.data.result
+      const actionSysId = extractSysId(actionResult.sys_id)
+
+      // Verify ui_policy link; if POST didn't set it, use fallback chain
+      const alreadyLinked = await verifyUiPolicyLink(client, actionSysId, policySysId)
+      if (!alreadyLinked) {
+        const linked = await linkUiPolicyReference(client, actionSysId, policySysId)
+        if (!linked) unlinkableActions.push(action.field_name)
+      }
+
+      createdActions.push(actionResult)
     }
 
-    return createSuccessResult({
+    const result: Record<string, any> = {
       created: true,
       ui_policy: {
         sys_id: policySysId,
@@ -161,7 +173,7 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
         mandatory: action.mandatory === "true",
         readonly: action.readonly === "true",
         cleared: action.cleared === "true",
-        ui_policy_reference: policySysId,
+        ui_policy_linked: !unlinkableActions.includes(action.field),
       })),
       total_actions: createdActions.length,
       best_practices: [
@@ -171,7 +183,16 @@ export async function execute(args: any, context: ServiceNowContext): Promise<To
         "Order matters when multiple policies affect same field",
         "Test with different user roles and data",
       ],
-    })
+    }
+
+    if (unlinkableActions.length > 0) {
+      result.warning =
+        "Some actions could not be linked to the UI policy: " +
+        unlinkableActions.join(", ") +
+        ". Link them manually in the ServiceNow UI."
+    }
+
+    return createSuccessResult(result)
   } catch (error: any) {
     return createErrorResult(error.message)
   }

package/src/servicenow/servicenow-mcp-unified/tools/ui-policies/link-ui-policy.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared helper to link a sys_ui_policy_action record to its parent UI policy.
+ *
+ * ServiceNow's REST Table API POST silently ignores the "ui_policy" reference
+ * field on sys_ui_policy_action during creation. This module provides a
+ * cascading fallback (PATCH → PUT → GlideRecord) to set the reference after
+ * the record has been created.
+ */
+
+import type { AxiosInstance } from "axios"
+
+/**
+ * Verify that the ui_policy reference field is set on a sys_ui_policy_action record.
+ */
+export async function verifyUiPolicyLink(
+  client: AxiosInstance,
+  actionSysId: string,
+  expectedSysId: string,
+): Promise<boolean> {
+  try {
+    const res = await client.get(
+      "/api/now/table/sys_ui_policy_action/" + actionSysId + "?sysparm_fields=ui_policy",
+    )
+    const ref = res.data.result?.ui_policy
+    const val = typeof ref === "object" && ref !== null ? ref.value : ref
+    return !!val && val !== "" && val === expectedSysId
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Attempt to link a sys_ui_policy_action record to its parent UI policy using
+ * a cascading fallback chain:
+ *   Tier 1 — PATCH (standard Table API update)
+ *   Tier 2 — PUT   (full record update)
+ *   Tier 3 — GlideRecord via Scripted REST endpoint (last resort)
+ *
+ * Returns true if the link was successfully set and verified.
+ */
+export async function linkUiPolicyReference(
+  client: AxiosInstance,
+  actionSysId: string,
+  uiPolicySysId: string,
+): Promise<boolean> {
+  const url = "/api/now/table/sys_ui_policy_action/" + actionSysId
+  const body = { ui_policy: uiPolicySysId }
+
+  // Tier 1: PATCH
+  try {
+    await client.patch(url, body)
+    if (await verifyUiPolicyLink(client, actionSysId, uiPolicySysId)) return true
+  } catch {
+    // fall through
+  }
+
+  // Tier 2: PUT
+  try {
+    await client.put(url, body)
+    if (await verifyUiPolicyLink(client, actionSysId, uiPolicySysId)) return true
+  } catch {
+    // fall through
+  }
+
+  // Tier 3: GlideRecord via Scripted REST endpoint
+  try {
+    const script =
+      "var gr = new GlideRecord('sys_ui_policy_action');\n" +
+      "gr.get('" + actionSysId + "');\n" +
+      "gr.setValue('ui_policy', '" + uiPolicySysId + "');\n" +
+      "gr.update();\n" +
+      "gs.print(gr.getValue('ui_policy'));"
+
+    await client.post("/api/snow_flow_exec/execute", {
+      script,
+      execution_id: "link_ui_policy_" + actionSysId,
+    })
+    if (await verifyUiPolicyLink(client, actionSysId, uiPolicySysId)) return true
+  } catch {
+    // all tiers exhausted
+  }
+
+  return false
+}

package/src/servicenow/servicenow-mcp-unified/tools/ui-policies/snow_create_ui_policy_action.ts

@@ -10,18 +10,15 @@
  *   - "disabled" is the actual column name for "Read only" in the UI
  *   - "table" is auto-derived from the parent UI policy but must be sent for field validation
  *
- * Platform limitation:
- *   The "ui_policy" reference field on sys_ui_policy_action cannot be set via
- *   the REST Table API (POST/PUT/PATCH all silently ignore it). This is a known
- *   ServiceNow platform restriction for parent-child reference fields.
- *   Workaround: after Table API creation, a direct XML POST is attempted to set
- *   the ui_policy reference. If the XML POST also fails, the action is created
- *   without the reference — it can be linked manually in the UI.
+ * The "ui_policy" reference field is set via POST during creation. If the
+ * platform silently ignores it, a cascading fallback (PATCH → PUT → GlideRecord)
+ * ensures the link is established.
  */
 
 import type { MCPToolDefinition, ServiceNowContext, ToolResult } from "../../shared/types.js"
 import { getAuthenticatedClient } from "../../shared/auth.js"
 import { createSuccessResult, createErrorResult } from "../../shared/error-handler.js"
+import { linkUiPolicyReference, verifyUiPolicyLink } from "./link-ui-policy.js"
 
 export const toolDefinition: MCPToolDefinition = {
   name: "snow_create_ui_policy_action",
@@ -113,24 +110,9 @@ export async function execute(args: Record<string, unknown>, context: ServiceNow
     const action = response.data.result
     const actionSysId = action.sys_id?.value || action.sys_id
 
-    const linked = await (async () => {
-      try {
-        const xmlBody =
-          "<record>" + "<sys_id>" + actionSysId + "</sys_id>" + "<ui_policy>" + uid + "</ui_policy>" + "</record>"
-        await client.post("/sys_ui_policy_action.do?XML&sys_id=" + actionSysId, xmlBody, {
-          headers: { "Content-Type": "application/xml" },
-        })
-
-        const verify = await client.get(
-          "/api/now/table/sys_ui_policy_action/" + actionSysId + "?sysparm_fields=ui_policy",
-        )
-        const ref = verify.data.result?.ui_policy
-        const val = typeof ref === "object" && ref !== null ? ref.value : ref
-        return !!val && val !== ""
-      } catch (_e) {
-        return false
-      }
-    })()
+    // Check if the POST already set the reference; if not, use the fallback chain
+    const alreadyLinked = await verifyUiPolicyLink(client, actionSysId, uid)
+    const linked = alreadyLinked || (await linkUiPolicyReference(client, actionSysId, uid))
 
     const refVal = action.ui_policy
     const resolvedRef = typeof refVal === "object" && refVal !== null ? refVal.value : refVal