Announcing ServiceNow SDK 3.0

[BryceG]

We are pleased to announce the release of 3.0.0 of the @Servicenow/sdk is available for download on npm!

This release includes some major changes to our CLI commands, new features like Now.include for referencing content from other files, dependencies support to enhance scripting development, and many bug fixes!

Command line changes:

The driving reason for the 3.0 version change is to reflect the breaking changes in our CLI commands that have gone through major changes in this version.  This is to align with our future development features we have planned out and provide some more consistent naming conventions with the actions being performed on the platform.

• init command replaces create is new way to create or scaffold new applications with the SDK. 
  • Better support for npx!  Use npx @servicenow/sdk init to get started with creating or converting an application
  • Removed automatic deploy to instance at end of run
• install command replaces deploy for installing the build output of the application to your instance
• transform command replaces fetch for downloading and transforming metadata from the instance to fluent or updating metadata folder.  This command can also be used for transforming individual files and directories into fluent, if you wish to move smaller pieces of an application from metadata to fluent.
• dependencies command is now exposed for downloading table definitions and typescript type definitions to your local project
• auth command changes to use flags in place of some interactive components
• build command adds a --frozenKeys which is useful for CI system.  When specified the keys.ts file will not be updated and attempts to update it will result in a build error.  This is useful if you want to ensure keys files get updated properly by engineers during PR reviews for example.

New Features

• Now.include utility function!  This can be used for referencing any text content in another file and assigning it to a field on any fluent entity.  This is very helpful for moving fields that contain large content or are better modified in a file with the proper extension, such as javascript, html, and css content.  If changes are made on the instance, they will be reflected to the include file during transform.

Script include example:

SampleClass.now.ts

Record({
  $id: Now.ID["SampleClass"],
  table: "sys_script_include",
  data: {
    name: "SampleClass",
    apiName: "x_sample.SampleClass",
    access: "public",
    caller_access: "caller_tracking",
    protection_policy: "read-only",
    source: Now.include("./SampleClass.server.js"),
  },
});

SampleClass.server.js

class SampleClassScriptInclude {
  constructor() {}

  hello() {
    gs.info("Hello World");
  }
}

const SampleClass = SampleClassScriptInclude;

Sys UI Page sample:

Record({
  $id: Now.ID["example_ui_page"],
  table: "sys_ui_page",
  data: {
    processing_script: Now.include("./example_ui_page.server.js"),
    html: Now.include("./example_ui_page.html"),
    client_script: Now.include("./example_ui_page.client.js"),
  },
});

The dependencies command

The dependencies command also downloads typing information for client and server side development from the instance, similar to what you get in the on instance script editor.  These types are saved to the @types/servicenow folder in your project, and can then be imported with tsconfig.json files, to be applied to your js and ts files.  We recommend using an extension naming format for this to separate client vs server side files to get proper type information applied to them by typescript.  This will give you a rich development environment for things like script includes, server side script, and client scripts when you use GlideRecord or g_form for example. 

You can see an example of that here in the samples repo: sdk-examples

Script include types will be automatically scanned for from any .js file in your src/fluent directory.  The scanner will look for usages of expressions such as global.JSUtil in the files and download the type information for those.

Other Changes

• Add support for unload and unload.demo custom directories.

• Table API adds support for licensing configuration records. 

• Updating lint rules to allow use of fetch and consolewhich are supported in SN Rhino engine
• Record entity detects if new lines exist in field content and uses string literal to preserve them and not write \n
• Fix issue with transitive dependencies not being bundled when multiple versions of the same dependency are referenced for sys modules
• Fix issue with Table entity not syncing choice field changes from instance
• Support remote tables
• Remove script and html tagged template literal syntax highlighting from extension.  This was causing issues with code appearing broken due to escape characters interfering with syntax highlight parsing.  Recommend using Now.include instead and leverage native file extension capabilities of your editor
• Fix column attributes on transform being deleted
• Wrap html fields with CDATA to fix unescaped characters issue on jelly syntax
• Allow arbitrary fields on any fluent entity.  Fluent entities now allow any arbitrary field to be defined that are not part of the built in type to allow setting fields that exist on your instance but not in our type system.

[dabi]

Hi @BryceG , what purpose do the table definitions /schemas serve once downloaded by the dependencies command?
https://github.com/ServiceNow/sdk-examples/tree/main/dependencies-sample/src/fluent/generated/schema 

[nalessandro]

When will this be available in the web IDE? Now.Include only works on desktop IDE but Now SDK 3 doesn't include a 'sync' like the web IDE. To me, this is essential for a SaaS Platform to adopt a viable developer based IDE experience.

[BryceG]

@nalessandro IDE 2.1 will include SDK 3