@servicenow/sdk-build-plugins 4.6.0 → 4.7.0

package/src/business-rule-plugin.ts

@@ -1,7 +1,7 @@
 import { CallExpressionShape, type ObjectShape, Plugin, type ArrayShape, type Shape } from '@servicenow/sdk-build-core'
 import { ModuleFunctionShape } from './server-module-plugin'
 import { NowIdShape } from './now-id-plugin'
-import { createSdkDocEntry, generateDeprecatedDiagnostics } from './utils'
+import { generateDeprecatedDiagnostics } from './utils'
 import { NowIncludeShape } from './now-include-plugin'
 
 // Similar to lodash's groupBy, but simply stores the last element of each group
@@ -45,7 +45,6 @@ const brAliases = {
 
 export const BusinessRulePlugin = Plugin.create({
     name: 'BusinessRulePlugin',
-    docs: [createSdkDocEntry('BusinessRule', ['sys_script'])],
     records: {
         sys_script: {
             async toShape(record, { transform }) {

package/src/call-expression-plugin.ts

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

package/src/claims-plugin.ts

@@ -8,7 +8,6 @@ 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 { createSdkDocEntry, generateDeprecatedDiagnostics, validateClientSideScript } from './utils'
+import { generateDeprecatedDiagnostics, validateClientSideScript } from './utils'
 import { NowIncludeShape } from './now-include-plugin'
 
 enum UITypeMapping {
@@ -44,7 +44,6 @@ 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

@@ -9,8 +9,7 @@ import {
     getDefaultMaxLength,
 } from './column/column-helper'
 import { ModuleFunctionShape } from './server-module-plugin'
-import { generateDeprecatedDiagnostics } from './utils'
-import { create } from 'xmlbuilder2'
+import { generateDeprecatedDiagnostics, generateChoiceSetFile } from './utils'
 
 // BCP 47 language tag pattern: 2-3 letter base language with optional subtags (e.g., 'en', 'zh-Hans', 'en-US')
 export const BCP47_LANGUAGE_TAG_PATTERN = /^[a-z]{2,3}(-[a-zA-Z0-9]{2,8})*$/
@@ -48,6 +47,9 @@ const columnAliases = {
     referenceKey: ['reference_key'],
     referenceQual: ['reference_qual'],
     columnType: ['column_type'],
+    virtualType: ['virtual_type'],
+    useReferenceQualifier: ['use_reference_qualifier'],
+    dynamicRefQual: ['dynamic_ref_qual'],
 }
 
 const calculationAliases = {
@@ -66,7 +68,6 @@ const documentationAliases = {
 
 export const ColumnPlugin = Plugin.create({
     name: 'ColumnPlugin',
-    docs: [],
     records: {
         sys_choice: {
             coalesce: ['name', 'element', 'value'],
@@ -92,48 +93,9 @@ export const ColumnPlugin = Plugin.create({
                 value: `sys_choice_${record.get('name').getValue()}_${record.get('element').getValue()}`,
             }),
             async toFile(choiceSet, { config, descendants, transform }) {
-                const tableName = choiceSet.get('name').asString().getValue()
-                const elementName = choiceSet.get('element').asString().getValue()
-                const xml = create().ele('record_update')
-                const root = xml.ele('sys_choice_set', { table: tableName, field: elementName })
-                descendants.query('sys_choice').forEach((choice) => {
-                    const child = root.ele('sys_choice', { action: choice.getAction() })
-                    child.ele('sys_id').txt(choice.getId().getValue())
-                    child.ele('name').txt(tableName)
-                    child.ele('element').txt(elementName)
-
-                    for (const prop of [
-                        'label',
-                        'value',
-                        'sequence',
-                        'dependent_value',
-                        'hint',
-                        'inactive',
-                        'inactive_on_update',
-                        'language',
-                    ]) {
-                        choice
-                            .get(prop)
-                            .ifDefined()
-                            ?.toString()
-                            .pipe((p) => child.ele(prop).txt(p.getValue()))
-                    }
-                })
-
-                const child = root.ele('sys_choice_set', { action: choiceSet.getAction() })
-                child.ele('sys_id').txt(choiceSet.getId().getValue())
-                child.ele('sys_scope', { display_value: config.scope }).txt(config.scopeId)
-                child.ele('name').txt(tableName)
-                child.ele('element').txt(elementName)
-
                 return {
                     success: true,
-                    value: {
-                        source: choiceSet,
-                        name: `${await transform.getUpdateName(choiceSet)}.xml`,
-                        category: choiceSet.getInstallCategory(),
-                        content: xml.end({ prettyPrint: true }),
-                    },
+                    value: await generateChoiceSetFile(choiceSet, descendants.query('sys_choice'), config, transform),
                 }
             },
         },
@@ -183,6 +145,17 @@ export const ColumnPlugin = Plugin.create({
                     )
                 }
                 const columnType = COLUMN_API_TO_TYPE[callee] ?? column.get('columnType').asString().getValue()
+
+                const dynamicRefQualShape = column.get('dynamicRefQual')
+                const dynamicRefQualRef =
+                    dynamicRefQualShape.isString() && dynamicRefQualShape.getValue() !== ''
+                        ? await factory.createReference({
+                              source: dynamicRefQualShape,
+                              table: 'sys_filter_option_dynamic',
+                              guid: dynamicRefQualShape,
+                          })
+                        : dynamicRefQualShape.ifDefined()
+
                 return {
                     success: true,
                     value: (
@@ -257,21 +230,27 @@ export const ColumnPlugin = Plugin.create({
                                         )
                                     })
                                     .toCdata(),
-                                choice: $.from('dropdown')
-                                    .map((d) =>
-                                        d.isString()
-                                            ? Math.max(choiceDropdown.indexOf(d.getValue() as choiceDropdownType), 0)
-                                            : undefined
-                                    )
-                                    .def(0),
+                                choice: $.from('dropdown').map((d) => {
+                                    if (!d.isString()) {
+                                        return undefined
+                                    }
+                                    const idx = choiceDropdown.indexOf(d.getValue() as choiceDropdownType)
+                                    // Index 0 ('none') is the platform default — leave undefined so
+                                    // the install XML emits empty <choice/>, matching stock records.
+                                    return idx > 0 ? idx : undefined
+                                }),
                                 choice_table: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) =>
                                     dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() ===
                                     'choices_from_other_table'
                                         ? dynamicValueDefinitions.asObject().get('table').ifString()
                                         : undefined
                                 ),
-                                virtual: $.from('dynamicValueDefinitions')
-                                    .map((dynamicValueDefinitions) => {
+                                virtual: $.from('dynamicValueDefinitions', 'formula')
+                                    .map((dynamicValueDefinitions, formula) => {
+                                        const hasFormula = formula.isString() && formula.getValue() !== ''
+                                        if (hasFormula) {
+                                            return true
+                                        }
                                         const calculationType = dynamicValueDefinitions
                                             .ifObject()
                                             ?.get('type')
@@ -371,10 +350,29 @@ export const ColumnPlugin = Plugin.create({
                                                 `readOnly cannot be false with readOnlyOption ${readOnlyOptionValue}.`
                                             )
                                         }
+                                        if (readOnlyValue === true && readOnlyOptionValue) {
+                                            diagnostics.hint(
+                                                readOnly,
+                                                `readOnly is unnecessary when readOnlyOption '${readOnlyOptionValue}' is declared.`
+                                            )
+                                        }
                                         return readOnlyValue ?? !!readOnlyOptionValue
                                     })
                                     .def(false),
-                                read_only_option: $.from('readOnlyOption'),
+                                // Pair read_only_option with read_only so the platform's
+                                // DictionaryReadOnlyOptionListener doesn't clear read_only on subsequent
+                                // installs when it sees a previously-set option go to null.
+                                read_only_option: $.from('readOnly', 'readOnlyOption').map(
+                                    (readOnly, readOnlyOption) => {
+                                        const opt = readOnlyOption.ifString()?.getValue()
+                                        if (opt) {
+                                            return opt
+                                        }
+                                        return readOnly.ifBoolean()?.getValue() === true
+                                            ? 'instance_configured'
+                                            : undefined
+                                    }
+                                ),
                                 reference: $.from('referenceTable'),
                                 spell_check: $.from('spellCheck').toBoolean().def(false),
                                 table_reference: $.from('tableReference').toBoolean().def(false),
@@ -382,6 +380,50 @@ export const ColumnPlugin = Plugin.create({
                                 unique: $.toBoolean().def(false),
                                 widget: $,
                                 xml_view: $.from('xmlView').toBoolean().def(false),
+                                formula: $.from('formula').toCdata(),
+                                virtual_type: $.from('virtualType', 'formula')
+                                    .map((virtualType, formula) => {
+                                        const explicit = virtualType.ifString()?.getValue()
+                                        const hasFormula = formula.isString() && formula.getValue() !== ''
+                                        const derived = hasFormula ? 'formula' : 'script'
+                                        if (explicit && explicit !== derived) {
+                                            const reason = hasFormula
+                                                ? `formula is set, implying 'formula'`
+                                                : `formula is not set, implying 'script'`
+                                            diagnostics.warn(
+                                                virtualType,
+                                                `virtualType is set to '${explicit}' but ${reason}. The explicit value '${explicit}' will be used.`
+                                            )
+                                            return explicit
+                                        }
+                                        return derived
+                                    })
+                                    .def('script'),
+                                use_reference_qualifier: $.from('useReferenceQualifier', 'referenceQual')
+                                    .map((useReferenceQualifier, referenceQual) => {
+                                        const explicit = useReferenceQualifier.ifString()?.getValue()
+                                        const hasDynamic = !!dynamicRefQualRef
+                                        const hasRef = referenceQual.isString() && referenceQual.getValue() !== ''
+                                        const derived = hasDynamic ? 'dynamic' : hasRef ? 'advanced' : 'simple'
+                                        if (explicit && explicit !== derived) {
+                                            const reason =
+                                                hasDynamic && hasRef
+                                                    ? `both dynamicRefQual and referenceQual are set`
+                                                    : hasDynamic
+                                                      ? `dynamicRefQual is set, implying 'dynamic'`
+                                                      : hasRef
+                                                        ? `referenceQual is set, implying 'advanced'`
+                                                        : `neither dynamicRefQual nor referenceQual is set, implying 'simple'`
+                                            diagnostics.warn(
+                                                useReferenceQualifier,
+                                                `useReferenceQualifier is set to '${explicit}' but ${reason}. The explicit value '${explicit}' will be used.`
+                                            )
+                                            return explicit
+                                        }
+                                        return derived
+                                    })
+                                    .def('simple'),
+                                dynamic_ref_qual: $.val(dynamicRefQualRef),
                             })),
                         })
                     ).with(...documentationRecords, ...choiceRecords, ...choiceSetRecords),
@@ -559,31 +601,40 @@ export function columnToCallExpression(
                             return dropdownIndex !== -1 ? choiceDropdown[dropdownIndex] : undefined
                         })
                         .def('none'),
-                    dynamicValueDefinitions: $.from('calculation', 'choice_table', 'choice_field').map(
-                        (calculation, choiceTable, choiceField) => {
-                            if (
-                                calculation.ifString()?.getValue() &&
-                                calculation.asString().getValue() !== DEFAULT_COLUMN_CALCULATION
-                            ) {
-                                return new ObjectShape({
-                                    source: calculation,
-                                    properties: {
-                                        type: 'calculated_value',
-                                        calculatedValue: calculation,
-                                    },
-                                }).withAliasedKeys(calculationAliases)
-                            }
-                            if (choiceTable.ifString()?.getValue() && choiceField.ifString()?.getValue()) {
-                                return {
-                                    type: 'choices_from_other_table',
-                                    table: choiceTable.asString().getValue(),
-                                    field: choiceField.asString().getValue(),
-                                }
+                    dynamicValueDefinitions: $.from(
+                        'calculation',
+                        'choice_table',
+                        'choice_field',
+                        'virtual_type',
+                        'virtual'
+                    ).map((calculation, choiceTable, choiceField, virtualType, virtual) => {
+                        // Server only reads calculation when virtual_type='script' and virtual=true
+                        const vType = virtualType.ifString()?.getValue()
+                        const isVirtual = virtual.ifBoolean()?.getValue() ?? virtual.ifString()?.getValue() === 'true'
+                        if (
+                            isVirtual &&
+                            vType !== 'formula' &&
+                            calculation.ifString()?.getValue() &&
+                            calculation.asString().getValue() !== DEFAULT_COLUMN_CALCULATION
+                        ) {
+                            return new ObjectShape({
+                                source: calculation,
+                                properties: {
+                                    type: 'calculated_value',
+                                    calculatedValue: calculation,
+                                },
+                            }).withAliasedKeys(calculationAliases)
+                        }
+                        if (choiceTable.ifString()?.getValue() && choiceField.ifString()?.getValue()) {
+                            return {
+                                type: 'choices_from_other_table',
+                                table: choiceTable.asString().getValue(),
+                                field: choiceField.asString().getValue(),
                             }
-
-                            return undefined
                         }
-                    ),
+
+                        return undefined
+                    }),
                     // Direct dependent parameter for DocumentIdColumn, TemplateValueColumn, and FieldListColumn
                     dependent: $.from('dependent').map((dependent) => {
                         if (dependent?.isString()) {
@@ -645,6 +696,42 @@ export function columnToCallExpression(
                     unique: $.toBoolean().def(false),
                     widget: $.def(''),
                     xmlView: $.from('xml_view').toBoolean().def(false),
+                    formula: $.from('virtual_type', 'formula').map((virtualType, formula) => {
+                        // Server only reads formula when virtual_type='formula'
+                        if (virtualType.ifString()?.getValue() !== 'formula') {
+                            return undefined
+                        }
+                        return formula.ifString()?.ifNotEmpty()
+                    }),
+                    virtualType: $.from('virtual_type', 'formula').map((virtualType, formula) => {
+                        const qualifier = virtualType.ifString()?.getValue()
+                        const hasFormula = formula.isString() && formula.getValue() !== ''
+                        if (hasFormula && qualifier === 'formula') {
+                            return undefined
+                        }
+                        if (!hasFormula && (!qualifier || qualifier === 'script')) {
+                            return undefined
+                        }
+                        return qualifier
+                    }),
+                    useReferenceQualifier: $.from('use_reference_qualifier', 'dynamic_ref_qual', 'reference_qual').map(
+                        (useReferenceQualifier, dynamicRefQual, referenceQual) => {
+                            const qualifier = useReferenceQualifier.ifString()?.getValue()
+                            const hasDynamicRefQual = dynamicRefQual.isString() && dynamicRefQual.getValue() !== ''
+                            const hasReferenceQual = referenceQual.isString() && referenceQual.getValue() !== ''
+                            if (hasDynamicRefQual && qualifier === 'dynamic') {
+                                return undefined
+                            }
+                            if (hasReferenceQual && qualifier === 'advanced') {
+                                return undefined
+                            }
+                            if (!hasDynamicRefQual && !hasReferenceQual && (!qualifier || qualifier === 'simple')) {
+                                return undefined
+                            }
+                            return qualifier
+                        }
+                    ),
+                    dynamicRefQual: $.from('dynamic_ref_qual').def(''),
                 }))
                 .withAliasedKeys(columnAliases),
         ],

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 { createSdkDocEntry, generateDeprecatedDiagnostics } from './utils'
+import { generateDeprecatedDiagnostics } from './utils'
 
 const crossScopeAliases = {
     targetName: ['target_name'],
@@ -23,7 +23,6 @@ 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,7 +1,6 @@
 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) =>
@@ -56,7 +55,6 @@ 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,7 +41,6 @@ const shapeCreators: Record<
 
 export const DataPlugin = Plugin.create({
     name: 'DataPlugin',
-    docs: [],
     shapes: [
         {
             shape: CallExpressionShape,