@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/record-plugin.ts

@@ -1,5 +1,4 @@
-import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
-import { unloadBuilder } from '@servicenow/sdk-build-core'
+import { CallExpressionShape, Database, Plugin, unloadBuilder, type Record } from '@servicenow/sdk-build-core'
 import { NowIdShape } from './now-id-plugin'
 import {
     Acl,
@@ -10,6 +9,8 @@ import {
     Role,
     Test,
     UserPreference,
+    ImportSet,
+    Sla,
 } from '@servicenow/sdk-core/runtime/app'
 import {
     SPWidget,
@@ -18,12 +19,22 @@ import {
     CssInclude,
     JsInclude,
 } from '@servicenow/sdk-core/runtime/service-portal'
+import {
+    CatalogItem,
+    CatalogClientScript,
+    VariableSet,
+    CatalogUiPolicy,
+    CatalogItemRecordProducer,
+} from '@servicenow/sdk-core/runtime/service-catalog'
 import { ClientScript } from '@servicenow/sdk-core/runtime/clientscript'
 import { ScriptAction, ScriptInclude } from '@servicenow/sdk-core/runtime/sys'
 import { List } from '@servicenow/sdk-core/runtime/ui'
 import { Table } from '@servicenow/sdk-core/runtime/db'
 import { RestApi } from '@servicenow/sdk-core/runtime/rest'
-import { UiAction, UiPage } from '@servicenow/sdk-core/runtime/ui'
+import { EmailNotification } from '@servicenow/sdk-core/runtime/notification'
+import { UiAction, UiPage, UiPolicy } from '@servicenow/sdk-core/runtime/ui'
+import { Applicability, UxListMenuConfig, Workspace } from '@servicenow/sdk-core/runtime/uxf'
+import { Dashboard } from '@servicenow/sdk-core/runtime/dashboard'
 
 export const RecordPlugin = Plugin.create({
     name: 'RecordPlugin',
@@ -32,31 +43,71 @@ export const RecordPlugin = Plugin.create({
             getUpdateName(record) {
                 return { success: true, value: `${record.getTable()}_${record.getId().getValue()}` }
             },
-            toShape(record) {
+            async diff(existing, incoming) {
+                const changeDatabase = existing.compare(incoming)
                 return {
                     success: true,
-                    value: new CallExpressionShape({
-                        source: record,
-                        callee: 'Record',
-                        args: [
-                            {
-                                $id: NowIdShape.from(record),
-                                table: record.getTable(),
-                                data: record.transform(
-                                    ({ $ }) =>
-                                        Object.fromEntries(
-                                            record
-                                                .keys()
-                                                .map((key) => [key, record.get(key).isString() ? $.def('') : $])
-                                        ) //to avoid writing empty string values to the code
-                                ),
-                            },
-                        ],
-                    }),
+                    value: changeDatabase.hasChanges() ? new Database(changeDatabase.query()) : new Database(),
+                }
+            },
+            async toShape(record, { compiler }) {
+                const tableName = record.getTable()
+                const columnTypes = compiler.getTableColumnTypes(tableName)
+
+                const dataProperties = record.transform(({ $ }) =>
+                    Object.fromEntries(
+                        record
+                            .keys()
+                            .filter((key) => key !== 'sys_name')
+                            .map((key) => {
+                                const shape = record.get(key)
+                                if (columnTypes?.has(key) && shape?.isString()) {
+                                    const expectedType = columnTypes.get(key)
+                                    try {
+                                        if (expectedType === 'boolean') {
+                                            return [key, $.val(shape.toBoolean())]
+                                        } else if (expectedType === 'number') {
+                                            return [key, $.val(shape.toNumber())]
+                                        } else if (expectedType === 'array') {
+                                            return [key, $.val(shape.asString().split(',')).def([''])]
+                                        } else if (expectedType === 'array-optional') {
+                                            const arrayParts = shape.asString().includes(',')
+                                            return [key, arrayParts ? $.val(shape.asString().split(',')).def(['']) : $]
+                                        }
+                                    } catch {
+                                        // Keep as string if conversion fails
+                                    }
+                                }
+
+                                return [key, shape?.isString() ? $.def('') : $] //to avoid writing empty string values to the code
+                            })
+                    )
+                )
+
+                const value = new CallExpressionShape({
+                    source: record,
+                    callee: 'Record',
+                    exportName: record.get('sys_name')?.ifDefined()?.asString().getValue(),
+                    args: [
+                        {
+                            $id: NowIdShape.from(record),
+                            table: tableName,
+                            data: dataProperties,
+                        },
+                    ],
+                })
+
+                return {
+                    success: true,
+                    value,
                 }
             },
             async toFile(record, { config, database, transform }) {
-                const recordBuilder = unloadBuilder(config)
+                const recordBuilder = unloadBuilder({
+                    scope: config.scope,
+                    scopeId: config.scopeId,
+                    table: record.getTable(),
+                })
                 const updateName = await transform.getUpdateName(record)
                 const builder = recordBuilder.record(record, updateName)
 
@@ -101,13 +152,14 @@ export const RecordPlugin = Plugin.create({
 
                 const record = callExpression.getArgument(0).asObject()
                 const table = record.get('table').asString().getValue()
-                const tableOwningPlugin = TableOwnership[table]
+                const tableOwningPlugin = TableOwnership[table as keyof typeof TableOwnership]
                 if (tableOwningPlugin) {
                     diagnostics.hint(
                         callExpression,
                         `For a better experience, consider using the ${tableOwningPlugin} API`
                     )
                 }
+
                 return {
                     success: true,
                     value: await factory.createRecord({
@@ -125,16 +177,25 @@ export const RecordPlugin = Plugin.create({
             matcher: /\.xml$/,
             async toRecord(file, { parser, logger }) {
                 try {
-                    const [first, ...rest] = await parser.parsePayload(file)
+                    const records = await parser.parsePayload(file)
+                    const recordMap = new Map<string, Record>()
+                    for (const record of records) {
+                        const key = `${record.getTable()}::${record.getId().getValue()}`
+                        const existing = recordMap.get(key)
 
-                    if (!first) {
-                        return { success: false }
+                        const merged = existing
+                            ? existing.merge(record.properties()) // merge properties only to retain the action
+                            : record
+
+                        recordMap.set(key, merged)
                     }
 
-                    return {
-                        success: true,
-                        value: first.with(...rest),
+                    const mergedRecords = Array.from(recordMap.values())
+                    const [mergedFirst, ...mergedRest] = mergedRecords
+                    if (!mergedFirst) {
+                        return { success: false }
                     }
+                    return { success: true, value: mergedFirst.with(...mergedRest) }
                 } catch (e) {
                     logger.debug(e)
                     return { success: false }
@@ -145,6 +206,7 @@ export const RecordPlugin = Plugin.create({
 })
 
 export const TableOwnership = {
+    contract_sla: Sla.name,
     sys_security_acl: Acl.name,
     sys_security_acl_role: Acl.name,
     sys_app_application: ApplicationMenu.name,
@@ -181,7 +243,41 @@ export const TableOwnership = {
     sys_ui_action: UiAction.name,
     sys_ui_action_role: UiAction.name,
     sys_ui_action_view: UiAction.name,
+    sys_ui_policy: UiPolicy.name,
+    sys_ui_policy_action: UiPolicy.name,
+    sys_ui_policy_rl_action: UiPolicy.name,
     sysevent_script_action: ScriptAction.name,
+    sysevent_email_action: EmailNotification.name,
     sys_db_object: Table.name,
     sys_dictionary: Table.name,
+    sys_hub_flow: 'Flow',
+    sys_hub_trigger_instance_v2: 'wfa.trigger',
+    sys_hub_action_instance_v2: 'wfa.action',
+    sys_hub_sub_flow_instance_v2: 'wfa.subflow',
+    sys_hub_flow_logic_instance_v2: 'wfa.flowLogic',
+    sys_flow_step_definition: 'ActionStepDefinition',
+    sys_decision: 'DecisionTablePlugin',
+    sys_hub_action_type_definition: 'Action',
+    sys_hub_step_instance: 'wfa.action_step',
+    sys_transform_map: ImportSet.name,
+    sys_transform_entry: ImportSet.name,
+    sys_transform_script: ImportSet.name,
+    sys_ux_applicability: Applicability.name,
+    sys_ux_list_menu_config: UxListMenuConfig.name,
+    sys_ux_list_category: UxListMenuConfig.name,
+    sys_ux_list: UxListMenuConfig.name,
+    sys_ux_applicability_m2m_list: UxListMenuConfig.name,
+    sys_ux_page_registry: Workspace.name,
+    sys_ux_app_config: Workspace.name,
+    par_dashboard: Dashboard.name,
+    par_dashboard_canvas: Dashboard.name,
+    par_dashboard_tab: Dashboard.name,
+    par_dashboard_widget: Dashboard.name,
+    par_dashboard_permission: Dashboard.name,
+    par_dashboard_visibility: Dashboard.name,
+    item_option_new_set: VariableSet.name,
+    sc_cat_item: CatalogItem.name,
+    sc_cat_item_producer: CatalogItemRecordProducer.name,
+    catalog_script_client: CatalogClientScript.name,
+    catalog_ui_policy: CatalogUiPolicy.name,
 }

package/src/repack/index.ts

@@ -11,6 +11,16 @@ export async function checkModuleExists(
     return repackService.checkModuleExists(module)
 }
 
+export async function resolveModule(
+    module: string,
+    logger: RepackOptions['logger'],
+    fs: RepackOptions['fs'],
+    workingDir: RepackOptions['workingDir']
+): Promise<string | undefined> {
+    const repackService = await RepackService.create(logger, fs, workingDir)
+    return repackService.resolveModule(module)
+}
+
 export const REPACK_OUTPUT_DIR = path.join('.now', '.output')
 
 export class RepackService {
@@ -52,4 +62,8 @@ export class RepackService {
     async checkModuleExists(module: string) {
         return this.repack.checkModuleExists(module, this.fs, this.workingDir, this.logger!)
     }
+
+    async resolveModule(module: string): Promise<string | undefined> {
+        return this.repack.resolveModule(module, this.fs, this.workingDir, this.logger)
+    }
 }

package/src/repack/lint/Rules.ts

@@ -10,15 +10,6 @@ const NO_GLOBAL_THIS = 'ES2020 `globalThis` variable is not supported by the now
 
 type LogLevel = 'warn' | 'error'
 
-type ClassMethods = {
-    [className: string]: string[]
-}
-
-type GlideAPIMapping = {
-    defaults: ClassMethods
-    [namespace: string]: ClassMethods
-}
-
 type ESLintPropertyRule = {
     message: string
     object?: string
@@ -26,7 +17,7 @@ type ESLintPropertyRule = {
     name?: string
 }
 
-const glideAPIs: GlideAPIMapping = GlideAPIs
+const glideAPIs = GlideAPIs
 
 const globalsAllowList: string[] = ['console', 'fetch']
 

package/src/rest-api-plugin.ts

@@ -11,6 +11,7 @@ import {
 } from '@servicenow/sdk-build-core'
 import { ModuleFunctionShape } from './server-module-plugin'
 import { NowIdShape } from './now-id-plugin'
+import { NowIncludeShape } from './now-include-plugin'
 import { generateDeprecatedDiagnostics } from './utils'
 
 const DEFAULT_MEDIA_TYPE = 'application/json,application/xml,text/xml'
@@ -162,13 +163,12 @@ async function generateRouteAttributeRecords(
     attrType: string,
     attrMap: Map<string, Record>,
     factory: Factory,
-    diagnostics: Diagnostics,
-    callExpression: CallExpressionShape
+    diagnostics: Diagnostics
 ): Promise<Record[]> {
     const records: Record[] = []
     for (const attr of attributes) {
         const attrRecord = await factory.createRecord({
-            source: callExpression,
+            source: attr,
             table: `sys_ws_${attrType}`,
             explicitId: attr.asObject().get('$id'),
             properties: attr.asObject().transform(({ $ }) => ({
@@ -178,17 +178,19 @@ async function generateRouteAttributeRecords(
                 example_value: $.from('exampleValue').def(''),
                 web_service_definition: $.val(restDef.getId()),
             })),
+            installCategory: restDef.getInstallCategory(),
         })
 
         checkForDuplicateRecords(attrMap, attrRecord, attr.asObject(), diagnostics)
 
         const attributeMappingRecord = await factory.createRecord({
-            source: callExpression,
+            source: attr,
             table: `sys_ws_${attrType}_map`,
             properties: attr.asObject().transform(({ $ }) => ({
                 web_service_operation: $.val(routeDef.getId()),
                 [`web_service_${attrType}`]: $.val(attrRecord.getId()),
             })),
+            installCategory: restDef.getInstallCategory(),
         })
 
         records.push(attrRecord.with(attributeMappingRecord))
@@ -292,8 +294,7 @@ async function generateRouteAndRouteAttrRecords(
             'header',
             headersMap,
             factory,
-            diagnostics,
-            callExpression
+            diagnostics
         )
 
         const routeParameters = route.get('parameters')?.ifArray()?.getElements() ?? []
@@ -308,8 +309,7 @@ async function generateRouteAndRouteAttrRecords(
             'query_parameter',
             parametersMap,
             factory,
-            diagnostics,
-            callExpression
+            diagnostics
         )
 
         routeRecords.push(routeRecord.with(...headerRecords, ...parameterRecords))
@@ -318,11 +318,11 @@ async function generateRouteAndRouteAttrRecords(
     return routeRecords
 }
 
-function validateAttributesAndAssociations(
+function findOrphanedAttributes(
     attributes: Record[],
     attributeRouteAssociations: Record[],
     attributeType: string
-) {
+): Record[] {
     const attributeIdToRecordMap = new Map<string, Record>()
     attributes.forEach((attribute) => {
         attributeIdToRecordMap.set(attribute.getId().getValue(), attribute)
@@ -336,20 +336,21 @@ function validateAttributesAndAssociations(
         })
     )
 
-    const orphanedAttributes = Array.from(attributeIds).filter((id) => !referencedAttributeIds.has(id))
-    if (orphanedAttributes.length > 0) {
-        const orphanedAttributeNames = orphanedAttributes
-            .map((id) => {
-                const attribute = attributeIdToRecordMap.get(id)
-                return attribute?.get('name')?.getValue() || id
-            })
-            .join(', ')
+    const orphanedAttributeIds = Array.from(attributeIds).filter((id) => !referencedAttributeIds.has(id))
+    return orphanedAttributeIds
+        .map((id) => attributeIdToRecordMap.get(id))
+        .filter((record): record is Record => record !== undefined)
+}
 
-        throw new Error(
-            `Found ${orphanedAttributes.length} attribute record(s) without route associations: ${orphanedAttributeNames}. ` +
-                `Either associate these attributes with routes or delete them.`
-        )
-    }
+function validateAttributesAndAssociations(
+    attributes: Record[],
+    attributeRouteAssociations: Record[],
+    attributeType: string
+) {
+    const attributeIdToRecordMap = new Map<string, Record>()
+    attributes.forEach((attribute) => {
+        attributeIdToRecordMap.set(attribute.getId().getValue(), attribute)
+    })
 
     const invalidAttributeAssociations = attributeRouteAssociations.filter((association) => {
         const attr = association.get(`web_service_${attributeType}`)
@@ -453,7 +454,7 @@ export const RestApiPlugin = Plugin.create({
                     descendant: true,
                 },
             },
-            toShape(record, { descendants }) {
+            async toShape(record, { descendants, transform }) {
                 const versions = descendants.query('sys_ws_version')
                 const routes = descendants.query('sys_ws_operation')
                 const headers = descendants.query('sys_ws_header')
@@ -466,9 +467,7 @@ export const RestApiPlugin = Plugin.create({
                  * Case 1: No m2m records exists for a header or parameter record. Can happen in following scenarios:
                  *      - User has created a header or parameter record but these records are not associated with any routes on instance.
                  *      - User has removed all the m2m associations on instance but not the actual header or parameter record.
-                 * Solution: Throw error guiding user to do one of the following:
-                 *      - Associate the header or parameter record with a route
-                 *      - Delete the header or parameter record
+                 * Solution: Return orphaned attributes as unhandled records for partial success
                  *
                  * Case 2: Deleting a header record on instance wouldn't delete the m2m records which map those headers to a route.
                  * Solution: Throw error and request the user to cleanup the m2m records on instance.
@@ -476,81 +475,88 @@ export const RestApiPlugin = Plugin.create({
                 validateAttributesAndAssociations(headers, headerRouteAssociations, 'header')
                 validateAttributesAndAssociations(parameters, paramRouteAssociations, 'query_parameter')
 
+                const orphanedHeaders = findOrphanedAttributes(headers, headerRouteAssociations, 'header')
+                const orphanedParameters = findOrphanedAttributes(parameters, paramRouteAssociations, 'query_parameter')
+                const unhandledRecords = [...orphanedHeaders, ...orphanedParameters]
+
+                const routesWithScript = await Promise.all(
+                    routes.map(async (r) => {
+                        const script = await NowIncludeShape.fromRecord(r, r.get('operation_script'), transform)
+                        return r
+                            .transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(r)),
+                                name: $,
+                                active: $.toBoolean().def(true),
+                                consumes: $,
+                                method: $.from('http_method').def('GET'),
+                                script: $.val(script),
+                                produces: $,
+                                path: $.from('relative_path').def('/'),
+                                enforceAcl: $.val(splitAcls(r.get('enforce_acl'))).def([DEFAULT_REST_ENFORCED_ACL]),
+                                authorization: $.from('requires_acl_authorization').toBoolean().def(true),
+                                authentication: $.from('requires_authentication').toBoolean().def(true),
+                                internalRole: $.from('requires_snc_internal_role').toBoolean().def(true),
+                                shortDescription: $.from('short_description').def(''),
+                                requestExample: $.from('request_example').def(''),
+                                policy: $.from('sys_policy').def(''),
+                                parameters: $.val(
+                                    routeAttributeTransform(
+                                        paramRouteAssociations,
+                                        parameters,
+                                        r.getId().getValue(),
+                                        'query_parameter'
+                                    )
+                                ).def([]),
+                                headers: $.val(
+                                    routeAttributeTransform(
+                                        headerRouteAssociations,
+                                        headers,
+                                        r.getId().getValue(),
+                                        'header'
+                                    )
+                                ).def([]),
+                                version: $.from('web_service_version').map((v) => getVersionNumber(v, versions)),
+                            }))
+                            .withAliasedKeys(routeAliases)
+                    })
+                )
+
+                const shape = new CallExpressionShape({
+                    source: record,
+                    callee: 'RestApi',
+                    args: [
+                        record
+                            .transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                active: $.toBoolean().def(true),
+                                consumes: $.def(DEFAULT_MEDIA_TYPE),
+                                produces: $.def(DEFAULT_MEDIA_TYPE),
+                                enforceAcl: $.from('enforce_acl')
+                                    .map((v) => splitAcls(v))
+                                    .def([DEFAULT_REST_ENFORCED_ACL]),
+                                serviceId: $.from('service_id'),
+                                shortDescription: $.from('short_description').def(''),
+                                policy: $.from('sys_policy').def(''),
+                                docLink: $.from('doc_link').def(''),
+                                routes: $.val(routesWithScript).def([]),
+                                versions: $.val(versionsTransform(versions)).def([]),
+                            }))
+                            .withAliasedKeys(restDefAliases),
+                    ],
+                })
+
+                if (unhandledRecords.length > 0) {
+                    return {
+                        success: 'partial',
+                        value: shape,
+                        unhandledRecords,
+                    }
+                }
+
                 return {
                     success: true,
-                    value: new CallExpressionShape({
-                        source: record,
-                        callee: 'RestApi',
-                        args: [
-                            record
-                                .transform(({ $ }) => ({
-                                    $id: $.val(NowIdShape.from(record)),
-                                    name: $,
-                                    active: $.toBoolean().def(true),
-                                    consumes: $.def(DEFAULT_MEDIA_TYPE),
-                                    produces: $.def(DEFAULT_MEDIA_TYPE),
-                                    enforceAcl: $.from('enforce_acl')
-                                        .map((v) => splitAcls(v))
-                                        .def([DEFAULT_REST_ENFORCED_ACL]),
-                                    serviceId: $.from('service_id'),
-                                    shortDescription: $.from('short_description').def(''),
-                                    policy: $.from('sys_policy').def(''),
-                                    docLink: $.from('doc_link').def(''),
-                                    routes: $.val(
-                                        routes.map((r) =>
-                                            r
-                                                .transform(({ $ }) => ({
-                                                    $id: $.val(NowIdShape.from(r)),
-                                                    name: $,
-                                                    active: $.toBoolean().def(true),
-                                                    consumes: $,
-                                                    method: $.from('http_method').def('GET'),
-                                                    script: $.from('operation_script'),
-                                                    produces: $,
-                                                    path: $.from('relative_path').def('/'),
-                                                    enforceAcl: $.val(splitAcls(r.get('enforce_acl'))).def([
-                                                        DEFAULT_REST_ENFORCED_ACL,
-                                                    ]),
-                                                    authorization: $.from('requires_acl_authorization')
-                                                        .toBoolean()
-                                                        .def(true),
-                                                    authentication: $.from('requires_authentication')
-                                                        .toBoolean()
-                                                        .def(true),
-                                                    internalRole: $.from('requires_snc_internal_role')
-                                                        .toBoolean()
-                                                        .def(true),
-                                                    shortDescription: $.from('short_description').def(''),
-                                                    requestExample: $.from('request_example').def(''),
-                                                    policy: $.from('sys_policy').def(''),
-                                                    parameters: $.val(
-                                                        routeAttributeTransform(
-                                                            paramRouteAssociations,
-                                                            parameters,
-                                                            r.getId().getValue(),
-                                                            'query_parameter'
-                                                        )
-                                                    ).def([]),
-                                                    headers: $.val(
-                                                        routeAttributeTransform(
-                                                            headerRouteAssociations,
-                                                            headers,
-                                                            r.getId().getValue(),
-                                                            'header'
-                                                        )
-                                                    ).def([]),
-                                                    version: $.from('web_service_version').map((v) =>
-                                                        getVersionNumber(v, versions)
-                                                    ),
-                                                }))
-                                                .withAliasedKeys(routeAliases)
-                                        )
-                                    ).def([]),
-                                    versions: $.val(versionsTransform(versions)).def([]),
-                                }))
-                                .withAliasedKeys(restDefAliases),
-                        ],
-                    }),
+                    value: shape,
                 }
             },
         },

package/src/role-plugin.ts

@@ -32,6 +32,7 @@ export const RolePlugin = Plugin.create({
                     success: true,
                     value: new CallExpressionShape({
                         source: record,
+                        exportName: record.get('name').ifString()?.getValue(),
                         callee: 'Role',
                         args: [
                             record