isc-transforms-mcp 1.0.6 → 1.0.8

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "sailpoint.isc.transforms.accountAttribute.schema.json",
   "title": "SailPoint ISC Transform Schema - accountAttribute",
-  "description": "Strict schema derived from the SailPoint official Account Attribute operation documentation.",
+  "description": "Strict schema derived from the SailPoint official Account Attribute operation documentation. Retrieves a specific attribute value from an account associated with a source on an identity.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -12,15 +12,18 @@
   ],
   "properties": {
     "type": {
-      "const": "accountAttribute"
+      "const": "accountAttribute",
+      "description": "Transform operation type. Must be exactly 'accountAttribute'."
     },
     "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
+      "default": false,
+      "description": "If true, re-evaluates this transform during the nightly identity refresh cycle. Set to true when the source account data changes frequently. Default is false."
     },
     "attributes": {
       "type": "object",
@@ -32,113 +35,95 @@
         "sourceName": {
           "type": "string",
           "minLength": 1,
-          "description": "Source display name to search (e.g., 'Active Directory'). If the display name changes, this reference must be updated."
+          "description": "Source display name to search (e.g., 'Active Directory'). WARNING: references the mutable display name — if the source is renamed, this value must be updated. For stability, prefer applicationName. Mutually exclusive with applicationId and applicationName."
         },
         "applicationId": {
           "type": "string",
           "minLength": 1,
-          "description": "Alternative to sourceName: source external GUID."
+          "description": "External GUID of the source. Stable alternative to sourceName that does not break if the source is renamed. Mutually exclusive with sourceName and applicationName."
         },
         "applicationName": {
           "type": "string",
           "minLength": 1,
-          "description": "Alternative to sourceName: source immutable name."
+          "description": "Immutable internal source name. Most stable source reference — does not change when the source display name changes. Mutually exclusive with sourceName and applicationId."
         },
         "attributeName": {
           "type": "string",
           "minLength": 1,
-          "description": "Account attribute to return (must match the account attribute name visible in the UI or source schema)."
+          "description": "Name of the account attribute to retrieve. Must exactly match the attribute name visible in the source schema / account attribute list in the ISC UI."
         },
         "accountSortAttribute": {
           "type": "string",
           "minLength": 1,
           "default": "created",
-          "description": "Attribute name to sort returned accounts by when multiple accounts exist. Default 'created' (ascending; oldest wins)."
+          "description": "Account schema attribute used to sort multiple accounts before selecting one. Default is 'created' (ascending — oldest account wins). Must be a valid account schema attribute name."
         },
         "accountSortDescending": {
           "type": "boolean",
           "default": false,
-          "description": "Sort order when multiple accounts exist. Default false (ascending)."
+          "description": "Controls sort order when multiple accounts exist. false = ascending (oldest first, default). true = descending (newest first)."
         },
         "accountReturnFirstLink": {
           "type": "boolean",
           "default": false,
-          "description": "If true, return the value from the first account in the sorted list even if null; if false, return the first non-null value. Default false."
+          "description": "Controls null handling when multiple accounts exist. false = skip accounts with null values and return the first non-null (default). true = return the first sorted account's value even if it is null."
         },
         "accountFilter": {
           "type": "string",
           "minLength": 1,
-          "description": "Database filter (sailpoint.object.Filter) ANDed with the default source+identity filter. Only searchable fields are supported (nativeIdentity, displayName, entitlements)."
+          "description": "Database-level filter using sailpoint.object.Filter syntax. Applied before account retrieval. IMPORTANT: only the following fields are searchable at database level — nativeIdentity, displayName, entitlements. For other attributes (e.g. custom fields, status) use accountPropertyFilter. Example: !(nativeIdentity.startsWith(\"*DELETED*\"))"
         },
         "accountPropertyFilter": {
           "type": "string",
           "minLength": 1,
-          "description": "In-memory filter (sailpoint.object.Filter) applied after retrieval. All account attributes can be referenced."
+          "description": "In-memory filter using sailpoint.object.Filter syntax. Applied after account retrieval. All account attributes are available for filtering (not limited to searchable fields). Example: (status != \"terminated\")"
         },
         "input": {
-          "type": "object",
-          "description": "Explicit input object. If omitted, the transform uses implicit input configured via UI/source+attribute mapping.",
-          "additionalProperties": true
+          "description": "Explicit input data to override the implicit source+attribute mapping. Can be a nested transform object or a static string value.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "required": ["type"],
+              "properties": {
+                "type": { "type": "string", "minLength": 1 },
+                "attributes": { "type": "object" }
+              },
+              "additionalProperties": true
+            }
+          ]
         }
       },
       "allOf": [
         {
-          "description": "Exactly one source reference must be provided: sourceName OR applicationId OR applicationName.",
+          "description": "Exactly one source reference must be provided: sourceName OR applicationId OR applicationName. Using more than one is not allowed.",
           "oneOf": [
             {
-              "required": [
-                "sourceName"
-              ],
+              "required": ["sourceName"],
               "not": {
                 "anyOf": [
-                  {
-                    "required": [
-                      "applicationId"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "applicationName"
-                    ]
-                  }
+                  { "required": ["applicationId"] },
+                  { "required": ["applicationName"] }
                 ]
               }
             },
             {
-              "required": [
-                "applicationId"
-              ],
+              "required": ["applicationId"],
               "not": {
                 "anyOf": [
-                  {
-                    "required": [
-                      "sourceName"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "applicationName"
-                    ]
-                  }
+                  { "required": ["sourceName"] },
+                  { "required": ["applicationName"] }
                 ]
               }
             },
             {
-              "required": [
-                "applicationName"
-              ],
+              "required": ["applicationName"],
               "not": {
                 "anyOf": [
-                  {
-                    "required": [
-                      "sourceName"
-                    ]
-                  },
-                  {
-                    "required": [
-                      "applicationId"
-                    ]
-                  }
+                  { "required": ["sourceName"] },
+                  { "required": ["applicationId"] }
                 ]
               }
             }
@@ -149,16 +134,34 @@
   },
   "examples": [
     {
+      "name": "Get hire date from HR source",
       "type": "accountAttribute",
-      "name": "Account Attribute Transform",
       "attributes": {
         "sourceName": "Corporate HR",
-        "attributeName": "HIREDATE",
+        "attributeName": "HIREDATE"
+      }
+    },
+    {
+      "name": "Get status from newest non-service account",
+      "type": "accountAttribute",
+      "requiresPeriodicRefresh": true,
+      "attributes": {
+        "applicationName": "corp-active-directory",
+        "attributeName": "employeeStatus",
         "accountSortAttribute": "created",
         "accountSortDescending": true,
-        "accountReturnFirstLink": true,
+        "accountReturnFirstLink": false,
+        "accountFilter": "!(nativeIdentity.startsWith(\"*DELETED*\"))",
         "accountPropertyFilter": "(WORKER_STATUS__c == \"active\")"
       }
+    },
+    {
+      "name": "Get department using immutable source ID",
+      "type": "accountAttribute",
+      "attributes": {
+        "applicationId": "2c91808b7cda982781e0a6b92e0f01a9",
+        "attributeName": "department"
+      }
     }
   ]
 }

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

@@ -28,14 +28,34 @@
       "additionalProperties": false,
       "properties": {
         "inputFormat": {
-          "type": "string",
           "default": "ISO8601",
-          "description": "Format of the incoming date. Java SimpleDateFormat pattern or built-in named format."
+          "description": "Format of the incoming date. Must be one of the 5 named formats or a Java SimpleDateFormat pattern.",
+          "anyOf": [
+            {
+              "enum": ["ISO8601", "LDAP", "PEOPLE_SOFT", "EPOCH_TIME_JAVA", "EPOCH_TIME_WIN32"],
+              "description": "Built-in named format."
+            },
+            {
+              "type": "string",
+              "not": { "pattern": "^[A-Z][A-Z0-9_]+$" },
+              "description": "Java SimpleDateFormat pattern (e.g. dd-MM-yyyy, yyyy-MM-dd'T'HH:mm:ssZ)."
+            }
+          ]
         },
         "outputFormat": {
-          "type": "string",
           "default": "ISO8601",
-          "description": "Desired output format. Java SimpleDateFormat pattern or built-in named format."
+          "description": "Desired output format. Must be one of the 5 named formats or a Java SimpleDateFormat pattern.",
+          "anyOf": [
+            {
+              "enum": ["ISO8601", "LDAP", "PEOPLE_SOFT", "EPOCH_TIME_JAVA", "EPOCH_TIME_WIN32"],
+              "description": "Built-in named format."
+            },
+            {
+              "type": "string",
+              "not": { "pattern": "^[A-Z][A-Z0-9_]+$" },
+              "description": "Java SimpleDateFormat pattern (e.g. dd-MM-yyyy, yyyy-MM-dd'T'HH:mm:ssZ)."
+            }
+          ]
         },
         "input": {
           "description": "Explicitly defines the input data passed into the transform. Docs specify an object; in practice this is a nested transform object. If omitted, the transform uses the UI-configured source+attribute input.",

package/dist/transforms/lint.js

@@ -176,29 +176,85 @@ function lintRuleBackedInvariants(requestedType, normalized, msgs) {
 // ---------------------------------------------------------------------------
 function lintAccountAttribute(attrs) {
     const msgs = [];
+    // --- 1. Source reference: exactly one of sourceName / applicationId / applicationName ---
     const sourceFields = ["sourceName", "applicationId", "applicationName"];
     const presentSources = sourceFields.filter((f) => attrs?.[f] !== undefined && attrs?.[f] !== null && String(attrs[f]).trim() !== "");
     if (presentSources.length === 0) {
-        push(msgs, "error", "accountAttribute requires exactly one source reference: sourceName, applicationId, or applicationName.", "attributes");
+        push(msgs, "error", "accountAttribute requires exactly one source reference: sourceName (display name), " +
+            "applicationId (external GUID), or applicationName (immutable internal name).", "attributes");
     }
     else if (presentSources.length > 1) {
-        push(msgs, "error", `accountAttribute must have exactly ONE source reference; found multiple: ${presentSources.join(", ")}. Remove all but one.`, "attributes");
+        push(msgs, "error", `accountAttribute must have exactly ONE source reference; found multiple: ${presentSources.join(", ")}. ` +
+            "Remove all but one. Prefer applicationName for stability (display names can change).", "attributes");
     }
-    // Type checks for optional boolean attrs
+    // --- 2. sourceName: non-empty, and warn about display-name fragility ---
+    if (attrs?.sourceName !== undefined) {
+        if (typeof attrs.sourceName !== "string" || attrs.sourceName.trim() === "") {
+            push(msgs, "error", "sourceName must be a non-empty string matching the source's display name.", "attributes.sourceName");
+        }
+        else {
+            push(msgs, "warn", "sourceName references the source display name, which can change. " +
+                "If the source is renamed the transform will break. Consider using applicationName (immutable) for long-term stability.", "attributes.sourceName");
+        }
+    }
+    // --- 3. applicationId: non-empty string ---
+    if (attrs?.applicationId !== undefined) {
+        if (typeof attrs.applicationId !== "string" || attrs.applicationId.trim() === "") {
+            push(msgs, "error", "applicationId must be a non-empty string (external GUID of the source).", "attributes.applicationId");
+        }
+    }
+    // --- 4. applicationName: non-empty string ---
+    if (attrs?.applicationName !== undefined) {
+        if (typeof attrs.applicationName !== "string" || attrs.applicationName.trim() === "") {
+            push(msgs, "error", "applicationName must be a non-empty string (immutable internal source name).", "attributes.applicationName");
+        }
+    }
+    // --- 5. attributeName: required (caught by schema), but also check non-empty ---
+    if (attrs?.attributeName !== undefined) {
+        if (typeof attrs.attributeName !== "string" || attrs.attributeName.trim() === "") {
+            push(msgs, "error", "attributeName must be a non-empty string matching the account attribute name in the source schema.", "attributes.attributeName");
+        }
+    }
+    // --- 6. accountSortAttribute: non-empty string; default is 'created' ---
+    if (attrs?.accountSortAttribute !== undefined) {
+        if (typeof attrs.accountSortAttribute !== "string") {
+            push(msgs, "error", "accountSortAttribute must be a string (schema attribute name). Default is 'created'.", "attributes.accountSortAttribute");
+        }
+        else if (attrs.accountSortAttribute.trim() === "") {
+            push(msgs, "error", "accountSortAttribute must not be empty. Omit it to use the default ('created'), or provide a valid account schema attribute name.", "attributes.accountSortAttribute");
+        }
+    }
+    // --- 7. accountSortDescending: boolean ---
     if (attrs?.accountSortDescending !== undefined && typeof attrs.accountSortDescending !== "boolean") {
-        push(msgs, "error", "accountSortDescending must be a boolean.", "attributes.accountSortDescending");
+        push(msgs, "error", "accountSortDescending must be a boolean (true = descending, false = ascending). Default is false.", "attributes.accountSortDescending");
     }
+    // --- 8. accountReturnFirstLink: boolean ---
     if (attrs?.accountReturnFirstLink !== undefined && typeof attrs.accountReturnFirstLink !== "boolean") {
-        push(msgs, "error", "accountReturnFirstLink must be a boolean.", "attributes.accountReturnFirstLink");
-    }
-    if (attrs?.accountSortAttribute !== undefined && typeof attrs.accountSortAttribute !== "string") {
-        push(msgs, "error", "accountSortAttribute must be a string.", "attributes.accountSortAttribute");
+        push(msgs, "error", "accountReturnFirstLink must be a boolean. " +
+            "true = return the first sorted account's value even if null; false = skip nulls and return first non-null. Default is false.", "attributes.accountReturnFirstLink");
     }
-    if (attrs?.accountFilter !== undefined && typeof attrs.accountFilter !== "string") {
-        push(msgs, "error", "accountFilter must be a string.", "attributes.accountFilter");
+    // --- 9. accountFilter: type, non-empty, and searchable-fields hint ---
+    if (attrs?.accountFilter !== undefined) {
+        if (typeof attrs.accountFilter !== "string") {
+            push(msgs, "error", "accountFilter must be a string (sailpoint.object.Filter expression).", "attributes.accountFilter");
+        }
+        else if (attrs.accountFilter.trim() === "") {
+            push(msgs, "error", "accountFilter must not be empty if provided. Omit it to disable database-level filtering.", "attributes.accountFilter");
+        }
+        else {
+            push(msgs, "info", "accountFilter applies a database-level sailpoint.object.Filter. " +
+                "Only these fields are searchable at database level: nativeIdentity, displayName, entitlements. " +
+                "For other account attributes (e.g. custom fields, status), use accountPropertyFilter instead.", "attributes.accountFilter");
+        }
     }
-    if (attrs?.accountPropertyFilter !== undefined && typeof attrs.accountPropertyFilter !== "string") {
-        push(msgs, "error", "accountPropertyFilter must be a string.", "attributes.accountPropertyFilter");
+    // --- 10. accountPropertyFilter: type and non-empty ---
+    if (attrs?.accountPropertyFilter !== undefined) {
+        if (typeof attrs.accountPropertyFilter !== "string") {
+            push(msgs, "error", "accountPropertyFilter must be a string (sailpoint.object.Filter expression).", "attributes.accountPropertyFilter");
+        }
+        else if (attrs.accountPropertyFilter.trim() === "") {
+            push(msgs, "error", "accountPropertyFilter must not be empty if provided. Omit it to disable in-memory filtering.", "attributes.accountPropertyFilter");
+        }
     }
     return msgs;
 }
@@ -457,7 +513,10 @@ function lintDateCompare(attrs) {
 // ---------------------------------------------------------------------------
 function lintDateFormat(attrs) {
     const msgs = [];
-    const NAMED_FORMATS = new Set(["ISO8601", "EPOCH_TIME_JAVA", "EPOCH_TIME_WIN32", "LDAP_GENERALIZED_TIME"]);
+    // Exact set of named formats per SailPoint docs — no variants accepted.
+    const NAMED_FORMATS = new Set(["ISO8601", "LDAP", "PEOPLE_SOFT", "EPOCH_TIME_JAVA", "EPOCH_TIME_WIN32"]);
+    // A value that is ALL_CAPS_WITH_UNDERSCORES is clearly intended as a named constant, not a pattern.
+    const looksLikeNamedConstant = (s) => /^[A-Z][A-Z0-9_]+$/.test(s);
     const isLikelyPattern = (s) => /[yMdHhmsSZ]/.test(s);
     const checkFmt = (field) => {
         const raw = attrs?.[field];
@@ -468,15 +527,20 @@ function lintDateFormat(attrs) {
             return;
         }
         const t = raw.trim();
-        const lower = t.toLowerCase();
-        if (lower === "epoch" || lower === "unix" || lower === "unixtime" || lower === "javaepoch") {
-            push(msgs, "error", `Unsupported ${field} '${t}'. Use a documented named format: ${Array.from(NAMED_FORMATS).join(", ")}.`, `attributes.${field}`);
+        // If the value looks like a named constant (ALL_CAPS_UNDERSCORES), validate strictly.
+        // Do NOT fall through to isLikelyPattern — e.g. EPOCH_TIME_JAVA_IN_MILLIS contains
+        // 'H' and 'M' and would falsely pass the pattern check.
+        if (looksLikeNamedConstant(t)) {
+            if (!NAMED_FORMATS.has(t)) {
+                push(msgs, "error", `'${t}' is not a valid named format for ${field}. ` +
+                    `Allowed named formats: ${Array.from(NAMED_FORMATS).join(", ")}. ` +
+                    `Alternatively, use a Java SimpleDateFormat pattern (e.g. dd-MM-yyyy, yyyy-MM-dd'T'HH:mm:ssZ).`, `attributes.${field}`);
+            }
             return;
         }
-        if (NAMED_FORMATS.has(t.toUpperCase()))
-            return;
+        // Value looks like a date pattern — check it has at least one date token.
         if (!isLikelyPattern(t)) {
-            push(msgs, "warn", `${field} '${t}' doesn't match a known named format and doesn't look like a date pattern (missing date tokens like y/M/d/H).`, `attributes.${field}`);
+            push(msgs, "warn", `${field} '${t}' doesn't match a known named format and doesn't look like a date pattern (missing tokens like y/M/d/H).`, `attributes.${field}`);
         }
     };
     checkFmt("inputFormat");

package/package.json

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