isc-transforms-mcp 1.0.13 → 1.0.14

package/JSONS/sailpoint.isc.transforms.static.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "sailpoint.isc.transforms.static.schema.json",
   "title": "SailPoint ISC Transform Schema - static",
-  "description": "Strict schema derived from SailPoint official Static operation documentation. Returns a fixed string value. Docs also allow Velocity Template Language (VTL) in the value, and allow dynamic variables in attributes to be referenced within the VTL.",
+  "description": "Strict schema for the SailPoint ISC Static transform. Returns a fixed string value or evaluates a Velocity Template Language (VTL) expression. The 'value' attribute holds either a literal string (e.g. 'Contractor') or a VTL template (e.g. \"#if($workerType=='Employee')Full-Time#{else}Contingent#end\"). Additional sibling keys in the attributes object are dynamic VTL variables — each can be a static string or a nested transform whose output feeds the VTL expression. IMPORTANT: Attribute ordering matters — all dynamic variable attributes must be evaluated before the value expression runs. Reference variables using $varName or ${varName} (formal reference) or $!varName / $!{varName} (quiet reference, suppresses null output).",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,34 +12,37 @@
   ],
   "properties": {
     "type": {
-      "const": "static"
+      "const": "static",
+      "description": "Transform operation type. Must be exactly 'static'."
     },
     "name": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Display name for this transform, shown in UI dropdowns and identity profile mappings."
     },
     "requiresPeriodicRefresh": {
       "type": "boolean",
       "default": false,
-      "description": "Whether the transform should be reevaluated nightly as part of identity refresh. Default false."
+      "description": "If true, re-evaluates this transform during the nightly identity refresh cycle. Set to true if the VTL expression uses dynamic variables that may change over time. Default is false."
     },
     "attributes": {
       "type": "object",
-      "description": "Static value plus optional dynamic variables (per docs).",
+      "description": "Required container. Must include 'value' (the fixed string or VTL expression). Any additional keys are dynamic VTL variables — each key name maps to a static string or a nested transform. Use $keyName or ${keyName} in value to reference them. Attribute ordering in the identity profile matters: all variable attributes must be placed before the static transform.",
       "required": [
         "value"
       ],
       "properties": {
         "value": {
           "type": "string",
-          "description": "Static string value or Velocity template."
+          "description": "The output of this transform. Either a fixed string literal (e.g. 'Contractor') or a VTL expression referencing dynamic variables defined as sibling keys in attributes (e.g. \"#if($workerType=='Employee')Full-Time#{else}Contingent#end\" or \"$first.$last@example.com\"). Supports: $varName (simple), ${varName} (formal), $!varName (quiet — outputs empty string if null), $!{varName} (quiet formal). VTL conditionals: #if($var=='value')result#{else}alternative#end."
         }
       },
       "additionalProperties": {
-        "description": "Dynamic variables referenced in Velocity template. Can be string literals or nested transforms.",
+        "description": "Dynamic VTL variable. The key becomes the variable name referenced as $keyName in value. The value can be a static string (e.g. 'HR') or a nested transform object (e.g. accountAttribute, identityAttribute) whose output feeds the VTL expression.",
         "anyOf": [
           {
-            "type": "string"
+            "type": "string",
+            "description": "Static string value for this VTL variable."
           },
           {
             "$ref": "#/$defs/NestedTransform"
@@ -51,50 +54,52 @@
   "$defs": {
     "NestedTransform": {
       "type": "object",
-      "description": "Nested transform object used as a dynamic variable. Docs examples often omit 'name'.",
+      "description": "A nested transform object used as a dynamic VTL variable value. The output of this nested transform is substituted for the variable reference in value. Common types: accountAttribute, identityAttribute, getReferenceIdentityAttribute. The 'name' field is optional in nested transforms per SailPoint docs.",
       "additionalProperties": false,
       "required": [
-        "type"
+        "type",
+        "attributes"
       ],
       "properties": {
         "id": {
-          "type": "string"
+          "type": "string",
+          "description": "Optional ID when referencing an existing saved transform."
         },
         "name": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Optional display name for the nested transform."
         },
         "type": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "The operation type of the nested transform (e.g., 'accountAttribute', 'identityAttribute', 'getReferenceIdentityAttribute')."
         },
         "requiresPeriodicRefresh": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this nested transform re-evaluates during nightly refresh."
         },
         "attributes": {
-          "type": [
-            "object",
-            "null"
-          ],
+          "type": "object",
           "additionalProperties": true,
-          "description": "Operation-specific attributes for the nested transform (may be omitted for operations without attributes)."
+          "description": "Operation-specific attributes for the nested transform."
         }
       }
     }
   },
   "examples": [
     {
+      "name": "Fixed String",
       "type": "static",
-      "name": "Static Transform",
       "attributes": {
         "value": "Contractor"
       }
     },
     {
+      "name": "Email From Identity Attributes",
       "type": "static",
-      "name": "Static Transform (Template)",
       "attributes": {
-        "value": "${first}.${last}@example.com",
+        "value": "$first.$last@example.com",
         "first": {
           "type": "identityAttribute",
           "attributes": {
@@ -108,6 +113,36 @@
           }
         }
       }
+    },
+    {
+      "name": "Worker Type Conditional",
+      "type": "static",
+      "attributes": {
+        "value": "#if($workerType=='Employee')Full-Time#{else}Contingent#end",
+        "workerType": {
+          "type": "accountAttribute",
+          "attributes": {
+            "sourceName": "HR Source",
+            "attributeName": "workerType"
+          }
+        }
+      }
+    },
+    {
+      "name": "Manager Email Quiet Reference",
+      "type": "static",
+      "attributes": {
+        "value": "$!{managerEmail}",
+        "managerEmail": {
+          "type": "getReferenceIdentityAttribute",
+          "attributes": {
+            "name": "Cloud Services Deployment Utility",
+            "operation": "getReferenceIdentityAttribute",
+            "uid": "manager",
+            "attributeName": "email"
+          }
+        }
+      }
     }
   ]
 }

package/dist/transforms/lint.js

@@ -1021,16 +1021,55 @@ function lintSubstring(attrs) {
     return msgs;
 }
 // ---------------------------------------------------------------------------
-// 24. static — value must be a string
+// 24. static — value (fixed string or VTL), dynamic VTL variable cross-check
+// Docs: https://developer.sailpoint.com/docs/extensibility/transforms/operations/static
 // ---------------------------------------------------------------------------
 function lintStatic(attrs) {
     const msgs = [];
-    // Presence check is handled by checkRequired (spec.requiredAttributes).
-    // Here we only validate the type when value is present.
+    // 1. value type check — must be a string (fixed literal or VTL expression)
     if (attrs?.value !== undefined && attrs?.value !== null && typeof attrs.value !== "string") {
-        push(msgs, "error", "value must be a string.", "attributes.value");
+        push(msgs, "error", "value must be a string — either a fixed literal (e.g. 'Contractor') or a VTL expression " +
+            "(e.g. \"#if($workerType=='Employee')Full-Time#{else}Contingent#end\").", "attributes.value");
+        return msgs; // cannot do VTL analysis without a string value
+    }
+    const value = attrs?.value;
+    // 2. Empty value warning
+    if (typeof value === "string" && value.trim() === "") {
+        push(msgs, "warn", "value is an empty string — this will produce an empty (null-equivalent) attribute. " +
+            "Provide a non-empty fixed string or VTL expression.", "attributes.value");
+    }
+    if (typeof value === "string" && value.length > 0) {
+        // 3. Extract VTL variable references ($varName, ${varName}, $!varName, $!{varName})
+        const vtlRefs = new Set();
+        const refPattern = /\$!?\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g;
+        let m;
+        while ((m = refPattern.exec(value)) !== null) {
+            vtlRefs.add(m[1]);
+        }
+        if (vtlRefs.size > 0) {
+            // 4. Warn for each VTL reference that has no matching dynamic variable in attributes
+            for (const varName of vtlRefs) {
+                if (!Object.prototype.hasOwnProperty.call(attrs, varName)) {
+                    push(msgs, "warn", `VTL references $${varName} in value but no dynamic variable '${varName}' is defined in attributes. ` +
+                        `Add a '${varName}' key to attributes with a static string or nested transform that supplies the value.`, `attributes.${varName}`);
+                }
+            }
+            // 5. Ordering hint — VTL variables must be positioned before the value attribute in the identity profile
+            push(msgs, "info", "VTL variables detected in value. Attribute ordering matters in identity profiles: " +
+                "all dynamic variable attributes must be mapped and evaluated before the static transform's value expression runs. " +
+                "Review the attribute mapping order in your identity profile.", "attributes.value");
+        }
+        // 6. Warn for dynamic variables defined in attributes but never referenced in value (likely a typo or leftover)
+        const reservedKeys = new Set(["value"]);
+        for (const key of Object.keys(attrs ?? {})) {
+            if (reservedKeys.has(key))
+                continue;
+            if (!vtlRefs.has(key)) {
+                push(msgs, "warn", `Dynamic variable '${key}' is defined in attributes but not referenced as $${key} in value. ` +
+                    `If intentional, remove it to keep the transform clean; otherwise check for a typo.`, `attributes.${key}`);
+            }
+        }
     }
-    // Any other keys in attributes are valid dynamic VTL variable definitions — no unknown-attribute errors.
     return msgs;
 }
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isc-transforms-mcp",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "type": "module",
   "description": "MCP server for SailPoint Identity Security Cloud (ISC) Transform authoring — scaffold, strict lint, catalog, and safe upsert to live tenants.",
   "author": {