KosmoKrator

itsm

ServiceNow Lua API for KosmoKrator Agents

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

10 functions 7 read 3 write Username and password auth
Submit ServiceNow feedback View package source

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.

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.servicenow_list_incidents({
  query = "example_query",
  limit = 1
})
print(result)

Functions

servicenow_list_incidents

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

Operation
Read read
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).

servicenow_get_incident

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

Operation
Read read
Full name
servicenow.servicenow_get_incident
ParameterTypeRequiredDescription
id string yes The sys_id of the incident to retrieve.

servicenow_create_incident

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

Operation
Write write
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.

servicenow_update_incident

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

Operation
Write write
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.

servicenow_list_tasks

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

Operation
Read read
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).

servicenow_get_task

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

Operation
Read read
Full name
servicenow.servicenow_get_task
ParameterTypeRequiredDescription
id string yes The sys_id of the task to retrieve.

servicenow_create_task

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

Operation
Write write
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).

servicenow_list_users

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

Operation
Read read
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).

servicenow_get_user

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

Operation
Read read
Full name
servicenow.servicenow_get_user
ParameterTypeRequiredDescription
id string yes The sys_id of the user to retrieve.

servicenow_get_current_user

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

Operation
Read read
Full name
servicenow.servicenow_get_current_user
ParameterTypeRequiredDescription
No parameters.