Forem: James Freund

Next Experience: Record Watchers

James Freund — Fri, 13 Jan 2023 16:50:03 +0000

Precursor

Record watchers have been around for quite some time to provide real-time data on back-end forms in ServiceNow as well as in the Service Portal. Changes in instance data trigger an event on the front end, upon receiving the event you can then perform logic based on the change to instance data.

Similarly to making REST API calls there is a predefined npm package you can install to work just like @servicenow/ui-effect-http. This package is named @servicenow/ui-effect-amb and you will have to install it to utilize record watching functionality.

Record watchers can not truly be tested until the components are deployed to the instance directly. This is because there is no way to use the proxy from now-cli.json in websockets which is the paradigm that record watchers use.

This can make debugging quite difficult, so I apologize for the inconvenience.

Preparation

First things first you need to install the package.

npm install @servicenow/ui-effect-amb

This package needs to be imported to create an actionHandler similar to when you import @servicenow/ui-effect-http.

import { createAmbSubscriptionEffect } from "@servicenow/ui-effect-amb";

The function createAmbSubscriptionEffect takes two main parameters, a channelid string and an options object. Below is the definition of the effect and explains which parameters it expects.

createAmbSubscriptionEffect

 /*
 * @param {String} channelId - AMB Channel ID
 * @param {Object} options
 * @param {String} options.subscribeStartedActionType - Action dispatched when an amb subscription is started
 * @param {String} options.subscribeSucceededActionType - Action dispatched if an amb subscription succeeds
 * @param {String} options.subscribeFailedActionType - Action dispatched if an amb subscription fails
 * @param {String} options.unsubscribeSucceededActionType - Action dispatched when an amb unsubscribe is successful
 * @param {String} options.messageReceivedActionType - Action dispatched when a message is received on a channel
 * @param {Boolean} options.encodeURIComponentForChannelId - Encode channel id URL (default: true)
 *
 * @return {Object} AMB Subscription Effect Descriptor
 */

Channel ID

The channel ID is almost always going to be the same string because it essentially serves as the endpoint to kick off the record watcher.

//! This string will almost always be:
const channelID = "/rw/default/:table/:filter";

Usage

This function will return an object that can be attached directly to an actionHandler. The action handler that it is attached to will serve as the main way to start and stop a record watcher.

To make life easier I created a helper function which generates an ambSubscriptionEffect and fills in some default settings. Generally you will only need to really use the subscribeStartedActionType and messageReceivedActionType properties in the options object.

ambEffectHelper.js

import { createAmbSubscriptionEffect } from "@servicenow/ui-effect-amb";

const channelID = "/rw/default/:table/:filter";

export const createComponentWatcher = (prefix = "DEFAULT_PREFIX", options) => { 
    return createAmbSubscriptionEffect(channelID, {
        subscribeStartedActionType: `${prefix}_WATCHER_DEFAULT_STARTED`,
        subscribeSucceededActionType: `${prefix}_WATCHER_DEFAULT_SUBSCRIBED`,
        subscribeFailedActionType: `${prefix}_WATCHER_DEFAULT_FAILED`,
        unsubscribeSucceededActionType: `${prefix}_WATCHER_DEFAULT_UNSUBSCRIBED`,
        messageReceivedActionType: `${prefix}_WATCHER_DEFAULT_CHANGED`,
        ...options,
    });
};

Now that we have our helper function set up we can quickly build actionHandlers to start or stop a record watcher subscription.

actionHandlers.js

import { createComponentWatcher } from "../ambEffectHelper";

export default {
    actionHandlers: {


        //┌─────────────────────────────────────────────────────────────
        //! This will beging the record watcher subscription
        //! an important detail to note is the subscribe: true
        //! in the dispatch call.
        //└─────────────────────────────────────────────────────────────
        START_RECORD_WATCHER: ({ state, dispatch }) => {
            const recordTable = "incident";
            const recordID = "7f96bd071b32c010f89b99bc1d4bcbf9";
            const originalFilter = `state=1^sys_id=${recordID}`;
            const filter = btoa(originalFilter).replace(/=/g, '-');
            dispatch(`SETUP_RECORD_WATCHER`, {
                table: recordTable,
                filter: filter,
                subscribe: true,
            });
        },


        //┌─────────────────────────────────────────────────────────────
        //! This actionHandler is nearly the same, but stops the
        //! record watcher instead of starting it.
        //└─────────────────────────────────────────────────────────────
        STOP_RECORD_WATCHER: ({ state, dispatch }) => {
            const recordTable = "incident";
            const recordID = "7f96bd071b32c010f89b99bc1d4bcbf9";
            const originalFilter = `state=1^sys_id=${recordID}`;
            const filter = btoa(originalFilter).replace(/=/g, '-');
            dispatch(`SETUP_RECORD_WATCHER`, {
                table: recordTable,
                filter: filter,
                subscribe: false,
            });
        },


        //┌─────────────────────────────────────────────────────────────
        //! This actionHandler allows you to start and stop
        //! a record watcher using our helper function.
        //└─────────────────────────────────────────────────────────────
        SETUP_RECORD_WATCHER: createComponentWatcher("RECORD", {
            subscribeStartedActionType: `RECORD_WATCHER_STARTED`,
            messageReceivedActionType: `RECORD_WATCHER_ITEM_CHANGED`,
        }),


        //┌─────────────────────────────────────────────────────────────
        //! This is really just to let you know a subscription
        //! to a record watcher has been started. Serves no other
        //! purpose.
        //└─────────────────────────────────────────────────────────────
        RECORD_WATCHER_STARTED: (coeffects) => {
            console.log(`RECORD_WATCHER_STARTED`, coeffects);
        },


        //┌─────────────────────────────────────────────────────────────
        //! This is the most important actionHandler, it will be
        //! triggered any time a record that fits the query is
        //! inserted/updated/deleted.
        //!
        //! From here you can perform any logic you want.
        //└─────────────────────────────────────────────────────────────
        RECORD_WATCHER_ITEM_CHANGED: ({ action, dispatch }) => {
            const { payload } = action;
            console.log(`RECORD_WATCHER_ITEM_CHANGED`, payload);
            const { data: { operation } } = payload;

            //! Do something based on the operation
            //! insert | update | delete
            dispatch(`RECORD_WATCHER_${operation}`, payload);
        },


    }
}

Conclusion

With this basic setup you can now perform any logic you want when a record is inserted, updated or deleted within the encodedQuery you define for your record watcher.

Since components can't always be directly attached to each other, this is a nice way to form a basic type of communication between different components.

Disclaimer

Again, the only way to truly test to see if your record watcher is working is to deploy your component to your instance, this a major detractor in the setup process, but with some effort you too can begin record watching!

Next Experience: UI Renderer React

James Freund — Fri, 13 Jan 2023 16:35:07 +0000

Precursor

ServiceNow originally put out their own react renderer for their early workspace components. This allowed them to develop complex components in React while they were still working on their own component design library.

Once their own component library was fully built out they removed the @servicenow/ui-renderer-react library from existence. I believe removing the react renderer was for a good reason and would have impacted the adoption of their new component system, but now its been a few years and that component system could use a content boost.

There are tons of amazing utilities and components built using React that cannot be used in now components simply because a react renderer didn't exist. If one did exist, it would allow us all to tap into thousands of useful components.

This was the main reason I originally built the @quixomatic/ui-renderer-react library. However, that solution required manual modifications to global ServiceNow CLI files, making it difficult to distribute and maintain across teams and projects.

The New Solution: I've now created @quixomatic/ui-renderer-react-simple - a React 18 renderer that requires zero global file modifications and provides one-command setup for any ServiceNow project.

The Problem We Solved

The original challenge wasn't just creating a React renderer - it was dealing with ServiceNow's babel plugin that transforms JSX. The plugin would detect React components but transform them to Snabbdom VNodes instead of React elements, causing the infamous "Objects are not valid as a React child" error.

Previous Solution: Required manually editing global babel plugin files in ~/.snc/.extensions/.

New Solution: Creates a local "fake" @servicenow/ui-renderer-react package that tricks the babel plugin into using proper React JSX transformation, plus automatically patches the babel plugin - no global modifications needed!

Installation (The Easy Way!)

The new solution provides one-command setup with automatic babel plugin patching:

# Install the package and React 18
npm install @quixomatic/ui-renderer-react-simple react@18 react-dom@18

# Run the automatic setup script (includes babel patching!)
npx setup-servicenow-react

# Complete the setup
npm install

That's it! No manual file editing, no global modifications, no complex setup instructions. The setup script automatically handles everything including babel plugin patching.

What the Setup Does

The setup script automatically:

Creates src/node_modules/@servicenow/ui-renderer-react/ directory
Copies the React 18 renderer to masquerade as the official ServiceNow renderer
Updates your package.json with the local dependency
Ensures React 18 dependencies are present
🆕 Automatically patches ServiceNow's babel plugin for React support
🆕 Creates a backup of the original babel plugin for easy restoration

This tricks ServiceNow's babel plugin into thinking you have the official React renderer, so it uses React JSX transformation instead of Snabbdom.

CLI Commands

The new version includes convenient CLI commands:

# Complete setup (fake package + babel patch)
npx setup-servicenow-react

# Just patch the babel plugin (if already set up)
npx patch-servicenow-babel

# Restore the original babel plugin
npx restore-servicenow-babel

Usage

With the new setup, your components use the exact same pattern as before, but now import from the "official" ServiceNow package:

Component Setup

import { createCustomElement } from "@servicenow/ui-core";
import react from "@servicenow/ui-renderer-react";  // Note: Now imports from @servicenow!
import view from "./view";
import styles from "./styles.scss";

createCustomElement("my-react-component", {
    renderer: { type: react },
    view,
    properties: {
        title: { default: "Hello React 18!" },
        count: { default: 0 }
    },
    actionHandlers: {
        INCREMENT: ({ state, updateProperties }) => {
            const { properties } = state;
            updateProperties({ count: properties.count + 1 });
        },
        DECREMENT: ({ state, updateProperties }) => {
            const { properties } = state;
            updateProperties({ count: properties.count - 1 });
        }
    },
    styles
});

React Component with Modern Hooks

import React, { useState, useEffect, useCallback } from "react";

export default function MyReactComponent(state) {
    const { dispatch, properties } = state;
    const { title, count } = properties;

    // All React 18 hooks work perfectly!
    const [localState, setLocalState] = useState('');
    const [isLoading, setIsLoading] = useState(false);

    // useEffect works
    useEffect(() => {
        console.log('Component mounted with React 18!');
        return () => console.log('Cleanup on unmount');
    }, []);

    // useCallback works
    const handleIncrement = useCallback(() => {
        setIsLoading(true);
        dispatch('INCREMENT');
        setTimeout(() => setIsLoading(false), 300);
    }, [dispatch]);

    return (
        <div className="my-react-component">
            <h1>{title}</h1>
            <div className="counter">
                <button 
                    onClick={() => dispatch('DECREMENT')}
                    disabled={isLoading}
                >
                    -
                </button>
                <span className="count">{count}</span>
                <button 
                    onClick={handleIncrement}
                    disabled={isLoading}
                >
                    {isLoading ? '...' : '+'}
                </button>
            </div>
            <input 
                type="text"
                value={localState}
                onChange={(e) => setLocalState(e.target.value)}
                placeholder="Local React state works too!"
            />
        </div>
    );
}

Hybrid Components (Snabbdom + React)

You can still mix Snabbdom parents with React children:

import { createCustomElement } from "@servicenow/ui-core";
import snabbdom from "@servicenow/ui-renderer-snabbdom";
import './my-react-component';  // Import the React component

const view = (state, { updateState }) => {
    const { showReact = false } = state;

    return (
        <div>
            <h1>Snabbdom Parent Component</h1>
            <button on-click={() => updateState({ showReact: !showReact })}>
                {showReact ? 'Hide' : 'Show'} React Component
            </button>

            {showReact && (
                <my-react-component title="Embedded React!" count={5} />
            )}
        </div>
    );
};

createCustomElement("hybrid-component", {
    renderer: { type: snabbdom },
    view
});

New Features & Benefits

React 18 Support

✅ All React 18 hooks (useId, useDeferredValue, useTransition, etc.)
✅ Concurrent rendering features
✅ Automatic batching
✅ Improved performance with createRoot API

Zero Global Modifications (Automated!)

✅ 🆕 Automatic babel plugin patching - no manual editing required
✅ 🆕 Backup/restore functionality for babel plugin
✅ 🆕 Cross-platform babel plugin detection (Windows/macOS/Linux)
✅ No need to manually edit ServiceNow CLI files
✅ Works with any ServiceNow CLI version
✅ Team-friendly - no setup coordination needed
✅ Works in CI/CD environments

Professional Distribution

✅ Published on npm with semantic versioning
✅ Automated testing across platforms
✅ Comprehensive documentation and examples
✅ Open source with contribution guidelines

Better Error Handling

✅ Built-in React error boundaries
✅ Proper error logging and reporting
✅ Graceful degradation on component failures
✅ 🆕 Graceful babel patching failure handling

Migration from Original Solution

If you're using the original @quixomatic/ui-renderer-react:

# Remove the old package
npm uninstall @quixomatic/ui-renderer-react

# Install the new solution
npm install @quixomatic/ui-renderer-react-simple react@18 react-dom@18

# Run the automated setup (includes babel patching!)
npx setup-servicenow-react
npm install

# Update your imports (only change needed!)
// Old
import react from "@quixomatic/ui-renderer-react";

// New  
import react from "@servicenow/ui-renderer-react";

🆕 Key Migration Benefits:

No more manual babel file editing - everything is automated
Easy restoration - restore original babel plugin anytime with npx restore-servicenow-babel
Better reliability - automatic detection and patching across different system configurations

Your components will work exactly the same - just with React 18 features and zero manual configuration!

Babel Plugin Details

How It Works

The babel plugin patcher:

Automatically locates ServiceNow's babel plugin file in ~/.snc/.extensions/ui-component/
Creates a backup before making any changes
Patches the React renderer configuration to use the correct module path instead of the faulty u() function
Removes old renderer entries if they exist
Verifies the patch was applied successfully

Manual Control

If you need manual control over the babel plugin:

# Patch just the babel plugin
npx patch-servicenow-babel

# Restore the original babel plugin
npx restore-servicenow-babel

# Verify current patch status
npx patch-servicenow-babel verify

Troubleshooting Babel Issues

If babel patching fails:

# Check ServiceNow CLI installation
snc --version

# Try patching separately
npx patch-servicenow-babel

# If needed, restore and retry
npx restore-servicenow-babel
npx patch-servicenow-babel

Example Repository

Check out the complete example repository which includes:

Basic Examples: Simple counter and form components
Advanced Examples: Complex forms with validation
Hook Examples: Demonstrating all React 18 hooks
Hybrid Examples: Mixing Snabbdom and React
Documentation: Complete setup and usage guides

Check out a full scaffolded project repository which includes nested react components using shadcn and tailwind within a parent snabbdom component.

Troubleshooting

The new solution eliminates most common issues, but if you encounter problems:

"Objects are not valid as a React child"

This usually means the setup didn't complete:

# Re-run the complete setup
npx setup-servicenow-react
npm install

React Hooks Not Working

Ensure React 18 is installed:

npm list react react-dom
# Should show 18.x.x versions

Babel Plugin Issues

If babel patching fails:

# Try patching separately
npx patch-servicenow-babel

# If that fails, check ServiceNow CLI
snc --version

Import Errors

Make sure you're importing from the correct package:

import react from "@servicenow/ui-renderer-react";  // Correct

Conclusion

With this new solution, integrating React 18 into ServiceNow components is now truly effortless. The one-command setup with automatic babel plugin patching eliminates all complexity and manual configuration that made previous solutions difficult to distribute.

Key Improvements in v1.1.0:

🚀 Automatic babel plugin patching - no manual editing required
🔄 Backup/restore functionality for easy rollback
🛡️ Cross-platform compatibility - works on Windows, macOS, and Linux
⚡ One-command setup - literally just npx setup-servicenow-react

This opens the door to using the entire React ecosystem within ServiceNow:

UI Libraries: Material-UI, Ant Design, Chakra UI, shadcn/ui
Utilities: React Hook Form, React Query, Zustand
Visualization: D3 React components, Chart libraries
And thousands more from the React community

The solution is production-ready, team-friendly, future-proof, and now completely automated. Go forth and be reactive - with React 18! 🚀

Package Information:

NPM: @quixomatic/ui-renderer-react-simple
GitHub: Repository
License: MIT
Latest Version: 1.1.0 (with automatic babel plugin patching)