@servicenow/sdk-build-plugins 4.4.1 → 4.6.0

package/src/service-portal/page-route-map-plugin.ts

@@ -0,0 +1,124 @@
+import { CallExpressionShape, Plugin, type Shape } from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../now-id-plugin'
+import { toReference, createSdkDocEntry } from '../utils'
+import { getRolesString } from './utils'
+
+function getPortalsString(portalsShape: Shape): string {
+    const portals = portalsShape
+        .ifArray()
+        ?.getElements()
+        .map((p) => {
+            const ref = toReference(p)
+            return typeof ref === 'string' ? ref : ref.getValue()
+        })
+        .filter((id) => id !== '')
+
+    if (!portals || portals.length === 0) {
+        return ''
+    }
+    return [...new Set(portals)].join(',')
+}
+
+export const SPPageRouteMapPlugin = Plugin.create({
+    name: 'SPPageRouteMapPlugin',
+    docs: [createSdkDocEntry('SPPageRouteMap', ['sp_page_route_map'])],
+    records: {
+        sp_page_route_map: {
+            coalesce: ['route_from_page', 'portals'],
+            toShape(record) {
+                const portalsStr = record.get('portals').ifString()?.getValue() ?? ''
+                const portalsArray = portalsStr
+                    ? portalsStr
+                          .split(',')
+                          .map((p) => p.trim())
+                          .filter((p) => p !== '')
+                    : []
+
+                const rolesStr = record.get('roles').ifString()?.getValue() ?? ''
+                const rolesArray = rolesStr
+                    ? rolesStr
+                          .split(',')
+                          .map((r) => r.trim())
+                          .filter((r) => r !== '')
+                    : []
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'SPPageRouteMap',
+                        args: [
+                            record.transform(({ $ }) => {
+                                const config: { [key: string]: typeof $ | undefined } = {
+                                    $id: $.val(NowIdShape.from(record)),
+                                    routeFromPage: $.from('route_from_page'),
+                                    routeToPage: $.from('route_to_page'),
+                                    shortDescription: $.from('short_description').def(''),
+                                    active: $.from('active').toBoolean().def(true),
+                                    order: $.from('order').toNumber().def(10),
+                                }
+                                if (portalsArray.length > 0) {
+                                    config['portals'] = $.val(portalsArray)
+                                }
+                                if (rolesArray.length > 0) {
+                                    config['roles'] = $.val(rolesArray)
+                                }
+                                return config
+                            }),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'SPPageRouteMap') {
+                    return { success: false }
+                }
+
+                const args = callExpression.getArgument(0).asObject()
+
+                const routeFromShape = args.get('routeFromPage')
+                const routeToShape = args.get('routeToPage')
+                const routeFromRef = toReference(routeFromShape)
+                const routeToRef = toReference(routeToShape)
+                const routeFromStr = typeof routeFromRef === 'string' ? routeFromRef : routeFromRef.getValue()
+                const routeToStr = typeof routeToRef === 'string' ? routeToRef : routeToRef.getValue()
+
+                if (routeFromStr !== '' && routeToStr !== '' && routeFromStr === routeToStr) {
+                    diagnostics.error(
+                        routeToShape.getOriginalNode(),
+                        `Invalid SPPageRouteMap: "routeToPage" must be different from "routeFromPage".`
+                    )
+                }
+
+                const portalsString = getPortalsString(args.get('portals'))
+                const rolesString = getRolesString(args.get('roles'), diagnostics)
+
+                const routeMapRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_page_route_map',
+                    explicitId: args.get('$id'),
+                    properties: args.transform(({ $ }) => ({
+                        route_from_page: $.from('routeFromPage').map(toReference).def(''),
+                        route_to_page: $.from('routeToPage').map(toReference).def(''),
+                        short_description: $.from('shortDescription').def(''),
+                        portals: $.val(portalsString).def(''),
+                        roles: $.val(rolesString).def(''),
+                        active: $.def(true),
+                        order: $.def(10),
+                    })),
+                })
+
+                return {
+                    success: true,
+                    value: routeMapRecord,
+                }
+            },
+        },
+    ],
+})

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

@@ -0,0 +1,342 @@
+import { Plugin, CallExpressionShape, type Record, type Shape } from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../now-id-plugin'
+import { createSdkDocEntry } from '../utils'
+
+function convertToNumber(value: Shape, defaultValue: number = 0): number {
+    if (!value || value.isUndefined() || value.ifString()?.isEmpty()) {
+        return defaultValue
+    }
+    return value.toNumber()?.getValue() ?? defaultValue
+}
+
+export const ServicePortalPlugin = Plugin.create({
+    name: 'ServicePortalPlugin',
+    docs: [createSdkDocEntry('ServicePortal', ['sp_portal'])],
+    records: {
+        sp_portal: {
+            relationships: {
+                m2m_sp_portal_search_source: {
+                    descendant: true,
+                    via: 'sp_portal',
+                },
+                m2m_sp_portal_knowledge_base: {
+                    descendant: true,
+                    via: 'sp_portal',
+                },
+                m2m_sp_portal_catalog: {
+                    descendant: true,
+                    via: 'sp_portal',
+                },
+                m2m_sp_portal_taxonomy: {
+                    descendant: true,
+                    via: 'sp_portal',
+                },
+            },
+            toShape(record, { descendants }) {
+                // Handle search sources
+                const searchSources = descendants.query('m2m_sp_portal_search_source').map((m2m) => {
+                    return {
+                        searchSource: m2m.get('sp_search_source'),
+                        order: convertToNumber(m2m.get('order'), 100),
+                    }
+                })
+
+                // Handle knowledge bases
+                const knowledgeBases = descendants
+                    .query('m2m_sp_portal_knowledge_base')
+                    .filter((m2m) => !m2m.get('kb_knowledge_base')?.ifString()?.isEmpty())
+                    .map((m2m) => {
+                        return {
+                            knowledgeBase: m2m.get('kb_knowledge_base'),
+                            order: convertToNumber(m2m.get('order'), 100),
+                            active: m2m.get('active')?.isUndefined()
+                                ? undefined
+                                : m2m.get('active')?.toBoolean()?.getValue(),
+                        }
+                    })
+
+                // Handle catalogs
+                const catalogs = descendants
+                    .query('m2m_sp_portal_catalog')
+                    .filter((m2m) => !m2m.get('sc_catalog')?.ifString()?.isEmpty())
+                    .map((m2m) => {
+                        return {
+                            catalog: m2m.get('sc_catalog'),
+                            order: convertToNumber(m2m.get('order'), 100),
+                            active: m2m.get('active')?.isUndefined()
+                                ? undefined
+                                : m2m.get('active')?.toBoolean()?.getValue(),
+                        }
+                    })
+
+                // Handle taxonomies
+                const taxonomies = descendants.query('m2m_sp_portal_taxonomy').map((m2m) => {
+                    return {
+                        taxonomy: m2m.get('taxonomy'),
+                        order: convertToNumber(m2m.get('order'), 100),
+                        active: m2m.get('active')?.isUndefined()
+                            ? undefined
+                            : m2m.get('active')?.toBoolean()?.getValue(),
+                    }
+                })
+
+                const portalRecord = new CallExpressionShape({
+                    source: record,
+                    callee: 'ServicePortal',
+                    args: [
+                        record.transform(({ $ }) => ({
+                            $id: $.val(NowIdShape.from(record)),
+                            title: $,
+                            urlSuffix: $.from('url_suffix').def(''),
+                            icon: $.from('icon').def(''),
+                            logo: $.from('logo').def(''),
+                            logoAltText: $.from('logo_alt_text').def(''),
+                            quickStartConfig: $.from('quick_start_config').def(''),
+                            embeddableMacroponents: $.from('embeddable_macroponents').def(''),
+                            communicationChannels: $.from('communication_channels').def(''),
+                            cssVariables: $.from('css_variables').def(''),
+                            theme: $.from('theme').def(''),
+                            darkTheme: $.from('dark_theme').def(''),
+                            mainMenu: $.from('sp_rectangle_menu').def(''),
+                            categoryHomePage: $.from('sc_category_page').def(''),
+                            homePage: $.from('homepage').def(''),
+                            searchResultsConfiguration: $.from('search_results_configuration').def(''),
+                            searchApplication: $.from('search_application').def(''),
+                            alternatePortal: $.from('alternate_portal').def(''),
+                            catalogHomePage: $.from('sc_catalog_page').def(''),
+                            loginPage: $.from('login_page').def(''),
+                            knowledgeHomePage: $.from('kb_knowledge_page').def(''),
+                            chatQueue: $.from('sp_chat_queue').def(''),
+                            notFoundPage: $.from('notfound_page').def(''),
+                            textIndexGroup: $.from('ts_index_group').def(''),
+                            enableAiSearch: $.from('enable_ais').toBoolean().def(false),
+                            enableCertificateBasedAuthentication: $.from('enable_certificate_based_authentication')
+                                .toBoolean()
+                                .def(false),
+                            defaultPortal: $.from('default').toBoolean().def(false),
+                            enableWebEmbeddables: $.from('enable_embeddables').toBoolean().def(false),
+                            enableFavorites: $.from('enable_favorites').toBoolean().def(false),
+                            inactive: $.from('inactive').toBoolean().def(false),
+                            hidePortalName: $.from('hide_portal_name').toBoolean().def(false),
+                            supportRightToLeftLanguages: $.from('rtl_enabled').toBoolean().def(false),
+                            searchSources: $.val(searchSources).def([]),
+                            knowledgeBases: $.val(knowledgeBases).def([]),
+                            catalogs: $.val(catalogs).def([]),
+                            taxonomies: $.val(taxonomies).def([]),
+                        })),
+                    ],
+                })
+
+                return {
+                    success: true,
+                    value: portalRecord,
+                }
+            },
+        },
+        m2m_sp_portal_search_source: {
+            coalesce: ['sp_portal', 'sp_search_source'],
+        },
+        m2m_sp_portal_knowledge_base: {
+            coalesce: ['sp_portal', 'kb_knowledge_base'],
+        },
+        m2m_sp_portal_catalog: {
+            coalesce: ['sp_portal', 'sc_catalog'],
+        },
+        m2m_sp_portal_taxonomy: {
+            coalesce: ['sp_portal', 'taxonomy'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== 'ServicePortal') {
+                    return { success: false }
+                }
+                const portalArgs = callExpression.getArgument(0).asObject()
+
+                const urlSuffix = portalArgs.get('urlSuffix').ifString()
+                if (urlSuffix) {
+                    const raw = urlSuffix.getValue()
+                    let normalized = raw.toLowerCase().replace(/[^a-zA-Z0-9_]/g, '_')
+                    while (normalized.indexOf('__') !== -1) {
+                        normalized = normalized.replace(/__/g, '_')
+                    }
+                    while (normalized !== '' && normalized.charAt(normalized.length - 1) === '_') {
+                        normalized = normalized.substring(0, normalized.length - 1)
+                    }
+                    if (raw !== normalized) {
+                        diagnostics.error(
+                            urlSuffix.getOriginalNode(),
+                            `Invalid url_suffix '${raw}'. Use lowercase alphanumeric and single underscores only (e.g. '${normalized}')`
+                        )
+                    }
+                }
+                const catalogsForM2M = portalArgs.get('catalogs')?.ifArray()?.getElements() ?? []
+                const knowledgeBasesForM2M = portalArgs.get('knowledgeBases')?.ifArray()?.getElements() ?? []
+
+                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(''),
+                    icon: $.from('icon'),
+                    logo: $.from('logo'),
+                    logo_alt_text: $.from('logoAltText'),
+                    quick_start_config: $.from('quickStartConfig'),
+                    embeddable_macroponents: $.from('embeddableMacroponents'),
+                    communication_channels: $.from('communicationChannels'),
+                    css_variables: $.from('cssVariables'),
+                    theme: $.from('theme'),
+                    dark_theme: $.from('darkTheme'),
+                    sp_rectangle_menu: $.from('mainMenu'),
+                    sc_category_page: $.from('categoryHomePage'),
+                    homepage: $.from('homePage'),
+                    search_results_configuration: $.from('searchResultsConfiguration'),
+                    search_application: $.from('searchApplication'),
+                    alternate_portal: $.from('alternatePortal'),
+                    sc_catalog_page: $.from('catalogHomePage'),
+                    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),
+                    enable_embeddables: $.from('enableWebEmbeddables').def(false),
+                    enable_favorites: $.from('enableFavorites').def(false),
+                    inactive: $.from('inactive').def(false),
+                    hide_portal_name: $.from('hidePortalName').def(false),
+                    rtl_enabled: $.from('supportRightToLeftLanguages').def(false),
+                }))
+
+                const portalRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_portal',
+                    explicitId: portalArgs.get('$id'),
+                    properties: baseProperties,
+                })
+
+                // Handle search sources
+                const searchSources = portalArgs.get('searchSources')?.ifArray()?.getElements() ?? []
+
+                const searchSourceRecords: Record[] = []
+                for (const source of searchSources) {
+                    const sourceObj = source.asObject()
+                    const searchSourceRecord = await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_portal_search_source',
+                        properties: {
+                            sp_portal: portalRecord,
+                            sp_search_source: sourceObj.get('searchSource'),
+                            order: convertToNumber(sourceObj.get('order'), 100),
+                        },
+                    })
+                    searchSourceRecords.push(searchSourceRecord)
+                }
+
+                // Handle knowledge bases
+
+                const knowledgeBaseRecords: Record[] = []
+                for (const kb of knowledgeBasesForM2M) {
+                    const kbObj = kb.asObject()
+                    const knowledgeBaseRecord = await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_portal_knowledge_base',
+                        properties: {
+                            sp_portal: portalRecord,
+                            kb_knowledge_base: kbObj.get('knowledgeBase'),
+                            order: convertToNumber(kbObj.get('order'), 100),
+                            active: kbObj.get('active')?.isUndefined()
+                                ? true
+                                : kbObj.get('active').toBoolean().getValue(),
+                        },
+                    })
+                    knowledgeBaseRecords.push(knowledgeBaseRecord)
+                }
+
+                // Handle catalogs
+                const catalogRecords: Record[] = []
+                for (const cat of catalogsForM2M) {
+                    const catObj = cat.asObject()
+                    const catalogRecord = await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_portal_catalog',
+                        properties: {
+                            sp_portal: portalRecord,
+                            sc_catalog: catObj.get('catalog'),
+                            order: convertToNumber(catObj.get('order'), 100),
+                            active: catObj.get('active')?.isUndefined()
+                                ? true
+                                : catObj.get('active').toBoolean().getValue(),
+                        },
+                    })
+                    catalogRecords.push(catalogRecord)
+                }
+
+                // Handle taxonomies
+                const taxonomies = portalArgs.get('taxonomies')?.ifArray()?.getElements() ?? []
+                const taxonomyRecords: Record[] = []
+                for (const tax of taxonomies) {
+                    const taxObj = tax.asObject()
+                    const taxonomyRecord = await factory.createRecord({
+                        source: callExpression,
+                        table: 'm2m_sp_portal_taxonomy',
+                        properties: {
+                            sp_portal: portalRecord,
+                            taxonomy: taxObj.get('taxonomy'),
+                            order: convertToNumber(taxObj.get('order'), 100),
+                            active: taxObj.get('active')?.isUndefined()
+                                ? true
+                                : taxObj.get('active').toBoolean().getValue(),
+                        },
+                    })
+                    taxonomyRecords.push(taxonomyRecord)
+                }
+
+                return {
+                    success: true,
+                    value: portalRecord.with(
+                        ...searchSourceRecords,
+                        ...knowledgeBaseRecords,
+                        ...catalogRecords,
+                        ...taxonomyRecords
+                    ),
+                }
+            },
+        },
+    ],
+})

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

@@ -0,0 +1,135 @@
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../now-id-plugin'
+import { DEFAULT_ORDER, getIncludeRecords } from './utils'
+import { createSdkDocEntry } from '../utils'
+
+export const SPThemePlugin = Plugin.create({
+    name: 'SPThemePlugin',
+    docs: [createSdkDocEntry('SPTheme', ['sp_theme'])],
+    records: {
+        sp_theme: {
+            relationships: {
+                m2m_sp_theme_js_include: { via: 'sp_theme', descendant: true },
+                m2m_sp_theme_css_include: { via: 'sp_theme', descendant: true },
+            },
+            toShape(record, { descendants }) {
+                const cssIncludeRecords = descendants.query('m2m_sp_theme_css_include')
+                const cssIncludes = cssIncludeRecords
+                    .map((m2m) => {
+                        const orderValue = m2m.get('order')
+                        const order =
+                            (orderValue?.ifString()?.isEmpty() ? undefined : orderValue?.toNumber()?.getValue()) ??
+                            DEFAULT_ORDER
+                        return {
+                            order,
+                            include: m2m.get('sp_css_include'),
+                        }
+                    })
+                    .sort((a, b) => a.order - b.order)
+
+                const jsIncludeRecords = descendants.query('m2m_sp_theme_js_include')
+                const jsIncludes = jsIncludeRecords
+                    .map((m2m) => {
+                        const orderValue = m2m.get('order')
+                        const order =
+                            (orderValue?.ifString()?.isEmpty() ? undefined : orderValue?.toNumber()?.getValue()) ??
+                            DEFAULT_ORDER
+                        return {
+                            order,
+                            include: m2m.get('sp_js_include'),
+                        }
+                    })
+                    .sort((a, b) => a.order - b.order)
+
+                const themeOptions = record.transform(({ $ }) => ({
+                    $id: $.val(NowIdShape.from(record)),
+                    name: $,
+                    customCss: $.from('css_variables').def(''),
+                    header: $.def(''),
+                    footer: $.def(''),
+                    fixedHeader: $.from('navbar_fixed').toBoolean().def(true),
+                    fixedFooter: $.from('footer_fixed').toBoolean().def(true),
+                    turnOffScssCompilation: $.from('turn_off_scss_compilation').toBoolean().def(false),
+                    matchingNextExperienceTheme: $.from('matching_now_experience_theme').def(''),
+                    cssIncludes: $.val(cssIncludes.length > 0 ? cssIncludes : undefined),
+                    jsIncludes: $.val(jsIncludes.length > 0 ? jsIncludes : undefined),
+                    icon: $.def(''),
+                    logo: $.def(''),
+                    logoAltText: $.from('logo_alt_text').def(''),
+                }))
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'SPTheme',
+                        args: [themeOptions],
+                    }),
+                }
+            },
+        },
+        m2m_sp_theme_css_include: {
+            coalesce: ['sp_css_include', 'sp_theme'],
+        },
+        m2m_sp_theme_js_include: {
+            coalesce: ['sp_js_include', 'sp_theme'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { diagnostics, factory }) {
+                if (callExpression.getCallee() !== 'SPTheme') {
+                    return { success: false }
+                }
+
+                const theme = callExpression.getArgument(0).asObject()
+
+                const themeRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sp_theme',
+                    explicitId: theme.get('$id'),
+                    properties: theme.transform(({ $ }) => ({
+                        name: $,
+                        css_variables: $.from('customCss').def(''),
+                        header: $,
+                        footer: $,
+                        navbar_fixed: $.from('fixedHeader').def(true),
+                        footer_fixed: $.from('fixedFooter').def(true),
+                        turn_off_scss_compilation: $.from('turnOffScssCompilation').def(false),
+                        matching_now_experience_theme: $.from('matchingNextExperienceTheme').def(''),
+                        icon: $,
+                        logo: $,
+                        logo_alt_text: $.from('logoAltText').def(''),
+                    })),
+                })
+
+                const cssIncludes = await getIncludeRecords(
+                    theme.get('cssIncludes'),
+                    themeRecord.getId(),
+                    factory,
+                    'm2m_sp_theme_css_include',
+                    'sp_css_include',
+                    'sp_theme',
+                    diagnostics
+                )
+
+                const jsIncludes = await getIncludeRecords(
+                    theme.get('jsIncludes'),
+                    themeRecord.getId(),
+                    factory,
+                    'm2m_sp_theme_js_include',
+                    'sp_js_include',
+                    'sp_theme',
+                    diagnostics
+                )
+
+                return {
+                    success: true,
+                    value: themeRecord.with(...cssIncludes, ...jsIncludes),
+                }
+            },
+        },
+    ],
+})