glide-types

Contains type declaration for Glide Scriptable APIs to be used in NowSDK for API type support in module JS development. Published to npm as @servicenow/glide https://artifact-npm.devsnc.com/#browse/search=keyword%3Dglide-type

Owners

samyak.shah matthew.clase venkat.kaluva

Stages of the Types Build Process

The Jenkinsfile in this repo defines all stages of the Glide-Types build process, starting with collecting info for scriptable APIs from the various code.devsnc repos, generating Typescript type declarations with method stubs, and bundling those declarations into an npm artifact that can be included in a NowSDK project.

Multibranch pipeline for Jenkins job: https://build.devsnc.com/teams-star/job/star/job/groups/job/platform/job/glide-types-multibranch-pipeline/

1. Collect and Build Typescript API declarations via Maven Javadoc Plugin

The maven javadoc plugin uses a custom doclet for collecting info from the Java codebase. Jenkins builds the doclet from this repo: https://code.devsnc.com/dev/java-typescript-transformer/tree/scratch/103. 'snc-parent/pom.xml' defines the dependency on this custom transformer across the various repos. The doclet collects scriptable APIs from Glide as well as other repos (see Jenkinsfile for list). The doclet collects scriptable APIs from Glide as well as other repos (see Jenkinsfile for list).

Generated class example:

Collection involves the following steps:

1. Gather declared namespaces and API extension points from all plugin.xml files
      - Each module may have many plugins with plugin.xml which define certain scriptable API extension points 
      - The transformer iterates all source files in the module to create a mapping between the exported APIs defined in this file and the plugin namespace in order to invoke the APIs via script. 
      -  Each namespace mapping is written to the target directory in 'target/classes/resources/npm_artifacts/<namespace>/mapping.txt'
 2. Generate TS declarations for the Scriptable APIs in the module
      - Creates a .ts file based on the scriptable name 
          * (defined in GlideScriptable or GenerateDeclaration 'name' parameter, falling back to classname if those are not present)
      - written to 'target/classes/resources/npm_artifacts/types/<api>.ts
          * mapped into correct folder at later stage by Jenkins process
      - Only certian Scriptable APIs are published which meet the following criteria:
          * Class has @GenerateDeclaration annotation OR class has @externalDoc annotation AND either @GlideScriptable annotation OR extends ScopedScriptableObject
          * Note: all scriptable methods are published when class has @GenerateDeclaration tag
          * Note: only scriptable methods with @externalDoc on the method javadoc are published when class is @GlideScriptable or ScopedScriptableObject unless it also has @GenerateDeclaration 
   3. Generate TS stub classes for imports 
       Scriptable classes have a complex relationship of importing each other (and importing non-scriptable classes). To mantain this relationship in Typescript a separate 'imports' folder is generated to hold stub classes used as imports without type info
       - 'target/classes/resources/npm_artifacts/imports/<class>.ts 
   4. When javadoc plugin has run on all modules, Jenkins copies output from each 'target' directory to './npm_artifacts' and stashes them

2. Jenkins Builds NPM Package Structure

  1. Unstashes collected artifacts from step #1
  2. Uses mapping.txt files to move every API from './types/<api>.ts' to its' corresponding namespace directory (i.e. './sn_name/<api.ts>')
       - non-namespace APIs remain in 'types' directory
  3. Removes empty directories (namespace dirs with no APIs exposed)
  4. Stashes results again for next stage

3. Pushing TS Files to glide-types Repo

  1. Unstashes artifacts from step #2
  2. Addes all generated files to git branch defined by multi branch job which invoked build process
  3. Files pushed to 'src' directory (ex 'src/imports/*', 'src/types/*...)
  4. Files viewable in repo
  

Example src with types, imports, and namespace APIs: https://code.devsnc.com/dev/glide-types/tree/release/washingtondc/src

4. Publishing NPM Package

  1. Pipeline checks out glide-types repo with specified branch
  2. Updates package.json file at root with version specified in Jenkins build parameters
  3. Commits this change to repo
  4. Performs mvn release step and the following npm steps:
        1. Copy overwrites any TS files in 'imports' with their corresponding 'types' so that return types have correct type support
        2. Creates a JSON mapping of namespaces to APIs for linting purposes  
        3. Runs 'ts --build' step to ensure package is correct 
        4. Runs publish
  5. Artifact published to nexus as @servicenow/glide
       - Publish info defined in glide-types/pom.xml 

How to publish your API to @servicenow/glide npm artifact using Jenkins

1. Ensure the Java API you wish to expose is Scriptable and has @externalDoc or @GenerateDeclaration tags
2. Must extend ScopedScriptableObject or have @GlideScriptable annotation
3. Add matching 'name' parameter to annotation if the Java classname does not match the getClassName() method return vlaue

4. Create a new branch off of master for this repo. [ServiceNow branch naming convention](https://buildtools1.service-now.com/kb_view_customer.do?sysparm_article=KB0528607).

5. Create a new jenkins job for your branch https://build.devsnc.com/teams-star/job/star/job/groups/job/platform/job/glide-types-multibranch-pipeline/ with the following parameters:
    1. push_ts_files: push generated TS files to glide-types repo src/ directory
    2. publish_to_npm: publish the types to npm. 
        - Note: It can be good to do a run with push_ts_files=true, and then check this box when you have verified correctness in glide-types repo
    3. publish_version: version to publish to npm
6. Ensure package is published to npm and update your local Fluent project with new glide-types version

Package Naming Conventions

• Any java API exposed in Glide will be exposed in @servicenow/glide package
• This repo will contain sub package exports with namespaced APIs
  • Ex: import { AppStoreAPI } from @servicenow/sn_appstore_api
• And a separate folder in glide
  • Ex: import { AppStoreAPI } from @servicenow/glide/sn_appstore_api