@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/service-catalog/service-catalog-diagnostics.ts

@@ -0,0 +1,254 @@
+import type { Diagnostics, ObjectShape } from '@servicenow/sdk-build-core'
+
+/**
+ * Validates that at most one of executionPlan, flow, or workflow is defined.
+ * These fields are mutually exclusive in the FulfillmentProcess type.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateFulfillmentProcessExclusivity(arg: ObjectShape, diagnostics: Diagnostics): boolean {
+    const fields = ['executionPlan', 'flow', 'workflow'] as const
+    const defined = fields.filter((f) => {
+        const val = arg.get(f)
+        return val.isDefined() && (!!val.ifRecordId() || !val.ifString()?.isEmpty())
+    })
+
+    if (defined.length > 1) {
+        diagnostics.error(
+            arg,
+            `Only one of executionPlan, flow, or workflow can be specified. Found: ${defined.join(', ')}. Remove the extra fields so that only one fulfillment method is configured.`
+        )
+        return false
+    }
+    return true
+}
+
+/**
+ * Validates that categories are only provided when catalogs are also provided.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateCategoriesRequireCatalogs(arg: ObjectShape, diagnostics: Diagnostics): boolean {
+    const hasCategories =
+        arg.get('categories').isDefined() && (arg.get('categories').ifArray()?.getElements()?.length ?? 0) > 0
+    const hasCatalogs =
+        arg.get('catalogs').isDefined() && (arg.get('catalogs').ifArray()?.getElements()?.length ?? 0) > 0
+
+    if (hasCategories && !hasCatalogs) {
+        diagnostics.error(
+            arg.get('categories'),
+            `'categories' requires 'catalogs' to also be specified. Categories can only be selected after the Catalogs field is populated.`
+        )
+        return false
+    }
+    return true
+}
+
+/**
+ * Validates that catalogItem and variableSet are not both provided.
+ * When appliesTo is 'set', variableSet should be provided; when 'item', catalogItem should be provided.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateCatalogItemVariableSetExclusivity(
+    arg: ObjectShape,
+    diagnostics: Diagnostics,
+    context: string
+): boolean {
+    const hasCatalogItem = arg.get('catalogItem').isDefined() && !arg.get('catalogItem').ifString()?.isEmpty()
+    const hasVariableSet = arg.get('variableSet').isDefined() && !arg.get('variableSet').ifString()?.isEmpty()
+
+    if (hasCatalogItem && hasVariableSet) {
+        diagnostics.error(
+            arg,
+            `${context}: 'catalogItem' and 'variableSet' are mutually exclusive. Specify only one. When appliesTo is 'set', use variableSet; when 'item', use catalogItem.`
+        )
+        return false
+    }
+
+    const appliesTo = arg.get('appliesTo')?.ifString()?.getValue()
+    if (appliesTo === 'set' && hasCatalogItem) {
+        diagnostics.error(
+            arg.get('catalogItem'),
+            `${context}: 'catalogItem' should not be specified when appliesTo is 'set'. Use 'variableSet' instead.`
+        )
+        return false
+    }
+    if (appliesTo === 'item' && hasVariableSet) {
+        diagnostics.error(
+            arg.get('variableSet'),
+            `${context}: 'variableSet' should not be specified when appliesTo is 'item'. Use 'catalogItem' instead.`
+        )
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Validates that variableMessage is provided when variableMessageType is set in a UI policy action.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateUiPolicyActionMessage(actionObj: ObjectShape, diagnostics: Diagnostics): boolean {
+    const hasMessageType =
+        actionObj.get('variableMessageType').isDefined() && !actionObj.get('variableMessageType').ifString()?.isEmpty()
+    const hasMessage =
+        actionObj.get('variableMessage').isDefined() && !actionObj.get('variableMessage').ifString()?.isEmpty()
+
+    if (hasMessageType && !hasMessage) {
+        diagnostics.error(
+            actionObj.get('variableMessageType'),
+            `'variableMessage' is required when 'variableMessageType' is specified. Provide a message to display on the field.`
+        )
+        return false
+    }
+
+    if (hasMessage && !hasMessageType) {
+        diagnostics.error(
+            actionObj.get('variableMessage'),
+            `'variableMessageType' is required when 'variableMessage' is specified. Provide a message type (info, warning, or error).`
+        )
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Validates that 'field' is provided when 'mapToField' is true in a variable config.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateMapToFieldRequiresField(config: ObjectShape, diagnostics: Diagnostics): boolean {
+    const mapToField = config.get('mapToField')
+    const isMapToFieldTrue = mapToField.isDefined() && mapToField.ifBoolean()?.getValue() === true
+    const hasField = config.get('field').isDefined() && !config.get('field').ifString()?.isEmpty()
+
+    if (isMapToFieldTrue && !hasField) {
+        diagnostics.error(mapToField, `'field' is required when 'mapToField' is true. Specify the field to map to.`)
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Validates that mandatory is not true when hidden or readOnly is true, and vice versa.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateMandatoryReadOnlyHidden(config: ObjectShape, diagnostics: Diagnostics): boolean {
+    const isMandatory = config.get('mandatory').isDefined() && config.get('mandatory').ifBoolean()?.getValue() === true
+    const isReadOnly = config.get('readOnly').isDefined() && config.get('readOnly').ifBoolean()?.getValue() === true
+    const isHidden = config.get('hidden').isDefined() && config.get('hidden').ifBoolean()?.getValue() === true
+
+    if (isMandatory && isReadOnly) {
+        diagnostics.error(
+            config.get('mandatory'),
+            `'mandatory' cannot be true when 'readOnly' is true. A field cannot be both required and read-only.`
+        )
+        return false
+    }
+
+    if (isMandatory && isHidden) {
+        diagnostics.error(
+            config.get('mandatory'),
+            `'mandatory' cannot be true when 'hidden' is true. A field cannot be both required and hidden.`
+        )
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Validates lookup variable configuration: table-based and choice-based properties are mutually exclusive,
+ * and price fields are not allowed when uniqueValuesOnly is true.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateLookupSourceExclusivity(config: ObjectShape, diagnostics: Diagnostics): boolean {
+    const lookupSource = config.get('lookupSource')
+    const lookupSourceValue = lookupSource?.ifString()?.getValue()
+    const hasLookupSource = lookupSource.isDefined() && !lookupSource.ifString()?.isEmpty()
+    const hasLookupFromTable =
+        config.get('lookupFromTable').isDefined() && !config.get('lookupFromTable').ifString()?.isEmpty()
+    const hasLookupValueField =
+        config.get('lookupValueField').isDefined() && !config.get('lookupValueField').ifString()?.isEmpty()
+
+    const isChoicesSource = hasLookupSource && lookupSourceValue === 'choices'
+
+    if (isChoicesSource) {
+        if (hasLookupFromTable) {
+            diagnostics.error(
+                config.get('lookupFromTable'),
+                `'lookupFromTable' should not be specified when 'lookupSource' is 'choices'.`
+            )
+            return false
+        }
+
+        if (hasLookupValueField) {
+            diagnostics.error(
+                config.get('lookupValueField'),
+                `'lookupValueField' should not be specified when 'lookupSource' is 'choices'.`
+            )
+            return false
+        }
+
+        return true
+    }
+
+    const requiredNode = lookupSource.isDefined() ? lookupSource : config
+
+    if (!hasLookupFromTable) {
+        diagnostics.error(requiredNode, `'lookupFromTable' is required when 'lookupSource' is not 'choices'.`)
+        return false
+    }
+
+    if (!hasLookupValueField) {
+        diagnostics.error(requiredNode, `'lookupValueField' is required when 'lookupSource' is not 'choices'.`)
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Validates reference qualifier fields are mutually exclusive and consistent with useReferenceQualifier.
+ * referenceQualCondition, dynamicRefQual, and referenceQual are mutually exclusive.
+ * Returns true if valid, false if a diagnostic was emitted.
+ */
+export function validateReferenceQualifierExclusivity(
+    config: ObjectShape,
+    diagnostics: Diagnostics,
+    context: string
+): boolean {
+    const hasRefQualCondition =
+        config.get('referenceQualCondition').isDefined() && !config.get('referenceQualCondition').ifString()?.isEmpty()
+    const hasDynamicRefQual =
+        config.get('dynamicRefQual').isDefined() && !config.get('dynamicRefQual').ifString()?.isEmpty()
+    const hasRefQual = config.get('referenceQual').isDefined() && !config.get('referenceQual').ifString()?.isEmpty()
+
+    const useRefQualShape = config.get('useReferenceQualifier')
+    const useRefQual = useRefQualShape?.ifString()?.getValue()
+
+    if ((useRefQual === 'simple' || useRefQualShape.ifString()?.isEmpty()) && !hasRefQualCondition) {
+        diagnostics.error(
+            useRefQualShape,
+            `${context}: 'referenceQualCondition' is required when 'useReferenceQualifier' is 'simple'.`
+        )
+        return false
+    }
+
+    if (useRefQual === 'dynamic' && !hasDynamicRefQual) {
+        diagnostics.error(
+            useRefQualShape,
+            `${context}: 'dynamicRefQual' is required when 'useReferenceQualifier' is 'dynamic'.`
+        )
+        return false
+    }
+
+    if (useRefQual === 'advanced' && !hasRefQual) {
+        diagnostics.error(
+            useRefQualShape,
+            `${context}: 'referenceQual' is required when 'useReferenceQualifier' is 'advanced'.`
+        )
+        return false
+    }
+
+    return true
+}

package/src/service-catalog/shape-to-record.ts

@@ -0,0 +1,279 @@
+import {
+    CallExpressionShape,
+    type Record,
+    type Factory,
+    type ObjectShape,
+    type Diagnostics,
+} from '@servicenow/sdk-build-core'
+import { getVariableTypeFromName } from './variable-helper'
+import { VariableTypeName } from './variable-helper'
+import { convertRolesToString, getVisibilityId, validateFieldNameBelongsToTable } from './utils'
+import {
+    validateMapToFieldRequiresField,
+    validateMandatoryReadOnlyHidden,
+    validateLookupSourceExclusivity,
+    validateReferenceQualifierExclusivity,
+} from './service-catalog-diagnostics'
+
+export async function buildVariableRecords(options: {
+    factory: Factory
+    diagnostics: Diagnostics
+    variablesConfig: ObjectShape
+    parent: Record
+    parentArg?: ObjectShape
+}): Promise<Record[]> {
+    const { variablesConfig, factory, parent, diagnostics, parentArg } = options
+    const records: Record[] = []
+    let catItemRecord: Record
+    let variableSetRecord: Record
+    if (parent?.getTable() === 'sc_cat_item' || parent?.getTable() === 'sc_cat_item_producer') {
+        catItemRecord = parent
+    }
+    if (parent?.getTable() === 'item_option_new_set') {
+        variableSetRecord = parent
+    }
+    if (parent?.getTable() === 'sc_cat_item_producer' && parentArg) {
+        validateFieldNameBelongsToTable(parentArg, diagnostics, 'RecordProducer')
+    }
+
+    // Convert entries to array to use for-of loop
+    const entries = Array.from(variablesConfig.entries())
+
+    // Use for-of loop with await instead of forEach
+    for (const [k, v] of entries) {
+        const callExpr = v.as(CallExpressionShape)
+        const calleeName = callExpr.getCallee()
+        const variable = callExpr.getArgument(0)
+        if (!variable.isObject() || !variable.asObject().isDefined()) {
+            continue
+        }
+        const config = variable.asObject()
+
+        // Validate mapToField/field consistency (applies to all non-minimal variables)
+        if (
+            calleeName !== VariableTypeName.BREAK &&
+            calleeName !== VariableTypeName.CONTAINER_END &&
+            calleeName !== VariableTypeName.CONTAINER_SPLIT
+        ) {
+            validateMapToFieldRequiresField(config, diagnostics)
+        }
+
+        // Validate mandatory/readOnly/hidden consistency (applies to interactive variables)
+        if (
+            calleeName !== VariableTypeName.BREAK &&
+            calleeName !== VariableTypeName.CONTAINER_END &&
+            calleeName !== VariableTypeName.CONTAINER_SPLIT &&
+            calleeName !== VariableTypeName.CONTAINER_START &&
+            calleeName !== VariableTypeName.LABEL &&
+            calleeName !== VariableTypeName.RICH_TEXT_LABEL &&
+            calleeName !== VariableTypeName.CUSTOM &&
+            calleeName !== VariableTypeName.CUSTOM_WITH_LABEL &&
+            calleeName !== VariableTypeName.UI_PAGE
+        ) {
+            validateMandatoryReadOnlyHidden(config, diagnostics)
+        }
+
+        // Validate lookup source exclusivity (applies to lookup variables)
+        if (
+            calleeName === VariableTypeName.LOOKUP_SELECT_BOX ||
+            calleeName === VariableTypeName.LOOKUP_MULTIPLE_CHOICE
+        ) {
+            validateLookupSourceExclusivity(config, diagnostics)
+        }
+
+        // Validate reference qualifier exclusivity (applies to reference and requested-for variables)
+        if (calleeName === VariableTypeName.REFERENCE) {
+            validateReferenceQualifierExclusivity(config, diagnostics, 'ReferenceVariable')
+        }
+        if (calleeName === VariableTypeName.REQUESTED_FOR) {
+            validateReferenceQualifierExclusivity(config, diagnostics, 'RequestedForVariable')
+        }
+
+        const useEncryption =
+            calleeName === VariableTypeName.MASKED ? (config.get('useEncryption')?.getValue() ?? true) : false
+        const varType = getVariableTypeFromName(calleeName)
+
+        const referenceTable =
+            calleeName === VariableTypeName.REQUESTED_FOR ? 'sys_user' : config.get('referenceTable')?.getValue()
+
+        const useReferenceQualifier =
+            calleeName === VariableTypeName.LIST_COLLECTOR ||
+            calleeName === VariableTypeName.LOOKUP_SELECT_BOX ||
+            calleeName === VariableTypeName.LOOKUP_MULTIPLE_CHOICE
+                ? 'advanced'
+                : 'simple'
+
+        const props = callExpr
+            .getArgument(0)
+            .asObject()
+            .transform(({ $ }) => ({
+                name: $.val(k),
+                type: $.val(varType).def(6),
+                question_text: $.from('question').def(''),
+                order: $.def(0),
+                active: $.from('active').toBoolean().def(true),
+                mandatory: $.from('mandatory').toBoolean().def(false),
+                read_only: $.from('readOnly').toBoolean().def(false),
+                hidden: $.from('hidden').toBoolean().def(false),
+                disable_initial_slot_fill: $.from('disableInitialSlotFill').toBoolean().def(false),
+                conversational_label: $.from('conversationalLabel').def(''),
+                layout: $.from('layout').def('normal'),
+                tooltip: $.from('tooltip').def(''),
+                example_text: $.from('exampleText').def(''),
+                show_help: $.from('showHelp').toBoolean().def(false),
+                help_tag: $.from('helpTag').def('More information'),
+                help_text: $.from('helpText').def(''),
+                instructions: $.from('instructions').def('').toCdata(),
+                variable_width: $.from('width').def(''),
+                attributes: $.from('attributes').def(''),
+                default_value: $.from('defaultValue').def(''),
+                read_roles: $.from('readRoles').map(convertRolesToString).def([]),
+                write_roles: $.from('writeRoles').map(convertRolesToString).def([]),
+                create_roles: $.from('createRoles').map(convertRolesToString).def([]),
+                delete_roles: $.from('deleteRoles').map(convertRolesToString).def([]),
+                cat_item: $.val(catItemRecord).def(''),
+                variable_set: $.val(variableSetRecord).def(''),
+                reference: $.val(referenceTable).def(''),
+                visible_standalone: $.from('visibleStandalone').toBoolean().def(true),
+                visible_summary: $.from('visibleSummary').toBoolean().def(true),
+                visible_guide: $.from('visibleGuide').toBoolean().def(true),
+                visible_bundle: $.from('visibleBundle').toBoolean().def(true),
+                not_available_conversation: $.from('removeFromConversationalInterfaces').toBoolean().def(false),
+                display_title: $.from('displayTitle').toBoolean().def(false),
+                macro: $.from('macro').def(''),
+                summary_macro: $.from('summaryMacro').def(''),
+                sp_widget: $.from('widget').def(''),
+                macroponent: $.from('macroponent').def(''),
+                topic_block: $.from('topicBlock').def(''),
+                list_table: $.from('listTable').def(''),
+                reference_qual: $.from('referenceQual').def(''),
+                lookup_source: $.from('lookupSource').def(''),
+                lookup_table: $.from('lookupFromTable').def(''),
+                lookup_value: $.from('lookupValueField').def(''),
+                lookup_label: $.from('lookupLabelFields')
+                    .def([])
+                    .map((fields) => (Array.isArray(fields) ? fields.join(',') : fields))
+                    .def(''),
+                lookup_price: $.from('lookupPriceField').def(''),
+                rec_lookup_price: $.from('lookupRecurringPriceField').def(''),
+                choice_table: $.from('choiceTable').def(''),
+                choice_field: $.from('choiceField').def(''),
+                lookup_dependent_question: $.from('choicesDependOn').def(''),
+                choice_direction: $.from('choiceDirection').def('down'),
+                include_none: $.from('includeNone').toBoolean().def(false),
+                lookup_unique: $.from('uniqueValuesOnly').toBoolean().def(false),
+                mask_use_confirmation: $.from('useConfirmation').toBoolean().def(false),
+                mask_use_encryption: $.val(useEncryption).toBoolean().def(false),
+                do_not_select_first: $.from('doNotSelectFirstChoice').toBoolean().def(false),
+                scale_min: $.from('scaleMin').def(0),
+                scale_max: $.from('scaleMax').def(5),
+                use_reference_qualifier: $.from('useReferenceQualifier').def(useReferenceQualifier),
+                reference_qual_condition: $.from('referenceQualCondition').def(''),
+                dynamic_ref_qual: $.from('dynamicRefQual').def(''),
+                enable_also_request_for: $.from('enableAlsoRequestFor').toBoolean().def(false),
+                rich_text: $.from('richText').toCdata().def(''),
+                validate_regex: $.from('validateRegex').def(''),
+                ui_page: $.from('uiPage').def(''),
+                default_html_value: $.from('defaultHTML').toCdata().def(''),
+                map_to_field: $.from('mapToField').toBoolean().def(false),
+                field: $.from('field').def(''),
+                delivery_plan: $.from('deliveryPlan').def(''),
+                visibility: $.from('visibility')
+                    .map((v) => (v.isString() ? getVisibilityId(v.getValue()) : undefined))
+                    .def(1),
+                roles_to_use_also_request_for: $.from('rolesToUseAlsoRequestFor').map(convertRolesToString).def([]),
+                category: $.from('category').def(''),
+                pricing_implications: $.from('pricingImplications').toBoolean().def(false),
+                show_help_on_load: $.from('alwaysExpand').toBoolean().def(false),
+                use_dynamic_default: $.from('useDynamicDefault').toBoolean().def(false),
+                // save_script: $.from('saveScript').toCdata().def(DEFAULT_SAVE_SCRIPT),
+                read_script: $.from('readScript').toCdata().def(''),
+                post_insert_script: $.from('postInsertScript').toCdata().def(''),
+                unique: $.def(false),
+                global: $.toBoolean().def(false),
+                description: $.toCdata().def(''),
+                dynamic_value_dot_walk_path: $.from('dotWalkPath').def(''),
+                dynamic_value_field: $.from('dependentQuestion').def(''),
+            }))
+
+        const varRecord = await factory.createRecord({
+            source: callExpr,
+            table: 'item_option_new',
+            properties: props,
+        })
+        const varPricingDetails = config.get('pricingDetails').ifArray()?.getElements() ?? []
+        const varPricingDetailsRecords: Record[] = []
+        for (const pricingDetail of varPricingDetails) {
+            const pricingDetailObj = pricingDetail.asObject()
+            varPricingDetailsRecords.push(
+                await factory.createRecord({
+                    source: callExpr,
+                    table: 'fx_price',
+                    properties: {
+                        id: varRecord.getId().getValue(),
+                        field: pricingDetailObj.get('field').getValue(),
+                        amount: pricingDetailObj.get('amount').getValue(),
+                        currency: pricingDetailObj.get('currencyType').getValue(),
+                        type: 'calculated',
+                        table: 'item_option_new',
+                    },
+                })
+            )
+        }
+        if (
+            (calleeName === VariableTypeName.MULTIPLE_CHOICE || calleeName === VariableTypeName.SELECT_BOX) &&
+            config.get('choices').isDefined()
+        ) {
+            const choices = config.get('choices').asObject()
+            const entries = Array.from(choices.entries())
+            const choiceRecords: Record[] = []
+
+            // Use a regular for loop instead of forEach to handle async operations
+            for (const [key, value] of entries) {
+                const choiceObj = value.asObject()
+                const choiceProps = choiceObj.transform(({ $ }) => ({
+                    value: $.val(key),
+                    text: $.from('label').def(key),
+                    inactive: $.from('inactive').toBoolean().def(false),
+                    order: $.from('sequence').def(0),
+                    question: $.val(varRecord).def(''),
+                }))
+
+                const choiceRecord = await factory.createRecord({
+                    source: callExpr,
+                    table: 'question_choice',
+                    properties: choiceProps,
+                })
+
+                const pricingDetails = choiceObj.get('pricingDetails').ifArray()?.getElements() ?? []
+                const pricingDetailsRecords: Record[] = []
+                for (const pricingDetail of pricingDetails) {
+                    const pricingDetailObj = pricingDetail.asObject()
+                    pricingDetailsRecords.push(
+                        await factory.createRecord({
+                            source: callExpr,
+                            table: 'fx_price',
+                            properties: {
+                                id: choiceRecord.getId().getValue(),
+                                amount: pricingDetailObj.get('amount')?.getValue(),
+                                currency: pricingDetailObj.get('currencyType')?.getValue(),
+                                type: 'calculated',
+                                field: pricingDetailObj.get('field')?.getValue(),
+                                table: 'question_choice',
+                            },
+                        })
+                    )
+                }
+                choiceRecords.push(choiceRecord.with(...pricingDetailsRecords))
+            }
+
+            // Now that all choiceRecords are created, add them to the varRecord
+            records.push(varRecord.with(...choiceRecords))
+        } else {
+            records.push(varRecord)
+        }
+        records.push(...varPricingDetailsRecords)
+    }
+
+    return records
+}