Skip to main content
Version: 4.6.0

AiAgenticWorkflow

Configure an AI Agentic Workflow using the Fluent API. This API provides a structured interface for creating AI Agentic Workflows in ServiceNow's AI Agent Studio, automatically handling all underlying complexity and relationships between multiple tables.


Overview

The AiAgenticWorkflow API enables you to define intelligent workflows that can:

  • Orchestrate Multiple Agents: Coordinate multiple AI agents working together as a team
  • Process Context: Apply custom scripts to transform context before execution
  • Control Access: Define role-based security and data access controls
  • Trigger Automatically: Configure triggers for automatic workflow invocation
  • Manage Versions: Support multiple versions with different configurations
  • Execute Dynamically: Run with dynamic user identity based on role-based access

The plugin automatically generates all required ServiceNow records (~7 tables) with proper relationships and defaults.

Default Value Suppression

The plugin follows a "only specify what differs from defaults" pattern. During transform (ServiceNow → Fluent), fields that match their default values are automatically omitted from the generated code. This keeps Fluent files clean and minimal. For example:

  • active: true → omitted (default for workflow)
  • executionMode: 'copilot' → omitted (default)
  • sysDomain: 'global' → omitted (default)
  • enableDiscovery: false → omitted (default for trigger config)
  • portal: '' → omitted (empty string default)

Only specify fields when their values differ from the defaults listed in this document.


Supported Record Types

Based on the metadata files generated by this plugin:

Record TypeTableDescription
AI Agentic Workflowsn_aia_usecasePrimary workflow definition
AI Teamsn_aia_teamTeam configuration for the workflow
AI Team Membersn_aia_team_memberTeam member associations (agents in the team)
AI Versionsn_aia_versionVersion information for the workflow
Use Case Config Overridesn_aia_usecase_config_overrideConfiguration overrides for the workflow
Trigger Configurationsn_aia_trigger_configurationAutomated trigger definitions
Trigger Agent Usecase M2Msn_aia_trigger_agent_usecase_m2mMapping between triggers, workflows, and use cases
Agent Access Role Configurationsys_agent_access_role_configurationRole-based data access controls

API Parameters

Main Configuration

Field NameTypeMandatoryDefaultDescription
$idNow.ID[string]YesUnique identifier for the workflow
namestringYesDisplay name of the AI Agentic Workflow
descriptionstringYesBrief description of what the workflow does
securityAclSecurityAclUserAccessConfigYesMANDATORY - Automatically generates sys_security_acl and sys_security_acl_role records. Uses discriminated union on type: 'Any authenticated user', 'Specific role', or 'Public'
teamTeamTypeNoTeam configuration with nested members array
versionsAIAVersion[]NoArray of version configurations
runAsstringNoField name for run-as user (dynamic resolution). Omit for dynamic user identity
dataAccessDataAccessConfigWorkflowTypeNoData access controls (required when runAs is not set)
triggerConfigTriggerConfigType[]NoArray of trigger configurations for automatic invocation
recordType'custom' | 'template' | 'aia_internal'No'template'Record type
executionMode'copilot' | 'autopilot'No'copilot'Execution mode for the workflow
activebooleanNotrueWhether the workflow is active
sysDomainstringNo'global'Domain ID
contextProcessingScriptfunction | stringNoScript to process context - supports inline or Now.include()
memoryScopestringNo'global'Memory scope for team members

Note: The following fields are auto-generated by the plugin and should not be specified by users:

  • internalName: Auto-generated from domain.scope.name
  • Trigger useCase: Auto-populated with parent workflow ID

Team Configuration (team)

Team configuration for organizing multiple agents. The team has a nested members array.

Key Fields:

  • $id — Unique identifier (MANDATORY for teams)
  • name — Team name
  • sysDomain — Domain ID (default: 'global', omit if global)
  • members — Array of agent sys_ids or Record references

Note: Team description is auto-populated from the workflow's description field. Do not specify it.


Team Members (team.members)

Simple array of agent sys_ids or Record references nested within the team configuration.

Example:

import { AiAgenticWorkflow, Record } from '@servicenow/sdk/core'

const summaryAgent = Record({
table: 'sn_aia_agent',
$id: Now.ID['summary_agent'],
data: { name: 'Record Summary Agent' },
})

const searchAgent = Record({
table: 'sn_aia_agent',
$id: Now.ID['search_agent'],
data: { name: 'Search Q&A Agent' },
})

AiAgenticWorkflow({
name: 'Dynamic User Workflow',
description: 'Workflow with dynamic user identity',
securityAcl: {
$id: Now.ID['dynamic_user_workflow_acl'],
type: 'Any authenticated user',
},
dataAccess: {
roleList: [
itilRole, // Role reference
userAdminRole, // Role reference
],
description: 'Data access for itil and user_admin roles',
},
team: {
$id: Now.ID['my_team'],
name: 'Analysis Team',
members: [summaryAgent, searchAgent],
},
})

Important Notes:

  • Using the Record API is recommended for better readability and portability across instances
  • When using sys_id strings, they must be valid GUIDs (32-character hex strings)
  • Non-GUID strings will trigger validation errors

Version Configuration (versions)

Version information for the workflow.

Key Fields:

  • name — Version name
  • number — Version number
  • instructions — Version-specific instructions
  • state — Version state: 'published', 'draft', 'committed', or 'withdrawn' (default: 'draft', omit if draft)

Run As User (runAs)

Specifies which user the Agentic Workflow runs as.

Important Notes:

  • If runAs is set to a user sys_id, the workflow runs as that specific user
  • If runAs is omitted, the workflow uses dynamic user identity and dataAccess becomes mandatory
  • Dynamic user identity means the workflow inherits roles from the invoking user based on dataAccess.roleList

Security ACL Configuration (securityAcl)

MANDATORY - Automatically generates sys_security_acl and sys_security_acl_role records for this workflow. Controls who can invoke the workflow.

Access Types

'Any authenticated user' — Any logged-in user can invoke this workflow.

'Specific role' — Only users who hold at least one of the listed roles can access. roles is required.

'Public' — No authentication required.

Important Notes:

  • securityAcl controls who can invoke the workflow (access control)
  • runAs / dataAccess controls which user identity the workflow runs under (execution context) — these are separate concerns
  • The plugin automatically creates sys_security_acl and sys_security_acl_role records
  • The ACL name is derived from the workflow's internal name: {domain}.{scope}.{workflowName}

Data Access Controls (dataAccess)

MANDATORY when runAs is omitted - Defines which roles the workflow can inherit from the invoking user during execution.

Note: The action field is automatically set to 'limit_to_roles' by the plugin. Fields like agent, agentTable, name, and sysDomain are also auto-populated. The entire dataAccess object is omitted from transform output when no roles are specified.

Example

import { AiAgenticWorkflow, Role } from '@servicenow/sdk/core'

const itilRole = Role({
$id: Now.ID['itil_role'],
name: 'x_app.itil',
description: 'ITIL role for incident management',
})

const userAdminRole = Role({
$id: Now.ID['user_admin_role'],
name: 'x_app.user_admin',
description: 'User administration role',
})

AiAgenticWorkflow({
name: 'Dynamic User Workflow',
description: 'Workflow with dynamic user identity',
securityAcl: {
$id: Now.ID['dynamic_user_workflow_acl'],
type: 'Any authenticated user',
},
// runAs is omitted — dynamic user identity
dataAccess: {
roleList: [
itilRole, // Role reference
userAdminRole, // Role reference
],
description: 'Data access for itil and user_admin roles',
},
})

When to Use:

  • Use dataAccess when you want the workflow to run with dynamic user identity (omit runAs)
  • Omit dataAccess when runAs is set to a specific user sys_id

Trigger Configuration (triggerConfig)

Configure automatic workflow invocation based on record changes or schedules.

Trigger Types

Trigger TypeDescription
record_createTriggers when a new record is created
record_create_or_updateTriggers when a record is created or updated
record_updateTriggers when an existing record is updated
emailTriggers based on email events
scheduledTriggers at scheduled intervals
dailyTriggers daily at a specified time
weeklyTriggers weekly on a specified day
monthlyTriggers monthly on a specified day
ui_actionTriggers from a UI action

Complete Examples

Example 1: Workflow with Data Access (from AiAgenticWorkflow.now.ts)

This example matches the actual transform output — only non-default fields are specified.

import { AiAgenticWorkflow } from '@servicenow/sdk/core'

export const exampleAgenticWorkflow = AiAgenticWorkflow({
$id: Now.ID['employee_record_summarization_workflow'],
name: 'Employee Record Summarization',
description: 'Analyzes employee records and generates summaries',
recordType: 'custom',
securityAcl: {
$id: Now.ID['employee_summarization_workflow_acl'],
type: 'Any authenticated user',
},
team: {
$id: Now.ID['employee_summarization_team'],
name: 'Employee Summarization Team',
members: [
'274b465a7d5f42e581664209557b2b18', // Record Summary Agent sys_id
'2dfb22af3351f2101ea99d273e5c7ba3', // Search Q&A Agent sys_id
],
},
versions: [
{
name: 'V1',
number: 1,
state: 'published',
instructions: 'Fetch employee record, analyze key fields, and generate summary',
},
{
name: 'V2',
number: 2,
instructions: 'Enhanced version with validation and department analysis',
},
],
triggerConfig: [
// Record based trigger
{
name: 'Employee Record Created',
targetTable: 'x_snc_cust_app_age_employee',
triggerFlowDefinitionType: 'record_create',
triggerCondition: 'first_nameISNOTEMPTY',
objectiveTemplate: 'Summarize employee record ${sys_id}',
runAsScript: Now.include('./run-as-script.js'),
showNotifications: true,
channel: 'Now Assist Panel',
},
// Schedule based trigger
{
name: 'Weekly Employee Review',
active: true,
targetTable: 'x_snc_cust_app_age_employee',
triggerFlowDefinitionType: 'scheduled',
objectiveTemplate: 'Review all employee records for the week',
schedule: {
runDayOfWeek: 2, // Monday
runDayOfMonth: 2,
starting: '1970-01-01 09:00:00', // 9:00 AM
time: '1970-01-01 09:00:00', // 9:00 AM
},
channel: 'Now Assist Panel',
},
],
dataAccess: {
roleList: ['2831a114c611228501d4ea6c309d626d'], // admin role sys_id
description: 'Restrict workflow access to admin role',
},
})

Example 2: Workflow with Dynamic User Identity (from DynamicUserWorkflow.now.ts)

import { AiAgenticWorkflow } from '@servicenow/sdk/core'

export const dynamicUserWorkflow = AiAgenticWorkflow({
$id: Now.ID['incident_management_workflow'],
name: 'Incident Management Workflow',
description:
'This workflow analyzes incident records, identifies patterns, and provides resolution recommendations',
recordType: 'custom',
runAs: '<sys_user_id>'
team: {
$id: Now.ID['incident_workflow_team'],
name: 'Incident Management Team',
members: [],
},
versions: [
{
name: 'V1',
number: 1,
state: 'published',
instructions:
'Analyze incident ${number} with priority ${priority}. Identify potential root causes and suggest resolution steps based on similar past incidents.',
},
],
// Security ACL — controls who can invoke this workflow
securityAcl: {
$id: Now.ID['incident_management_workflow_acl'],
type: 'Any authenticated user',
},
})

Best Practices

1. Security Configuration

  • Always set securityAcl — it is mandatory and auto-generates the sys_security_acl record
  • securityAcl.type controls who can invoke the workflow: 'Any authenticated user', 'Specific role', or 'Public'
  • securityAcl.$id is required — it identifies the generated ACL record
  • runAs is separate from securityAcl: it is a field name used for dynamic user resolution (not who can invoke the workflow)
  • Use dataAccess.roleList when runAs is not set, to restrict which roles the workflow can inherit from the invoking user

2. Team Configuration

  • Always provide team.$id when creating a team (mandatory for teams)
  • Use meaningful team names that describe the purpose
  • Use simple array of strings for team.members - just agent sys_ids or Record references
  • Do not set team description - it is auto-populated from the workflow's description
  • No need to specify sysDomain - it defaults to 'global'
  • No need to specify memoryScope - it defaults to 'global'

3. Version Management

  • Omit state for draft versions (default is 'draft')
  • Use state: 'published' for production
  • Increment number for new versions (e.g., 1, 2, 3)
  • Use meaningful name (e.g., "V1", "V2")

4. Trigger Configuration

  • Only specify non-default fields - defaults are automatically suppressed during transform
  • Use 'Now Assist Panel' for channel - auto-mapped to sys_id
  • Use specific triggerCondition to avoid unnecessary invocations
  • Include objectiveTemplate in trigger config for the objective message
  • Validate starting field format: YYYY-MM-DD HH:MM:SS
  • Trigger mappings are auto-generated - no need to specify them manually
  • Default values to omit: active: false, enableDiscovery: false, showNotifications: false, description: '', portal: '', profile: '', runAs: '', runAsUser: '', businessRule: '', domain: 'global'

5. Script Fields

  • Use module imports for external script files (or Now.include() for legacy scripts)
  • Keep scripts concise and focused
  • Handle errors gracefully in scripts
  • Return proper values from context processing scripts
  • CDATA tags are handled automatically - don't add them manually

6. Schedule Configuration

  • Use nested schedule object for scheduled triggers
  • Set triggerFlowDefinitionType to 'scheduled', 'daily', 'weekly', or 'monthly'
  • runDayOfWeek: 1=Sunday, 2=Monday, ..., 7=Saturday
  • runDayOfMonth: 1-31 for monthly schedules
  • Date/time format: YYYY-MM-DD HH:MM:SS (e.g., '1970-01-01 09:00:00')
  • Duration format for repeatInterval: YYYY-MM-DD HH:MM:SS (e.g., '1970-01-05 12:00:00' for 5 days)
  • Omit empty schedule fields — only specify fields with actual values

7. Record References

  • All String | Record<table> fields support both sys_id strings and Record references
  • Use Record references for better portability across instances
  • Supported fields: runAs, runAsUser, channel, profile, portal, businessRule
  • businessRule also accepts Fluent BusinessRule() objects defined in the same project
  • Channel supports names: Use 'Now Assist Panel' directly (auto-mapped to sys_id)

Common Patterns

Pattern 1: Workflow with Triggers

AiAgenticWorkflow({
$id: Now.ID['triggered_workflow'],
name: 'Triggered Workflow',
description: 'Workflow with automatic triggers',
securityAcl: { $id: Now.ID['triggered_workflow_acl'], type: 'Any authenticated user' },
runAs: 'user_sys_id',
team: {
$id: Now.ID['triggered_team'],
members: ['agent_sys_id_1'],
},
triggerConfig: [
{
name: 'Record Trigger',
targetTable: 'incident',
triggerFlowDefinitionType: 'record_create',
triggerCondition: 'priority=1',
objectiveTemplate: 'Process incident ${number}',
channel: 'Now Assist Panel',
},
],
})

Pattern 2: Workflow with Scheduled Triggers

AiAgenticWorkflow({
name: 'Scheduled Review Workflow',
description: 'Workflow that runs on a schedule',
acl: '',
runAs: 'user_sys_id',
team: {
$id: Now.ID['scheduled_team'],
members: ['6816f79cc0a8016401c5a33be04be441'],
},
triggerConfig: [
{
name: 'Weekly Review',
targetTable: 'incident',
triggerFlowDefinitionType: 'scheduled',
objectiveTemplate: 'Review all incidents for the week',
channel: 'Now Assist Panel',
schedule: {
runDayOfWeek: 2, // Monday
time: '1970-01-01 09:00:00', // 9:00 AM
triggerStrategy: 'every',
},
},
{
name: 'Monthly Report',
targetTable: 'incident',
triggerFlowDefinitionType: 'scheduled',
objectiveTemplate: 'Generate monthly incident report',
channel: 'Now Assist Panel',
schedule: {
runDayOfMonth: 1, // First day of month
time: '1970-01-01 08:00:00', // 8:00 AM
repeatInterval: '1970-01-05 12:00:00',
},
},
],
})

Troubleshooting

Team Not Created

Problem: Team configuration provided but team record not generated.

Solution:

  • Ensure team.$id is provided (mandatory for teams)
  • Use Now.ID['team_name'] format for the ID
  • Check that team.members array is provided (nested within team object)

Data Access Validation Error

Problem: Error: "dataAccess.roleList is mandatory when runAs is empty"

Solution:

  • Either set runAs to a user sys_id
  • Or provide dataAccess.roleList with at least one role

Trigger Not Firing

Problem: Trigger configured but workflow not invoked automatically.

Solution:

  • Verify triggerConfig.active is true
  • Check triggerCondition matches your records
  • Ensure targetTable is correct
  • Verify objectiveTemplate is set in trigger config
  • Validate starting field format: YYYY-MM-DD HH:MM:SS

Script Fields Not Working

Problem: Scripts showing as [object Object] or not executing.

Solution:

  • Use string format for scripts: `(function() { ... })()`
  • Or use module imports for external files (preferred), or Now.include('./script-file.js') for legacy scripts
  • Ensure CDATA tags are NOT manually added (handled automatically)
  • Check script parameter names match expected values

Workflow Not Using Coalesce

Problem: Workflow $id is optional but workflow not found.

Solution:

  • Workflows use coalesce on name field - ensure unique names
  • $id is optional for workflows (unlike teams which require it)
  • If you need explicit IDs, you can still provide $id

Table Schema

sn_aia_usecase

Column NameTypeMandatoryDefault ValueDescription
advanced_modeTrue/FalseFALSEfalseWhether advanced mode is enabled
applicability_scriptScriptFALSEjavascript:new sn_aia.AgentExecutionUtil().getApplicabilityDefaultScript();Script that determines when workflow is applicable
base_planTranslated TextFALSEBase plan instructions
conditionConditionsFALSECondition table reference
context_processing_scriptScriptFALSEjavascript:sn_aia.agents.USECASE_CONTEXT_PROCESSING_SCRIPT_TEMPLATE;Script for processing context
descriptionTranslated TextTRUEDescription of the workflow
execution_modeChoiceFALSEcopilotExecution mode (copilot/autopilot)
internal_nameStringFALSEInternal name (domain.scope.name)
nameTranslated TextTRUEDisplay name of the workflow
parentReferenceFALSEReference to parent use case
record_typeChoiceFALSEcustomRecord type (template/custom etc.)
source_idReferenceFALSEReference to source workflow
strategyReferenceFALSEReference to workflow strategy
sys_domainDomain IDFALSEDomain identifier
teamReferenceFALSEReference to team

sn_aia_team

Column NameTypeMandatoryDefault ValueDescription
descriptionTranslated TextFALSEDescription of the team
nameTranslated TextFALSEName of the team
sys_domainDomain IDFALSEDomain identifier

sn_aia_team_member

Column NameTypeMandatoryDefault ValueDescription
agentReferenceFALSEReference to the AI Agent
memory_scopeChoiceFALSEglobalMemory scope for the agent
sys_domainDomain IDFALSEDomain identifier
teamReferenceFALSEReference to the team

sn_aia_version

Column NameTypeMandatoryDefault ValueDescription
conditionCondition StringFALSECondition for version activation
instructionsTranslated TextFALSEVersion-specific instructions
stateChoiceFALSEdraftState of the version (draft/published etc.)
sys_domainDomain IDFALSEglobalDomain identifier
sys_overridesReferenceFALSEReference to override version
target_idDocument IDTRUEReference to target record
target_tableTable NameTRUEName of the target table
version_nameTranslated TextTRUEDisplay name of the version
version_numberIntegerFALSEVersion number

sn_aia_usecase_config_override

Column NameTypeMandatoryDefault ValueDescription
activeTrue/FalseFALSEWhether the configuration is active
run_as_userReferenceFALSEUser to run the workflow as
sys_domainDomain IDFALSEDomain identifier
sys_overridesReferenceFALSEReference to override configuration
usecase_configurationReferenceTRUEReference to the workflow

sys_agent_access_role_configuration

Column NameTypeMandatoryDefault ValueDescription
actionChoiceTRUElimit_to_rolesAction to perform for access control
agentDocument IDTRUEReference to the workflow
agent_tableTable NameTRUEsn_aia_usecaseTable name of the workflow
descriptionStringFALSEDescription of the access configuration
nameStringTRUEName of the access configuration
role_listListFALSEList of roles that have access
sys_domainDomain IDFALSEglobalDomain identifier

sn_aia_trigger_configuration

Column NameTypeMandatoryDefault ValueDescription
activeTrue/FalseFALSEfalseWhether the trigger is active
business_ruleReferenceFALSEReference to business rule
channelReferenceTRUEChannel for the trigger
conditionConditionsTRUECondition for triggering
descriptionStringFALSEDescription of the trigger
enable_discoveryTrue/FalseFALSEfalseWhether to enable discovery
internal_nameStringFALSEInternal name of the trigger
nameStringTRUEName of the trigger
notification_scriptReferenceFALSEReference to notification script
objective_templateEmail ScriptTRUETemplate for objective message
portalReferenceFALSEReference to portal
profileReferenceFALSEReference to profile
run_asField NameFALSEField name for run-as user
run_as_scriptScriptFALSEScript to determine run-as user
run_as_userReferenceFALSEReference to run-as user
run_dayofmonthIntegerFALSEDay of month to run
run_dayofweekDay of WeekFALSEDay of week to run (1=Sunday, 7=Saturday)
run_periodDurationFALSERun period/interval
run_startBasic DateTimeFALSEStart date/time (YYYY-MM-DD HH:MM:SS)
run_timeBasic TimeFALSETime to run
show_notificationsTrue/FalseFALSEfalseWhether to show notifications
sys_domainDomain IDFALSEglobalDomain identifier
sys_overridesReferenceFALSEReference to override trigger
target_tableTable NameTRUETable to monitor for triggers
trigger_flowReferenceFALSEReference to flow
trigger_flow_definition_typeChoiceFALSEType of flow definition
trigger_strategyChoiceFALSEStrategy for triggering
usecaseReferenceFALSEReference to use case
usecase_discoveryTrue/FalseFALSEfalseWhether to enable usecase discovery

sn_aia_trigger_agent_usecase_m2m

Column NameTypeMandatoryDefault ValueDescription
activeTrue/FalseFALSEtrueWhether the mapping is active
objective_templateEmail ScriptFALSETemplate for objective message
related_resource_recordDocument IDTRUEReference to the related record (workflow)
related_resource_tableTable NameTRUEsn_aia_usecaseName of the related table
sys_domainDomain IDFALSEglobalDomain identifier
sys_overridesReferenceFALSEReference to override mapping
trigger_configurationReferenceTRUEReference to trigger configuration