KosmoKrator

productivity

ServiceNow Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the ServiceNow KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.servicenow.*. Use lua_read_doc("integrations.servicenow") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic ServiceNow workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.servicenow.list_incidents({query = "example_query", limit = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("servicenow"))' --json
kosmo integrations:lua --eval 'print(docs.read("servicenow.list_incidents"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local servicenow = app.integrations.servicenow
local result = servicenow.list_incidents({query = "example_query", limit = 1})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.servicenow, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.servicenow.default.* or app.integrations.servicenow.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need ServiceNow, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

ServiceNow — Lua API Reference

list_incidents

List incidents from the ServiceNow incident table.

Parameters

NameTypeRequiredDescription
querystringnoServiceNow encoded query string (e.g. "priority=1^state=2")
limitintegernoMaximum number of incidents to return (default: 20)

Query Syntax

Use ^ to separate conditions. Common operators:

  • = equals
  • != not equals
  • LIKE contains
  • STARTSWITH starts with
  • ^OR or-condition
  • ^NQ new query (AND group)

Examples

-- List all open incidents
local result = app.integrations.servicenow.list_incidents({
  query = "active=true"
})

-- High-priority incidents
local result = app.integrations.servicenow.list_incidents({
  query = "priority=1^ORpriority=2",
  limit = 50
})

get_incident

Retrieve a single ServiceNow incident by its sys_id.

Parameters

NameTypeRequiredDescription
idstringyesThe sys_id of the incident

Example

local result = app.integrations.servicenow.get_incident({
  id = "a9e4e1e14f3c41200bae4b8d0210c7d3"
})

create_incident

Create a new ServiceNow incident.

Parameters

NameTypeRequiredDescription
short_descriptionstringyesBrief summary of the incident
descriptionstringnoDetailed description
prioritystringno"1" (critical), "2" (high), "3" (moderate), "4" (low), "5" (planning)

Example

local result = app.integrations.servicenow.create_incident({
  short_description = "Email server not responding",
  description = "The mail server at mail.example.com has been unreachable since 09:00 UTC.",
  priority = "1"
})
print("Created incident: " .. result.result.number)

update_incident

Update an existing ServiceNow incident.

Parameters

NameTypeRequiredDescription
idstringyesThe sys_id of the incident
fieldsobjectyesField names and their new values

Common Fields

FieldDescription
stateIncident state: 1 (new), 2 (in progress), 3 (on hold), 6 (resolved), 7 (closed)
priorityPriority 1–5
short_descriptionUpdated summary
descriptionUpdated description
work_notesInternal work notes
commentsAdditional comments
assigned_tosys_id of the assignee

Example

local result = app.integrations.servicenow.update_incident({
  id = "a9e4e1e14f3c41200bae4b8d0210c7d3",
  fields = {
    state = "6",
    work_notes = "Root cause identified: DNS misconfiguration. Fix applied."
  }
})

list_tasks

List tasks from the ServiceNow task table.

Parameters

NameTypeRequiredDescription
querystringnoServiceNow encoded query string
limitintegernoMaximum number of tasks to return (default: 20)

Example

local result = app.integrations.servicenow.list_tasks({
  query = "active=true^assigned_to=javascript:gs.getUserID()",
  limit = 10
})

get_task

Retrieve a single ServiceNow task by its sys_id.

Parameters

NameTypeRequiredDescription
idstringyesThe sys_id of the task

Example

local result = app.integrations.servicenow.get_task({
  id = "b5e2f1e14f3c41200bae4b8d0210c8e4"
})

create_task

Create a new ServiceNow task.

Parameters

NameTypeRequiredDescription
short_descriptionstringyesBrief summary of the task
descriptionstringnoDetailed description
assigned_tostringnosys_id of the user to assign
prioritystringnoPriority "1" through "5"

Example

local result = app.integrations.servicenow.create_task({
  short_description = "Provision new laptop for onboarding employee",
  description = "Order and configure a MacBook Pro for Jane Smith, starting March 1.",
  priority = "3"
})

list_users

List users from the ServiceNow sys_user table.

Parameters

NameTypeRequiredDescription
querystringnoServiceNow encoded query string
limitintegernoMaximum number of users to return (default: 20)

Example

-- Find active users in the IT department
local result = app.integrations.servicenow.list_users({
  query = "active=true^department=IT",
  limit = 50
})

for _, user in ipairs(result.result) do
  print(user.name .. " - " .. user.email)
end

get_user

Retrieve a single ServiceNow user by their sys_id.

Parameters

NameTypeRequiredDescription
idstringyesThe sys_id of the user

Example

local result = app.integrations.servicenow.get_user({
  id = "6816f79cc0a8016401c5a33be04be441"
})
print(result.result.name)

get_current_user

Get the profile of the currently authenticated ServiceNow user. Useful for verifying credentials.

Parameters

None.

Example

local result = app.integrations.servicenow.get_current_user()
print("Logged in as: " .. result.result.name)

Multi-Account Usage

If you have multiple ServiceNow instances configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.servicenow.list_incidents({})

-- Explicit default (portable across setups)
app.integrations.servicenow.default.list_incidents({})

-- Named accounts (e.g. production vs. development)
app.integrations.servicenow.production.list_incidents({})
app.integrations.servicenow.development.list_incidents({})

All functions are identical across accounts — only the credentials and instance differ.

Raw agent markdown 
# ServiceNow — Lua API Reference

## list_incidents

List incidents from the ServiceNow incident table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | no | ServiceNow encoded query string (e.g. `"priority=1^state=2"`) |
| `limit` | integer | no | Maximum number of incidents to return (default: 20) |

### Query Syntax

Use `^` to separate conditions. Common operators:

- `=` equals
- `!=` not equals
- `LIKE` contains
- `STARTSWITH` starts with
- `^OR` or-condition
- `^NQ` new query (AND group)

### Examples

```lua
-- List all open incidents
local result = app.integrations.servicenow.list_incidents({
  query = "active=true"
})

-- High-priority incidents
local result = app.integrations.servicenow.list_incidents({
  query = "priority=1^ORpriority=2",
  limit = 50
})
```

---

## get_incident

Retrieve a single ServiceNow incident by its sys_id.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The sys_id of the incident |

### Example

```lua
local result = app.integrations.servicenow.get_incident({
  id = "a9e4e1e14f3c41200bae4b8d0210c7d3"
})
```

---

## create_incident

Create a new ServiceNow incident.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `short_description` | string | yes | Brief summary of the incident |
| `description` | string | no | Detailed description |
| `priority` | string | no | `"1"` (critical), `"2"` (high), `"3"` (moderate), `"4"` (low), `"5"` (planning) |

### Example

```lua
local result = app.integrations.servicenow.create_incident({
  short_description = "Email server not responding",
  description = "The mail server at mail.example.com has been unreachable since 09:00 UTC.",
  priority = "1"
})
print("Created incident: " .. result.result.number)
```

---

## update_incident

Update an existing ServiceNow incident.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The sys_id of the incident |
| `fields` | object | yes | Field names and their new values |

### Common Fields

| Field | Description |
|-------|-------------|
| `state` | Incident state: `1` (new), `2` (in progress), `3` (on hold), `6` (resolved), `7` (closed) |
| `priority` | Priority 1–5 |
| `short_description` | Updated summary |
| `description` | Updated description |
| `work_notes` | Internal work notes |
| `comments` | Additional comments |
| `assigned_to` | sys_id of the assignee |

### Example

```lua
local result = app.integrations.servicenow.update_incident({
  id = "a9e4e1e14f3c41200bae4b8d0210c7d3",
  fields = {
    state = "6",
    work_notes = "Root cause identified: DNS misconfiguration. Fix applied."
  }
})
```

---

## list_tasks

List tasks from the ServiceNow task table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | no | ServiceNow encoded query string |
| `limit` | integer | no | Maximum number of tasks to return (default: 20) |

### Example

```lua
local result = app.integrations.servicenow.list_tasks({
  query = "active=true^assigned_to=javascript:gs.getUserID()",
  limit = 10
})
```

---

## get_task

Retrieve a single ServiceNow task by its sys_id.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The sys_id of the task |

### Example

```lua
local result = app.integrations.servicenow.get_task({
  id = "b5e2f1e14f3c41200bae4b8d0210c8e4"
})
```

---

## create_task

Create a new ServiceNow task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `short_description` | string | yes | Brief summary of the task |
| `description` | string | no | Detailed description |
| `assigned_to` | string | no | sys_id of the user to assign |
| `priority` | string | no | Priority `"1"` through `"5"` |

### Example

```lua
local result = app.integrations.servicenow.create_task({
  short_description = "Provision new laptop for onboarding employee",
  description = "Order and configure a MacBook Pro for Jane Smith, starting March 1.",
  priority = "3"
})
```

---

## list_users

List users from the ServiceNow sys_user table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | no | ServiceNow encoded query string |
| `limit` | integer | no | Maximum number of users to return (default: 20) |

### Example

```lua
-- Find active users in the IT department
local result = app.integrations.servicenow.list_users({
  query = "active=true^department=IT",
  limit = 50
})

for _, user in ipairs(result.result) do
  print(user.name .. " - " .. user.email)
end
```

---

## get_user

Retrieve a single ServiceNow user by their sys_id.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The sys_id of the user |

### Example

```lua
local result = app.integrations.servicenow.get_user({
  id = "6816f79cc0a8016401c5a33be04be441"
})
print(result.result.name)
```

---

## get_current_user

Get the profile of the currently authenticated ServiceNow user. Useful for verifying credentials.

### Parameters

None.

### Example

```lua
local result = app.integrations.servicenow.get_current_user()
print("Logged in as: " .. result.result.name)
```

---

## Multi-Account Usage

If you have multiple ServiceNow instances configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.servicenow.list_incidents({})

-- Explicit default (portable across setups)
app.integrations.servicenow.default.list_incidents({})

-- Named accounts (e.g. production vs. development)
app.integrations.servicenow.production.list_incidents({})
app.integrations.servicenow.development.list_incidents({})
```

All functions are identical across accounts — only the credentials and instance differ.
Metadata-derived Lua example 
local result = app.integrations.servicenow.list_incidents({query = "example_query", limit = 1})
print(result)

Functions

list_incidents Read

List incidents from the ServiceNow incident table. Supports filtering via an encoded query string (sysparm_query) and a configurable result limit.

Lua path
app.integrations.servicenow.list_incidents
Full name
servicenow.servicenow_list_incidents
ParameterTypeRequiredDescription
query string no ServiceNow encoded query string to filter results (e.g. "priority=1^state=2"). See ServiceNow query operators for syntax.
limit integer no Maximum number of incidents to return (default: 20).
get_incident Read

Retrieve a single ServiceNow incident by its sys_id. Returns the full incident record.

Lua path
app.integrations.servicenow.get_incident
Full name
servicenow.servicenow_get_incident
ParameterTypeRequiredDescription
id string yes The sys_id of the incident to retrieve.
create_incident Write

Create a new ServiceNow incident. Provide a short description, an optional full description, and a priority level.

Lua path
app.integrations.servicenow.create_incident
Full name
servicenow.servicenow_create_incident
ParameterTypeRequiredDescription
short_description string yes A brief summary of the incident.
description string no A detailed description of the incident.
priority string no Priority level: "1" (critical), "2" (high), "3" (moderate), "4" (low), "5" (planning). Defaults to the system default if omitted.
update_incident Write

Update an existing ServiceNow incident. Provide the incident sys_id and the fields to update.

Lua path
app.integrations.servicenow.update_incident
Full name
servicenow.servicenow_update_incident
ParameterTypeRequiredDescription
id string yes The sys_id of the incident to update.
fields object yes An object of field names and their new values. Common fields: state, priority, short_description, description, work_notes, comments, assigned_to.
list_tasks Read

List tasks from the ServiceNow task table. Supports filtering via an encoded query string and a configurable result limit.

Lua path
app.integrations.servicenow.list_tasks
Full name
servicenow.servicenow_list_tasks
ParameterTypeRequiredDescription
query string no ServiceNow encoded query string to filter results (e.g. "active=true^assigned_to=javascript:gs.getUserID()").
limit integer no Maximum number of tasks to return (default: 20).
get_task Read

Retrieve a single ServiceNow task by its sys_id. Returns the full task record.

Lua path
app.integrations.servicenow.get_task
Full name
servicenow.servicenow_get_task
ParameterTypeRequiredDescription
id string yes The sys_id of the task to retrieve.
create_task Write

Create a new ServiceNow task. Provide a short description and optional additional fields.

Lua path
app.integrations.servicenow.create_task
Full name
servicenow.servicenow_create_task
ParameterTypeRequiredDescription
short_description string yes A brief summary of the task.
description string no A detailed description of the task.
assigned_to string no The sys_id of the user to assign the task to.
priority string no Priority level: "1" (critical) through "5" (planning).
list_users Read

List users from the ServiceNow sys_user table. Supports filtering via an encoded query string and a configurable result limit.

Lua path
app.integrations.servicenow.list_users
Full name
servicenow.servicenow_list_users
ParameterTypeRequiredDescription
query string no ServiceNow encoded query string to filter results (e.g. "active=true^department=IT").
limit integer no Maximum number of users to return (default: 20).
get_user Read

Retrieve a single ServiceNow user by their sys_id. Returns the full user record.

Lua path
app.integrations.servicenow.get_user
Full name
servicenow.servicenow_get_user
ParameterTypeRequiredDescription
id string yes The sys_id of the user to retrieve.
get_current_user Read

Get the profile of the currently authenticated ServiceNow user. Useful for verifying credentials and retrieving the logged-in user's details.

Lua path
app.integrations.servicenow.get_current_user
Full name
servicenow.servicenow_get_current_user
ParameterTypeRequiredDescription
No parameters.