servicenow-sdk-fluent

name servicenow-sdk-fluent description Builds ServiceNow applications with the ServiceNow SDK and Fluent API (TypeScript): tables, flows, business rules, script includes, ACLs, REST, inbound email, and workflow-as-code. Aligns with official ServiceNow sdk-examples on GitHub when debugging or scaffolding. Use when the user works on ServiceNow SDK, Fluent DSL, now-sdk, @servicenow/sdk, .now.ts files, Glide/Flow Designer code, or email parsing on ServiceNow. Also when they say "create a ServiceNow app" or "build a flow" in that context. ServiceNow SDK Application Builder Read this SKILL.md first for prerequisites, CLI commands, and Key rules (tables, flows, inbound email). For exhaustive API examples, read references/fluent-patterns.md . For subflows, parallel blocks, for-each, and email pipelines, read references/flow-advanced.md . For the official runnable samples (clone list, sample index, how to diff against your code), read references/sdk-examples-repo.md — companion to ServiceNow/sdk-examples . For typed Fluent API reference (version-matched llmsFull / llms from ServiceNow), read references/sdk-api-docs-agents.md — links servicenow.github.io/sdk agent files and versions.json . If a reference example conflicts with the Key rules sections below or with sdk-examples on main , prefer Key rules first, then reconcile using the matching sample file from sdk-examples; for API signatures , prefer version-matched llmsFull from versions.json . This skill enables the agent to generate production-ready ServiceNow applications using the ServiceNow SDK (now-sdk) and the Fluent DSL. Fluent is a TypeScript-based domain-specific language that compiles to ServiceNow metadata XML. It covers tables, flows, business rules, script includes, ACLs, REST APIs, and more. Important: Authentication is handled externally The user has already authenticated with their ServiceNow instance using the SDK CLI. Auth credentials are stored in the system keychain — NOT in project files. You do NOT need to create .env files or handle credentials. If the user needs to set up a new auth profile, point them to: now-sdk auth save < alias > --host https://<instance>.service-now.com --username <user> --default But do NOT run auth commands yourself. The user handles this manually. Prerequisites — Verify Before Generating Code Before writing any Fluent code, quickly check the project has the basics: now.config.json must exist in the project root with at minimum: { "scope" : "x_<vendor>_<app>" , "scopeId" : "<sys_id_of_app>" } For TypeScript projects, also needs: { "transpiledSourceDir" : "dist/src" } package.json must have SDK dependencies: { "type" : "module" , "scripts" : { "build" : "now-sdk build" , "install-app" : "now-sdk install" , "transform" : "now-sdk transform" , "dependencies" : "now-sdk dependencies" } , "devDependencies" : { "@servicenow/sdk" : "^4.0.0" , "@servicenow/glide" : "^27.0.0" } } For TypeScript, add: { "scripts" : { "build" : "rm -rf dist && tsc -b && now-sdk build" } , "devDependencies" : { "typescript" : "^5.5.0" } } If the project doesn't exist yet , the user should scaffold it with: npx @servicenow/sdk init This walks through template selection and links the auth profile. If prerequisites are met, proceed directly to writing Fluent code. Project Structure All Fluent files go in src/fluent/ with the .now.ts extension. Organize by concern: my-sn-app/ ├── now.config.json ├── package.json ├── tsconfig.json # if TypeScript ├── src/ │ ├── fluent/ │ │ ├── tables/ │ │ │ └── email-data.now.ts │ │ ├── flows/ │ │ │ └── inbound-email-parser.now.ts │ │ ├── business-rules/ │ │ ├── script-includes/ │ │ ├── acls/ │ │ └── index.now.ts # barrel exports (optional) │ ├── server/ # JS/TS modules (.server.js or .server.ts) │ └── client/ # front-end code (if fullstack) ├── @types/ # auto-generated type defs (via `now-sdk dependencies`) └── metadata/ # auto-generated XML (build output, do not edit) SDK CLI Commands Reference (v3.0+ / v4.x) These are the commands Claude Code should use or instruct the user to run: Command Purpose Example now-sdk build Compile Fluent → metadata XML now-sdk build now-sdk install Build + pack + deploy to instance now-sdk install --auth <alias> now-sdk transform Download/sync metadata from instance to local now-sdk transform --auth <alias> now-sdk dependencies Fetch table defs and type info from instance now-sdk dependencies --auth <alias> now-sdk init Scaffold a new app or convert existing npx @servicenow/sdk init now-sdk pack Package build output into installable archive now-sdk pack now-sdk auth save Store auth credentials in system keychain User handles manually Build and Install Workflow The standard development cycle is: # 1. Write or modify Fluent code in src/fluent/*.now.ts # 2. Build — compiles Fluent to metadata XML now-sdk build # 3. Install — packages and deploys to the instance now-sdk install --auth < alias > Build flags: --debug true — include debug info --generate-deletes true — remove records from instance that were deleted locally --lint true — run linting during build --frozenKeys — fail if keys.ts needs updating (useful for CI) Install flags: --auth <alias> — which auth profile to use --open-browser true — open the app in browser after install Syncing from Instance To pull changes made on the instance back to local: now-sdk transform --auth < alias > This downloads metadata and converts supported types to Fluent .now.ts files in src/fluent/generated/ . Fetching Type Definitions To get table schemas and type info for IntelliSense: now-sdk dependencies --auth < alias > This populates @types/servicenow/ with type definitions for GlideRecord etc. Core Fluent Patterns Read references/fluent-patterns.md for the full API reference with examples covering Tables, Flows, Business Rules, Script Includes, ACLs, Records, and more. The most important patterns for email parsing apps are summarized below. Table Definition import { Table , StringColumn , ReferenceColumn , IntegerColumn , DateTimeColumn , HtmlColumn , ChoiceColumn } from '@servicenow/sdk/core' export const x_vendor_app_email_data = Table ({ name : 'x_vendor_app_email_data' , label : 'Parsed Email Data' , schema : { x_vendor_app_sender : StringColumn ({ label : 'Sender' , maxLength : 255 , mandatory : true }), x_vendor_app_subject : StringColumn ({ label : 'Subject' , maxLength : 500 }), x_vendor_app_received_date : DateTimeColumn ({ label : 'Received Date' }), x_vendor_app_body_text : HtmlColumn ({ label : 'Email Body' }), x_vendor_app_status : ChoiceColumn ({ label : 'Processing Status' , // choices is an OBJECT (keys = values), NOT an array choices : { new : { label : 'New' }, parsed : { label : 'Parsed' }, error : { label : 'Error' }, }, default : 'new' // use 'default', NOT 'defaultValue' }) } }) Key rules for tables: Table name MUST start with the app scope prefix: x_<vendor>_<app>_ Column names MUST also be prefixed with the scope Available column types: StringColumn , IntegerColumn , BooleanColumn , DateTimeColumn , ReferenceColumn , ChoiceColumn , HtmlColumn , DecimalColumn , URLColumn , DurationColumn , TimeColumn , FieldListColumn , GlideListColumn HtmlColumn — NOT HTMLColumn (casing matters, build will fail) ChoiceColumn choices must be an object { key: { label } } , NOT an array ChoiceColumn default value uses default: , NOT defaultValue: Use ReferenceColumn with reference: '<table_name>' for foreign keys Flow with Inbound Email Trigger import { action, Flow , wfa, trigger } from '@servicenow/sdk/automation' export const emailParserFlow = Flow ( { $id : Now . ID [ 'email_parser_flow' ], name : 'Email Parser Flow' , // description must be a single string literal — NO string concatenation with + description : 'Parses inbound emails and extracts data to custom table' , }, wfa. trigger ( trigger. application . inboundEmail , { $id : Now . ID [ 'inbound_email_trigger' ] }, { // Use 'email_conditions' (NOT 'condition' or 'record_type') // Encoded query format: NO spaces around operator — 'subjectLIKEorder%' email_conditions : 'subjectLIKEorder%' , target_table : 'incident' , // optional: table for reply record } ), ( params ) => { // Inbound email trigger data pills — direct on params.trigger (NOT params.trigger.email.*) // params.trigger.from_address — sender email address // params.trigger.subject — email subject // params.trigger.body_text — plain-text body // params.trigger.inbound_email — reference to sys_email record (for .body, .sys_id, etc.) // params.trigger.user — reference to sys_user who sent the email // Log for debugging wfa. action ( action. core . log , { $id : Now . ID [ 'log_email_received' ] }, { log_level : 'info' , log_message : `Processing email from: ${wfa.dataPill(params.trigger.from_address, 'string' )} ` , } ) // Create record in custom table // createRecord uses 'table_name' (NOT 'table') and values: TemplateValue({}) (NOT a plain object) wfa. action ( action. core . createRecord , { $id : Now . ID [ 'create_parsed_record' ] }, { table_name : 'x_vendor_app_email_data' , values : TemplateValue ({ x_vendor_app_sender : wfa. dataPill (params. trigger . from_address , 'string' ), x_vendor_app_subject : wfa. dataPill (params. trigger . subject , 'string' ), x_vendor_app_body_text : wfa. dataPill (params. trigger . body_text , 'string' ), x_vendor_app_status : 'new' , }), } ) } ) Key rules for flows: Every element needs a unique $id using Now.ID['unique_key'] The $id keys must be unique across the entire application description must be a single string literal — string concatenation with + will cause a build error Trigger types: trigger.record.created , trigger.record.updated , trigger.application.inboundEmail , trigger.schedule.daily , etc. Inbound email trigger config : use email_conditions with encoded query (no spaces around operator). Valid fields: email_conditions , target_table , order , stop_condition_evaluation Inbound email data pills — accessed directly on params.trigger : params.trigger.from_address — sender address (string) params.trigger.subject — subject line (string) params.trigger.body_text — plain-text body (string) params.trigger.inbound_email — the sys_email record reference (use .body , .sys_id , etc.) params.trigger.user — sys_user reference for the sender WRONG : params.trigger.email.subject / params.trigger.email.from — these do NOT exist createRecord inputs: table_name (NOT table ) + values: TemplateValue({...}) (NOT a plain object) TemplateValue is a global — no import needed Use wfa.dataPill() to reference runtime values from trigger or prior actions Use wfa.flowLogic.if() / wfa.flowLogic.elseIf() / wfa.flowLogic.else() for branching Actions: action.core.log , action.core.createRecord , action.core.createTask , action.core.lookUpRecord (capital U), action.core.sendEmail , action.core.getAttachmentsOnRecord , action.core.copyAttachment Flow Logic — Branching wfa. flowLogic . if ( { $id : Now . ID [ 'check_condition' ], condition : ` ${wfa.dataPill(params.trigger.current.severity, 'string' )} =1` }, () => { // actions for when condition is true } ) wfa. flowLogic . else ( { $id : Now . ID [ 'else_block' ] }, () => { // actions for all other cases } ) Email Parsing Workflow — Step by Step When the user asks to build an email parsing application, follow this sequence: Step 1: Analyze the Sample Email