@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/flow-io-to-record.ts

@@ -0,0 +1,533 @@
+import {
+    CallExpressionShape,
+    type Logger,
+    type Database,
+    type Diagnostics,
+    type Factory,
+    type ObjectShape,
+    type Record,
+} from '@servicenow/sdk-build-core'
+import {
+    addFieldsToColumn,
+    COLUMN_API_TO_TYPE,
+    COLUMN_TYPE_TO_API,
+    getDefaultMaxLength,
+} from '../../column/column-helper'
+import { ChoiceColumn, choiceDropdown, type choiceDropdownType, GenericColumn } from '@servicenow/sdk-core/runtime/db'
+import { builtInComplexObjects } from './built-in-complex-objects'
+import { buildComplexObjectFromSchema, parseAttributesToObject } from './schema-to-flow-object'
+import {
+    formatComplexObjectAttributes,
+    generateSchemaFromObject,
+    generateVariableSchemaObject,
+    getComplexObjectAttributes,
+} from './complex-objects'
+import { getChoiceRecords, getDocumentationRecords } from '../../column/column-to-record'
+
+import { ChoiceDropdown, COLUMN_DEFAULTS, createActionErrorAndStatusRecords } from './flow-constants'
+import { NowIdShape } from '../../now-id-plugin'
+
+/**
+ * Helper function to extract user-defined attributes from a column config's attributes object.
+ * Handles string, number, and boolean values.
+ *
+ * @param config - The ObjectShape containing the column configuration
+ * @returns A Record of attribute key-value pairs (all values converted to strings)
+ */
+function extractUserAttributes(config: ObjectShape): globalThis.Record<string, string> {
+    const userAttributes: globalThis.Record<string, string> = {}
+    const userAttributesObj = config.get('attributes')?.ifObject()?.asObject()
+
+    if (userAttributesObj) {
+        const entries = userAttributesObj.entries()
+        for (const [key, value] of entries) {
+            userAttributes[key] = value.getValue()?.toString() ?? ''
+        }
+    }
+
+    return userAttributes
+}
+
+/**
+ * Generate the variable records and possibly complex object records for the inputs or outputs
+ * of an action/subflow. The main input here is the ObjectShape for a single set of inputs or outputs
+ * of an action/subflow definition.
+ */
+export async function buildVariableRecords(options: {
+    variablesConfig: ObjectShape
+    parentRecord: Record
+    factory: Factory
+    diagnostics: Diagnostics
+    parentTable: string
+    varTable: string
+    isOutput?: boolean
+}): Promise<{ variableRecords: Record[]; complexObjectRecords: Record[] }> {
+    const { variablesConfig, parentRecord, factory, diagnostics, parentTable, varTable, isOutput = false } = options
+
+    const records: Record[] = []
+    const complexObjects: Record[] = []
+
+    const tableName = `var__m_${varTable}_${parentRecord.getId().getValue()}`
+    const entries = variablesConfig.entries()
+    for (const [i, [k, v]] of entries.entries()) {
+        const callExpr = v.as(CallExpressionShape)
+        const config = callExpr.getArgument(0).asObject()
+        const props = config.transform(({ $ }) => ({
+            element: $.val(k),
+            label: $.def(k),
+            mandatory: $.toBoolean().def(false),
+            active: $.val(true),
+            order: $.val(i + 1),
+            hint: $.def(''),
+            model: $.val(parentRecord),
+            model_id: $.val(parentRecord),
+            model_table: $.val(parentTable),
+            name: $.val(tableName),
+            default_value: $.from('default').def(''),
+        }))
+        const partialVarRecord = await factory.createRecord({
+            source: callExpr,
+            table: varTable,
+            properties: props,
+        })
+
+        const additionalProperties: globalThis.Record<string, unknown> = {}
+        const varSysId = partialVarRecord.getId().getValue()
+        if (callExpr.getCallee() === 'FlowObject' || callExpr.getCallee() === 'FlowArray') {
+            // Create a new complex-object schema row
+            const co_type_name = config.get('co_type_name')?.ifString()?.getValue()
+            const complexObjectId = co_type_name || `FD${varSysId}`
+            const isArray = callExpr.getCallee() === 'FlowArray'
+            const isFlowVariable = varTable === 'sys_hub_flow_variable'
+            const schemaObj = generateSchemaFromObject(
+                config,
+                complexObjectId,
+                k,
+                parentRecord.getId().getValue(),
+                i,
+                isArray,
+                diagnostics,
+                isFlowVariable
+            )
+
+            // Use explicit $id from config if provided (for non-deterministic complex objects from UI)
+            const explicitId = config.get('$id')?.ifString()?.getValue()
+
+            const complexRecord = await factory.createRecord({
+                source: callExpr,
+                table: 'sys_complex_object',
+                properties: {
+                    name: complexObjectId,
+                    namespace: 'FlowDesigner',
+                    type: callExpr.getCallee() === 'FlowArray' ? 'complex_object_collection' : 'complex_object_schema',
+                    serialized_content: JSON.stringify(schemaObj),
+                    ...(explicitId ? { sys_id: explicitId } : {}),
+                },
+            })
+
+            const systemAttributes = getComplexObjectAttributes(schemaObj, complexObjectId, isArray)
+            // Extract user-defined attributes from column config if present (e.g., visible: 'false')
+            const userAttributes = extractUserAttributes(config)
+            // Merge system attributes with user-defined attributes
+            const allAttributes = { ...systemAttributes, ...userAttributes }
+            additionalProperties['attributes'] = formatComplexObjectAttributes(allAttributes)
+            additionalProperties['internal_type'] = 'string'
+            additionalProperties['max_length'] = 65000
+
+            complexObjects.push(complexRecord)
+
+            // Create additional sys_variable_value record for FlowObject and FlowArray types, but only for outputs
+            if (isOutput) {
+                const variableValue = generateVariableSchemaObject(schemaObj, complexObjectId, isArray)
+                const variableValueRecord = await createVariableValueRecord({
+                    callExpr,
+                    factory,
+                    varSysId,
+                    parentRecord,
+                    parentTable,
+                    name: k,
+                    index: i,
+                    variableValue,
+                })
+                records.push(variableValueRecord)
+            }
+            const updatedCallExpr = addFieldsToColumn({ name: k, table: tableName, display: false }, callExpr)
+            const columnRecords = await getDocumentationRecords(updatedCallExpr, {}, factory, diagnostics, true)
+            records.push(...columnRecords)
+        } else {
+            // Extract attributes from column config if present
+            const userAttributes = extractUserAttributes(config)
+            const attributesStr = Object.entries(userAttributes)
+                .map(([key, value]) => `${key}=${value}`)
+                .join(',')
+            additionalProperties['attributes'] = attributesStr
+            let internal_type: string
+            if (callExpr.getCallee() === GenericColumn.name) {
+                internal_type = config.get('columnType')?.ifString()?.getValue() ?? 'string'
+            } else {
+                internal_type = COLUMN_API_TO_TYPE[callExpr.getCallee() as keyof typeof COLUMN_API_TO_TYPE] ?? 'string'
+            }
+            // Handle reference columns - extract reference table
+            if (internal_type === 'reference') {
+                const referenceTable = config.get('referenceTable')?.ifString()?.getValue()
+                if (referenceTable) {
+                    additionalProperties['reference'] = referenceTable
+                }
+            }
+            additionalProperties['internal_type'] = internal_type
+            additionalProperties['max_length'] =
+                config.get('maxLength')?.ifNumber()?.getValue() ?? getDefaultMaxLength(internal_type)
+            const updatedCallExpr = addFieldsToColumn({ name: k, table: tableName, display: false }, callExpr)
+            const columnRecords = await getColumnRecords(updatedCallExpr, factory, diagnostics)
+            records.push(...columnRecords)
+
+            if (internal_type === 'choice') {
+                validateAndPopulateChoiceProperties(config, additionalProperties, diagnostics)
+            }
+        }
+
+        const varRecord = partialVarRecord.merge(additionalProperties)
+        records.push(varRecord)
+    }
+
+    if (isOutput) {
+        const additionalOutputs = await createActionErrorAndStatusRecords(
+            parentRecord,
+            tableName,
+            varTable,
+            factory,
+            diagnostics
+        )
+        records.push(...additionalOutputs)
+    }
+
+    return { variableRecords: records, complexObjectRecords: complexObjects }
+}
+
+/**
+ * Generate an object corresponding to the variable records passed in.
+ *
+ * For each variable record passed in there will be a key/value in the return value where
+ * the key is the element name of the variable record and the value is a call expression corresponding
+ * to the details of that variable record. The call expressions match the FlowValueType and can be
+ * a Column or a FlowObject (FlowArrays are currently not yet handled)
+ *
+ * If the variable record has a co_object_name attribute we will lookup a corresponding sys_complex_object
+ * record where the name field matches the attributes value. That complex object record will hold the schema
+ * for this object input in the serialized_content column. We use that data to construct the related call expression
+ * data for the full flow object definition
+ *
+ * @param variableRecords Records representing inputs or outputs (sys_hub_*_input / output)
+ * @param ctx              Plugin context object supplied by build-core plugin
+ */
+export function buildVariableShapes(
+    variableRecords: Record[],
+    descendants: Database,
+    logger?: Logger
+): globalThis.Record<string, CallExpressionShape> | undefined {
+    const shapes: globalThis.Record<string, CallExpressionShape> = {}
+
+    for (const variable of variableRecords) {
+        const name = variable.get('element').asString().getValue()
+
+        if (name === '__action_status__' || name === '__dont_treat_as_error__') {
+            continue
+        }
+
+        const callExpressionName =
+            COLUMN_TYPE_TO_API[variable.get('internal_type').asString().getValue()] ?? GenericColumn.name
+        const additionalProps = {}
+
+        // Detect FlowObject variables by looking for a co_type_name attribute.
+        const attributesStr = variable.get('attributes')?.ifString()?.getValue() ?? ''
+        const attributes = parseAttributesToObject(attributesStr)
+
+        if (attributes.dynamic === 'true') {
+            logger?.warn(`Unsupported data type found for input = ${name}, falling back to Record() api`)
+            return undefined
+        }
+
+        const maybeCoTypeName = attributes.co_type_name
+        if (maybeCoTypeName !== undefined) {
+            const coRecord = descendants.query('sys_complex_object', { name: maybeCoTypeName })
+
+            // First try descendants, then fallback to built-in complex objects
+            let serializedContent = coRecord[0]?.get('serialized_content')?.ifString()?.getValue()
+            let complexObjectSysId: string | undefined = coRecord[0]?.getId().getValue()
+            if (!serializedContent) {
+                // Check built-in complex objects
+                const builtIn = builtInComplexObjects[maybeCoTypeName]
+                serializedContent = builtIn?.data.serialized_content
+                complexObjectSysId = undefined // Built-in objects don't have a sys_id
+            }
+
+            if (!serializedContent) {
+                throw new Error(`unable to find sys_complex_object with co_type_name: ${maybeCoTypeName}`)
+            }
+
+            // Check if co_type_name is deterministically generated (pattern: FD<variable_sys_id>)
+            const varSysId = variable.getId().getValue()
+            const isDeterministic = maybeCoTypeName === `FD${varSysId}`
+
+            // Only include $id and co_type_name if NOT deterministically generated
+            const schema = JSON.parse(serializedContent)
+            shapes[name] = buildComplexObjectFromSchema(
+                variable,
+                schema,
+                attributes,
+                isDeterministic ? undefined : complexObjectSysId,
+                isDeterministic ? undefined : maybeCoTypeName
+            )
+        } else {
+            const variableName = variable.get('name').ifString()?.getValue()
+            const documentation = variableName
+                ? descendants.query('sys_documentation', { name: variableName, element: name })
+                : []
+
+            shapes[name] = buildBasicVariableShape(
+                callExpressionName,
+                variable,
+                additionalProps,
+                descendants,
+                documentation
+            )
+        }
+    }
+
+    return shapes
+}
+
+function buildBasicVariableShape(
+    callExpressionName: string,
+    variable: Record,
+    additionalProps: globalThis.Record<string, unknown>,
+    descendants: Database,
+    documentation: Record[]
+) {
+    if (callExpressionName === ChoiceColumn.name) {
+        // choice column with choices from other table
+        const choiceTable = variable.get('choice_table').ifString()?.getValue()
+        if (choiceTable && choiceTable !== '') {
+            additionalProps = {
+                dynamicValueDefinitions: {
+                    type: 'choices_from_other_table',
+                    table: choiceTable,
+                    field: variable.get('choice_field').asString().getValue(),
+                },
+            }
+        } else {
+            const name = variable.get('name').ifString()?.getValue()
+            const element = variable.get('element').ifString()?.getValue()
+            const choices = descendants.query('sys_choice', { name, element })
+            additionalProps = {
+                choices: choices.reduce<
+                    globalThis.Record<string, { label?: string | undefined; sequence?: number | undefined }>
+                >((acc, choice) => {
+                    const value = choice.get('value').ifString()?.getValue()
+                    const sequence = Number(choice.get('sequence').ifString()?.getValue() ?? 0)
+                    if (!value || value === '-- None --') {
+                        return acc
+                    }
+                    const entry: { label?: string | undefined; sequence?: number | undefined } = {
+                        label: choice.get('label').ifString()?.getValue(),
+                    }
+                    if (sequence !== 0) {
+                        entry.sequence = sequence
+                    }
+                    acc[value] = entry
+                    return acc
+                }, {}),
+            }
+        }
+    }
+
+    const fieldType = variable.get('internal_type').ifString()?.getValue() ?? 'string'
+    const defaultMaxLength = getDefaultMaxLength(fieldType)
+    const maxLength = Number(variable.get('max_length').ifString()?.getValue() ?? defaultMaxLength)
+    const hint = documentation[0]?.get('hint')?.ifString()?.getValue() ?? ''
+
+    // Extract referenceTable for reference and records column types
+    const referenceTable = variable.get('reference')?.ifString()?.getValue()
+    if (referenceTable && (fieldType === 'reference' || fieldType === 'records')) {
+        additionalProps['referenceTable'] = referenceTable
+    }
+
+    // Add dependent field for template_value and field_list column types
+    if (fieldType === 'template_value' || fieldType === 'field_list') {
+        const dependent = variable.get('dependent')?.ifString()?.getValue()
+        additionalProps['dependent'] = dependent ?? ''
+    }
+
+    return new CallExpressionShape({
+        source: variable,
+        callee: callExpressionName,
+        args: [
+            variable
+                .transform(({ $ }) => ({
+                    label: $,
+                    ...(variable.getTable() === 'sys_flow_step_definition_output' ||
+                    variable.getTable() === 'sys_flow_step_definition_input'
+                        ? { sysId: $.val(NowIdShape.from(variable)) }
+                        : {}),
+                    mandatory: $.toBoolean().def(false),
+                    maxLength: $.val(maxLength).def(defaultMaxLength),
+                    dropdown: $.from('choice')
+                        .map((choice) => (choice.isNumber() ? choiceDropdown[choice.getValue()] : undefined))
+                        .def(choiceDropdown[1]),
+                    default: $.from('default_value')
+                        .map((value) => {
+                            if (!value.isDefined()) {
+                                return undefined
+                            }
+
+                            if (fieldType === 'string') {
+                                return value.toString().getValue()
+                            }
+                            if (fieldType === 'boolean') {
+                                return Boolean(value.getValue())
+                            }
+                            if (fieldType === 'integer') {
+                                return Number(value.getValue())
+                            }
+                            return value.getValue()
+                        })
+                        .def(COLUMN_DEFAULTS[fieldType as keyof typeof COLUMN_DEFAULTS] ?? ''),
+                    ...(hint ? { hint: $.val(hint) } : {}),
+                    columnType: $.from('internal_type')
+                        .map((fieldType) => {
+                            if (callExpressionName === GenericColumn.name) {
+                                return fieldType
+                            }
+                            return undefined
+                        })
+                        .def(undefined),
+                }))
+                .merge(additionalProps),
+        ],
+    })
+}
+
+/**
+ * Creates a sys_variable_value record for FlowObject and FlowArray types
+ */
+async function createVariableValueRecord(options: {
+    callExpr: CallExpressionShape
+    factory: Factory
+    varSysId: string
+    parentRecord: Record
+    parentTable: string
+    name: string
+    index: number
+    variableValue: object
+}): Promise<Record> {
+    const { callExpr, factory, varSysId, parentRecord, parentTable, name, index, variableValue } = options
+
+    return await factory.createRecord({
+        source: callExpr,
+        table: 'sys_variable_value',
+        properties: {
+            document: parentTable,
+            document_key: parentRecord.getId().getValue(),
+            value: JSON.stringify(variableValue),
+            order: index + 1,
+            name,
+            variable: varSysId,
+        },
+    })
+}
+
+export async function getColumnRecords(
+    callExpression: CallExpressionShape,
+    factory: Factory,
+    diagnostics: Diagnostics
+) {
+    // Verify
+    const callee = callExpression.getCallee()
+    if (!(callee in COLUMN_API_TO_TYPE) && !(callee === GenericColumn.name)) {
+        return []
+    }
+
+    const column = callExpression.getArgument(0).asObject()
+    if (!column.has('table') || !column.has('name')) {
+        return []
+    }
+
+    const choiceRecords = await getChoiceRecords(callExpression, {}, factory, diagnostics)
+    const documentationRecords = await getDocumentationRecords(callExpression, {}, factory, diagnostics, true)
+    return [...choiceRecords, ...documentationRecords]
+}
+
+/**
+ * Validates and populates choice properties for dynamic value definitions
+ * that use choices from other tables
+ */
+function validateAndPopulateChoiceProperties(
+    config: ObjectShape,
+    additionalProperties: globalThis.Record<string, unknown>,
+    diagnostics: Diagnostics
+) {
+    // Check if dynamic value definitions exist
+    const dynamicValueDefs = config.has('dynamicValueDefinitions')
+        ? config.get('dynamicValueDefinitions').asObject()
+        : undefined
+
+    if (dynamicValueDefs) {
+        // Validate type is 'choices_from_other_table'
+        const type = dynamicValueDefs.get('type')
+        if (!type.isString() || type.getValue() !== 'choices_from_other_table') {
+            diagnostics.error(type, 'Invalid dynamicValueDefinitions type, expected "choices_from_other_table"')
+            return
+        }
+
+        // Populate required choice properties
+        additionalProperties['choice_table'] = dynamicValueDefs.get('table').getValue()
+        additionalProperties['choice_field'] = dynamicValueDefs.get('field').getValue()
+    }
+
+    // Default to dropdown_with_none
+    let choiceValue = ChoiceDropdown.DROPDOWN_WITHOUT_NONE
+
+    // Handle dropdown type configuration
+    const defaultValue = config.get('default')
+    const choiceTypeNode = config.get('dropdown')
+
+    if (choiceTypeNode.isString()) {
+        const choiceTypeValue = choiceTypeNode.getValue() as choiceDropdownType
+        const choiceDropdownValue = choiceDropdown.indexOf(choiceTypeValue)
+
+        if (choiceDropdownValue === ChoiceDropdown.DROPDOWN_WITHOUT_NONE) {
+            // Validate default value exists for dropdown_without_none
+            if (defaultValue.isUndefined()) {
+                diagnostics.error(config, 'Default value is required for dropdown type "dropdown_without_none"')
+                return
+            }
+            choiceValue = ChoiceDropdown.DROPDOWN_WITHOUT_NONE
+        } else if (choiceDropdownValue !== ChoiceDropdown.DROPDOWN_WITH_NONE) {
+            // Only dropdown_with_none and dropdown_without_none are valid
+            diagnostics.error(
+                choiceTypeNode,
+                'Invalid dropdown type, expected "dropdown_with_none" or "dropdown_without_none"'
+            )
+            return
+        } else {
+            choiceValue = choiceDropdownValue
+        }
+    }
+
+    // Set the choice value
+    additionalProperties['choice'] = choiceValue
+
+    // Add default value if provided
+    if (!defaultValue.isUndefined()) {
+        additionalProperties['default_value'] = defaultValue.getValue()
+    }
+}
+
+/**
+ * Via regex matcher for sys_complex_object relationships that checks if the parent's
+ * co_type_name attribute matches the child's name field.
+ */
+export const complexObjectMatchesIoRecord: { parent: [string, string]; child: [string, string] } = {
+    parent: ['attributes', 'co_type_name=([^,]+)'],
+    child: ['name', '(.+)'],
+}