@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/complex-objects.ts

@@ -0,0 +1,656 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: This file builds dynamic complex object schemas
+import { CallExpressionShape, type ObjectShape, type Diagnostics } from '@servicenow/sdk-build-core'
+
+import { COLUMN_API_TO_TYPE } from '../../column/column-helper'
+import { ELEMENT_MAPPING_PROVIDER } from './flow-constants'
+
+const ALLOWED_ARRAY_TYPES = ['String', 'Integer', 'Boolean', 'Date', 'Reference']
+const ALLOWED_OBJECT_TYPES = ['Choice', 'String', 'Integer', 'Boolean', 'Date', 'Reference']
+
+/**
+ * Maps column types to their corresponding schema types
+ */
+const COLUMN_TYPE_TO_SCHEMA_TYPE = {
+    string: 'String',
+    object: 'Object',
+    integer: 'Integer',
+    decimal: 'Decimal',
+    number: 'Number',
+    boolean: 'Boolean',
+    glide_date_time: 'Date',
+    choice: 'Choice',
+    'array.string': 'String',
+    'array.integer': 'Integer',
+    'array.object': 'Object',
+    'array.boolean': 'Boolean',
+    'array.datetime': 'Date',
+    reference: 'Reference',
+}
+
+/**
+ * Maps ServiceNow column types to their array UI type equivalents
+ * For example: 'glide_date_time' -> 'datetime' (for use in 'array.datetime')
+ */
+const COLUMN_TYPE_TO_ARRAY_UI_TYPE: Record<string, string> = {
+    glide_date_time: 'datetime',
+    string: 'string',
+    integer: 'integer',
+    boolean: 'boolean',
+    reference: 'reference',
+}
+
+// Maps API column types -> schema types (defaults to 'String')
+const mapApiToSchema = (api: string): string =>
+    COLUMN_TYPE_TO_SCHEMA_TYPE[COLUMN_API_TO_TYPE[api] as keyof typeof COLUMN_TYPE_TO_SCHEMA_TYPE] ?? 'String' //TODO.. probably throw if the value doesn't exist
+
+/**
+ * Default max_length for fields inside FlowArray elements.
+ * These fields need higher max_length to accommodate larger data structures.
+ */
+const MAX_LENGTH_ARRAY_ELEMENT = 65000
+
+/**
+ * Default max_length for regular fields (not inside FlowArray elements).
+ */
+const MAX_LENGTH_REGULAR_FIELD = 0
+
+type FacetFieldParams = {
+    type: string
+    config: ObjectShape
+    field: string
+    order: number
+    choiceOption?: string
+    mandatoryOverride?: boolean
+    columnApiType?: string
+    isArrayElement?: boolean
+}
+
+const buildFieldFacet = ({
+    type,
+    config,
+    field,
+    order,
+    choiceOption = '',
+    columnApiType,
+    isArrayElement = false,
+}: FacetFieldParams) => {
+    const result: Record<string, string> = {}
+    // Map schema types to their uiTypeLabel
+    const uiTypeLabel =
+        type === 'Boolean' ? 'True/False' : type === 'Date' && columnApiType === 'DateTimeColumn' ? 'Date/Time' : type
+    // Use the column API type to determine the correct uiType
+    const uiType = columnApiType ? COLUMN_API_TO_TYPE[columnApiType] || type.toLowerCase() : type.toLowerCase()
+
+    const additionalProperties: globalThis.Record<string, unknown> = {}
+
+    // Handle reference columns - extract reference table
+    if (uiType === 'reference') {
+        const referenceTable = config.get('referenceTable')?.ifString()?.getValue()
+        if (referenceTable) {
+            additionalProperties['reference'] = referenceTable
+        }
+    }
+
+    // Fields inside FlowArray elements should have higher default max_length
+    const defaultMaxLength = isArrayElement ? MAX_LENGTH_ARRAY_ELEMENT : MAX_LENGTH_REGULAR_FIELD
+
+    result['SimpleMapFacet'] = JSON.stringify({
+        uiTypeLabel,
+        read_only: 'false',
+        uiType,
+        choiceOption,
+        default_value: String(config.get('default')?.ifDefined()?.getValue() ?? ''),
+        hint: config.get('hint')?.ifString()?.getValue() ?? '',
+        label: config.get('label')?.ifString()?.getValue() ?? field,
+        mandatory: String(config.get('mandatory')?.ifBoolean()?.getValue() ?? false),
+        order: `${order + 1}`,
+        max_length: String(config.get('maxLength')?.ifDefined()?.getValue() ?? defaultMaxLength),
+        ...additionalProperties,
+    })
+
+    if (type === 'Choice') {
+        const choices = config.get('choices')?.ifDefined()?.asObject()
+        if (!choices) {
+            return result
+        }
+        result['SimpleChoiceFacet'] = JSON.stringify({
+            complex_choice_map_key$: {},
+            choice_map_key$: choices.keys().reduce<Record<string, string>>((acc, key, i) => {
+                const choiceValue = choices.get(key)
+                let choiceLabel = ''
+                let order = i + 1
+                if (choiceValue.isString()) {
+                    choiceLabel = choiceValue.getValue()
+                } else {
+                    choiceLabel = choiceValue.asObject().get('label')?.ifString()?.getValue() ?? key
+                    order = choiceValue.asObject().get('sequence')?.ifNumber()?.getValue() ?? i + 1
+                }
+
+                acc[choiceLabel] = JSON.stringify({ label: choiceLabel, value: key, order })
+                return acc
+            }, {}),
+        })
+    }
+
+    return result
+}
+
+const buildArrayFieldFacet = ({
+    type,
+    config,
+    element,
+    field,
+    order,
+    choiceOption = '',
+    actionId,
+    columnApiType,
+}: {
+    type: string
+    config: ObjectShape
+    element: ObjectShape
+    field: string
+    order: number
+    choiceOption?: string
+    actionId: string
+    columnApiType?: string
+}) => {
+    const label = config.get('label')?.ifString()?.getValue() ?? field
+    const childName = config?.get('childName')?.ifString()?.getValue() || `${field}_child0`
+    const childLabel = element.get('label')?.ifString()?.getValue() ?? field
+
+    // Determine the correct uiType for arrays
+    // For DateTimeColumn: columnApiType='DateTimeColumn' -> columnType='glide_date_time' -> arrayUiType='datetime'
+    let arrayUiType = type.toLowerCase()
+    if (columnApiType) {
+        const columnType = COLUMN_API_TO_TYPE[columnApiType]
+        if (columnType && COLUMN_TYPE_TO_ARRAY_UI_TYPE[columnType]) {
+            arrayUiType = COLUMN_TYPE_TO_ARRAY_UI_TYPE[columnType]
+        } else if (columnType) {
+            arrayUiType = columnType
+        }
+    }
+
+    return {
+        SimpleMapFacet: JSON.stringify({
+            max_rows: null,
+            child_hint: '',
+            child_maxsize: '',
+            child_name: childName || `${field}_child0`,
+            child_label: childLabel || `${label}_child0`,
+            child_type_label: type,
+            child_type: arrayUiType,
+            child_defaultValue: '',
+            child_uiUniqueId: `${actionId}-${field}-child0`,
+            uiUniqueId: `${actionId}-${field}`,
+            uiTypeLabel: `Array.${type}`,
+            read_only: 'false',
+            uiType: `array.${arrayUiType}`,
+            choiceOption,
+            default_value: type === 'Boolean' ? 'false' : '',
+            hint: config.get('hint')?.ifString()?.getValue() ?? '',
+            label: label,
+            mandatory: String(config.get('mandatory')?.ifBoolean()?.getValue() ?? false),
+            order: `${order + 1}`,
+            max_length: String(config.get('maxLength')?.ifNumber()?.getValue() ?? 65000),
+        }),
+    }
+}
+
+// ---------- Type facet ----------
+
+const buildTypeFacet = (
+    complexObjectId: string,
+    actionId: string,
+    objectName: string,
+    label: string,
+    mandatory: boolean,
+    order: number
+) => ({
+    //TODO: These fields exist in what FD generates but it is not clear that they are actually all required
+    SimpleMapFacet: JSON.stringify({
+        sourceId: '',
+        choiceOption: '',
+        default_value: '',
+        label: label || objectName,
+        mandatory: String(mandatory),
+        uiUniqueId: `${actionId}-${objectName}`, //this is windsurf generated slop but it might be good enough?
+        uiTypeLabel: 'Object',
+        co_type_name: complexObjectId,
+        read_only: 'false',
+        hint: null,
+        uiType: 'object',
+        order: `${order}`,
+        max_length: '65000', //TODO max length on complex objects is not enforced but this exists in what FD currently generates, check to see if we can clean it up and remove it
+    }),
+})
+
+// Build type facet for array types
+const buildArrayTypeFacet = ({
+    complexObjectId,
+    actionId,
+    objectName,
+    parentConfig,
+    childConfig,
+    order,
+    elementType,
+    child,
+    columnApiType,
+}: {
+    complexObjectId: string
+    actionId: string
+    objectName: string
+    parentConfig: ObjectShape
+    childConfig: ObjectShape
+    order: number
+    elementType: string
+    child: string
+    columnApiType?: string
+}) => {
+    const label = parentConfig.get('label').ifString()?.getValue() || objectName
+    const hint = parentConfig.get('hint').ifString()?.getValue() || ''
+    const mandatory = parentConfig.get('mandatory').ifBoolean()?.getValue() || false
+    const maxRows = parentConfig.get('maxRows').ifNumber()?.getValue() || ''
+    const childLabel = childConfig.get('label').ifString()?.getValue() || `${objectName.toLowerCase()}_child0_label`
+    const childMaxLength = childConfig.get('maxLength').ifNumber()?.getValue() || 0
+    const childHint = childConfig.get('hint').ifString()?.getValue() || ''
+    const childDefaultValue = childConfig.get('default')?.ifDefined()?.getValue() || ''
+    const choiceOption = childConfig.get('dropdown')?.ifDefined()?.ifString()?.getValue() || ''
+
+    // Determine the correct uiType for arrays
+    // For DateTimeColumn: columnApiType='DateTimeColumn' -> columnType='glide_date_time' -> arrayUiType='datetime'
+    let arrayUiType = elementType.toLowerCase()
+    if (columnApiType) {
+        const columnType = COLUMN_API_TO_TYPE[columnApiType]
+        if (columnType && COLUMN_TYPE_TO_ARRAY_UI_TYPE[columnType]) {
+            arrayUiType = COLUMN_TYPE_TO_ARRAY_UI_TYPE[columnType]
+        } else if (columnType) {
+            arrayUiType = columnType
+        }
+    }
+
+    return {
+        SimpleMapFacet: JSON.stringify({
+            sourceId: '',
+            max_rows: String(maxRows),
+            choiceOption: choiceOption,
+            default_value: '',
+            label: label || objectName,
+            child_hint: childHint,
+            child_maxsize: String(childMaxLength),
+            mandatory: String(mandatory),
+            child_name: child,
+            uiUniqueId: `${actionId}-${objectName}`,
+            uiTypeLabel: `Array.${elementType}`,
+            co_type_name: complexObjectId,
+            child_label: childLabel,
+            child_type_label: elementType,
+            read_only: 'false',
+            sourceUiUniqueId: '',
+            sourceType: '',
+            hint: hint,
+            uiType: `array.${arrayUiType}`,
+            child_defaultValue: String(childDefaultValue),
+            child_type: arrayUiType,
+            order: `${order}`,
+            max_length: '65000',
+            child_uiUniqueId: `${actionId}-${objectName}-child`,
+        }),
+    }
+}
+
+function validateReferenceColumnUsage(
+    fieldType: string | undefined,
+    isFlowVariable: boolean,
+    diagnostics: Diagnostics,
+    source: CallExpressionShape
+): void {
+    if (fieldType === 'ReferenceColumn' && !isFlowVariable) {
+        diagnostics.error(
+            source,
+            'Reference type fields are not allowed inside FlowObject or FlowArray structures when used in subflow or action inputs or outputs.'
+        )
+    }
+}
+
+/**
+ * Create the resulting co schema for the fields of a complex object. This will recurse when
+ * a nested object is found.
+ */
+function createSchemaForFields(
+    fields: ObjectShape,
+    actionId: string,
+    diagnostics: Diagnostics,
+    isFlowVariable: boolean = false,
+    isArrayElement: boolean = false
+): Record<string, any> {
+    const resultSchema: Record<string, any> = {}
+    fields.entries().forEach(([fieldName, fieldValue], order) => {
+        const fieldCallExpr = fieldValue.as(CallExpressionShape)
+        const fieldConfig = fieldCallExpr.getArgument(0)?.asObject()
+        const fieldType = fieldCallExpr.getCallee()
+        validateReferenceColumnUsage(fieldType, isFlowVariable, diagnostics, fieldCallExpr)
+
+        if (fieldType === 'FlowObject') {
+            const nestedFields = fieldConfig?.get('fields')?.asObject()
+            if (nestedFields) {
+                resultSchema[fieldName] = createSchemaForFields(
+                    nestedFields,
+                    actionId,
+                    diagnostics,
+                    isFlowVariable,
+                    isArrayElement
+                )
+            }
+
+            resultSchema[`${fieldName}.$field_facets`] = buildFieldFacet({
+                type: 'Object',
+                config: fieldConfig,
+                field: fieldName,
+                order,
+                isArrayElement,
+            })
+            return
+        } else if (fieldType === 'FlowArray') {
+            // Handle FlowArray type
+            const elementType = fieldConfig?.get('elementType')?.as(CallExpressionShape)
+            const elementConfig = elementType?.getArgument(0)?.asObject()
+            const elementCallee = elementType?.getCallee()
+
+            let elementTypeString = 'Any' // Default to 'Any' if we can't determine
+
+            if (elementCallee === 'FlowObject') {
+                const nestedFields = elementConfig?.get('fields')?.asObject()
+                if (nestedFields) {
+                    elementTypeString = 'Object'
+                    // Create schema for nested FlowObject fields
+                    // For nested FlowArrays with FlowObject elements, wrap in array with fieldName as key
+                    // Mark nested fields as array elements for proper max_length defaults
+                    const nestedSchema = createSchemaForFields(
+                        nestedFields,
+                        actionId,
+                        diagnostics,
+                        isFlowVariable,
+                        true
+                    )
+                    resultSchema[fieldName] = [
+                        {
+                            [fieldName]: nestedSchema,
+                        },
+                    ]
+                    resultSchema[`${fieldName}.$field_facets`] = buildArrayFieldFacet({
+                        type: elementTypeString,
+                        config: fieldConfig,
+                        element: elementConfig,
+                        field: fieldName,
+                        order,
+                        actionId,
+                    })
+                    return
+                }
+            } else if (elementCallee) {
+                // For primitive types, map to appropriate schema type
+                elementTypeString = mapApiToSchema(elementCallee)
+            }
+            // For primitive arrays, always use "Any" in schema (ServiceNow requirement)
+            resultSchema[fieldName] = ['Any']
+            resultSchema[`${fieldName}.$field_facets`] = buildArrayFieldFacet({
+                type: elementTypeString,
+                config: fieldConfig,
+                element: elementConfig,
+                field: fieldName,
+                order,
+                actionId,
+                columnApiType: elementCallee, // Pass the column API type for correct uiType generation
+            })
+
+            return
+        } else {
+            //basic field type
+            const schemaType = mapApiToSchema(fieldType)
+            resultSchema[fieldName] = schemaType === 'Choice' ? 'String' : schemaType
+            validateObjectElementType(fieldCallExpr, schemaType, diagnostics)
+
+            if (schemaType === 'Choice') {
+                const isDynamic = fieldConfig.get('dynamicValueDefinitions')?.isDefined()
+                if (isDynamic) {
+                    diagnostics.error(fieldConfig, 'Dynamic value definitions are not supported')
+                }
+            }
+
+            resultSchema[`${fieldName}.$field_facets`] = buildFieldFacet({
+                type: schemaType,
+                config: fieldConfig,
+                field: fieldName,
+                order,
+                columnApiType: fieldType,
+                isArrayElement,
+            })
+        }
+    })
+
+    return resultSchema
+}
+
+/**
+ * Generate schema object from FlowObject or FlowArray structure
+ * @param objectConfig - The config of the FlowObject or FlowArray {fields/elementType, mandatory, label}
+ * @param complexObjectId - The ID of the complex object
+ * @param objectName - The name of the object
+ * @param actionId - The ID of the action
+ * @param order - The order of the object
+ * @param isArray - Whether this is a FlowArray type
+ * @param diagnostics - Diagnostics instance for error reporting
+ * @param isFlowVariable - Whether this is a flow variable (allows ReferenceColumn)
+ * @returns The generated schema object
+ */
+export function generateSchemaFromObject(
+    objectConfig: ObjectShape,
+    complexObjectId: string,
+    objectName: string,
+    actionId: string,
+    order: number,
+    isArray: boolean = false,
+    diagnostics: Diagnostics,
+    isFlowVariable: boolean = false
+): Record<string, any> {
+    const rootKey = `FlowDesigner:${complexObjectId}`
+    const result: Record<string, any> = {}
+
+    if (isArray) {
+        // Handle FlowArray type
+        const elementShape = objectConfig.get('elementType')?.as(CallExpressionShape)
+        const elementCallee = elementShape?.getCallee()
+        validateReferenceColumnUsage(elementCallee, isFlowVariable, diagnostics, elementShape)
+
+        let collectionField: string | Record<string, unknown> = 'String' // Default
+        let elementTypeString: string | Record<string, unknown> = 'String' // Default
+        const child = objectConfig.get('childName').ifString()?.getValue() || `${objectName.toLowerCase()}_child0`
+        const config = elementShape.getArgument(0).asObject()
+        if (elementCallee === 'FlowObject') {
+            const schema = createSchemaForFields(
+                config.get('fields').asObject('fields property should be object shaped'),
+                actionId,
+                diagnostics,
+                isFlowVariable
+            )
+            collectionField = { [child]: schema }
+            elementTypeString = 'Object'
+        } else if (elementCallee) {
+            collectionField = mapApiToSchema(elementCallee)
+            elementTypeString = collectionField
+
+            // Validate the array element type
+            validateArrayElementType(elementShape, elementTypeString, diagnostics)
+        }
+
+        // Attach the array type facets
+        const typeFacets = buildArrayTypeFacet({
+            complexObjectId,
+            actionId,
+            objectName,
+            parentConfig: objectConfig,
+            childConfig: config,
+            order,
+            elementType: elementTypeString,
+            child,
+            columnApiType: elementCallee, // Pass the column API type for correct uiType generation
+        })
+
+        // Create array schema structure
+        result[rootKey] = {
+            $COCollectionField: [collectionField],
+            '$COCollectionField.$field_facets': {
+                SimpleMapFacet: JSON.stringify({
+                    'up-shift-collection-level': 'true',
+                }),
+            },
+            '$COCollectionField.$type_facets': typeFacets,
+        }
+        result[`${rootKey}.$type_facets`] = typeFacets
+    } else {
+        // Handle FlowObject type (original behavior)
+        result[rootKey] = createSchemaForFields(
+            objectConfig.get('fields').asObject('fields property should be object shaped'),
+            actionId,
+            diagnostics,
+            isFlowVariable
+        )
+
+        const label = objectConfig.get('label').ifString()?.getValue() || objectName
+        const mandatory = objectConfig.get('mandatory').ifBoolean()?.getValue() || false
+
+        // Attach the type facets for the root object
+        result[`${rootKey}.$type_facets`] = buildTypeFacet(
+            complexObjectId,
+            actionId,
+            objectName,
+            label,
+            mandatory,
+            order
+        )
+    }
+
+    return result
+}
+
+/**
+ * Generate variable schema object for FlowObject or FlowArray types
+ * @param schemaObject - The schema object
+ * @param complexObjectId - The ID of the complex object
+ * @param isArray - Whether this is a FlowArray type
+ * @returns The generated variable schema object
+ */
+export function generateVariableSchemaObject(
+    schemaObject: Record<string, unknown>,
+    complexObjectId: string,
+    isArray: boolean = false
+): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+
+    result['version'] = '1.0'
+
+    if (isArray) {
+        // Handle FlowArray type
+        result['complexObject'] = {
+            name$: complexObjectId,
+            $COCollectionField: [],
+        }
+    } else {
+        // Handle FlowObject type
+        // Extract the object fields from the schema and convert to the required format
+        const rootKey = `FlowDesigner:${complexObjectId}`
+        const schemaFields = (schemaObject[rootKey] || {}) as Record<string, string>
+        const objectFields: Record<string, unknown> = {}
+
+        // Process each field in the schema, excluding special fields like $field_facets
+        Object.keys(schemaFields).forEach((key) => {
+            if (!key.includes('$')) {
+                objectFields[key] = {
+                    $cv: {
+                        $c: `java.lang.${schemaFields[key]}`,
+                        $v: '',
+                    },
+                }
+            }
+        })
+
+        result['complexObject'] = objectFields
+    }
+
+    result['complexObjectSchema'] = schemaObject
+    result['serializationFormat'] = 'JSON'
+    return result
+}
+
+/**
+ * Get the attributes for a complex object
+ * @param schemaObject - The schema object
+ * @param complexObjectId - The ID of the complex object
+ * @param isArray - Whether this is a FlowArray type
+ * @returns The attributes for the complex object
+ */
+export function getComplexObjectAttributes(
+    schemaObject: Record<string, any>,
+    complexObjectId: string,
+    isArray: boolean
+): Record<string, string> {
+    const typeFacets = JSON.parse(
+        schemaObject[`FlowDesigner:${complexObjectId}.$type_facets`]?.['SimpleMapFacet'] ?? '{}'
+    )
+
+    let result: Record<string, string> = {
+        co_type_name: typeFacets.co_type_name,
+        element_mapping_provider: ELEMENT_MAPPING_PROVIDER,
+        uiType: typeFacets.uiType,
+        uiTypeLabel: typeFacets.uiTypeLabel,
+        uiUniqueId: typeFacets.uiUniqueId,
+    }
+
+    if (isArray) {
+        result = {
+            ...result,
+            child_maxsize: typeFacets.child_maxsize,
+            child_hint: typeFacets.child_hint,
+            child_label: typeFacets.child_label,
+            child_name: typeFacets.child_name,
+            child_type: typeFacets.child_type,
+            child_type_label: typeFacets.child_type_label,
+            child_uiUniqueId: typeFacets.child_uiUniqueId,
+            max_rows: typeFacets.max_rows,
+            child_defaultValue: typeFacets.child_defaultValue,
+        }
+    }
+
+    return result
+}
+
+/**
+ * Converts the output of getComplexObjectAttributes to a comma-separated string in the format key1=value1,key2=value2
+ * @param attributes - The attributes object returned by getComplexObjectAttributes
+ * @returns A comma-separated string of key-value pairs
+ */
+export function formatComplexObjectAttributes(attributes: globalThis.Record<string, string | boolean>): string {
+    return Object.entries(attributes)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(',')
+}
+
+function validateArrayElementType(
+    elementType: CallExpressionShape,
+    elementTypeString: string,
+    diagnostics: Diagnostics
+) {
+    if (!ALLOWED_ARRAY_TYPES.includes(elementTypeString)) {
+        diagnostics.error(elementType, 'Invalid array element type')
+    }
+}
+
+function validateObjectElementType(
+    elementType: CallExpressionShape,
+    elementTypeString: string,
+    diagnostics: Diagnostics
+) {
+    if (!ALLOWED_OBJECT_TYPES.includes(elementTypeString)) {
+        diagnostics.error(elementType, 'Invalid array element type')
+    }
+}