arnoudkooi/sn-scriptsync/snu-artifacts

SN ScriptSync — Artifacts & File Structure

Conventions for naming, creating, and organizing ServiceNow artifacts as local files.

File Naming Conventions

⚠️ CRITICAL: Do NOT Create Separate Field Files for Configuration

NEVER create separate files for configuration/metadata fields:

• ❌ MyBusinessRule.collection.js (table name - this is a STRING reference)
• ❌ MyBusinessRule.when.js (when to run - this is a STRING choice)
• ❌ MyBusinessRule.active.js (active status - this is a BOOLEAN)
• ❌ MyUIAction.table.js (table reference - this is a STRING)
• ❌ MyOperation.http_method.js (HTTP method - this is a STRING)
• ❌ MyScript.action_insert.js (action flag - this is a BOOLEAN)

These configuration fields belong in the creation payload ONLY, not as separate files.

✅ DO create files for actual script/code/content fields:

1. Script fields (contain executable code):

• script → MyBusinessRule.script.js
• operation_script → MyOperation.operation_script.js
• client_script → MyWidget.client_script.js
• server_script → MyWidget.server_script.js
• processing_script → MyUIPage.processing_script.js

1. Template/HTML fields (contain markup):

• template → MyWidget.template.html
• html → MyUIPage.html

1. CSS fields (contain styles):

• css → MyWidget.css.scss

1. Special files:

• option_schema.json (widget configuration schema)
• demo_data.json (widget demo data)
• link.js (widget link function)

Rule of thumb: If the field contains code, markup, or styles → create a file. If it's a configuration value (string, boolean, number, reference) → include in payload only.

Common Fields Reference Table

Standard Scripts

• Use the artifact name with .script.js extension
• Example: HelloWorldUtils.script.js, DummyIncidentBR.script.js

Calculation Fields

• Use field name with .calculation.js extension
• Example: Foreign.calculation.js

Client Scripts for UI Actions

• Use artifact name with .client_script_v2.js extension
• Example: LargeBold.client_script_v2.js

Service Portal Widgets

• Widgets are folders containing multiple files
• File names: template.html, client_script.js, css.scss, script.js, etc.

Creating New Artifacts

Important: Understanding Table Metadata

When creating a new artifact, the extension needs to understand the table structure:

Key Considerations:

1. Mandatory Reference Fields: Some tables require references to other records (cannot be empty)
2. Field Mappings: Different tables store scripts in different fields
3. Required Setup: Some artifacts need parent records to exist first

Example: Scripted REST API (sys_ws_operation)

A sys_ws_operation record requires:

• Mandatory Reference: web_service_definition field must reference a sys_ws_definition record
• Script Field: The script content is stored in the operation_script field
• Parent Record Required: You must first create or have an existing REST API service definition

Workflow for Complex Artifacts:

1. Extension detects new file
2. Extension fetches table metadata from ServiceNow
3. Extension analyzes mandatory fields and references
4. Extension prompts user: "This requires a web_service_definition reference. Do you want to:

• Select an existing REST API service?
• Create a new REST API service?"

1. User provides required information
2. Extension creates the record with all required fields
3. Extension updates _map.json with the new sys_id

Pulling Existing Records (pull_records)

Use `pull_records` to fetch existing records (Script Includes, Business Rules, Widgets, UI Pages, etc.) matching a query or specific sys_id / sys_ids and write their code fields to disk with automatic _map.json registration:

{
  "command": "pull_records",
  "params": {
    "table": "sys_script",
    "query": "nameSTARTSWITHincident^active=true",
    "limit": 20
  }
}

This is the recommended way to pull scripts in the Global scope (where "Load Scope" is not practical) or ad-hoc sets of records across any table.

Working with Scoped Applications

⚠️ IMPORTANT: Do NOT create scope folders manually

Before creating files in a new scope folder:

1. Sync or pull at least one artifact first from ServiceNow for that scope (via pull_records or the SN Utils sync button)
2. This ensures the scope exists and the folder structure is correct
3. The extension will create the scope folder automatically during the first sync

Why this matters:

• Scope names must match exactly with ServiceNow
• The scope must exist in the instance
• Incorrect scope names will cause sync failures

Correct Workflow:

1. Create or identify a scope in ServiceNow (e.g., x_abc_my_app)
2. Create at least one artifact in that scope in ServiceNow
3. Pull that artifact using pull_records with {"table": "sys_script_include", "query": "sys_scope.scope=x_abc_my_app"}
4. The extension creates: <instance>/x_abc_my_app/<table>/
5. Now you can create new files in that scope folder

Creating Custom Tables

Use the typed `create_table` command — don't drive create_artifact against sys_db_object by hand. ServiceNow auto-creates the physical table plus its base sys_* fields (sys_id, sys_created_on, sys_updated_on, …); you only add your own columns.

Recipe:

1. `create_table` with name, label, optional scope and extends. With a non-global scope, the name is prefixed for you as <scope>_<name> (e.g. x_acme_myapp_project). The prefixed-vs-unprefixed naming is the usual stumbling block — let the command handle it, or pass an already-prefixed x_... name.
2. `add_column` for each field. Set display: true on the column you want as the display value (no separate update_record needed), and pass mandatory / default / choices inline so the column is usable in one call.
3. Seed data rows with rest_request POST /api/now/table/<name> (requires sn-scriptsync.restRequest.enabled). This is the blessed path for plain data rows — create_artifact requires fields.name, which is awkward when the display field isn't name.

Fallback (no typed command available): create the table via create_artifact/rest_request against sys_db_object using the full scoped name (x_<scope>_<name>); the base sys_* fields are created automatically; then add_column for the rest and set the display field.

Large / multi-field payloads (widgets)

When a payload has several large or multiline code fields — e.g. a widget's template / css / script / client_script — do not hand-build the JSON on a shell command line; the escaping is error-prone. Write the request body to a file with JSON.stringify (so newlines and quotes are encoded correctly) and send it with curl -d @body.json, or use the file transport. This applies to any artifact with multiline/large field values.

Verifying a widget preview (component-only screenshot)

To show just the rendered widget without a per-tab screenshot grant, combine activate_tab with the CDP capture_full_page selector:

1. activate_tab with openIfNotFound: true and waitForLoad: true (open/activate the widget preview).
2. capture_full_page with selector: ".my-widget" (or the widget's root class) for a clean, component-only screenshot — no per-tab grant required.

(capture_full_page uses the browser debugger — preflight with get_capabilities → cdp.available.)

Step-by-Step: Creating Simple Artifacts

For simple artifacts like Script Includes (no mandatory references):

Step 1: Create the file in the correct location

<your_instance>/global/sys_script_include/MyNewUtils.script.js

Or for a scoped app (after syncing at least one artifact):

<your_instance>/<your_scope>/sys_script_include/MyNewUtils.script.js

Step 2: Write your code

var MyNewUtils = Class.create();
MyNewUtils.prototype = {
    initialize: function() {
    },
    
    myFunction: function() {
        return 'Hello World';
    },
    
    type: 'MyNewUtils'
};

Step 3: Save the file

The sn-scriptsync extension will:

1. Detect the new file
2. Fetch table metadata to check for mandatory fields
3. Create the record in ServiceNow (prompting for required info if needed)
4. Automatically update _map.json with the new sys_id

⚠️ IMPORTANT: Only create the `.script.js` file

• Do NOT create separate files like .collection.js, .when.js, .active.js
• The extension will prompt for required fields (like collection for Business Rules)
• OR use create_artifact command to include all fields in one payload

Common Table Requirements

rm_story (Story) Table Specifics

Key Fields:

• name - Required by create_artifact (can be same as short_description)
• short_description - The story title/summary
• description - Detailed description (plain text)
• acceptance_criteria - HTML field - use HTML formatting, not markdown
• state - Story state (see values below)
• priority - Priority level (1-4)

State Values:

⚠️ IMPORTANT: acceptance_criteria is an HTML field!

Use HTML tags for formatting, NOT markdown:

<!-- ✅ CORRECT - HTML formatting -->
<b>Acceptance Criteria:</b>
<ul>
  <li>Widget displays correctly</li>
  <li>Score tracking works</li>
  <li>No console errors</li>
</ul>