isc-transforms-mcp 1.0.13 → 1.0.15

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "sailpoint.isc.transforms.identityAttribute.schema.json",
   "title": "SailPoint ISC Transform Schema - identityAttribute",
-  "description": "Strict schema derived from SailPoint official Identity Attribute operation documentation. Retrieves the value of a user's identity attribute by its system (camel-cased) name.",
+  "description": "Strict schema for the SailPoint ISC identityAttribute transform. Retrieves the value of an identity attribute by its camelCase system name. IMPORTANT LIMITATION: This transform is NOT intended for use within another identity profile attribute's calculation. Due to multi-threaded identity processing, the referenced attribute may not yet exist or may hold stale data at evaluation time. Intended use cases are provisioning policies and entitlement request forms. For identity profile attribute mappings that need source account data, use accountAttribute instead.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,16 +12,18 @@
   ],
   "properties": {
     "type": {
-      "const": "identityAttribute"
+      "const": "identityAttribute",
+      "description": "Transform operation type. Must be exactly 'identityAttribute'."
     },
     "name": {
       "type": "string",
-      "minLength": 1
+      "minLength": 1,
+      "description": "Display name for this transform, shown in UI dropdowns and provisioning policy mappings."
     },
     "requiresPeriodicRefresh": {
       "type": "boolean",
       "default": false,
-      "description": "Whether the transform logic should be reevaluated every evening as part of identity refresh. Default false."
+      "description": "If true, re-evaluates this transform during the nightly identity refresh cycle. Default is false."
     },
     "attributes": {
       "type": "object",
@@ -29,15 +31,20 @@
       "required": [
         "name"
       ],
+      "description": "Required container for identityAttribute operation attributes.",
       "properties": {
         "name": {
           "type": "string",
           "minLength": 1,
-          "description": "System (camel-cased) name of the identity attribute to retrieve (e.g., 'email', 'uid')."
+          "description": "The camelCase system name of the identity attribute to retrieve. This is the internal attribute name, not the display label. Examples: 'uid' (SailPoint User Name), 'email', 'identificationNumber' (Employee Number), 'manager', 'department', 'displayName'. Find the system name in Admin UI → Identity Profiles → Identity Attributes."
         },
         "input": {
-          "description": "Optional explicit input data. If omitted, the transform uses input from the source+attribute combination configured in the UI. Modeled as a nested transform object.",
-          "oneOf": [
+          "description": "Optional explicit input data for this transform. If omitted, the transform uses the source and attribute combination configured in the identity profile UI. When provided, must be a nested transform object or a static string value.",
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "Static string input value."
+            },
             {
               "$ref": "#/$defs/NestedTransform"
             }
@@ -49,7 +56,7 @@
   "$defs": {
     "NestedTransform": {
       "type": "object",
-      "description": "Nested transform object used as explicit input (name optional in docs).",
+      "description": "A nested transform object used as explicit input to this transform. Provides the input data that feeds the identityAttribute lookup. The 'name' field is optional in nested transforms per SailPoint docs.",
       "additionalProperties": false,
       "required": [
         "type",
@@ -57,18 +64,22 @@
       ],
       "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', 'static')."
         },
         "requiresPeriodicRefresh": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether this nested transform re-evaluates during nightly refresh."
         },
         "attributes": {
           "type": "object",
@@ -80,25 +91,39 @@
   },
   "examples": [
     {
-      "attributes": {
-        "name": "email"
-      },
+      "name": "Get SailPoint User Name",
       "type": "identityAttribute",
-      "name": "Identity Attribute Transform"
-    },
-    {
       "attributes": {
         "name": "uid"
-      },
-      "type": "identityAttribute",
-      "name": "Identity Attribute Transform"
+      }
     },
     {
+      "name": "Get Employee Number",
+      "type": "identityAttribute",
       "attributes": {
         "name": "identificationNumber"
-      },
+      }
+    },
+    {
+      "name": "Get Manager",
       "type": "identityAttribute",
-      "name": "Identity Attribute Transform"
+      "attributes": {
+        "name": "manager"
+      }
+    },
+    {
+      "name": "Get Email with Explicit Input",
+      "type": "identityAttribute",
+      "attributes": {
+        "name": "email",
+        "input": {
+          "type": "accountAttribute",
+          "attributes": {
+            "sourceName": "HR Source",
+            "attributeName": "workEmail"
+          }
+        }
+      }
     }
   ]
 }

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,20 +1021,92 @@ 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}`);
+            }
+        }
+    }
+    return msgs;
+}
+// ---------------------------------------------------------------------------
+// 25. identityAttribute — name format + critical use-case limitation
+// Docs: https://developer.sailpoint.com/docs/extensibility/transforms/operations/identity-attribute
+// ---------------------------------------------------------------------------
+function lintIdentityAttribute(attrs) {
+    const msgs = [];
+    // 1. name: must be a camelCase system name — no spaces, ideally no hyphens
+    const name = attrs?.name;
+    if (typeof name === "string" && name.trim().length > 0) {
+        if (/\s/.test(name)) {
+            push(msgs, "error", `attributes.name '${name}' contains whitespace. Identity attribute system names are camelCase with no spaces ` +
+                "(e.g., 'uid', 'email', 'identificationNumber'). Check the identity profile attribute's system name in the Admin UI.", "attributes.name");
+        }
+        else if (/-/.test(name)) {
+            push(msgs, "warn", `attributes.name '${name}' contains a hyphen. Identity attribute system names are camelCase ` +
+                "(e.g., 'identificationNumber', not 'identification-number'). Verify this is the exact system name shown in the Admin UI.", "attributes.name");
+        }
+    }
+    // 2. Critical use-case limitation — identityAttribute is NOT safe inside identity profile attribute calculations
+    push(msgs, "warn", "identityAttribute is NOT intended for use within another identity profile attribute's calculation. " +
+        "Due to multi-threaded identity processing, the referenced attribute may not yet exist or may hold stale data at evaluation time. " +
+        "Intended use: provisioning policies and entitlement request forms. " +
+        "If you need an account attribute value inside an identity profile mapping, use accountAttribute instead.", "type");
+    // 3. input: must be a nested transform object if provided
+    if (attrs?.input !== undefined) {
+        const inp = attrs.input;
+        if (!(isPlainObject(inp) && typeof inp.type === "string")) {
+            push(msgs, "warn", "input must be a nested transform object {type, attributes} providing explicit input data. " +
+                "If omitted, the transform uses the source+attribute combination configured in the identity profile UI.", "attributes.input");
+        }
     }
-    // Any other keys in attributes are valid dynamic VTL variable definitions — no unknown-attribute errors.
     return msgs;
 }
 // ---------------------------------------------------------------------------
-// 25. indexOf / lastIndexOf
+// 27. indexOf / lastIndexOf
 // ---------------------------------------------------------------------------
 function lintIndexOf(t, attrs) {
     const msgs = [];
@@ -1047,7 +1119,7 @@ function lintIndexOf(t, attrs) {
     return msgs;
 }
 // ---------------------------------------------------------------------------
-// 26. randomAlphaNumeric / randomNumeric — length
+// 28. randomAlphaNumeric / randomNumeric — length
 // ---------------------------------------------------------------------------
 function lintRandom(t, attrs) {
     const msgs = [];
@@ -1063,7 +1135,7 @@ function lintRandom(t, attrs) {
     return msgs;
 }
 // ---------------------------------------------------------------------------
-// 27. rfc5646 — format type check
+// 29. rfc5646 — format type check
 // ---------------------------------------------------------------------------
 function lintRfc5646(attrs) {
     const msgs = [];
@@ -1155,6 +1227,8 @@ export function lintTransform(input) {
         messages.push(...lintSubstring(attrs));
     if (requestedType === "static")
         messages.push(...lintStatic(attrs));
+    if (requestedType === "identityAttribute")
+        messages.push(...lintIdentityAttribute(attrs));
     if (requestedType === "indexOf" || requestedType === "lastIndexOf")
         messages.push(...lintIndexOf(requestedType, attrs));
     if (requestedType === "randomAlphaNumeric" || requestedType === "randomNumeric")

package/package.json

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