ServiceNow Integration

[vivche]

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

---

Reference: [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)

---

🔄 Version Update

Updated version from 0.236.011 to 0.236.012

---

🧪 Testing

All bugs were discovered and validated during ServiceNow integration testing:

1. OpenAPI actions tested with both Basic Auth and OAuth 2.0 bearer tokens
2. Group actions tested with OAuth authentication in workspace context
3. Group agents tested with per-user semantic kernel mode enabled

---

📝 Files Changed

Documentation Added:

• 3 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

---

🎯 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

---

[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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[paullizer]

There are changes to the loader but were not massive, and I dont think they negatively affect the workflow of existing actions.

[Bionic711]

I, at this time, cannot approve this PR. The changes to the loader break the separation of duties currently implemented in the active group concepts and allow cross-contamination of group RAG data across different agents/plugins.

I advocate to remove the SKLoader changes and approve everything else.

[paullizer]

I, at this time, cannot approve this PR. The changes to the loader break the separation of duties currently implemented in the active group concepts and allow cross-contamination of group RAG data across different agents/plugins.

I advocate to remove the SKLoader changes and approve everything else.

Good catch, @vivche. if you want, lets talk about correcting the code if you think its necessary or you can proceed to remove it and test out your changes with it returned to previous state