@servicenow/sdk-build-plugins 4.5.0 → 4.6.1

package/src/service-portal/portal-plugin.ts

@@ -173,17 +173,40 @@ export const ServicePortalPlugin = Plugin.create({
                         )
                     }
                 }
-                // Extract first catalog and knowledgeBase from arrays to populate portal fields
                 const catalogsForM2M = portalArgs.get('catalogs')?.ifArray()?.getElements() ?? []
                 const knowledgeBasesForM2M = portalArgs.get('knowledgeBases')?.ifArray()?.getElements() ?? []
-                const firstCatalogFromArray =
-                    catalogsForM2M.length > 0 ? catalogsForM2M[0]?.asObject()?.get('catalog') : undefined
-                const firstKnowledgeBaseFromArray =
-                    knowledgeBasesForM2M.length > 0
-                        ? knowledgeBasesForM2M[0]?.asObject()?.get('knowledgeBase')
-                        : undefined
 
-                // Build portal properties with conditional catalog and knowledgeBase
+                const deprecatedKnowledgeBase = portalArgs.get('knowledgeBase')
+                if (deprecatedKnowledgeBase?.isDefined()) {
+                    if (knowledgeBasesForM2M.length > 0) {
+                        diagnostics.error(
+                            deprecatedKnowledgeBase.getOriginalNode(),
+                            `Cannot use both 'knowledgeBase' and 'knowledgeBases'. Remove 'knowledgeBase' and use only the 'knowledgeBases' array instead.`
+                        )
+                    } else {
+                        diagnostics.warn(
+                            deprecatedKnowledgeBase.getOriginalNode(),
+                            `'knowledgeBase' is deprecated. Use the 'knowledgeBases' array instead.`
+                        )
+                    }
+                }
+
+                const deprecatedCatalog = portalArgs.get('catalog')
+                if (deprecatedCatalog?.isDefined()) {
+                    if (catalogsForM2M.length > 0) {
+                        diagnostics.error(
+                            deprecatedCatalog.getOriginalNode(),
+                            `Cannot use both 'catalog' and 'catalogs'. Remove 'catalog' and use only the 'catalogs' array instead.`
+                        )
+                    } else {
+                        diagnostics.warn(
+                            deprecatedCatalog.getOriginalNode(),
+                            `'catalog' is deprecated. Use the 'catalogs' array instead.`
+                        )
+                    }
+                }
+
+                // Build portal properties
                 const baseProperties = portalArgs.transform(({ $ }) => ({
                     title: $,
                     url_suffix: $.from('urlSuffix').def(''),
@@ -203,13 +226,13 @@ export const ServicePortalPlugin = Plugin.create({
                     search_application: $.from('searchApplication'),
                     alternate_portal: $.from('alternatePortal'),
                     sc_catalog_page: $.from('catalogHomePage'),
-                    sc_catalog: $.val(firstCatalogFromArray),
-                    kb_knowledge_base: $.val(firstKnowledgeBaseFromArray),
                     login_page: $.from('loginPage'),
                     kb_knowledge_page: $.from('knowledgeHomePage'),
                     sp_chat_queue: $.from('chatQueue'),
                     notfound_page: $.from('notFoundPage'),
                     ts_index_group: $.from('textIndexGroup'),
+                    ...(knowledgeBasesForM2M.length === 0 ? { kb_knowledge_base: $.from('knowledgeBase') } : {}),
+                    ...(catalogsForM2M.length === 0 ? { sc_catalog: $.from('catalog') } : {}),
                     enable_ais: $.from('enableAiSearch').def(false),
                     enable_certificate_based_authentication: $.from('enableCertificateBasedAuthentication').def(false),
                     default: $.from('defaultPortal').def(false),

package/src/service-portal/utils.ts

@@ -1,5 +1,163 @@
 import { NowIncludeShape } from '../now-include-plugin'
-import { type Record, Shape, type RecordId, type Diagnostics, type Factory } from '@servicenow/sdk-build-core'
+import {
+    type Record,
+    Shape,
+    type RecordId,
+    type Diagnostics,
+    type Factory,
+    CallExpressionShape,
+    isGUID,
+} from '@servicenow/sdk-build-core'
+import { noThrow, reverseObject } from '../utils'
+import { WidgetCategories } from '@servicenow/sdk-core/runtime/service-portal'
+import { NowIdShape } from '../now-id-plugin'
+
+function convertOptionSchemaKeys(optionSchema: unknown, convertKey: (key: string) => string): unknown {
+    if (!Array.isArray(optionSchema)) {
+        return optionSchema
+    }
+    return optionSchema.map((option: globalThis.Record<string, unknown>) =>
+        Object.fromEntries(Object.entries(option).map(([k, v]) => [convertKey(k), v]))
+    )
+}
+
+const toCamelCase = (key: string) => key.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
+
+/**
+ * Shared toShape implementation for SPWidget and SPHeaderFooter
+ */
+export async function createWidgetToShape(
+    record: Record,
+    descendants: { query: (table: string) => Record[] },
+    callee: 'SPWidget' | 'SPHeaderFooter',
+    tablePrefix: string = 'sp_widget',
+    includeStaticField: boolean = false
+) {
+    const folderName =
+        record.get('id')?.asString()?.getValue()?.replace(/[\s-]/g, '_') ||
+        record.get('name')?.asString()?.getValue()?.toLowerCase().replace(/[\s-]/g, '_')
+    const dependencies = descendants.query('m2m_sp_widget_dependency')
+    const angularProviders = descendants.query('m2m_sp_ng_pro_sp_widget')
+    const templates = descendants.query('sp_ng_template').map((template) => {
+        return {
+            $id: template.getId(),
+            id: template.get('id'),
+            htmlTemplate: template.get('template'),
+        }
+    })
+
+    const category = reverseObject(WidgetCategories)[record.get('category').ifString()?.getValue() || '']
+    const serverScript = await createIncludeShape(
+        record,
+        record.get('script'),
+        'server_script',
+        'js',
+        folderName,
+        tablePrefix
+    )
+    const clientScript = await createIncludeShape(
+        record,
+        record.get('client_script'),
+        'client_script',
+        'js',
+        folderName,
+        tablePrefix
+    )
+    const css = await createIncludeShape(record, record.get('css'), 'style', 'scss', folderName, tablePrefix)
+    const htmlTemplate = await createIncludeShape(
+        record,
+        record.get('template'),
+        'template',
+        'html',
+        folderName,
+        tablePrefix
+    )
+    const linkScript = await createIncludeShape(
+        record,
+        record.get('link'),
+        'link-script',
+        'js',
+        folderName,
+        tablePrefix
+    )
+
+    return {
+        success: true,
+        value: new CallExpressionShape({
+            source: record,
+            callee,
+            args: [
+                record.transform(({ $ }) => {
+                    const baseTransform = {
+                        $id: $.val(NowIdShape.from(record)),
+                        name: $,
+                        category: $.val(category).def('custom'),
+                        clientScript: $.val(clientScript).def(''),
+                        serverScript: $.val(serverScript).def(''),
+                        controllerAs: $.from('controller_as').def('c'),
+                        htmlTemplate: $.val(htmlTemplate).def(''),
+                        customCss: $.val(css).def(''),
+                        dataTable: $.from('data_table')
+                            .map((v: Shape) => {
+                                const val = v.ifString()?.getValue()
+                                return val && val.trim() !== '' ? val : 'sp_instance'
+                            })
+                            .def('sp_instance'),
+                        demoData: $.from('demo_data')
+                            .map((d: Shape) => {
+                                const json = d.ifString()?.getValue()
+
+                                const parsed = noThrow(() => json && JSON.parse(json))
+                                return parsed instanceof Error ? json : parsed
+                            })
+                            .def(''),
+                        description: $.def(''),
+                        docs: $.def(''),
+                        fields: $.from('field_list')
+                            .map((fields: Shape) => {
+                                const fieldStr = fields.ifString()?.getValue()
+                                const fieldArray = fieldStr?.split(',').filter((f: string) => f.trim())
+                                return fieldArray && fieldArray.length > 0 ? fieldArray : undefined
+                            })
+                            .def(undefined),
+                        hasPreview: $.from('has_preview').toBoolean().def(false),
+                        id: $.def(''),
+                        internal: $.toBoolean().def(false),
+                        linkScript: $.val(linkScript).def(''),
+                        roles: $.map((role: Shape) => {
+                            const roleStr = role.ifString()?.getValue()
+                            const roleArray = roleStr?.split(',').filter((r: string) => r.trim())
+                            return roleArray && roleArray.length > 0 ? roleArray : undefined
+                        }).def(undefined),
+                        servicenow: $.toBoolean().def(false),
+                        optionSchema: $.from('option_schema')
+                            .map((v: Shape) => {
+                                const json = v.ifString()?.getValue()
+                                const parsed = noThrow(() => json && JSON.parse(json))
+                                const result = parsed instanceof Error ? json : parsed
+                                return convertOptionSchemaKeys(result, toCamelCase)
+                            })
+                            .def(''),
+                        public: $.toBoolean().def(false),
+                        dependencies: $.val(
+                            dependencies.length > 0 ? dependencies.map((dep) => dep.get('sp_dependency')) : undefined
+                        ),
+                        angularProviders: $.val(
+                            angularProviders.length > 0
+                                ? angularProviders.map((ap) => ap.get('sp_angular_provider'))
+                                : undefined
+                        ),
+                        templates: $.val(templates.length > 0 ? templates : undefined),
+                    }
+
+                    return includeStaticField
+                        ? { ...baseTransform, static: $.from('static').toBoolean().def(false) }
+                        : baseTransform
+                }),
+            ],
+        }),
+    }
+}
 
 /**
  * Creates a NowIncludeShape with a custom file path suffix and extension
@@ -9,9 +167,10 @@ export async function createIncludeShape(
     content: string | Shape,
     suffix: string,
     extension: 'js' | 'html' | 'scss',
-    folderName: string
+    folderName: string,
+    tablePrefix: string = 'sp_widget'
 ): Promise<NowIncludeShape> {
-    const baseName = `sp_widget_${folderName}`
+    const baseName = `${tablePrefix}_${folderName}`
     const includedText = content instanceof Shape ? content.toString().getValue() : content
 
     return new NowIncludeShape({
@@ -23,6 +182,248 @@ export async function createIncludeShape(
 
 export const DEFAULT_ORDER = 100
 
+/**
+ * Shared toRecord implementation for SPWidget and SPHeaderFooter
+ */
+export async function createWidgetToRecord(
+    callExpression: CallExpressionShape,
+    {
+        diagnostics,
+        factory,
+        config,
+    }: {
+        diagnostics: Diagnostics
+        factory: Factory
+        config: { scope: string }
+    },
+    options: {
+        callee: 'SPWidget' | 'SPHeaderFooter'
+        table: 'sp_widget' | 'sp_header_footer'
+        includeStaticField?: boolean
+        getDefaultClientScript: (controller: string) => string
+        defaultServerScript: string
+        defaultLinkScript: string
+        defaultHtmlTemplate: string
+    }
+) {
+    const { table, includeStaticField = false } = options
+    const widget = callExpression.getArgument(0).asObject()
+    const dependencies =
+        widget
+            .get('dependencies')
+            .ifArray()
+            ?.map((dep) => (dep.isString() ? dep.getValue() : dep.ifRecord()?.getId()))
+            .filter((dep) => dep) ?? []
+    const angularProviders =
+        widget
+            .get('angularProviders')
+            .ifArray()
+            ?.map((ap) => (ap.isString() ? ap.getValue() : ap.ifRecord()?.getId()))
+            .filter((ap) => ap) ?? []
+
+    const templates: Array<{ $id: string; id: unknown; htmlTemplate: unknown }> =
+        widget
+            .get('templates')
+            .ifArray()
+            ?.map((shp) => shp.getValue() as { $id: string; id: unknown; htmlTemplate: unknown }) ?? []
+    const widgetId = widget.get('id').ifString()
+    if (widgetId && !/^[a-zA-Z0-9_-]+$/g.test(widgetId.getValue())) {
+        diagnostics.error(
+            widgetId.getOriginalNode(),
+            `Invalid value: must contain only alphanumeric, -, or _ characters`
+        )
+    }
+
+    const clientScript = widget.get('clientScript')
+    const clientScriptValue =
+        clientScript instanceof NowIncludeShape ? clientScript.getValue() : clientScript.ifString()?.getValue()
+    if (clientScriptValue && clientScriptValue.trim().length > 0) {
+        const clientScriptPattern =
+            /^(function|api\.controller\s?=\s?function)\s?([$a-z_][$0-9a-z_]*)?\s?\(.*\)\s?\n?{/i
+        if (!clientScriptPattern.test(clientScriptValue.trim())) {
+            diagnostics.error(
+                clientScript.getOriginalNode(),
+                `Client controller must contain a JavaScript function. Example: api.controller = function($scope) { ... }`
+            )
+        }
+    }
+
+    const htmlTemplate = widget.get('htmlTemplate')
+    const htmlTemplateValue =
+        htmlTemplate instanceof NowIncludeShape ? htmlTemplate.getValue() : htmlTemplate.ifString()?.getValue()
+    if (htmlTemplateValue && htmlTemplateValue.length > 0 && htmlTemplateValue.indexOf('href="#"') > 0) {
+        diagnostics.error(
+            htmlTemplate.getOriginalNode(),
+            `Do not use href="#" in the Service Portal, use href="javascript:void(0)" instead`
+        )
+    }
+
+    const roles = widget
+        .get('roles')
+        .ifArray()
+        ?.map((role) => {
+            if (role.isString()) {
+                return role
+            }
+            if (role.isRecord()) {
+                return role.get('name')
+            }
+
+            return undefined
+        })
+        .filter((role) => role) as Shape[] | undefined
+
+    if (roles) {
+        roles
+            .filter((role) => isGUID(role.getValue() as string))
+            .forEach((role) =>
+                diagnostics.error(
+                    role!.getOriginalNode(),
+                    `expecting role names or role records created by the Role or Record plugins, not sys_ids`
+                )
+            )
+    }
+
+    const controller = widget.get('controllerAs').ifString()?.getValue() || 'c'
+    const servicenow =
+        (widget.get('servicenow').ifBoolean()?.getValue() &&
+            (config.scope.startsWith('sn_') || config.scope.startsWith('snc_'))) ||
+        false
+
+    const widgetRecord = await factory.createRecord({
+        source: callExpression,
+        table,
+        explicitId: widget.get('$id'),
+        properties: widget.transform(({ $ }) => {
+            const baseTransform = {
+                name: $,
+                category: $.map((v) => {
+                    const catKey = v.ifString()?.getValue() || ''
+                    return WidgetCategories[catKey as keyof typeof WidgetCategories]
+                }).def('custom'),
+                client_script: $.from('clientScript').def(options.getDefaultClientScript(controller)),
+                script: $.from('serverScript').def(options.defaultServerScript),
+                controller_as: $.from('controllerAs').def('c'),
+                template: $.from('htmlTemplate').def(options.defaultHtmlTemplate),
+                css: $.from('customCss').def(''),
+                data_table: $.from('dataTable').def('sp_instance'),
+                demo_data: $.from('demoData')
+                    .map((v) => (v.ifString() || v instanceof NowIncludeShape ? v : JSON.stringify(v.getValue())))
+                    .def(''),
+                description: $.def(''),
+                docs: $.map((v) => (v.isString() ? v : v.ifRecord()?.getId())),
+                field_list: $.from('fields')
+                    .map((v) => v.getValue()?.toString())
+                    .def(''),
+                has_preview: $.from('hasPreview').toBoolean().def(false),
+                id: $.def(''),
+                internal: $.def(false),
+                servicenow: $.val(servicenow),
+                link: $.from('linkScript').def(options.defaultLinkScript),
+                roles: $.val(roles?.map((r) => r.getValue()).toString()).def(''),
+                option_schema: $.from('optionSchema')
+                    .map((v) => {
+                        const json = v.getValue()
+                        const converted = convertOptionSchemaKeys(json, (key: string) =>
+                            key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)
+                        )
+                        return converted && JSON.stringify(converted)
+                    })
+                    .def(''),
+                public: $.def(false),
+            }
+
+            return includeStaticField
+                ? { ...baseTransform, static: $.from('static').toBoolean().def(false) }
+                : baseTransform
+        }),
+    })
+
+    return {
+        success: true,
+        value: widgetRecord.with(
+            ...(await Promise.all(
+                templates.map(async (template) => {
+                    return await factory.createRecord({
+                        source: callExpression,
+                        table: 'sp_ng_template',
+                        explicitId: template.$id,
+                        properties: {
+                            id: template.id,
+                            sp_widget: widgetRecord.getId(),
+                            template: template.htmlTemplate,
+                        },
+                    })
+                })
+            )),
+            ...(await Promise.all(
+                dependencies.map(async (dep) => {
+                    return await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_widget_dependency',
+                        properties: {
+                            sp_dependency: dep!,
+                            sp_widget: widgetRecord.getId(),
+                        },
+                    })
+                })
+            )),
+            ...(await Promise.all(
+                angularProviders.map(async (ap) => {
+                    return await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_ng_pro_sp_widget',
+                        properties: {
+                            sp_angular_provider: ap!,
+                            sp_widget: widgetRecord.getId(),
+                        },
+                    })
+                })
+            ))
+        ),
+    }
+}
+
+/**
+ * Converts a roles Shape (array of strings, Role() expressions, or Record references)
+ * to a deduplicated comma-separated string of role names.
+ * @param rolesShape - Shape containing the roles array
+ * @param diagnostics - Optional diagnostics for reporting invalid role entries
+ * @returns Comma-separated string of unique role names, or empty string if no roles
+ */
+export function getRolesString(rolesShape: Shape, diagnostics?: Diagnostics): string {
+    const roles = rolesShape
+        .ifArray()
+        ?.getElements()
+        .map((role) => {
+            if (role.isString()) {
+                return role.getValue()
+            }
+            if (role instanceof CallExpressionShape) {
+                const name = role.getArgument(0).asObject().get('name')
+                if (name.isString()) {
+                    return name.getValue()
+                }
+            }
+            if (role.isRecord()) {
+                const name = role.get('name')
+                if (name?.isString()) {
+                    return name.getValue()
+                }
+            }
+            if (diagnostics) {
+                diagnostics.error(role, 'roles must be strings or role records')
+            }
+            return undefined
+        })
+        .filter((r): r is string => r !== undefined && r.trim() !== '')
+
+    if (!roles || roles.length === 0) {
+        return ''
+    }
+    return [...new Set(roles)].join(',')
+}
+
 export async function getIncludeRecords(
     shape: Shape,
     parentId: Shape,