# Jitbit External Tool — search_bookstack

## Overview

<table id="bkmrk-fieldvalue-workflow-"><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody><tr><td>Workflow ID</td><td>qLw7S1Rr0eznKDhi</td></tr><tr><td>n8n URL</td><td>[https://n8n.pbr.org.au/workflow/qLw7S1Rr0eznKDhi](https://n8n.pbr.org.au/workflow/qLw7S1Rr0eznKDhi)</td></tr><tr><td>Status</td><td>Active</td></tr><tr><td>Trigger</td><td>Webhook — called by Jitbit AI as a registered External Tool</td></tr><tr><td>Webhook URL</td><td>`https://n8n.pbr.org.au/webhook/jitbit-search-bookstack`</td></tr><tr><td>Systems</td><td>Jitbit Helpdesk (caller), BookStack (search target)</td></tr></tbody></table>

---

## Purpose

This workflow acts as a bridge between the Jitbit AI assistant and PBR's internal BookStack documentation wiki. It is registered in Jitbit as an **External Tool** named `search_bookstack`. When the Jitbit AI is answering a helpdesk ticket and determines that relevant internal documentation may exist, it automatically calls this tool, passing search keywords extracted from the ticket. The workflow queries BookStack and returns a formatted list of matching pages — titles, types, URLs, and content previews — which the AI incorporates into its response to the technician.

---

## How It Works

1. **Jitbit AI calls the webhook** via HTTP POST with a JSON body containing a `query` parameter — search keywords extracted by the AI from the ticket subject and body.
2. **Search BookStack** — the workflow calls `GET /api/search` on BookStack with the query string, requesting up to 8 results. Authentication uses the BookStack API token.
3. **Build response** — a Set node formats the results into a plain-text string. Each result includes: name, content type (page, chapter, or book), full URL, and a content preview snippet (up to 200 characters, HTML tags stripped).
4. **Respond to Jitbit** — the workflow returns a JSON response to the Jitbit AI containing the formatted `result` string and a `total_found` count.

---

## Jitbit External Tool Configuration

This workflow is registered in Jitbit under **Admin &gt; AI Features &gt; External Tools** with the following settings:

<table id="bkmrk-fieldvalue-namesearc"><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody><tr><td>Name</td><td>`search_bookstack`</td></tr><tr><td>URL</td><td>`https://n8n.pbr.org.au/webhook/jitbit-search-bookstack`</td></tr><tr><td>Description</td><td>Search PBR's internal IT documentation wiki (BookStack) for relevant articles, configuration guides, troubleshooting procedures, and technical documentation. Use this when a ticket involves a known system, technology, or procedure that may be documented internally.</td></tr></tbody></table>

### Parameters

<table id="bkmrk-namedescriptionrequi"><thead><tr><th>Name</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>`query`</td><td>Search terms extracted from the ticket — keywords describing the system or issue (e.g. "Proxmox iSCSI timeout" or "PA-440 IPsec VPN")</td><td>Yes</td></tr></tbody></table>

---

## Response Format

The workflow returns a JSON object to the Jitbit AI:

```json
{
  "result": "Page Title (page): https://bookstack.pbr.org.au/books/book-slug/page/page-slug
  Preview: content snippet...

Another Page (book): https://...",
  "total_found": 29
}
```

The `result` field is a formatted plain-text string the AI can read directly. `total_found` is the total number of matching results in BookStack (not just the 8 returned).

---

## Nodes

<table id="bkmrk-nodetypepurpose-rece"><thead><tr><th>Node</th><th>Type</th><th>Purpose</th></tr></thead><tbody><tr><td>Receive from Jitbit AI</td><td>Webhook (POST, responseMode: responseNode)</td><td>Entry point — receives the search query from Jitbit AI</td></tr><tr><td>Search BookStack</td><td>HTTP Request (GET)</td><td>Calls `https://bookstack.pbr.org.au/api/search` with the query and count=8</td></tr><tr><td>Build Jitbit Response</td><td>Set</td><td>Formats the BookStack results array into a plain-text string; strips HTML tags from preview\_html.content; falls back to "No preview available" if content is empty</td></tr><tr><td>Respond to Jitbit</td><td>Respond to Webhook</td><td>Returns the JSON result to the Jitbit AI caller</td></tr></tbody></table>

---

## Credentials

<table id="bkmrk-credentialtypeused-f"><thead><tr><th>Credential</th><th>Type</th><th>Used For</th></tr></thead><tbody><tr><td>BookStack Token</td><td>HTTP Header Auth (`Authorization: Token id:secret`)</td><td>BookStack search API</td></tr></tbody></table>

---

## Maintenance Notes

- The BookStack API token is stored as an HTTP Header Auth credential in n8n. Regenerate it at `https://bookstack.pbr.org.au` under the Claude\_AI user profile if access is revoked.
- The result count is capped at 8 to keep AI responses focused. This can be adjusted in the Search BookStack node query parameter `count` if broader results are needed.
- BookStack search uses keyword matching. If searches return poor results, the issue is likely in the quality of keywords the Jitbit AI is passing — this is controlled by Jitbit's AI system prompt, not this workflow.
- Books and chapters without page-level content return "No preview available" in the result — this is expected behaviour, as BookStack only generates preview snippets for pages.