ServiceNow Integration #640

vivche · 2026-01-24T00:25:47Z

ServiceNow Integration Documentation and Bug Fixes

Overview

This PR adds comprehensive documentation for integrating ServiceNow with Simple Chat and fixes four critical bugs that were discovered during the ServiceNow integration testing. The bugs affect OpenAPI actions, group actions, group agents, and Azure AI Search connection testing.

📚 ServiceNow Integration Documentation

What's New

Complete ServiceNow Integration Guide

Comprehensive step-by-step integration guide covering both Basic Authentication and OAuth 2.0
Detailed OAuth 2.0 setup documentation with production security considerations
Agent behavioral instructions optimized for ServiceNow operations
7 OpenAPI specifications for ServiceNow Incident Management and Knowledge Base APIs

Documentation Files:

docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md - Main integration guide (760 lines)
docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md - OAuth 2.0 setup guide (480+ lines)
docs/how-to/agents/ServiceNow/servicenow_agent_instructions.txt - Agent instructions (263 lines)
docs/how-to/agents/ServiceNow/open_api_specs/ - 7 OpenAPI YAML files (both bearer token and basic auth versions)

Key Features:

OAuth 2.0 Resource Owner Password Credential grant type setup with security considerations
Basic Authentication setup for testing environments
Integration user creation and role assignment guidance
Token management and refresh strategies
Troubleshooting guide
Production deployment considerations

🐛 Bug Fixes

1. OpenAPI Basic Authentication Fix

Issue Behavior:
OpenAPI actions configured with Basic Authentication failed with "session not authenticated" error, even when credentials were correct. The agent would report inability to access the API despite the credentials being stored successfully.

Root Cause:
Mismatch between how the UI stored Basic Auth credentials (as username:password string in auth.key) and how the OpenAPI plugin factory expected them (as separate username and password properties in additionalFields).

Files Modified:

application/single_app/semantic_kernel_plugins/openapi_plugin_factory.py

Reference: OPENAPI_BASIC_AUTH_FIX.md

2. Group Action OAuth Schema Merging Fix

Issue Behavior:
Group actions with OAuth bearer token authentication failed with HTTP 401 Unauthorized errors. When editing a group action, the additionalFields property was empty ({}), missing all authentication configuration fields that were present in working global actions.

Root Cause:
Group action backend routes (route_backend_plugins.py) did not call get_merged_plugin_settings() to merge UI form data with OpenAPI schema defaults, while global action routes did. This caused group actions to be saved without authentication configuration fields like auth_method, base_url, and authentication credentials.

Files Modified:

application/single_app/route_backend_plugins.py

Reference: GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md

3. Group Agent Loading Fix

Issue Behavior:
Group agents were not appearing in the agent list when per-user semantic kernel mode was enabled. When users selected a group agent, it would fall back to the global "researcher" agent with zero plugins/actions available. Group agents would ask clarifying questions instead of executing available ServiceNow actions.

Root Cause:
The load_user_semantic_kernel() function only loaded personal agents and global agents (when merge enabled), but completely omitted group agents from groups the user is a member of. The function did not fetch or load group agents despite the user having valid group memberships.

Files Modified:

application/single_app/semantic_kernel_loader.py

Reference: GROUP_AGENT_LOADING_FIX.md

4. Azure AI Search Test Connection Fix

Issue Behavior:
When clicking "Test Azure AI Search Connection" button on the App Settings "Search & Extract" page with managed identity authentication enabled, the test failed with NameError: name 'search_resource_manager' is not defined. Even when the variable was defined, bearer token authentication didn't work with Azure AI Search.

Root Cause:
The old implementation used a REST API approach with manually acquired bearer tokens, which is fundamentally incompatible with how Azure AI Search handles managed identity authentication on the data plane. Azure AI Search requires SDK-specific authentication handling and rejects bearer tokens acquired through standard DefaultAzureCredential.get_token() flows.

Files Modified:

application/single_app/route_backend_settings.py

Reference: [AZURE_AI_SEARCH_TEST_CONNECTION_FIX.md](https://github.com/user-attachments/files/24832462/AZURE_AI_SEARCH_TEST_CONNECTION_FIX.md) [GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md](https://github.com/user-attachments/files/24832463/GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md) [GROUP_AGENT_LOADING_FIX.md](https://github.com/user-attachments/files/24832464/GROUP_AGENT_LOADING_FIX.md) [OPENAPI_BASIC_AUTH_FIX.md](https://github.com/user-attachments/files/24832465/OPENAPI_BASIC_AUTH_FIX.md) AZURE_AI_SEARCH_TEST_CONNECTION_FIX.md

📊 Impact Summary

ServiceNow Integration

✅ Complete documentation for enterprise ServiceNow integration
✅ Support for both OAuth 2.0 (production) and Basic Auth (testing)
✅ Reusable OpenAPI specifications for Incident Management and Knowledge Base
✅ Production-ready agent instructions with best practices

Bug Fixes

✅ OpenAPI Basic Auth: Enables basic authentication for OpenAPI actions (critical for testing)
✅ Group Action OAuth: Fixes OAuth authentication for all group actions (high severity)
✅ Group Agent Loading: Enables group agents in per-user kernel mode (high severity)
✅ AI Search Test: Fixes managed identity authentication testing (medium severity)

🔄 Version Update

Updated version from 0.236.011 to 0.236.012

🧪 Testing

All bugs were discovered and validated during ServiceNow integration testing:

OpenAPI actions tested with both Basic Auth and OAuth 2.0 bearer tokens
Group actions tested with OAuth authentication in workspace context
Group agents tested with per-user semantic kernel mode enabled
Azure AI Search connection tested with managed identity authentication

📝 Files Changed

Documentation Added:

4 bug fix documentation files (docs/fixes/)
3 ServiceNow integration documentation files
7 OpenAPI specification files
1 agent instructions file

Code Modified:

config.py - Version update
openapi_plugin_factory.py - Basic auth credential parsing fix
route_backend_plugins.py - Schema merging for group actions
semantic_kernel_loader.py - Group agent loading in per-user mode
route_backend_settings.py - AI Search test connection with managed identity

🎯 Related Issues

These fixes were discovered during ServiceNow integration work and are critical for:

Enterprise integrations requiring OAuth authentication
Multi-tenant deployments using group workspaces
Managed identity authentication scenarios
OpenAPI-based integrations with basic authentication

- Added custom_subdomain_name to OpenAI resource for managed identity authentication - Created Speech Service resource with custom subdomain configuration - Added RBAC role assignments for Speech Service (Managed Identity and App Service MI) - Includes Cognitive Services Speech User and Speech Contributor roles - Documentation: Azure Speech managed identity setup guide

…velopment into Development

- Add comprehensive ServiceNow integration guide with OAuth 2.0 setup - Include OpenAPI specifications for Incident Management and Knowledge Base APIs - Add agent instructions for ServiceNow support agent - Fix GROUP_ACTION_OAUTH_SCHEMA_MERGING: Ensure additionalFields preserved during schema merge - Fix GROUP_AGENT_LOADING: Improve group agent loading reliability - Fix OPENAPI_BASIC_AUTH: Support basic authentication in OpenAPI actions - Fix AZURE_AI_SEARCH_TEST_CONNECTION: Improve AI Search connection testing - Update version to 0.236.012

Copilot

Pull request overview

This PR adds comprehensive ServiceNow integration documentation and implements four critical bug fixes discovered during ServiceNow integration testing. The changes enable enterprise integrations with ServiceNow for incident management and knowledge base operations while fixing issues affecting OpenAPI authentication, group workspace functionality, and Azure AI Search connectivity testing.

Changes:

Comprehensive ServiceNow integration documentation including OAuth 2.0 setup guide, agent behavioral instructions, and 7 OpenAPI specifications
Fix for OpenAPI Basic Authentication credential parsing to support username:password format
Fix for group action OAuth authentication by adding schema merging (parity with global actions)
Fix for group agent loading in per-user semantic kernel mode to include all workspace agents
Fix for Azure AI Search connection testing with managed identity authentication using SDK instead of REST API
Infrastructure updates for Azure Speech Service with managed identity support and custom subdomain configuration

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/how-to/azure_speech_managed_identity_manul_setup.md	New documentation explaining Azure Speech Service managed identity setup requirements (filename has typo)
docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md	Comprehensive ServiceNow integration guide covering setup, configuration, and testing
docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md	Detailed OAuth 2.0 configuration guide for production ServiceNow deployments
docs/how-to/agents/ServiceNow/servicenow_agent_instructions.txt	Agent behavioral instructions optimized for ServiceNow operations
docs/how-to/agents/ServiceNow/open_api_specs/*.yaml	Seven OpenAPI specification files for ServiceNow APIs (bearer token and basic auth versions)
application/single_app/semantic_kernel_plugins/openapi_plugin_factory.py	Adds credential format transformation for basic auth, bearer tokens, and OAuth2
application/single_app/semantic_kernel_loader.py	Adds group agent and action loading for per-user semantic kernel mode
application/single_app/route_backend_settings.py	Replaces REST API approach with SDK-based Azure AI Search connection testing
application/single_app/route_backend_plugins.py	Adds schema merging to group action routes for OAuth field population
deployers/terraform/main.tf	Adds Speech Service resource with custom subdomain and RBAC role assignments
application/single_app/static/images/custom_logo.png	Updated custom logo image (binary file)
application/single_app/static/images/custom_logo_dark.png	Updated dark theme custom logo image (binary file)
application/single_app/config.py	Version bump from 0.236.011 to 0.236.012

docs/how-to/agents/ServiceNow/servicenow_agent_instructions.txt

docs/how-to/agents/ServiceNow/open_api_specs/sample_servicenow_incident_api.yaml

docs/how-to/azure_speech_managed_identity_manul_setup.md

application/single_app/semantic_kernel_plugins/openapi_plugin_factory.py

application/single_app/config.py

docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md

application/single_app/route_backend_settings.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…_incident_api.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md

docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md

docs/how-to/azure_speech_managed_identity_manul_setup.md

docs/how-to/agents/ServiceNow/servicenow_agent_instructions.txt

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…factory.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

….012

…mplechat-development into servicenow-integration

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

application/single_app/semantic_kernel_loader.py

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

docs/how-to/azure_speech_managed_identity_manul_setup.md

docs/explanation/fixes/v0.236.012/OPENAPI_BASIC_AUTH_FIX.md

docs/how-to/azure_speech_managed_identity_manul_setup.md

application/single_app/semantic_kernel_loader.py

- Changed 'indexes = list(...)' to '_ = list(...)' - Follows Python convention for discarded return values - AI Search connection test only needs to verify the API call succeeds

…nrelated to this servicenow integration

- OPENAPI_BASIC_AUTH_FIX.md: 0.235.026 → 0.236.012 - GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md: 0.235.028 → 0.236.012 - GROUP_AGENT_LOADING_FIX.md: 0.235.027 → 0.236.012 - AZURE_AI_SEARCH_TEST_CONNECTION_FIX.md: 0.235.004 → 0.236.012"

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 9 comments.

docs/explanation/fixes/v0.236.012/OPENAPI_BASIC_AUTH_FIX.md

docs/explanation/fixes/v0.236.012/AZURE_AI_SEARCH_TEST_CONNECTION_FIX.md

docs/how-to/agents/ServiceNow/open_api_specs/sample_now_knowledge_latest_spec.yaml

application/single_app/semantic_kernel_plugins/openapi_plugin_factory.py

docs/explanation/fixes/v0.236.012/GROUP_AGENT_LOADING_FIX.md

docs/explanation/fixes/v0.236.012/GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md

docs/how-to/agents/ServiceNow/open_api_specs/sample_servicenow_incident_api_basicauth.yaml

docs/how-to/agents/ServiceNow/open_api_specs/sample_now_knowledge_latest_spec_basicauth.yaml

docs/how-to/agents/ServiceNow/SERVICENOW_INTEGRATION.md

…dge_latest_spec.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…ION_FIX.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…dge_latest_spec_basicauth.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…_incident_api_basicauth.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

…mplechat-development into servicenow-integration

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Copilot · 2026-01-24T02:16:00Z

application/single_app/semantic_kernel_plugins/openapi_plugin_factory.py

+        # For bearer tokens stored as 'key' type
+        if auth_type == 'key' and auth_method == 'bearer':
+            token = auth_config.get('key', '')
+            debug_print(f"[Factory] Applying basic auth transformation")


The debug message on line 164 says "Applying basic auth transformation" but this is actually for bearer token authentication. This should say "Applying bearer auth transformation" to match the context.

Suggested change

debug_print(f"[Factory] Applying basic auth transformation")

debug_print(f"[Factory] Applying bearer auth transformation")

Copilot · 2026-01-24T02:16:01Z

docs/explanation/fixes/v0.236.012/GROUP_AGENT_LOADING_FIX.md

+   - Removed redundant single-agent loading logic
+
+2. **`config.py`** (Line 91)
+   - Updated VERSION from "0.235.026" to "0.235.027"


The "Files Modified" section states "Updated VERSION from '0.235.026' to '0.235.027'", but the actual change in this PR updates VERSION from "0.236.011" to "0.236.012". While the header correctly indicates this fix is implemented in version 0.236.012, the "Files Modified" section contains outdated version information that may confuse readers. Consider either removing the specific version numbers from the "Files Modified" section or updating them to reflect the actual change (0.236.011 → 0.236.012).

Suggested change

- Updated VERSION from "0.235.026" to "0.235.027"

- Updated VERSION from "0.236.011" to "0.236.012"

Copilot · 2026-01-24T02:16:01Z

docs/explanation/fixes/v0.236.012/GROUP_ACTION_OAUTH_SCHEMA_MERGING_FIX.md

+   - **Parity achieved:** Both global and group routes now call `get_merged_plugin_settings()`
+
+2. **`config.py`**
+   - Updated VERSION from "0.235.027" to "0.235.028"


The "Files Modified" section states "Updated VERSION from '0.235.027' to '0.235.028'", but the actual change in this PR updates VERSION from "0.236.011" to "0.236.012". While the header correctly indicates this fix is implemented in version 0.236.012, the "Files Modified" section contains outdated version information that may confuse readers. Consider either removing the specific version numbers from the "Files Modified" section or updating them to reflect the actual change (0.236.011 → 0.236.012).

Suggested change

- Updated VERSION from "0.235.027" to "0.235.028"

- Updated VERSION from "0.236.011" to "0.236.012"

Copilot · 2026-01-24T02:16:01Z

docs/how-to/agents/ServiceNow/SERVICENOW_OAUTH_SETUP.md

+   - URL: `https://devnnnnnn.service-now.com`
+
+2. **Navigate to OAuth Application Registry:**
+2. **Navigate to OAuth Application Registry:**


Lines 74 and 75 are duplicate. The instruction "Navigate to OAuth Application Registry:" appears twice consecutively.

Suggested change

2. **Navigate to OAuth Application Registry:**

Chen, Vivien added 6 commits January 2, 2026 10:42

Merge branch 'Development' of https://github.com/vivche/simplechat-de…

be56540

…velopment into Development

Merge remote-tracking branch 'upstream/Development' into Development

e13ba0c

Removed the readme files for bug fix details

502355f

Updated servicenow integration readme

33bee68

Copilot AI review requested due to automatic review settings January 24, 2026 00:25

Copilot started reviewing on behalf of vivche January 24, 2026 00:26 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

Chen, Vivien added 2 commits January 23, 2026 19:46

chore: Revert custom logo changes to upstream version

cd8c520

chore: Revert terraform main.tf to upstream version

fb8181b

Copilot AI review requested due to automatic review settings January 24, 2026 00:52

Copilot started reviewing on behalf of vivche January 24, 2026 00:53 View session

Chen, Vivien and others added 3 commits January 23, 2026 19:57

Removed the two openai sample spec downloaed from servicennow site

660d76c

Update docs/how-to/agents/ServiceNow/servicenow_agent_instructions.txt

de866eb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/how-to/agents/ServiceNow/open_api_specs/sample_servicenow…

20f994a

…_incident_api.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jan 24, 2026

View reviewed changes

Update docs/how-to/azure_speech_managed_identity_manul_setup.md

351f143

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 24, 2026 01:01

Copilot started reviewing on behalf of vivche January 24, 2026 01:01 View session

vivche and others added 3 commits January 23, 2026 20:01

Update application/single_app/semantic_kernel_plugins/openapi_plugin_…

5fe5b14

…factory.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Checked in the bug fix detail readme to docs/explanation/fixes/v0.236…

9626219

….012

Merge branch 'servicenow-integration' of https://github.com/vivche/si…

6364827

…mplechat-development into servicenow-integration

Copilot AI reviewed Jan 24, 2026

View reviewed changes

application/single_app/semantic_kernel_loader.py Outdated Show resolved Hide resolved

Chen, Vivien added 2 commits January 23, 2026 20:17

Added version number to the feature readme files

dce54a1

Added version number to document, and removed redudant import statement

8353d77

Copilot AI review requested due to automatic review settings January 24, 2026 01:29

Copilot started reviewing on behalf of vivche January 24, 2026 01:29 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

refactor: use _ for intentionally unused variable in AI Search test

5aa7007

- Changed 'indexes = list(...)' to '_ = list(...)' - Follows Python convention for discarded return values - AI Search connection test only needs to verify the API call succeeds

Removed azure_speech_managed_indeity_manual readme file since it is u…

548d8d8

…nrelated to this servicenow integration

Copilot AI review requested due to automatic review settings January 24, 2026 01:45

Copilot started reviewing on behalf of vivche January 24, 2026 01:45 View session

Chen, Vivien and others added 2 commits January 23, 2026 20:52

Update application/single_app/semantic_kernel_loader.py

b0be501

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jan 24, 2026

View reviewed changes

Update docs/how-to/agents/ServiceNow/open_api_specs/sample_now_knowle…

e264a13

…dge_latest_spec.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 24, 2026 01:55

Copilot started reviewing on behalf of vivche January 24, 2026 01:55 View session

vivche and others added 4 commits January 23, 2026 20:55

Update docs/explanation/fixes/v0.236.012/AZURE_AI_SEARCH_TEST_CONNECT…

b04bd67

…ION_FIX.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/how-to/agents/ServiceNow/open_api_specs/sample_now_knowle…

84c01e9

…dge_latest_spec_basicauth.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/how-to/agents/ServiceNow/open_api_specs/sample_servicenow…

c8e383e

…_incident_api_basicauth.yaml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/explanation/fixes/v0.236.012/GROUP_AGENT_LOADING_FIX.md

39dc7a4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jan 24, 2026

View reviewed changes

Chen, Vivien added 3 commits January 23, 2026 20:59

Remvoed debug statements that might include senstive info

2e8c737

Merge branch 'servicenow-integration' of https://github.com/vivche/si…

d0581d5

…mplechat-development into servicenow-integration

Updated version number in the feature document

2bb45d7

Copilot AI review requested due to automatic review settings January 24, 2026 02:06

Copilot started reviewing on behalf of vivche January 24, 2026 02:06 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

	debug_print(f"[Factory] Applying basic auth transformation")
	debug_print(f"[Factory] Applying bearer auth transformation")

	- Updated VERSION from "0.235.026" to "0.235.027"
	- Updated VERSION from "0.236.011" to "0.236.012"

	- Updated VERSION from "0.235.027" to "0.235.028"
	- Updated VERSION from "0.236.011" to "0.236.012"

ServiceNow Integration #640

Are you sure you want to change the base?

ServiceNow Integration #640

Uh oh!

Conversation

vivche commented Jan 24, 2026

ServiceNow Integration Documentation and Bug Fixes

Overview

📚 ServiceNow Integration Documentation

What's New

🐛 Bug Fixes

1. OpenAPI Basic Authentication Fix

2. Group Action OAuth Schema Merging Fix

3. Group Agent Loading Fix

4. Azure AI Search Test Connection Fix

📊 Impact Summary

ServiceNow Integration

Bug Fixes

🔄 Version Update

🧪 Testing

📝 Files Changed

🎯 Related Issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 24, 2026