@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/schema-to-flow-object.ts

@@ -0,0 +1,385 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: This file processes dynamic JSON schemas
+import {
+    CallExpressionShape,
+    ObjectShape,
+    UndefinedShape,
+    type Record as FluentRecord,
+} from '@servicenow/sdk-build-core'
+import {
+    StringColumn,
+    IntegerColumn,
+    DecimalColumn,
+    BooleanColumn,
+    DateTimeColumn,
+    ChoiceColumn,
+    choiceDropdown,
+    ReferenceColumn,
+} from '@servicenow/sdk-core/runtime/db'
+import { ChoiceDropdown } from './flow-constants'
+
+/**
+ * Reverse of `generateSchemaFromObject`.
+ * Takes the `serialized_content` field from a `sys_complex_object` record and
+ * rebuilds a `FlowObject(...)` call-expression shape that can be placed back in
+ * the Fluent source.
+ */
+
+// ------------------------------------------------------------
+// Schema <-> Column API mappings (inverse of COLUMN_TYPE_TO_SCHEMA_TYPE)
+// ------------------------------------------------------------
+const SCHEMA_TYPE_TO_COLUMN_API: Record<string, string> = {
+    string: StringColumn.name,
+    integer: IntegerColumn.name,
+    number: DecimalColumn.name,
+    boolean: BooleanColumn.name,
+    date: DateTimeColumn.name,
+    glide_date_time: DateTimeColumn.name,
+    choice: ChoiceColumn.name,
+    reference: ReferenceColumn.name,
+}
+
+/**
+ * Build a `CallExpressionShape` for a simple (non-object) field given its
+ * schema primitive type and associated facets.
+ */
+function buildPrimitiveFieldCallExpr(fieldFacet: ObjectShape, source: FluentRecord): CallExpressionShape {
+    const childType = fieldFacet.get('childType').ifDefined()?.asString()?.getValue()
+    const schemaType = childType ?? fieldFacet.get('type')?.asString()?.getValue()
+    const callee = SCHEMA_TYPE_TO_COLUMN_API[schemaType] ?? StringColumn.name
+
+    const additionalProps: globalThis.Record<string, unknown> = {}
+
+    // Extract referenceTable for ReferenceColumn type
+    const referenceTable = fieldFacet.get('reference')?.ifString()?.getValue()
+    if (referenceTable && schemaType === 'reference') {
+        additionalProps['referenceTable'] = referenceTable
+    }
+
+    const isChoiceColumn = callee === ChoiceColumn.name
+    const isStringColumn = callee === StringColumn.name
+
+    return new CallExpressionShape({
+        source,
+        callee,
+        args: [
+            fieldFacet
+                .transform(({ $ }) => ({
+                    label: $.from('label', 'childLabel').map((label, child) => (child.isDefined() ? child : label)),
+                    mandatory: $.toBoolean().def(false),
+                    ...(isStringColumn && {
+                        maxLength: $.from('maxLength', 'childMaxLength')
+                            .map((maxLength, child) => {
+                                const value = child.isDefined() ? child : maxLength
+                                if (value.isString() && value.getValue() !== '') {
+                                    return value.toNumber().getValue()
+                                }
+                                return 0
+                            })
+                            .def(0),
+                    }),
+                    default: $.from('defaultValue', 'childDefaultValue')
+                        .map((defaultValue, childDefault) => (childDefault.isDefined() ? childDefault : defaultValue))
+                        .def(''),
+                    hint: $.from('hint', 'childHint')
+                        .map((hint, childHint) => (childHint.isDefined() ? childHint : hint))
+                        .def(''),
+                    ...(isChoiceColumn && {
+                        choices: $.def({}),
+                        dropdown: $.from('choiceOption')
+                            .map((value) => {
+                                const val = value.getValue()
+                                if (
+                                    value.if(UndefinedShape) ||
+                                    val === '' ||
+                                    value.toNumber().getValue() === ChoiceDropdown.DROPDOWN_WITH_NONE
+                                ) {
+                                    return undefined
+                                }
+                                return choiceDropdown[ChoiceDropdown.DROPDOWN_WITHOUT_NONE]
+                            })
+                            .def(choiceDropdown[ChoiceDropdown.DROPDOWN_WITH_NONE]),
+                    }),
+                }))
+                .merge(additionalProps),
+        ],
+    })
+}
+
+/**
+ * Recursively converts the schema representation for a FlowArray into an
+ * `ObjectShape` that will be supplied as the first argument to a
+ * `FlowArray(...)` call-expression.
+ */
+function buildFlowArrayFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const rootContent = schemaContent['$COCollectionField']
+    if (!rootContent) {
+        throw new Error('Invalid complex object schema: $COCollectionField not found')
+    }
+    let rootTypeFacet = parseTypeFacet(source, schemaContent, '$COCollectionField')
+    if (!rootTypeFacet) {
+        rootTypeFacet = parentTypeFacet
+    }
+    const type = rootTypeFacet.get('type')?.asString()?.getValue()
+    let elementType: CallExpressionShape
+    if (type === 'array.object') {
+        const childKey = parentTypeFacet.get('childName')?.asString()?.getValue()
+        elementType = buildFlowObjectFromSchema(rootContent[0][childKey], source, rootTypeFacet)
+    } else {
+        elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowArray',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                ...(complexObjectSysId ? { $id: $.val(complexObjectSysId) } : {}),
+                ...(co_type_name ? { co_type_name: $.val(co_type_name) } : {}),
+                elementType: $.val(elementType),
+                label: $.def(''),
+                mandatory: $.toBoolean().def(false),
+                hint: $.def(''),
+                maxRows: $.from('maxRows', 'max_rows')
+                    .map((maxRows, max_rows) => {
+                        const value = max_rows.isDefined() ? max_rows : maxRows
+                        if (value.isString() && value.getValue() !== '') {
+                            return value.toNumber().getValue()
+                        }
+                        return undefined
+                    })
+                    .def(undefined),
+                childName: $,
+            })),
+        ],
+    })
+}
+
+function buildNestedFlowArrayFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape
+): CallExpressionShape {
+    const type = parentTypeFacet.get('type')?.asString()?.getValue()
+    let elementType: CallExpressionShape
+    if (type === 'array.object') {
+        // Unwrap the wrapper if present (used for nested array.object)
+        // ServiceNow stores nested array.object elements in two ways:
+        // 1. With $<num>_<fieldName> wrapper (e.g., $0_task)
+        // 2. With the field name itself as wrapper (e.g., tasks inside tasks array)
+        const keys = Object.keys(schemaContent)
+        const wrapperKey = keys.find((k) => /^\$\d+_/.test(k)) ?? keys.find((k) => !k.endsWith('.$field_facets'))
+        const innerContent = wrapperKey ? schemaContent[wrapperKey] : schemaContent
+        elementType = buildFlowObjectFromSchema(innerContent, source, parentTypeFacet)
+    } else {
+        elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowArray',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                elementType: $.val(elementType),
+                label: $.def(''),
+                mandatory: $.toBoolean().def(false),
+                hint: $.def(''),
+                maxRows: $.from('maxRows', 'max_rows')
+                    .map((maxRows, max_rows) => {
+                        const value = max_rows.isDefined() ? max_rows : maxRows
+                        if (value.isString() && value.getValue() !== '') {
+                            return value.toNumber().getValue()
+                        }
+                        return undefined
+                    })
+                    .def(undefined),
+                childName: $,
+            })),
+        ],
+    })
+}
+
+/**
+ * Recursively converts the schema representation for a FlowObject into an
+ * `ObjectShape` that will be supplied as the first argument to a
+ * `FlowObject(...)` call-expression.
+ */
+function buildFlowObjectFromSchema(
+    schemaContent: Record<string, any>,
+    source: FluentRecord,
+    parentTypeFacet: ObjectShape,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const properties: Record<string, unknown> = {}
+
+    if (typeof schemaContent === 'object') {
+        for (const [key, value] of Object.entries(schemaContent)) {
+            // Skip facet keys – they belong to the previous field name.
+            if (key.endsWith('.$field_facets')) {
+                continue
+            }
+
+            const fieldFacet = parseFieldFacet(source, schemaContent, key)
+            if (!fieldFacet) {
+                throw new Error(`Invalid complex object schema: ${key} facet not found`)
+            }
+            if (typeof value === 'string') {
+                // Primitive field
+                properties[key] = buildPrimitiveFieldCallExpr(fieldFacet, source)
+            } else if (typeof value === 'object' && value !== null) {
+                if (Array.isArray(value)) {
+                    // Nested FlowArray
+                    properties[key] = buildNestedFlowArrayFromSchema(value[0], source, fieldFacet)
+                } else {
+                    // Nested FlowObject
+                    properties[key] = buildFlowObjectFromSchema(value, source, fieldFacet)
+                }
+            }
+        }
+    }
+
+    return new CallExpressionShape({
+        source,
+        callee: 'FlowObject',
+        args: [
+            parentTypeFacet.transform(({ $ }) => ({
+                ...(complexObjectSysId ? { $id: $.val(complexObjectSysId) } : {}),
+                ...(co_type_name ? { co_type_name: $.val(co_type_name) } : {}),
+                fields: $.val(properties),
+                label: $.from('label', 'childLabel')
+                    .map((label, child) => (child.isDefined() ? child : label))
+                    .def(''),
+                mandatory: $.toBoolean().def(false),
+            })),
+        ],
+    })
+}
+
+/**
+ * Main entry ‑ convert `serialized_content` JSON → FlowObject or FlowArray call expression.
+ *
+ * @param schema Parsed `serialized_content`.
+ * @param source Optional source node to attach to created shapes.
+ * @param complexObjectSysId The sys_id of the sys_complex_object record (if available)
+ * @param co_type_name The name field from sys_complex_object
+ */
+export function buildComplexObjectFromSchema(
+    source: FluentRecord,
+    schema: Record<string, any>,
+    attributes: COAttributes,
+    complexObjectSysId?: string,
+    co_type_name?: string
+): CallExpressionShape {
+    const { co_type_name: attrCoTypeName, uiType, ...rest } = attributes
+    const rootKey = `FlowDesigner:${attrCoTypeName}`
+    if (!rootKey) {
+        throw new Error(`Invalid complex object schema: ${attrCoTypeName} not found`)
+    }
+    const rootContent = schema[rootKey]
+    let rootTypeFacet = parseTypeFacet(source, schema, rootKey)
+
+    if (!rootTypeFacet) {
+        throw new Error('Invalid complex object schema: root type facet not found')
+    }
+
+    rootTypeFacet = rootTypeFacet.merge({
+        type: uiType,
+        ...rest,
+    })
+    // Pass the explicit co_type_name parameter (undefined for deterministic, value for non-deterministic)
+    if (uiType.startsWith('array.')) {
+        return buildFlowArrayFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+    }
+    return buildFlowObjectFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+}
+
+function parseTypeFacet(source: FluentRecord, schema: Record<string, any>, key: string): ObjectShape | undefined {
+    const facetKey = `${key}.$type_facets`
+    return parseFacet(source, schema, facetKey)
+}
+
+function parseFieldFacet(source: FluentRecord, schema: Record<string, any>, key: string): ObjectShape | undefined {
+    const facetKey = `${key}.$field_facets`
+    return parseFacet(source, schema, facetKey)
+}
+
+function parseFacet(source: FluentRecord, schema: Record<string, any>, facetKey: string) {
+    const facet = schema[facetKey]?.SimpleMapFacet
+
+    if (!facet) {
+        return undefined
+    }
+
+    const choices = schema[facetKey]?.SimpleChoiceFacet
+
+    try {
+        const parsed = JSON.parse(facet)
+        const parsedChoices = choices ? JSON.parse(choices)['choice_map_key$'] : {}
+        return new ObjectShape({
+            source,
+            properties: {
+                type: parsed['uiType'],
+                label: parsed['label'],
+                mandatory: parsed['mandatory'],
+                reference: parsed['reference'],
+                childName: parsed['child_name'],
+                childMaxLength: parsed['child_maxsize'],
+                childHint: parsed['child_hint'],
+                maxLength: parsed['max_length'],
+                maxRows: parsed['max_rows'],
+                childType: parsed['child_type'],
+                childLabel: parsed['child_label'],
+                choiceOption: parsed['choiceOption'],
+                defaultValue: parsed['default_value'],
+                childDefaultValue: parsed['child_defaultValue'],
+                hint: parsed['hint'],
+                choices: Object.keys(parsedChoices).reduce(
+                    (acc, key) => {
+                        const { label, value, order } = JSON.parse(parsedChoices[key])
+                        acc[value] = { label, sequence: order }
+                        return acc
+                    },
+                    {} as globalThis.Record<string, { label: string; sequence: number }>
+                ),
+            },
+        })
+    } catch {
+        // Failed to parse facet - returning undefined
+    }
+
+    return undefined
+}
+
+export function getAttributeValue(attributesStr: string, key: string): string | undefined {
+    const attributes = parseAttributesToObject(attributesStr)
+    return attributes[key]
+}
+
+type COAttributes = {
+    dynamic: string
+    co_type_name: string
+    uiType: string
+    child_label?: string
+    child_name?: string
+    child_type?: string
+    [key: string]: string | undefined
+}
+
+export function parseAttributesToObject(attributesStr: string): COAttributes {
+    return attributesStr
+        .split(',')
+        .map((p) => p.trim())
+        .reduce((acc, pair) => {
+            const [key, value] = pair.split('=')
+            if (key && value !== undefined) {
+                acc[key as keyof COAttributes] = value
+            }
+            return acc
+        }, {} as COAttributes)
+}

package/src/flow/utils/service-catalog.ts

@@ -0,0 +1,174 @@
+import type { Database, Record, Shape, Source } from '@servicenow/sdk-build-core'
+import {
+    ArrayShape,
+    IdentifierShape,
+    PropertyAccessShape,
+    TemplateExpressionShape,
+    TemplateSpanShape,
+    isGUID,
+} from '@servicenow/sdk-build-core'
+import { getIdentifierFromRecord } from './utils'
+import {
+    CATALOG_VARIABLE_ACTIONS,
+    CORE_ACTIONS_SYS_ID_NAME_MAP,
+    CATALOG_ITEM_TABLE,
+    CATALOG_VARIABLE_TABLE,
+} from './flow-constants'
+
+/**
+ * Service Catalog Utility Functions
+ *
+ * This module contains utilities for transforming catalog item and catalog variable
+ * data between XML and Fluent formats, including:
+ * - Checking if an action is catalog-related
+ * - Finding catalog items by sys_id
+ * - Creating template expressions for catalog item references
+ * - Converting slushbucket format to catalog variable arrays
+ */
+
+/**
+ * Check if an action definition is a catalog-related action (getCatalogVariables or createCatalogTask).
+ * @param actionDefinition - The action definition shape
+ * @returns true if the action is getCatalogVariables or createCatalogTask, false otherwise
+ */
+export function isCatalogAction(actionDefinition: Shape | undefined): boolean {
+    const actionName = CORE_ACTIONS_SYS_ID_NAME_MAP[actionDefinition?.getValue() as string]
+    return actionName ? CATALOG_VARIABLE_ACTIONS.includes(actionName) : false
+}
+
+/**
+ * Helper function to find catalog item record by sys_id from database.
+ * @param sysId - The sys_id of the catalog item (must be 32 characters)
+ * @param database - Database instance to query
+ * @returns Catalog item record or undefined if not found
+ */
+export function findCatalogItemBySysId(sysId: string | undefined, database: Database | undefined): Record | undefined {
+    if (!database || !sysId || !isGUID(sysId)) {
+        return undefined
+    }
+    return database.get(CATALOG_ITEM_TABLE, sysId)
+}
+
+/**
+ * Helper function to create a template expression from an identifier.
+ * Creates: `${identifierName}`
+ */
+export function createTemplateExpressionFromIdentifier(
+    identifierName: string,
+    source: Source
+): TemplateExpressionShape {
+    return new TemplateExpressionShape({
+        source,
+        literalText: '',
+        spans: [
+            new TemplateSpanShape({
+                source,
+                expression: new IdentifierShape({ source, name: identifierName }),
+                literalText: '',
+            }),
+        ],
+    })
+}
+
+/**
+ * Helper function to create a PropertyAccessShape for a catalog variable reference.
+ * Creates: catalogItemIdentifierName.variables.varName
+ */
+export function createCatalogVariablePropertyAccess(
+    catalogItemRecord: Record,
+    catalogItemIdentifierName: string,
+    varName: string,
+    source: Source
+): PropertyAccessShape {
+    const catalogItemIdentifier = new IdentifierShape({
+        source: catalogItemRecord.getOriginalNode() || source,
+        name: catalogItemIdentifierName,
+        value: catalogItemRecord,
+    })
+    const variablesIdentifier = new IdentifierShape({
+        source,
+        name: 'variables',
+    })
+    const varNameIdentifier = new IdentifierShape({
+        source,
+        name: varName,
+    })
+
+    return new PropertyAccessShape({
+        source,
+        elements: [catalogItemIdentifier, variablesIdentifier, varNameIdentifier],
+    })
+}
+
+/**
+ * Convert slushbucket format (comma-separated sys_id:name pairs) to an array of catalog variable references.
+ * Example: "abc123:email,def456:html" → [catalogItem.variables.email, catalogItem.variables.html]
+ *
+ * @param slushBucketValue - Slushbucket string from XML
+ * @param catalogItemRecord - Catalog item record to look up variables
+ * @param source - Source for creating shapes
+ * @param actionInstanceUUID - UUID of the action instance (for label_cache lookup)
+ * @param flowRecord - Flow record containing label_cache
+ * @returns ArrayShape of PropertyAccessShape elements or undefined if conversion fails
+ */
+export function convertSlushBucketToCatalogVariableArray(
+    slushBucketValue: string,
+    catalogItemRecord: Record | undefined,
+    source: Source
+): ArrayShape | undefined {
+    if (!catalogItemRecord) {
+        return undefined
+    }
+
+    const variableShapes: PropertyAccessShape[] = []
+    const catalogItemIdentifierName = getIdentifierFromRecord(catalogItemRecord) || 'catalogItem'
+
+    //use slushbucket sys_ids to look up variable names
+    if (!slushBucketValue || !slushBucketValue.trim()) {
+        return undefined
+    }
+
+    const entries = slushBucketValue
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+
+    // Build a map of sysId → record by iterating allRecords once
+    const variableRecordBySysId = new Map<string, Record>()
+    for (const rec of catalogItemRecord.flat()) {
+        if (rec.getTable() === CATALOG_VARIABLE_TABLE) {
+            variableRecordBySysId.set(rec.getId().getValue(), rec)
+        }
+    }
+
+    for (const entry of entries) {
+        const [sysId] = entry.split(':')
+        if (!sysId || !sysId.trim()) {
+            continue
+        }
+        const variableRecord = variableRecordBySysId.get(sysId)
+
+        if (variableRecord) {
+            const varName = variableRecord.get('name')?.asString()?.getValue()
+            if (varName) {
+                // Create PropertyAccessShape: catalogItemIdentifierName.variables.varName
+                const propertyAccess = createCatalogVariablePropertyAccess(
+                    catalogItemRecord,
+                    catalogItemIdentifierName,
+                    varName,
+                    source
+                )
+                variableShapes.push(propertyAccess)
+            }
+        }
+    }
+
+    if (variableShapes.length === 0) {
+        return undefined
+    }
+
+    return new ArrayShape({
+        source,
+        elements: variableShapes,
+    })
+}