BookStackInstall

Overview

This node integrates with the BookStack API, enabling users to manage BookStack resources such as books, pages, chapters, shelves, users, roles, attachments, and tags. It supports a variety of operations including creating, updating, deleting, copying, moving, retrieving single or multiple resources, and exporting content.

The node offers two modes for specifying actions:

• Automatic mode: Users provide a natural language description of their request (e.g., "Move the chapter 'Introduction' to 'Getting Started'"), and the node attempts to parse and determine the appropriate resource and operation.
• Manual mode: Users explicitly select the resource and operation from dropdowns and provide required parameters.

Practical examples

• Automatically create a new book by describing it: "Create a new book about API documentation".
• Move a chapter to another book by describing: "Move the chapter 'Introduction' to 'Getting Started'".
• Manually delete a page by selecting resource "Page", operation "Delete", and providing the page ID.
• Retrieve all shelves or list all books.
• Copy an existing book or chapter to another shelf or book.

This flexibility makes the node useful for automating content management workflows in BookStack, especially when combined with natural language descriptions for quick task execution.

Properties

Name	Meaning
Tool Description	Choose how to determine the resource and operation: - Set Automatically: Provide a natural language request description; the node will parse and decide the resource and operation. - Set Manually: Select resource and operation explicitly.
Request Description	(Shown only if Tool Description is "Set Automatically") A text field where you describe what you want to do, e.g., "Create a new page about API documentation". The system uses this to infer the resource and operation.

Note: When "Set Manually" is selected, additional properties appear to specify:

• Resource (Book, Page, Chapter, Shelf, User, Role, Attachment, Tag)
• Operation (Create, Delete, Get, Get Many, Update, Copy, Move)
• Other fields depending on the resource and operation, such as:
  • ID (for get, update, delete)
  • Name (for create, update)
  • Description (for create, update on some resources)
  • HTML Content (for pages)
  • Book ID, Chapter ID (for pages and chapters)

Output

The node outputs an array of JSON objects corresponding to each input item processed. Each output item contains:

• json: The parsed JSON response from the BookStack API for the requested operation.
• If an error occurs and "Continue On Fail" is enabled, the output includes an error field with the error message.

The structure of the JSON depends on the specific resource and operation invoked, typically reflecting the BookStack API's response format for that endpoint.

The node does not output binary data.

Dependencies

• Requires connection to a BookStack instance via its API.
• Needs credentials containing:
  • Base URL of the BookStack API.
  • An API token and secret for authentication.
• The node uses HTTP requests authenticated with these credentials.
• No other external dependencies are required.

Troubleshooting

Common issues

• Invalid or missing credentials: Ensure the API base URL and tokens are correctly configured.
• Incorrect resource or operation selection: In manual mode, selecting incompatible resource-operation pairs or missing required parameters (like ID) will cause errors.
• Parsing failures in automatic mode: The natural language parser may fail to detect the intended operation/resource if the description is ambiguous or outside supported patterns.
• API errors: Errors returned by the BookStack API (e.g., resource not found, permission denied) will be surfaced in the node output.

Error messages and resolutions

• "Missing required parameter": Check that all mandatory fields (e.g., ID for delete/get/update) are provided.
• "Authentication failed": Verify API token and secret correctness.
• "Resource not found": Confirm the resource ID exists in BookStack.
• Parsing-related logs prefixed with [BookStack Debug] can help diagnose automatic mode detection issues.

Enabling "Continue On Fail" allows processing to continue even if some items fail, returning error details per item.

Links and References

• BookStack Official Documentation
• BookStack API Reference
• n8n Documentation on Creating Custom Nodes