--- tags: [flow, wfa, workflow-automation, flow-designer, trigger, data-pill, record-trigger, scheduled, service-catalog, inbound-email, sla] --- # Workflow Automation Flow Guide Comprehensive guide for creating and editing ServiceNow Workflow Automation (WFA) flows using the Fluent SDK. Covers Flow Designer flows including triggers, actions, flow logic, data pills, approvals, and service catalog integration. Use this when implementing event-driven automation, scheduled tasks, approval workflows, or any WFA component. ## When to Use - Creating or editing workflow automation flows - Implementing event-driven automation (record changes, emails, SLA events) - Building scheduled/recurring automations - Implementing approval workflows or notification processes **Important:** Flows consist of four integrated components -- Flow Configuration (metadata), Trigger (when), Actions (what), and Flow Logic (how). --- ## Temporal Requirements Analysis Pick the trigger family based on how the requirement is phrased: | Requirement phrasing | Trigger family | Typical types | | --------------------------------------------------------------- | ----------------------- | ------------------------------------------------- | | "when X is created/updated/happens" | **Record trigger** | `created`, `updated`, `createdOrUpdated` | | "every day/hour", "at 9 AM", "while active", "monitor" | **Scheduled trigger** | `daily`, `weekly`, `monthly`, `repeat`, `runOnce` | | "when email arrives", "when SLA breaches", "on catalog request" | **Application trigger** | `inboundEmail`, `slaTask`, `serviceCatalog` | For the complete trigger reference, see the [Trigger Guide](./wfa-trigger-guide.md). --- ## Component Quick Reference The four components of a flow, and where to find their full reference: | Component | Purpose | Reference | | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ | | **Trigger** | When the flow runs | [Trigger Guide](./wfa-trigger-guide.md) / [Trigger API](../api/flow/trigger-api.md) | | **Action** | What the flow does | [Actions Guide](./wfa-flow-actions-guide.md) / [Action API](../api/flow/action-api.md) | | **Flow Logic** | How the flow branches and loops | [Flow Logic Guide](./wfa-flow-logic-guide.md) / [Flow Logic API](../api/flow/wfa-flow-logic-api.md) | | **Configuration** | Metadata and execution context | [Flow API → Configuration Properties](../api/flow/flow-api.md#flow-configuration-properties) | Reusable building blocks (called from inside a flow): | Building block | Use when | Reference | | ----------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **Subflow** | Reusable callable unit with typed I/O; can use full flow logic | [Subflow Guide](./wfa-subflow-guide.md) / [Subflow API](../api/flow/subflow-api.md) | | **Custom Action** | Reusable sequence of OOB steps (no branching/looping) | [Custom Action Guide](./wfa-custom-action-guide.md) / [Custom Action API](../api/flow/custom-action-api.md) | --- ## Flow vs Subflow | Aspect | Flow | Subflow | | --------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ | | **Purpose** | Automates a business process end-to-end | Encapsulates reusable logic called by flows or other subflows | | **Trigger** | Required -- record event, schedule, or application trigger | None -- invoked programmatically via `wfa.subflow()` | | **Inputs** | From trigger (e.g. `params.trigger.current`) | Typed inputs passed by the caller | | **Outputs** | None | Typed outputs returned to the caller via `assignSubflowOutputs` | | **When to use** | Top-level automation triggered by an event or schedule | Shared logic reused across multiple flows; delegated units of work | --- ## Planning Your Flow When translating requirements into a flow: 1. **Identify the trigger** -- what event activates the flow? 2. **Plan the logic** -- what conditions, branches, or loops are needed? 3. **Select the actions** -- what operations should the flow perform? 4. **Identify reusable logic** -- should any steps be extracted into a Custom Action or Subflow? --- ## Core Principles 1. **Keep flows focused:** A flow should encapsulate a specific automation. Avoid adding side-effects (extra logging, ad-hoc notifications, defensive lookups) that aren't part of the core business logic. 2. **One verb per action:** Each business verb (create, update, send, notify) maps to exactly one fluent action. Multiple verbs require multiple actions. 3. **Use flow logic deliberately:** Add flow logic constructs (`if`, `forEach`, etc.) only when the business logic requires them. Avoid defensive conditionals, default branches, or decision paths added "just in case." 4. **Activation required:** Flows are created in a draft state. Activate them in Flow Designer before they execute. --- ## Rules & Anti-Patterns ### Rules - **Globals (do not import):** `TemplateValue`, `Time`, `Duration`, and `Now.ID[...]` are available globally from `@servicenow/sdk/global`. Use `TemplateValue({ ... })` directly -- not `wfa.TemplateValue`. - **File locations:** Flows + subflows live in `fluent/flows/`; custom actions live in `fluent/actions/`. - **Exactly one trigger per flow.** Subflows have no trigger (they are invoked). - **Background execution recommended:** set `run_flow_in: 'background'` on triggers that support it (see the [Trigger Guide](./wfa-trigger-guide.md)). - **Conditions use template literals:** `` `${wfa.dataPill(..., 'type')}=value` `` -- the literal is required so the data pill interpolates into the encoded query string. - **No JS in flow-logic conditions:** `if`/`elseIf`/`else` do not support `javascript:gs.daysAgoStart(30)`-style expressions. JS functions are allowed only in table-action conditions (`lookUpRecords`, `updateMultipleRecords`). - **Don't hardcode sys_ids:** resolve them via `lookUpRecord` or pass them in as flow inputs. - **Non-existent actions:** there is no `deleteMultipleRecords` -- use `lookUpRecords` + `forEach` + `deleteRecord`. - **Time helpers:** `Time.addDays()` / `Time.nowDateTime()` do not exist -- use data pills like `wfa.dataPill(params.trigger.current.due_date, 'glide_date_time')`. - **Action parameter naming differs per action** (`values` vs. `field_values`, `table` vs. `table_name`, etc.) -- see the [Action API](../api/flow/action-api.md) for the canonical names. - **Activation:** flows are created in a draft state; activate them in Flow Designer before they execute. ### Anti-Patterns #### Do NOT assign data pills to variables (in flows) WFA flows are declarative -- data pills must be used directly in action parameters, never captured in `const`/`let`/`var`. ```typescript fluent // WRONG const recordId = wfa.dataPill(result.record, 'reference'); wfa.action(action.core.updateRecord, {...}, { record: recordId }); // CORRECT wfa.action(action.core.updateRecord, {...}, { record: wfa.dataPill(result.record, 'reference') }); ``` **Exception:** inside a custom action body, `const stepResult = wfa.actionStep(...)` is correct -- it's the standard way to chain step outputs into downstream steps. #### Template literals work only in specific fields Supported: `ah_subject`, `log_message`. **NOT** supported: `ah_body`, `message` (SMS), or any field inside `TemplateValue({...})`. ```typescript fluent // WRONG ah_body: `Details: ${wfa.dataPill(desc, 'string')}`, // does not interpolate values: TemplateValue({ notes: `Status: ${wfa.dataPill(status, 'string')}` // does not interpolate }); // CORRECT ah_subject: `Incident ${wfa.dataPill(number, 'string')}`, ah_body: 'Please check your assignment for details.', values: TemplateValue({ notes: wfa.dataPill(status, 'string') // data pill directly, no template }); ``` #### Do NOT mix JavaScript and DSL paradigms WFA flows are declarative -- don't try to build helper functions or generic factories. ```typescript fluent // WRONG const getFieldValue = field => wfa.dataPill(params.trigger.current[field], 'string'); // CORRECT conditions: `priority=${wfa.dataPill(params.trigger.current.priority, 'string')}^active=true`; ``` --- ## Data Pills `wfa.dataPill()` wraps expressions with type information for Flow Designer XML serialization. The function is a passthrough at runtime -- the type argument is consumed by the build plugin to emit the correct XML. ```typescript fluent wfa.dataPill(_expression, _type: FlowDataType) ``` ### Usage Contexts - **Trigger data**: `params.trigger.current.*` -- record fields from the trigger record - **Action outputs**: `actionResult.fieldName` -- output fields of an action captured to a `const` - **Subflow outputs**: `subflowResult.fieldName` -- output fields of a subflow captured to a `const` - **Custom action inputs**: `params.inputs.*` -- the action's declared inputs (inside `Action()` body) - **Custom action step outputs**: `stepResult.fieldName` -- output of a `wfa.actionStep()` captured to a `const` - **Dot-walking**: `params.trigger.current.assigned_to.manager.email` -- traverse reference fields (multi-level supported) ### Common FlowDataType Values The SDK supports ~100 FlowDataType values; most flows use a small set. Common categories: | Category | Types | | ----------------- | ------------------------------------------------------------------------------------------------ | | **Basic** | `'string'`, `'integer'`, `'boolean'`, `'decimal'`, `'float'` | | **Email content** | `'string_full_utf8'` -- use for email subjects/bodies, NOT plain `'string'` | | **Date/Time** | `'datetime'`, `'glide_date_time'`, `'glide_date'`, `'glide_duration'`, `'due_date'` | | **Reference** | `'reference'`, `'document_id'`, `'table_name'`, `'field_name'` | | **Array** | `'array.object'`, `'array.string'`, `'records'` (use `'records'` for `forEach`) | | **Choice / Text** | `'choice'`, `'journal_input'`, `'multi_line_text'`, `'html'` | | **Other** | `'json'`, `'email'`, `'phone_number'`, `'url'`, `'currency'`, `'approval_rules'`, `'conditions'` | **Whole record vs. sys_id:** pass `params.trigger.current` with type `'reference'` for the whole record; use `params.trigger.current.sys_id` only when a parameter requires just the sys_id string. ### Data Pill Examples ```typescript fluent // Different sources wfa.dataPill(params.trigger.current, "reference") // trigger record wfa.dataPill(params.trigger.current.assigned_to.email, "string") // dot-walking through references wfa.dataPill(createResult.record, "reference") // action output wfa.dataPill(lookupResult.Records, "records") // record set for forEach wfa.dataPill(validation.isValid, "boolean") // subflow output wfa.dataPill(params.inputs.description, "string") // custom action input (inside Action()) wfa.dataPill(stepResult.record.number, "string") // custom action step output (inside Action()) // In a flow-logic condition (template literal required) condition: `${wfa.dataPill(params.trigger.current.priority, "string")}=1` // In a supported template-literal field (ah_subject, log_message) log_message: `Incident ${wfa.dataPill(params.trigger.current.number, "string")} created` ``` --- ## End-to-End Examples Complete flow definitions showing trigger, configuration, and action body working together -- including how to **chain actions** by capturing their return value as `const` and feeding outputs into downstream calls via `wfa.dataPill()`. For trigger-specific reference, see the [Trigger Guide](./wfa-trigger-guide.md); for action-specific examples, see the [Flow Actions Guide](./wfa-flow-actions-guide.md). ### Service Catalog with Approval & Fulfillment Catalog request → manager approval → fulfillment task. Demonstrates `trigger.application.serviceCatalog`, `getCatalogVariables`, `askForApproval` with `wfa.approvalRules()`, and conditional task creation. ```typescript fluent import { Flow, wfa, action, trigger } from "@servicenow/sdk/automation"; import { laptopCatalogItem } from "../catalogs/laptop-catalog.now"; Flow( { $id: Now.ID["catalog_approval_flow"], name: "Laptop Request - Approval & Fulfillment", runAs: "system" }, wfa.trigger( trigger.application.serviceCatalog, { $id: Now.ID["catalog_trigger"] }, { run_flow_in: "background" } ), params => { // Surface template variables onto the request item wfa.action( action.core.getCatalogVariables, { $id: Now.ID["fill_template_vars"] }, { requested_item: wfa.dataPill(params.trigger.request_item, "reference"), template_catalog_item: `${laptopCatalogItem}` } ); // Manager approval (blocking) const approval = wfa.action( action.core.askForApproval, { $id: Now.ID["manager_approval"] }, { record: wfa.dataPill(params.trigger.request_item, "reference"), table: "sc_req_item", approval_reason: "Manager approval required for laptop request", approval_conditions: wfa.approvalRules({ conditionType: "AND", ruleSets: [ { action: "ApprovesRejects", conditionType: "AND", rules: [[{ ruleType: "Any", users: [], groups: [""], manual: false }]] } ] }) } ); // Create the fulfillment task only on approval wfa.flowLogic.if( { $id: Now.ID["if_approved"], condition: `${wfa.dataPill(approval.approval_state, "choice")}=approved` }, () => { wfa.action( action.core.createCatalogTask, { $id: Now.ID["fulfillment_task"] }, { ah_requested_item: wfa.dataPill(params.trigger.request_item, "reference"), ah_short_description: "Procure and provision laptop", ah_wait: false } ); } ); } ); ``` ### Record Iteration with Flow Logic Covers record trigger + bulk lookup + `forEach` + `flowLogic.if` + conditional record update. Shows how flow logic constructs compose around action chaining. ```typescript fluent import { action, Flow, wfa, trigger } from "@servicenow/sdk/automation"; Flow( { $id: Now.ID["cmdb_critical_ci_flag_flow"], name: "Flag Critical CIs During Change Implementation", runAs: "system" }, wfa.trigger( trigger.record.updated, { $id: Now.ID["change_implementing"] }, { table: "change_request", condition: "state=-1^approval=approved", run_flow_in: "background" } ), params => { // Find all CIs related to the change const cis = wfa.action( action.core.lookUpRecords, { $id: Now.ID["find_related_cis"] }, { table: "cmdb_ci", conditions: `cmdb_ci=${wfa.dataPill(params.trigger.current.cmdb_ci, "string")}^operational_status=1`, max_results: 50 } ); // For each CI, flag the critical ones as "under change" wfa.flowLogic.forEach( wfa.dataPill(cis.Records, "records"), { $id: Now.ID["each_ci"] }, ci => { wfa.flowLogic.if( { $id: Now.ID["ci_is_critical"], condition: `${wfa.dataPill(ci.business_criticality, "string")}=1` }, () => { wfa.action( action.core.updateRecord, { $id: Now.ID["mark_under_change"] }, { table_name: "cmdb_ci", record: wfa.dataPill(ci.sys_id, "reference"), values: TemplateValue({ install_status: "3", work_notes: "Critical CI affected by approved change" }) } ); } ); } ); } ); ``` ### Subflow + Custom Action Composition A flow that invokes both reusable building blocks: a **subflow** (for branching validation logic) and a **custom action** (for a packaged escalation sequence). Shows how to compose flows from imported pieces. ```typescript fluent import { action, Flow, wfa, trigger } from "@servicenow/sdk/automation"; import { validateUserSubflow } from "../flows/validate-user-subflow.now"; import { escalateIncident } from "../actions/escalate-incident.now"; Flow( { $id: Now.ID["p1_incident_workflow"], name: "P1 Incident - Validate Caller and Escalate", runAs: "system" }, wfa.trigger( trigger.record.created, { $id: Now.ID["p1_created"] }, { table: "incident", condition: "priority=1", run_flow_in: "background" } ), params => { // Subflow - typed I/O, full flow logic inside const validation = wfa.subflow( validateUserSubflow, { $id: Now.ID["validate_caller"] }, { userId: wfa.dataPill(params.trigger.current.caller_id.sys_id, "string"), waitForCompletion: true } ); // Branch on subflow output; invoke a custom action on the happy path wfa.flowLogic.if( { $id: Now.ID["caller_valid"], condition: `${wfa.dataPill(validation.isValid, "boolean")}=true` }, () => { wfa.action( escalateIncident, { $id: Now.ID["run_escalate"] }, { incident: wfa.dataPill(params.trigger.current, "reference"), reason: "P1 incident from validated caller -- auto-escalated" } ); } ); } ); ```