Load ServiceNow Knowledge Base Articles

ServiceNow Knowledge Base Loader

pip install llama-index-readers-service-now

This loader reads Knowledge Base articles from a ServiceNow instance. The user needs to specify the ServiceNow instance URL and authentication credentials to initialize the SnowKBReader.

The loader uses the pysnc library to connect to ServiceNow and retrieve knowledge base articles. It supports authentication via username/password (basic auth) or with OAuth2 client credentials (password grant flow).

Important: This reader requires custom parsers for processing different file types. At minimum, an HTML parser must be provided for processing article bodies.

Authentication

The reader requires the following authentication parameters:

Required:

• instance: Your ServiceNow instance name (e.g., "dev12345" - without .service-now.com)
• username: ServiceNow username
• password: ServiceNow password
• custom_parsers: Dictionary mapping FileType enum values to BaseReader instances (REQUIRED)

Optional (for OAuth2 password grant flow):

• client_id: OAuth2 client ID (if provided, client_secret is also required)
• client_secret: OAuth2 client secret (if provided, client_id is also required)

If OAuth2 parameters are not provided, the reader will use basic authentication with username/password.

Event System

The ServiceNow Knowledge Base reader uses LlamaIndex's standard instrumentation event system to provide detailed tracking of the loading process. Events are fired at various stages during knowledge base article retrieval and attachment processing.

Available Events

• SNOWKBTotalPagesEvent: Fired when the total number of pages to process is determined
• SNOWKBPageFetchStartEvent: Fired when page data fetch starts
• SNOWKBPageFetchCompletedEvent: Fired when page data fetch completes successfully
• SNOWKBPageSkippedEvent: Fired when a page is skipped
• SNOWKBPageFailedEvent: Fired when page processing fails
• SNOWKBAttachmentProcessingStartEvent: Fired when attachment processing starts
• SNOWKBAttachmentProcessedEvent: Fired when attachment processing completes successfully
• SNOWKBAttachmentSkippedEvent: Fired when an attachment is skipped
• SNOWKBAttachmentFailedEvent: Fired when attachment processing fails

All events inherit from LlamaIndex's BaseEvent class and can be monitored using the standard LlamaIndex instrumentation dispatcher.

Features

• Load knowledge base articles by sys_id or KB numbers
• Automatically download and process attachments
• Requires custom parsers for different file types (HTML parser is mandatory)
• LlamaIndex event-driven architecture for monitoring processing
• Configurable knowledge base table (defaults to kb_knowledge)
• Support for filtering by workflow state (defaults to "Published")
• Configurable temporary folder for file processing

Required Custom Parsers

The reader requires custom parsers to process different file types. At minimum, an HTML parser must be provided for processing article bodies.

Important: The ServiceNow reader does not include built-in parsers. You must define your own custom parser classes that inherit from BaseReader and implement the load_data method.

Example Custom Parser Implementation

from llama_index.core.readers.base import BaseReader
from llama_index.core.schema import Document
from markitdown import MarkItDown
from typing import List, Union
import pathlib


class DocxParser(BaseReader):
    """DOCX parser using MarkItDown for text extraction."""

    def __init__(self):
        self.markitdown = MarkItDown()

    def load_data(
        self, file_path: Union[str, pathlib.Path], **kwargs
    ) -> List[Document]:
        """Load and parse a DOCX file."""
        result = self.markitdown.convert(source=file_path)

        return [
            Document(
                text=result.markdown, metadata={"file_path": str(file_path)}
            )
        ]


class HTMLParser(BaseReade