floe-servicenow 0.1.0

data/docs/cmdb.md

@@ -0,0 +1,343 @@
+# CMDB API Methods
+
+## Table of Contents
+
+| Method | Description |
+|--------|-------------|
+| [Get Configuration Item](#get-configuration-item) | Retrieve a single CI by sys_id |
+| [Query Configuration Items](#query-configuration-items) | Query multiple CIs with filtering |
+| [Create Configuration Item](#create-configuration-item) | Create a new CI |
+| [Update Configuration Item](#update-configuration-item) | Update an existing CI |
+| [Delete Configuration Item](#delete-configuration-item) | Delete a CI |
+| [Get CI Relationships](#get-ci-relationships) | Retrieve CI and its relationships |
+| [Create CI Relationship](#create-ci-relationship) | Create a relationship between two CIs |
+| [Get CI Classes](#get-ci-classes) | Retrieve available CMDB CI classes |
+
+## Get Configuration Item
+
+Retrieve a single Configuration Item (CI) by its sys_id.
+
+**Resource**: `servicenow://cmdb/get_ci`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the CI
+
+**Optional Parameters**:
+- `table` (string): CMDB table name (defaults to "cmdb_ci")
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/get_ci",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "table": "cmdb_ci_server"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "name": "web-server-01",
+    "ip_address": "192.168.1.100"
+  }
+}
+```
+
+## Query Configuration Items
+
+Query multiple Configuration Items with optional filtering.
+
+**Resource**: `servicenow://cmdb/query_cis`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `method` (string): HTTP method (typically "GET")
+
+**Optional Parameters**:
+- `table` (string): CMDB table name (defaults to "cmdb_ci")
+- `query` (string): Encoded query string
+- `limit` (integer): Maximum number of records to return
+- `offset` (integer): Starting record index for pagination
+- `fields` (string): Comma-separated list of fields to return
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/query_cis",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "method": "GET",
+    "table": "cmdb_ci_server",
+    "query": "operational_status=1",
+    "limit": 10,
+    "fields": "name,ip_address,os"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": [
+    {
+      "name": "web-server-01",
+      "ip_address": "192.168.1.100",
+      "os": "Linux"
+    }
+  ]
+}
+```
+
+## Create Configuration Item
+
+Create a new Configuration Item.
+
+**Resource**: `servicenow://cmdb/create_ci`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+
+**Optional Parameters**:
+- `table` (string): CMDB table name (defaults to "cmdb_ci")
+- Additional fields as key-value pairs for the CI
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/create_ci",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "table": "cmdb_ci_server",
+    "name": "new-server-01",
+    "ip_address": "192.168.1.200",
+    "os": "Ubuntu 20.04"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "xyz789",
+    "name": "new-server-01",
+    "ip_address": "192.168.1.200",
+    "os": "Ubuntu 20.04"
+  }
+}
+```
+
+## Update Configuration Item
+
+Update an existing Configuration Item.
+
+**Resource**: `servicenow://cmdb/update_ci`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the CI to update
+
+**Optional Parameters**:
+- `table` (string): CMDB table name (defaults to "cmdb_ci")
+- Additional fields as key-value pairs to update
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/update_ci",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "table": "cmdb_ci_server",
+    "ip_address": "192.168.1.150",
+    "operational_status": "1"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "name": "web-server-01",
+    "ip_address": "192.168.1.150",
+    "operational_status": "1"
+  }
+}
+```
+
+## Delete Configuration Item
+
+Delete a Configuration Item.
+
+**Resource**: `servicenow://cmdb/delete_ci`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the CI to delete
+
+**Optional Parameters**:
+- `table` (string): CMDB table name (defaults to "cmdb_ci")
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/delete_ci",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "table": "cmdb_ci_server"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "success": true
+  }
+}
+```
+
+## Get CI Relationships
+
+Retrieve a Configuration Item and its relationships.
+
+**Resource**: `servicenow://cmdb/get_ci_relationships`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the CI
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/get_ci_relationships",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "sys_id": "abc123def456",
+  "name": "web-server-01",
+  "relationships": [
+    {
+      "parent": "abc123def456",
+      "child": "xyz789",
+      "type": "Depends on::Used by"
+    }
+  ]
+}
+```
+
+## Create CI Relationship
+
+Create a relationship between two Configuration Items.
+
+**Resource**: `servicenow://cmdb/create_ci_relationship`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `parent_sys_id` (string): sys_id of the parent CI
+- `child_sys_id` (string): sys_id of the child CI
+- `relationship_type` (string): Type of relationship (e.g., "Depends on::Used by")
+
+**Optional Parameters**:
+- `connection_strength` (string): Strength of the connection (defaults to "1")
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/create_ci_relationship",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "parent_sys_id": "abc123",
+    "child_sys_id": "xyz789",
+    "relationship_type": "Depends on::Used by",
+    "connection_strength": "2"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "rel123",
+    "parent": "abc123",
+    "child": "xyz789",
+    "type": "Depends on::Used by",
+    "connection_strength": "2"
+  }
+}
+```
+
+## Get CI Classes
+
+Retrieve available CMDB CI classes (types).
+
+**Resource**: `servicenow://cmdb/get_ci_classes`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+
+**Optional Parameters**:
+- `limit` (integer): Maximum number of classes to return
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://cmdb/get_ci_classes",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "limit": 5
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": [
+    {
+      "name": "cmdb_ci_server",
+      "label": "Server",
+      "super_class": "cmdb_ci_computer"
+    },
+    {
+      "name": "cmdb_ci_computer",
+      "label": "Computer",
+      "super_class": "cmdb_ci_hardware"
+    }
+  ]
+}
+```

data/docs/incident.md

@@ -0,0 +1,270 @@
+# Incident API Methods
+
+## Table of Contents
+
+| Method | Description |
+|--------|-------------|
+| [Create Incident](#create-incident) | Create a new incident |
+| [Get Incident](#get-incident) | Retrieve a single incident by sys_id |
+| [Update Incident](#update-incident) | Update an existing incident |
+| [Resolve Incident](#resolve-incident) | Resolve an incident (state 6) |
+| [Close Incident](#close-incident) | Close an incident (state 7) |
+| [Query Incidents](#query-incidents) | Query multiple incidents with filtering |
+
+## Create Incident
+
+Create a new incident in ServiceNow.
+
+**Resource**: `servicenow://incident/create_incident`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `short_description` (string): Brief description of the incident
+
+**Optional Parameters**:
+- `urgency` (string): Urgency level (1=High, 2=Medium, 3=Low)
+- `impact` (string): Impact level (1=High, 2=Medium, 3=Low)
+- `priority` (string): Priority (calculated from urgency and impact)
+- `assignment_group` (string): sys_id of the assignment group
+- `assigned_to` (string): sys_id of the assigned user
+- `caller_id` (string): sys_id of the caller
+- `category` (string): Incident category
+- `subcategory` (string): Incident subcategory
+- Additional incident fields as key-value pairs
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/create_incident",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "short_description": "Network connectivity issue",
+    "urgency": "2",
+    "impact": "2",
+    "category": "Network"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123",
+    "number": "INC0010001",
+    "short_description": "Network connectivity issue",
+    "urgency": "2",
+    "impact": "2",
+    "state": "1"
+  }
+}
+```
+
+## Get Incident
+
+Retrieve a single incident by its sys_id.
+
+**Resource**: `servicenow://incident/get_incident`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the incident
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/get_incident",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "number": "INC0010001",
+    "short_description": "Network connectivity issue",
+    "state": "2",
+    "priority": "3"
+  }
+}
+```
+
+## Update Incident
+
+Update an existing incident.
+
+**Resource**: `servicenow://incident/update_incident`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the incident
+
+**Optional Parameters**:
+- Any incident field as key-value pairs to update
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/update_incident",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "state": "2",
+    "work_notes": "Investigating the issue"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "number": "INC0010001",
+    "state": "2",
+    "work_notes": "Investigating the issue"
+  }
+}
+```
+
+## Resolve Incident
+
+Resolve an incident (sets state to 6 - Resolved).
+
+**Resource**: `servicenow://incident/resolve_incident`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the incident
+
+**Optional Parameters**:
+- `close_notes` (string): Resolution notes
+- `close_code` (string): Resolution code
+- Any other incident fields to update
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/resolve_incident",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "close_notes": "Issue resolved by restarting the service",
+    "close_code": "Solved (Permanently)"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "number": "INC0010001",
+    "state": "6",
+    "close_notes": "Issue resolved by restarting the service"
+  }
+}
+```
+
+## Close Incident
+
+Close an incident (sets state to 7 - Closed).
+
+**Resource**: `servicenow://incident/close_incident`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `sys_id` (string): Unique identifier of the incident
+
+**Optional Parameters**:
+- `close_notes` (string): Closure notes
+- `close_code` (string): Closure code
+- Any other incident fields to update
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/close_incident",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "sys_id": "abc123def456",
+    "close_notes": "Incident closed after verification",
+    "close_code": "Closed/Resolved by Caller"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": {
+    "sys_id": "abc123def456",
+    "number": "INC0010001",
+    "state": "7",
+    "close_notes": "Incident closed after verification"
+  }
+}
+```
+
+## Query Incidents
+
+Query multiple incidents with optional filtering.
+
+**Resource**: `servicenow://incident/query_incidents`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+
+**Optional Parameters**:
+- `query` (string): Encoded query string (e.g., "active=true^priority=1")
+- `limit` (integer): Maximum number of records to return
+- `offset` (integer): Starting record index for pagination
+- `fields` (string): Comma-separated list of fields to return
+
+**Example**:
+
+```json
+{
+  "Resource": "servicenow://incident/query_incidents",
+  "Parameters": {
+    "instance_id": "dev12345",
+    "query": "active=true^priority=1",
+    "limit": 1,
+    "fields": "number,short_description,state,priority"
+  }
+}
+```
+
+**Response**:
+
+```json
+{
+  "result": [
+    {
+      "result": {
+        "sys_id": "abc123def456",
+        "number": "INC0010001",
+        "short_description": "Network connectivity issue",
+        "state": "2",
+        "priority": "3"
+      }
+    }
+  ]
+}
+```

data/docs/oauth.md

@@ -0,0 +1,98 @@
+# OAuth API Methods
+
+## Table of Contents
+
+| Method | Description |
+|--------|-------------|
+| [Get OAuth Token](#get-oauth-token) | Obtain OAuth access tokens using password or refresh_token grant types |
+
+## Get OAuth Token
+
+Obtain an OAuth access token using various grant types.
+
+**Resource**: `servicenow://oauth/token`
+
+**Required Parameters**:
+- `instance_id` (string): ServiceNow instance identifier
+- `grant_type` (string): OAuth grant type ("password" or "refresh_token")
+- `client_id` (string): OAuth client ID
+
+**Required Credentials** (varies by grant type):
+
+**Password Grant**:
+- `client_secret` (string): OAuth client secret
+- `username` (string): ServiceNow username
+- `password` (string): ServiceNow password
+
+**Refresh Token Grant**:
+- `client_secret` (string): OAuth client secret
+- `refresh_token` (string): Valid refresh token
+
+**Example - Password Grant**:
+
+```json
+{
+  "Resource": "servicenow://oauth/token",
+  "Credentials": {
+    "client_secret.$": "$$.Credentials.client_secret",
+    "username.$": "$$.Credentials.username",
+    "password.$": "$$.Credentials.password"
+  },
+  "Parameters": {
+    "instance_id": "dev12345",
+    "client_id": "your-client-id",
+    "grant_type": "password"
+  },
+  "ResultPath": "$$.Credentials.oauth_token"
+}
+```
+
+**Example - Refresh Token Grant**:
+
+```json
+{
+  "Resource": "servicenow://oauth/token",
+  "Credentials": {
+    "client_secret.$": "$$.Credentials.client_secret",
+    "refresh_token.$": "$$.Credentials.refresh_token"
+  },
+  "Parameters": {
+    "instance_id": "dev12345",
+    "client_id": "your-client-id",
+    "grant_type": "refresh_token"
+  },
+  "ResultPath": "$$.Credentials.oauth_token"
+}
+```
+
+**Response**:
+
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "refresh_token_value",
+  "scope": "useraccount",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+**Using the Access Token**:
+
+After obtaining an access token, use it in subsequent API calls:
+
+```json
+{
+  "Resource": "servicenow://cmdb/get_ci_classes",
+  "Credentials": {
+    "access_token.$": "$$.Credentials.oauth_token.access_token"
+  },
+  "Parameters": {
+    "instance_id": "dev12345",
+    "limit": 5
+  }
+}
+```
+
+**Complete Workflow Example**:
+- `examples/oauth.asl` - Combined OAuth flow supporting both password and refresh_token grant types with authenticated API call