@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/ui-policy-plugin.ts

@@ -9,6 +9,7 @@ import {
     type Shape,
 } from '@servicenow/sdk-build-core'
 import { validateClientSideScript } from './utils'
+import { NowIdShape } from './now-id-plugin'
 
 // Define table names as constants since they're not exported from the core tables
 const SYS_UI_POLICY = 'sys_ui_policy'
@@ -201,10 +202,7 @@ export const UiPolicyPlugin = Plugin.create({
                         const rlActionObj: {
                             list?: string
                             visible?: boolean | 'ignore'
-                            $id: string
-                        } = {
-                            $id: rlAction.getId().getValue(),
-                        }
+                        } = {}
 
                         const listValue = rlAction.get('list')?.ifString()?.getValue()
                         if (listValue) {
@@ -224,7 +222,7 @@ export const UiPolicyPlugin = Plugin.create({
                         }
 
                         // Skip if no meaningful properties (only $id exists)
-                        if (Object.keys(rlActionObj).length === 1 && rlActionObj.$id) {
+                        if (Object.keys(rlActionObj).length === 0) {
                             return null
                         }
 
@@ -247,7 +245,7 @@ export const UiPolicyPlugin = Plugin.create({
                                 const includeScriptFalse = runScriptsValue || isValidScript(scriptFalseValue)
 
                                 return {
-                                    $id: $.val(record.getId()),
+                                    $id: $.val(NowIdShape.from(record)),
                                     table: $.from('table').def(''),
                                     shortDescription: $.from('short_description'),
                                     active: $.toBoolean().def(true),
@@ -317,8 +315,6 @@ export const UiPolicyPlugin = Plugin.create({
                     return { success: false }
                 }
 
-                const $id = arg.get('$id')
-
                 // Validate table scope prefix for scoped apps
                 const tableValue = arg.get('table')
                 if (tableValue?.isString() && config?.scope) {
@@ -357,7 +353,7 @@ export const UiPolicyPlugin = Plugin.create({
                 const policyRecord = await factory.createRecord({
                     source: callExpression,
                     table: SYS_UI_POLICY,
-                    explicitId: $id,
+                    explicitId: arg.get('$id'),
                     properties: arg.transform(({ $ }) => ({
                         table: $.from('table').def(''),
                         short_description: $.from('shortDescription'),

package/src/utils.ts

@@ -1,4 +1,11 @@
-import { ts, type Shape, type ObjectShape, type Diagnostics, type Compiler } from '@servicenow/sdk-build-core'
+import {
+    ts,
+    type Shape,
+    type ObjectShape,
+    type Diagnostics,
+    type Compiler,
+    type PluginApiDoc,
+} from '@servicenow/sdk-build-core'
 
 export function toReference(shape: Shape) {
     return shape.ifRecord()?.getId() ?? shape.ifString()?.getValue() ?? ''
@@ -93,3 +100,19 @@ export function validateClientSideScript(script: string, compiler: Compiler): bo
 
     return isValid
 }
+
+/**
+ * Creates a documentation entry for first-party SDK plugins.
+ * Using this helper ensures apiName and docPath are always in sync.
+ *
+ * @param apiName - The API name (e.g., 'BusinessRule', 'Acl')
+ * @param tags - Keywords for categorization (typically includes the ServiceNow table name)
+ * @returns A complete PluginApiDoc entry
+ */
+export function createSdkDocEntry(apiName: string, tags: string[]): PluginApiDoc {
+    return {
+        apiName,
+        docPath: `@servicenow/sdk/docs/${apiName}/${apiName}.md`,
+        tags,
+    }
+}

package/src/ux-list-menu-config-plugin.ts

@@ -0,0 +1,312 @@
+import { Plugin, CallExpressionShape, type Record } from '@servicenow/sdk-build-core'
+
+import { NowIdShape } from './now-id-plugin'
+
+export const UxListMenuConfigPlugin = Plugin.create({
+    name: 'UxListMenuConfigPlugin',
+    records: {
+        sys_ux_list_menu_config: {
+            relationships: {
+                sys_ux_list_category: {
+                    via: 'configuration',
+                    descendant: true,
+                },
+                sys_ux_list: {
+                    via: 'configuration',
+                    descendant: true,
+                },
+            },
+            toShape(record, { descendants }) {
+                const categories = descendants.query('sys_ux_list_category').map((category) => {
+                    const lists = descendants
+                        .query('sys_ux_list')
+                        .filter((list) => {
+                            const categoryGuid = list.get('category').isString()
+                                ? list.get('category').getValue()
+                                : list.get('category').asRecord().getId().getValue()
+
+                            return categoryGuid === category.getId().getValue()
+                        })
+                        .map((list) => {
+                            const applicabilities = descendants.query('sys_ux_applicability_m2m_list').filter((app) => {
+                                const listGuid = app.get('list').isString()
+                                    ? app.get('list').getValue()
+                                    : app.get('list').asRecord().getId().getValue()
+
+                                return listGuid === list.getId().getValue()
+                            })
+
+                            const applicabilityShapes = applicabilities.map((app) => {
+                                return app.transform(({ $ }) => ({
+                                    $id: $.val(NowIdShape.from(app)),
+                                    active: $.from('active').def(true).toBoolean(),
+                                    applicability: $.from('applicability'),
+                                    order: $.from('order').def(0).toNumber(),
+                                }))
+                            })
+
+                            return list.transform(({ $ }) => {
+                                return {
+                                    $id: $.val(NowIdShape.from(list)),
+                                    active: $.from('active').def(true).toBoolean(),
+                                    applicabilities: $.val(applicabilityShapes),
+                                    columns: $.from('columns'),
+                                    condition: $.from('condition'),
+                                    enableInfiniteScroll: $.from('enable_infinite_scroll').def(false).toBoolean(),
+                                    fixedQuery: $.from('fixed_query').def(''),
+                                    groupByColumn: $.from('group_by_column').def(''),
+                                    groups: $.from('groups').def(''),
+                                    hideCellFilter: $.from('hide_cell_filter').def(false).toBoolean(),
+                                    hideCheckboxHover: $.from('hide_checkbox_hover').def(false).toBoolean(),
+                                    hideColumnFiltering: $.from('hide_column_filtering').def(false).toBoolean(),
+                                    hideColumnGrouping: $.from('hide_column_grouping').def(false).toBoolean(),
+                                    hideColumnResizing: $.from('hide_column_resizing').def(false).toBoolean(),
+                                    hideColumnSorting: $.from('hide_column_sorting').def(false).toBoolean(),
+                                    hideDragAndDrop: $.from('hide_drag_and_drop').def(false).toBoolean(),
+                                    hideEmptyStateImage: $.from('hide_empty_state_image').def(false).toBoolean(),
+                                    hideFirstPage: $.from('hide_first_page').def(false).toBoolean(),
+                                    hideHeader: $.from('hide_header').def(false).toBoolean(),
+                                    hideHighlightContent: $.from('hide_highlight_content').def(false).toBoolean(),
+                                    hideHighlightedValues: $.from('hide_highlighted_values').def(false).toBoolean(),
+                                    hideInlineEditing: $.from('hide_inline_editing').def(false).toBoolean(),
+                                    hideLastPage: $.from('hide_last_page').def(false).toBoolean(),
+                                    hideLastRefreshedText: $.from('hide_last_refreshed_text').def(false).toBoolean(),
+                                    hideLinks: $.from('hide_links').def(false).toBoolean(),
+                                    hideListActions: $.from('hide_list_actions').def(false).toBoolean(),
+                                    hideMenuButton: $.from('hide_menu_button').def(false).toBoolean(),
+                                    hideNextPage: $.from('hide_next_page').def(false).toBoolean(),
+                                    hideOptionToSaveAs: $.from('hide_option_to_save_as').def(false).toBoolean(),
+                                    hidePages: $.from('hide_pages').def(false).toBoolean(),
+                                    hidePagination: $.from('hide_pagination').def(false).toBoolean(),
+                                    hidePanelAdvanced: $.from('hide_panel_advanced').def(false).toBoolean(),
+                                    hidePanelButton: $.from('hide_panel_button').def(false).toBoolean(),
+                                    hidePanelConditionDelete: $.from('hide_panel_condition_delete')
+                                        .def(false)
+                                        .toBoolean(),
+                                    hidePanelFooter: $.from('hide_panel_footer').def(false).toBoolean(),
+                                    hidePanelRestore: $.from('hide_panel_restore').def(false).toBoolean(),
+                                    hidePersonalization: $.from('hide_personalization').def(false).toBoolean(),
+                                    hidePreviousPage: $.from('hide_previous_page').def(false).toBoolean(),
+                                    hideQuickEdit: $.from('hide_quick_edit').def(false).toBoolean(),
+                                    hideRange: $.from('hide_range').def(false).toBoolean(),
+                                    hideRecordCountBadge: $.from('hide_record_count_badge').def(false).toBoolean(),
+                                    hideReferenceLinks: $.from('hide_reference_links').def(false).toBoolean(),
+                                    hideRefreshButton: $.from('hide_refresh_button').def(false).toBoolean(),
+                                    hideRowCount: $.from('hide_row_count').def(false).toBoolean(),
+                                    hideRowSelector: $.from('hide_row_selector').def(false).toBoolean(),
+                                    hideRowsPerPageSelector: $.from('hide_rows_per_page_selector')
+                                        .def(false)
+                                        .toBoolean(),
+                                    hideSelectAll: $.from('hide_select_all').def(false).toBoolean(),
+                                    hideSharingButton: $.from('hide_sharing_button').def(false).toBoolean(),
+                                    hideTitle: $.from('hide_title').def(false).toBoolean(),
+                                    highlightContentColor: $.from('highlight_content_color').def(''),
+                                    highlightContentPattern: $.from('highlight_content_pattern').def(''),
+                                    listAttributes: $.from('list_attributes').def(''),
+                                    liveUpdates: $.from('live_updates').def('off'),
+                                    maxCharacters: $.from('max_characters').def(4000).toNumber(),
+                                    order: $.from('order').def(100).toNumber(),
+                                    override_word_wrap_user_pref: $.from('override_word_wrap_user_pref')
+                                        .def(false)
+                                        .toBoolean(),
+                                    roles: $.from('roles').def(''),
+                                    table: $.from('table').def(''),
+                                    title: $.from('title').def(''),
+                                    view: $.from('view').def(''),
+                                    wordWrap: $.from('word_wrap').def(false).toBoolean(),
+                                }
+                            })
+                        })
+
+                    return category.transform(({ $ }) => {
+                        return {
+                            $id: $.val(NowIdShape.from(category)),
+                            title: $.from('title').def(''),
+                            order: $.from('order').toNumber().def(100),
+                            description: $.from('description').def(''),
+                            lists: $.val(lists),
+                        }
+                    })
+                })
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'UxListMenuConfig',
+                        args: [
+                            record.transform(({ $ }) => {
+                                return {
+                                    $id: $.val(NowIdShape.from(record)),
+                                    name: $.from('name').def(''),
+                                    active: $.from('active').def(true).toBoolean(),
+                                    description: $.from('description').def(''),
+                                    categories: $.val(categories),
+                                }
+                            }),
+                        ],
+                    }),
+                }
+            },
+        },
+        sys_ux_list_category: {},
+        sys_ux_list: {
+            relationships: {
+                sys_ux_applicability_m2m_list: {
+                    via: 'list',
+                    descendant: true,
+                },
+            },
+        },
+        sys_ux_applicability_m2m_list: {},
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory }) {
+                if (callExpression.getCallee() !== 'UxListMenuConfig') {
+                    return { success: false }
+                }
+
+                const arg = callExpression.getArgument(0).asObject()
+
+                const UxListMenuConfigRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_ux_list_menu_config',
+                    explicitId: arg.get('$id'),
+                    properties: arg.transform(({ $ }) => ({
+                        name: $.from('name').def(''),
+                        description: $.from('description').def(''),
+                        active: $.from('active').def(true),
+                    })),
+                })
+
+                const categories = arg.get('categories').ifArray()?.getElements() ?? []
+
+                const childRecords: Record[] = []
+
+                for (const category of categories) {
+                    const categoryObject = category.asObject()
+
+                    const categoryRecord = await factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_ux_list_category',
+                        explicitId: categoryObject.get('$id'),
+                        properties: categoryObject.transform(({ $ }) => ({
+                            active: $.from('active').def(true),
+                            configuration: $.val(UxListMenuConfigRecord),
+                            description: $.from('description').def(''),
+                            title: $.from('title').def(''),
+                            order: $.from('order').def(100),
+                        })),
+                    })
+
+                    childRecords.push(categoryRecord)
+
+                    const lists = categoryObject.get('lists').ifArray()?.getElements() ?? []
+
+                    for (const list of lists) {
+                        const listObject = list.asObject()
+
+                        const listRecord = await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_ux_list',
+                            explicitId: listObject.get('$id'),
+                            properties: listObject.transform(({ $ }) => ({
+                                active: $.from('active').def(true),
+                                category: $.val(categoryRecord),
+                                columns: $.from('columns'),
+                                condition: $.from('condition'),
+                                configuration: $.val(UxListMenuConfigRecord),
+                                enable_infinite_scroll: $.from('enableInfiniteScroll').def(false),
+                                fixed_query: $.from('fixedQuery'),
+                                group_by_column: $.from('groupByColumn'),
+                                groups: $.from('groups'),
+                                hide_cell_filter: $.from('hideCellFilter').def(false),
+                                hide_checkbox_hover: $.from('hideCheckboxHover').def(false),
+                                hide_column_filtering: $.from('hideColumnFiltering').def(false),
+                                hide_column_grouping: $.from('hideColumnGrouping').def(false),
+                                hide_column_resizing: $.from('hideColumnResizing').def(false),
+                                hide_column_sorting: $.from('hideColumnSorting').def(false),
+                                hide_drag_and_drop: $.from('hideDragAndDrop').def(false),
+                                hide_empty_state_image: $.from('hideEmptyStateImage').def(false),
+                                hide_first_page: $.from('hideFirstPage').def(false),
+                                hide_header: $.from('hideHeader').def(false),
+                                hide_highlight_content: $.from('hideHighlightContent').def(false),
+                                hide_highlighted_values: $.from('hideHighlightedValues').def(false),
+                                hide_inline_editing: $.from('hideInlineEditing').def(false),
+                                hide_last_page: $.from('hideLastPage').def(false),
+                                hide_last_refreshed_text: $.from('hideLastRefreshedText').def(false),
+                                hide_links: $.from('hideLinks').def(false),
+                                hide_list_actions: $.from('hideListActions').def(false),
+                                hide_menu_button: $.from('hideMenuButton').def(false),
+                                hide_next_page: $.from('hideNextPage').def(false),
+                                hide_option_to_save_as: $.from('hideOptionToSaveAs').def(false),
+                                hide_pages: $.from('hidePages').def(false),
+                                hide_pagination: $.from('hidePagination').def(false),
+                                hide_panel_advanced: $.from('hidePanelAdvanced').def(false),
+                                hide_panel_button: $.from('hidePanelButton').def(false),
+                                hide_panel_condition_delete: $.from('hidePanelConditionDelete').def(false),
+                                hide_panel_footer: $.from('hidePanelFooter').def(false),
+                                hide_panel_restore: $.from('hidePanelRestore').def(false),
+                                hide_personalization: $.from('hidePersonalization').def(false),
+                                hide_previous_page: $.from('hidePreviousPage').def(false),
+                                hide_quick_edit: $.from('hideQuickEdit').def(false),
+                                hide_range: $.from('hideRange').def(false),
+                                hide_record_count_badge: $.from('hideRecordCountBadge').def(false),
+                                hide_reference_links: $.from('hideReferenceLinks').def(false),
+                                hide_refresh_button: $.from('hideRefreshButton').def(false),
+                                hide_row_count: $.from('hideRowCount').def(false),
+                                hide_row_selector: $.from('hideRowSelector').def(false),
+                                hide_rows_per_page_selector: $.from('hideRowsPerPageSelector').def(false),
+                                hide_select_all: $.from('hideSelectAll').def(false),
+                                hide_sharing_button: $.from('hideSharingButton').def(false),
+                                hide_title: $.from('hideTitle').def(false),
+                                highlight_content_color: $.from('highlightContentColor'),
+                                highlight_content_pattern: $.from('highlightContentPattern'),
+                                list_attributes: $.from('listAttributes'),
+                                live_updates: $.from('liveUpdates').def('off'),
+                                max_characters: $.from('maxCharacters').def(4000).toNumber(),
+                                order: $.from('order').def(100).toNumber(),
+                                override_word_wrap_user_pref: $.from('overrideWordWrapUserPref').def(false),
+                                roles: $.from('roles'),
+                                table: $.from('table'),
+                                title: $.from('title'),
+                                view: $.from('view'),
+                                word_wrap: $.from('wordWrap').def(false),
+                            })),
+                        })
+
+                        childRecords.push(listRecord)
+
+                        // Create sys_ux_applicability_m2m_list records
+                        const applicabilities = listObject.get('applicabilities').ifArray()?.getElements() ?? []
+                        for (const applicability of applicabilities) {
+                            const applicabilityObject = applicability.asObject()
+
+                            childRecords.push(
+                                await factory.createRecord({
+                                    source: callExpression,
+                                    table: 'sys_ux_applicability_m2m_list',
+                                    explicitId: applicabilityObject.get('$id'),
+                                    properties: applicabilityObject.transform(({ $ }) => ({
+                                        active: $.from('active').def(true),
+                                        applicability: $.from('applicability'),
+                                        list: $.val(listRecord),
+                                        order: $.from('order').def(0),
+                                    })),
+                                })
+                            )
+                        }
+                    }
+                }
+
+                return {
+                    success: true,
+                    value: UxListMenuConfigRecord.with(...childRecords),
+                }
+            },
+        },
+    ],
+})

package/src/workspace-plugin/chrome-tab.ts

@@ -0,0 +1,44 @@
+function newTabMenuTemplate(table: string) {
+    return {
+        label: {
+            translatable: true,
+            message: `New ${table}`,
+        },
+        routeInfo: {
+            route: 'record',
+            fields: {
+                table: table,
+                sysId: '-1',
+            },
+            multiInstField: 'sysId',
+        },
+        condition: {
+            tableDescription: {
+                table: table,
+                canCreate: true,
+            },
+        },
+    }
+}
+
+export function createChromeTabJsonStringForPageProp(tables: string[]) {
+    return JSON.stringify({
+        contextual: ['record'],
+        newTabMenu: tables.map((table) => newTabMenuTemplate(table)),
+        maxMainTabLimit: 10,
+        maxTotalSubTabLimit: 30,
+    })
+}
+
+// This next function reverse engineers createChromeTab to take that output as input (stringified JSON) and returns the tables
+export function parsePagePropChromeTabJson(chromeTab: string): string[] {
+    try {
+        const chromeTabJson = JSON.parse(chromeTab)
+        return chromeTabJson.newTabMenu.map(
+            (item: { routeInfo: { fields: { table: string } } }) => item.routeInfo.fields.table
+        )
+    } catch (e) {
+        console.log(`Failed to parse chrome tab json for Workspace plugin | ${e}`)
+        return []
+    }
+}

package/src/workspace-plugin/constants.ts

@@ -0,0 +1,53 @@
+export const DEFAULTS = {
+    record: {
+        MACROPONENT: 'e3c63f089db4729086517760a31f5558',
+        PARENT_MACROPONENT: 'c276387cc331101080d6d3658940ddd2',
+        NAME: 'Record Default',
+        DESCRIPTION: '',
+        SCREEN_CONDITION: '',
+        ORDER: 0,
+        FIELDS: 'table,sysId',
+        ROUTE_TYPE: 'record',
+        OPTIONAL_PARAMETERS: 'query,extraParams,views,selectedTab',
+    },
+    list: {
+        MACROPONENT: '2c08111d0fc21010036a83fa68767ef6',
+        PARENT_MACROPONENT: 'c276387cc331101080d6d3658940ddd2',
+        NAME: 'List Page',
+        DESCRIPTION: '',
+        SCREEN_CONDITION: '',
+        ORDER: 0,
+        FIELDS: '',
+        OPTIONAL_PARAMETERS: 'listId',
+        ROUTE_TYPE: 'list',
+    },
+    home: {
+        MACROPONENT: '163a913b532c0110aab9ddeeff7b1241',
+        PARENT_MACROPONENT: 'c276387cc331101080d6d3658940ddd2',
+        NAME: 'Dashboards Default',
+        DESCRIPTION: '',
+        SCREEN_CONDITION: '',
+        ORDER: 0,
+        FIELDS: '',
+        OPTIONAL_PARAMETERS: 'sysId,edit,tabSysId,filter,element',
+        ROUTE_TYPE: 'home',
+    },
+    'simple-list': {
+        MACROPONENT: '8515f3e853031010ffa5ddeeff7b1297',
+        PARENT_MACROPONENT: 'c276387cc331101080d6d3658940ddd2',
+        NAME: 'Simple List',
+        DESCRIPTION: '',
+        SCREEN_CONDITION: '',
+        ORDER: 0,
+        FIELDS: 'table',
+        OPTIONAL_PARAMETERS: 'listTitle,query,disableInlineEditing',
+        ROUTE_TYPE: 'simplelist',
+    },
+}
+
+export const TABLES = {
+    SCREEN_COLLECTION: 'sys_ux_screen_type',
+    SCREEN: 'sys_ux_screen',
+    ROUTE: 'sys_ux_app_route',
+    MACROPONENT: 'sys_ux_macroponent',
+}

package/src/workspace-plugin/fluent-utils.ts

@@ -0,0 +1,60 @@
+import type { Source, Record, Shape } from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../now-id-plugin'
+
+export const getExplicitIdGenerator = (source: Source, appConfigId: string) => (table: string, uniqueString: string) =>
+    new NowIdShape({ source, id: `${appConfigId}_${table}_${uniqueString}` })
+
+export const buildRecordKey = (record: Record) => `${record.getTable()}_${record.getId().getValue()}`
+
+/*
+This is just an equality check similar to the existing "strictEqual", except it's a little more relaxed.
+We want to make sure that our defaulted records aren't "tampered" with. If they are, this will detect it.
+
+Record.strictEqual() tests that the number of properties match, which is too agressive for our needs, because
+the number of properties on an actual record is almost always higher than on a generated record (due to sys_ columns, mostly).
+*/
+export const doesActualRecordMatchGeneratedRecord = (actualRecord: Record, generatedRecord: Record): boolean => {
+    for (const [gFieldName, gFieldValue] of generatedRecord.entries()) {
+        const generatedRecordValueAsString = convertFieldValueToString(gFieldValue)
+        const actualRecordValueAsString = convertFieldValueToString(actualRecord.get(gFieldName))
+        if (generatedRecordValueAsString !== actualRecordValueAsString) {
+            return false
+        }
+    }
+    return true
+}
+
+export const convertFieldValueToString = (fieldValue: Shape<unknown>): string => {
+    if (fieldValue.isRecord()) {
+        return fieldValue.asRecord().getId().getValue()
+    } else if (fieldValue.isBoolean()) {
+        return fieldValue.asBoolean().getValue().toString()
+    } else if (fieldValue.isNumber()) {
+        return fieldValue.asNumber().getValue().toString()
+    }
+    return fieldValue.asString().getValue()
+}
+
+export const serializeActualRecordAsOverrideToTheDefault = (
+    actualRecord: Record,
+    generatedRecord: Record
+): { [fieldName: string]: string } => {
+    // Looping through the generated record keys gives us a more controllable and precise list to track/record.
+    const serializedRecordValue: { [fieldName: string]: string } = {}
+    for (const field of generatedRecord.keys()) {
+        const fieldValue = actualRecord.get(field)
+        if (fieldValue.isRecord()) {
+            serializedRecordValue[field] = fieldValue.asRecord().getId().getValue()
+        } else {
+            try {
+                serializedRecordValue[field] = JSON.stringify(JSON.parse(fieldValue.asString().getValue())).replace(
+                    /\\/g,
+                    '\\\\'
+                )
+            } catch (e) {
+                serializedRecordValue[field] = fieldValue.asString().getValue()
+            }
+        }
+    }
+    return serializedRecordValue
+}