@servicenow/sdk-build-plugins 4.4.0 → 4.5.0

package/src/atf/test-plugin.ts

@@ -19,6 +19,7 @@ import {
 } from '@servicenow/sdk-build-core'
 import { NowIdShape } from '../now-id-plugin'
 import { ArrowFunctionShape } from '../arrow-function-plugin'
+import { createSdkDocEntry } from '../utils'
 import { create } from 'xmlbuilder2'
 import { Test } from '@servicenow/sdk-core/runtime/app'
 import {
@@ -33,6 +34,7 @@ import type { Duration } from '@servicenow/sdk/core'
 
 export const TestPlugin = Plugin.create({
     name: 'TestPlugin',
+    docs: [createSdkDocEntry('Test', ['sys_atf_test'])],
     records: {
         sys_atf_test: {
             relationships: {

package/src/basic-syntax-plugin.ts

@@ -30,9 +30,11 @@ import {
 } from '@servicenow/sdk-build-core'
 import { isDataHelper } from './data-plugin'
 import { getCallExpressionName } from './utils'
+import { NowIncludePlugin, NowIncludeShape } from './now-include-plugin'
 
 export const BasicSyntaxPlugin = Plugin.create({
     name: 'BasicSyntaxPlugin',
+    docs: [],
     files: [
         {
             entryPoint: true,
@@ -309,6 +311,7 @@ export const BasicSyntaxPlugin = Plugin.create({
 
                 const propsToRetain = new Set<string>(['$meta'])
                 const propsToAdd: ts.PropertyAssignmentStructure[] = []
+                const nowIncludePropsToCommit = new Set<string>()
                 for (const [name, value] of shape.entries({ resolve: false })) {
                     const existingPropKey = [...shape.getAliases(name), name].find((aliasedKey) =>
                         existingNames.has(aliasedKey)
@@ -324,6 +327,9 @@ export const BasicSyntaxPlugin = Plugin.create({
 
                         await commit(value, existingNames.get(existingPropKey) as ts.Expression)
                     } else if (!value.equals(shape.getDefault(name))) {
+                        if (value.is(NowIncludeShape)) {
+                            nowIncludePropsToCommit.add(name)
+                        }
                         propsToAdd.push({
                             name: ObjectShape.quotePropertyNameIfNeeded(name),
                             initializer: value.getCode(),
@@ -338,6 +344,15 @@ export const BasicSyntaxPlugin = Plugin.create({
                     target.addPropertyAssignments(propsToAdd)
                 }
 
+                // commit Now.include props to generate the include file.
+                for (const prop of nowIncludePropsToCommit) {
+                    const includeInitializer = target
+                        .getPropertyOrThrow(prop)
+                        .asKindOrThrow(ts.SyntaxKind.PropertyAssignment)
+                        .getInitializerOrThrow()
+                    await commit(shape.get(prop, false), includeInitializer, NowIncludePlugin)
+                }
+
                 const propsToRemove = [...existingNames.keys()].filter((key) => !propsToRetain.has(key))
                 propsToRemove.forEach((prop) => {
                     target.getProperty(prop)?.asKindOrThrow(ts.SyntaxKind.PropertyAssignment).remove()
@@ -544,6 +559,12 @@ export const BasicSyntaxPlugin = Plugin.create({
                 return transform.toShape(node.getExpression())
             },
         },
+        {
+            node: 'ParenthesizedExpression',
+            toShape(node, { transform }) {
+                return transform.toShape(node.getExpression())
+            },
+        },
         {
             node: 'Identifier',
             async toShape(node, { transform }) {

package/src/call-expression-plugin.ts

@@ -3,6 +3,7 @@ import { getCallExpressionName } from './utils'
 
 export const CallExpressionPlugin = Plugin.create({
     name: 'CallExpressionPlugin',
+    docs: [],
     nodes: [
         {
             node: 'CallExpression',

package/src/claims-plugin.ts

@@ -8,6 +8,7 @@ function getClaimsPath(project: Project, config: NowConfig): string {
 
 export const ClaimsPlugin = Plugin.create({
     name: 'ClaimsPlugin',
+    docs: [],
     files: [
         {
             entryPoint: true,

package/src/client-script-plugin.ts

@@ -1,6 +1,6 @@
 import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
-import { generateDeprecatedDiagnostics, validateClientSideScript } from './utils'
+import { createSdkDocEntry, generateDeprecatedDiagnostics, validateClientSideScript } from './utils'
 import { NowIncludeShape } from './now-include-plugin'
 
 enum UITypeMapping {
@@ -44,6 +44,7 @@ const clientScriptAliases = {
  */
 export const ClientScriptPlugin = Plugin.create({
     name: 'ClientScriptPlugin',
+    docs: [createSdkDocEntry('ClientScript', ['sys_script_client'])],
     records: {
         sys_script_client: {
             async toShape(record, { transform }) {

package/src/column-plugin.ts

@@ -66,6 +66,7 @@ const documentationAliases = {
 
 export const ColumnPlugin = Plugin.create({
     name: 'ColumnPlugin',
+    docs: [],
     records: {
         sys_choice: {
             coalesce: ['name', 'element', 'value'],

package/src/cross-scope-privilege-plugin.ts

@@ -1,6 +1,6 @@
 import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
-import { generateDeprecatedDiagnostics } from './utils'
+import { createSdkDocEntry, generateDeprecatedDiagnostics } from './utils'
 
 const crossScopeAliases = {
     targetName: ['target_name'],
@@ -23,6 +23,7 @@ const crossScopeAliases = {
  */
 export const CrossScopePrivilegePlugin = Plugin.create({
     name: 'CrossScopePrivilegePlugin',
+    docs: [createSdkDocEntry('CrossScopePrivilege', ['sys_scope_privilege'])],
     records: {
         sys_scope_privilege: {
             relationships: {

package/src/dashboard/dashboard-plugin.ts

@@ -1,6 +1,7 @@
 import { CallExpressionShape, type ObjectShape, Plugin, type Record as RecordType } from '@servicenow/sdk-build-core'
 import { NowIdShape } from '../now-id-plugin'
 import { resolveComponentToSysId, resolveComponentToName } from './dashboard-component-resolver'
+import { createSdkDocEntry } from '../utils'
 import { DEFAULT_PROPERTY_VALUES, removeRestrictedValues } from './dashboard-component-property-defaults'
 
 const transformWidget = (widget: RecordType) =>
@@ -55,6 +56,7 @@ const createWidgetProperties = (widgetData: ObjectShape, canvas: ObjectShape) =>
  */
 export const DashboardPlugin = Plugin.create({
     name: 'DashboardPlugin',
+    docs: [createSdkDocEntry('Dashboard', ['par_dashboard'])],
     records: {
         par_dashboard: {
             relationships: {

package/src/data-plugin.ts

@@ -41,6 +41,7 @@ const shapeCreators: Record<
 
 export const DataPlugin = Plugin.create({
     name: 'DataPlugin',
+    docs: [],
     shapes: [
         {
             shape: CallExpressionShape,

package/src/email-notification-plugin.ts

@@ -1,12 +1,6 @@
-import {
-    CallExpressionShape,
-    Plugin,
-    isGUID,
-    Shape,
-    type ObjectShape,
-    type Diagnostics,
-} from '@servicenow/sdk-build-core'
+import { CallExpressionShape, Plugin, isGUID, Shape, type ObjectShape } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
+import { showGuidFieldDiagnostic, createSdkDocEntry } from './utils'
 import type { EmailNotification } from '@servicenow/sdk-core/runtime/notification'
 
 // Use index access types instead of exported utility types
@@ -59,23 +53,9 @@ const isValidEmail = (email: string): boolean => {
     return emailRegex.test(email)
 }
 
-const showGuidFieldDiagnostic = (
-    inputReceived: Shape | undefined,
-    fieldName: string,
-    tableName: string,
-    diagnostics: Diagnostics
-) => {
-    if (inputReceived) {
-        const receivedValue = inputReceived.getValue()
-        diagnostics.error(
-            inputReceived,
-            `'${fieldName}' must be a valid GUID or a Record<'${tableName}'>. Received: '${receivedValue}'`
-        )
-    }
-}
-
 export const EmailNotificationPlugin = Plugin.create({
     name: 'EmailNotificationPlugin',
+    docs: [createSdkDocEntry('EmailNotification', ['sysevent_email_action'])],
     records: {
         sysevent_email_action: {
             toShape(record) {

package/src/flow/constants/flow-plugin-constants.ts

@@ -15,7 +15,7 @@ export const FLOW_PRIORITY_DEFAULT = 'MEDIUM'
 /**
  * Default user context for flow execution
  */
-export const RUN_AS_DEFAULT = 'system'
+export const RUN_AS_DEFAULT = 'user'
 
 /**
  * Default access level for flows

package/src/flow/flow-logic/flow-logic-plugin-helpers.ts

@@ -130,7 +130,7 @@ type FlowLogicParseResult =
  * FlowLogicValueInput objects with name/value pairs that represent the
  * original TypeScript configuration properties.
  */
-namespace FlowLogicValueProcessor {
+export namespace FlowLogicValueProcessor {
     /**
      * Generic factory function for creating flow logic entry objects.
      * All entry types (AssignSubflowOutput, SetFlowVariablesInput, FlowLogicValueInput)
@@ -766,8 +766,6 @@ namespace FlowLogicValueProcessor {
     // Constants for type handling
     const ARRAY_TYPE_PREFIX = 'array.' as const
     const ARRAY_TYPE_PREFIX_LENGTH = ARRAY_TYPE_PREFIX.length
-    const EXCLUDED_TYPE_ANNOTATIONS = new Set(['string', 'glide_date_time'])
-
     /**
      * Interface for child entry structure used in parsing
      */
@@ -829,50 +827,29 @@ namespace FlowLogicValueProcessor {
         return value
     }
 
-    /**
-     * Adds type annotation to a datapill if needed based on label cache
-     * @param pillName - Datapill name without braces
-     * @param labelCacheMap - Map of datapill names to types
-     * @returns Datapill with annotation if applicable
-     */
-    function addTypeAnnotationIfNeeded(pillName: string, labelCacheMap?: Map<string, string>): string {
-        if (!labelCacheMap) {
-            return `{{${pillName}}}`
-        }
-
-        const cachedType = labelCacheMap.get(pillName.trim())
-        if (cachedType && !EXCLUDED_TYPE_ANNOTATIONS.has(cachedType)) {
-            return `{{${pillName}|${cachedType}}}`
-        }
-
-        return `{{${pillName}}}`
-    }
-
     /**
      * Processes a pure datapill value (starts and ends with {{}})
+     * Strips any existing |type annotation and returns a clean datapill.
+     * Type info is preserved via labelCacheMap in wrapWithWfaDataPillExpression downstream.
      * @param value - Pure datapill string
-     * @param labelCacheMap - Map of datapill names to types
-     * @returns Processed datapill with type annotation if needed
+     * @param _labelCacheMap - Unused (type resolution handled downstream by transformDataPill)
+     * @returns Clean datapill without type annotation
      */
-    function processPureDatapill(value: string, labelCacheMap?: Map<string, string>): string {
-        const strippedValue = stripDatapillTypeAnnotation(value)
-        const pillName = strippedValue.slice(2, -2) // Remove {{ and }}
-        return addTypeAnnotationIfNeeded(pillName, labelCacheMap)
+    function processPureDatapill(value: string, _labelCacheMap?: Map<string, string>): string {
+        return stripDatapillTypeAnnotation(value)
     }
 
     /**
-     * Processes a template expression containing datapills mixed with text
+     * Processes a template expression containing datapills mixed with text.
+     * Strips any existing |type annotations and returns clean datapills.
+     * Type info is preserved via labelCacheMap in wrapWithWfaDataPillExpression downstream.
      * @param value - Template expression string
-     * @param labelCacheMap - Map of datapill names to types
-     * @returns Processed template with type annotations added to datapills
+     * @param _labelCacheMap - Unused (type resolution handled downstream by transformDataPill)
+     * @returns Processed template with type annotations stripped from datapills
      */
-    function processTemplateExpression(value: string, labelCacheMap?: Map<string, string>): string {
-        if (!labelCacheMap) {
-            return value
-        }
-
-        const datapillRegex = /\{\{([^}|]+)(?:\|[^}]+)?\}\}/g
-        return value.replace(datapillRegex, (_match, pillName) => addTypeAnnotationIfNeeded(pillName, labelCacheMap))
+    function processTemplateExpression(value: string, _labelCacheMap?: Map<string, string>): string {
+        const datapillRegex = /\{\{([^}|]+)\|[^}]+\}\}/g
+        return value.replace(datapillRegex, '{{$1}}')
     }
 
     /**
@@ -972,12 +949,26 @@ namespace FlowLogicValueProcessor {
             if (parsed.complexObjectSchema) {
                 // Find the $COCollectionField.$type_facets
                 for (const schemaKey in parsed.complexObjectSchema) {
+                    // Skip top-level $type_facets entries (handled as fallback below)
+                    if (schemaKey.endsWith('.$type_facets')) {
+                        continue
+                    }
                     const schema = parsed.complexObjectSchema[schemaKey]
-                    if (schema && schema.$COCollectionField && schema['$COCollectionField.$type_facets']) {
-                        const typeFacets = schema['$COCollectionField.$type_facets']
-                        if (typeFacets.SimpleMapFacet) {
-                            const facetData = JSON.parse(typeFacets.SimpleMapFacet)
-                            return facetData.child_type
+                    if (schema && schema.$COCollectionField) {
+                        // Array.Object format: child_type nested as $COCollectionField.$type_facets
+                        if (schema['$COCollectionField.$type_facets']?.SimpleMapFacet) {
+                            const facetData = JSON.parse(schema['$COCollectionField.$type_facets'].SimpleMapFacet)
+                            if (facetData.child_type) {
+                                return facetData.child_type
+                            }
+                        }
+                        // DEF0798866: Array.String format: child_type stored in top-level key "schemaKey.$type_facets"
+                        const topLevelTypeFacets = parsed.complexObjectSchema[`${schemaKey}.$type_facets`]
+                        if (topLevelTypeFacets?.SimpleMapFacet) {
+                            const facetData = JSON.parse(topLevelTypeFacets.SimpleMapFacet)
+                            if (facetData.child_type) {
+                                return facetData.child_type
+                            }
                         }
                     }
                 }
@@ -1081,8 +1072,15 @@ namespace FlowLogicValueProcessor {
         const firstBaseName = getBaseName(childObj.name)
 
         // Check if all children have the same base name (indicating FlowArray with repeated childName)
+        // When elementType is defined (i.e., the schema identifies this as a FlowArray — Array.Object,
+        // Array.String, Array.Integer, Array.DateTime, etc.), a single child is still a valid array
+        // element: the child is the childName wrapper whose inner value/children are the actual element.
+        // Without this, single-element FlowArray assignments fall into the object path, generating
+        // { childName: { fields } } or { childName: value } instead of [{ fields }] or [value].
+        // DEF0798866: single-element Array.Object/String subflow outputs generated incorrect Fluent code.
+        const minChildrenForArray = elementType !== undefined ? 1 : 2
         const allSameName =
-            children.length > 1 &&
+            children.length >= minChildrenForArray &&
             children.every((c) => {
                 const entry = c as ChildEntry
                 return getBaseName(entry.name) === firstBaseName
@@ -1525,7 +1523,11 @@ namespace FlowLogicValueProcessor {
                         // Ignore parse errors
                     }
                 }
-                const elementType = getArrayElementType(entry)
+                // DEF0798866: Use typeMap as fallback when schema-based detection fails.
+                // If entry.value doesn't contain complexObjectSchema (e.g., some ServiceNow XML
+                // formats omit the schema), fall back to the typeMap which always contains the
+                // output/variable type (e.g., 'array.string' -> 'string' element type).
+                const elementType = getArrayElementType(entry) ?? extractArrayElementType(typeMap?.get(entry.name))
                 const nestedTypeMap = extractNestedTypeSchema(entry)
                 const parsedValue = parseChildrenArray(
                     entry.children,

package/src/flow/flow-logic/flow-logic-plugin.ts

@@ -72,6 +72,7 @@ import type { ArrowFunctionShape } from '../../arrow-function-plugin'
  */
 export const FlowLogicPlugin = Plugin.create({
     name: 'FlowLogicPlugin',
+    docs: [],
     records: {
         sys_hub_flow_logic_instance_v2: {
             relationships: {

package/src/flow/plugins/approval-rules-plugin.ts

@@ -5,6 +5,7 @@ import { getCallExpressionName } from '../../utils'
 
 export const ApprovalRulesPlugin = Plugin.create({
     name: 'ApprovalRulesPlugin',
+    docs: [],
     nodes: [
         {
             node: 'CallExpression',

package/src/flow/plugins/flow-action-definition-plugin.ts

@@ -3,6 +3,7 @@ import { buildVariableRecords, complexObjectMatchesIoRecord } from '../utils/flo
 import { generateXML } from '../utils/flow-to-xml'
 import { slugifyString } from '../utils/flow-constants'
 import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { createSdkDocEntry } from '../../utils'
 import { StepInstanceShape } from './step-instance-plugin'
 
 const actionDefRelationships = {
@@ -108,6 +109,7 @@ const actionDefRelationships = {
 
 export const ActionDefinitionPlugin = Plugin.create({
     name: 'ActionDefinitionPlugin',
+    docs: [createSdkDocEntry('ActionDefinition', ['sys_hub_action_type_definition'])],
     records: {
         sys_hub_action_type_definition: {
             relationships: {
@@ -193,8 +195,8 @@ export const ActionDefinitionPlugin = Plugin.create({
             async diff(existing, incoming, descendants, context) {
                 return deleteMultipleDiff(existing, incoming, descendants, context)
             },
-            toFile(record, { config, database }) {
-                return generateXML(record, { config, database })
+            toFile(record, { config, database, self }) {
+                return generateXML(record, { config, database, plugin: self })
             },
         },
         sys_hub_action_input: {

package/src/flow/plugins/flow-data-pill-plugin.ts

@@ -156,6 +156,7 @@ function getForEachParameterName(identifierShape: IdentifierShape): string | nul
 
 export const DataPillPlugin = Plugin.create({
     name: 'DataPillPlugin',
+    docs: [],
     shapes: [
         {
             shape: PropertyAccessShape,

package/src/flow/plugins/flow-definition-plugin.ts

@@ -38,7 +38,7 @@ import {
     uuidToSysId,
     validateFlowVariableCall,
 } from '../utils/utils'
-import { getCallExpressionName } from '../../utils'
+import { createSdkDocEntry, getCallExpressionName } from '../../utils'
 import {
     extractLabelCache,
     createDefinitionMap,
@@ -610,9 +610,14 @@ function extractAllPills(
         const matchStart = match.index ?? 0
         const matchEnd = matchStart + fullMatch.length
 
+        // Strip type annotation if present (e.g., "uuid.field|integer" -> "uuid.field").
+        // ServiceNow stores datapills with type annotations like {{pill.path|datatype}}.
+        const pipeIndex = content.indexOf('|')
+        const cleanContent = pipeIndex !== -1 ? content.substring(0, pipeIndex) : content
+
         // Try UUID pattern first (more specific)
         // UUID format: 8-4-4-4-12 hex digits followed by dot and property path
-        const uuidMatch = content.match(
+        const uuidMatch = cleanContent.match(
             /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([a-zA-Z_][a-zA-Z0-9_.]*[a-zA-Z0-9_])$/
         )
 
@@ -1619,6 +1624,7 @@ function postProcessAssignSubflowOutputs(
 
 export const FlowDefinitionPlugin = Plugin.create({
     name: 'FlowDefinitionPlugin',
+    docs: [createSdkDocEntry('Flow', ['sys_hub_flow'])],
     records: {
         sys_hub_flow: {
             relationships: {
@@ -1680,8 +1686,8 @@ export const FlowDefinitionPlugin = Plugin.create({
             getUpdateName(record) {
                 return { success: true, value: `${record.getTable()}_${record.getId().getValue()}` }
             },
-            toFile(record, { config, database }) {
-                return generateXML(record, { config, database })
+            toFile(record, { config, database, self }) {
+                return generateXML(record, { config, database, plugin: self })
             },
             async diff(existing, incoming, descendants, context) {
                 return deleteMultipleDiff(existing, incoming, descendants, context)

package/src/flow/plugins/flow-diagnostics-plugin.ts

@@ -95,6 +95,7 @@ function isInsideFlowContext(node: ts.Node): boolean {
  */
 export const FlowDiagnosticsPlugin = Plugin.create({
     name: 'FlowDiagnosticsPlugin',
+    docs: [],
     shapes: [
         {
             shape: CallExpressionShape,