BookStack

Overview

This node integrates with the BookStack API, allowing users to manage BookStack resources such as books, pages, chapters, shelves, users, roles, attachments, and tags. It supports common operations like creating, retrieving (single or multiple), updating, and deleting these resources.

A key feature is the option to either manually specify the resource and operation or describe the desired action in natural language. When using the automatic mode, the node attempts to parse the description to determine the appropriate resource and operation, simplifying interaction for users unfamiliar with the API details.

Typical use cases include:

• Automatically fetching a specific book or page by ID.
• Creating new pages or books based on descriptive input.
• Listing all chapters in a book.
• Updating or deleting resources by specifying their IDs.

For example, a user could input "Create a new page about API documentation" in automatic mode, and the node will create a page with that title and some default content.

Properties

Additional properties relevant for manual mode and certain operations (not requested but present):

• Resource: Select the type of resource (Book, Page, Chapter, Shelf, User, Role, Attachment, Tag).
• Operation: Select the action to perform (Create, Delete, Get, Get Many, Update).
• Name: Name of the resource (required for Create and Update on some resources).
• Description: Description of the resource (for Book and Shelf).
• HTML Content: HTML content of a page (for Page resource).
• Book ID: ID of the book a page or chapter belongs to (required for creating pages/chapters).
• Chapter ID: ID of the chapter a page belongs to (optional).

Output

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

• json: The JSON response from the BookStack API for the requested operation. This includes the full data of the resource retrieved, created, updated, or confirmation of deletion.
• pairedItem: Metadata linking the output to the input item index.

If an error occurs and "Continue On Fail" is enabled, the output JSON will contain an error field with the error message.

The node does not output binary data.

Dependencies

• Requires connection credentials for the BookStack API, including:

  • Base URL of the BookStack instance.
  • An API token and secret for authentication.

• The node uses HTTP requests authenticated via these credentials to interact with the BookStack REST API.

• Pagination support is implemented for listing multiple resources, using offset-based pagination with configurable limits.

Troubleshooting

• Common Issues:

  • Incorrect or missing resource ID for Get, Update, or Delete operations will cause errors.
  • Invalid or expired API tokens will result in authentication failures.
  • Improperly formatted request descriptions in automatic mode may lead to incorrect resource or operation detection.
  • Network connectivity issues to the BookStack server.

• Error Messages:

  • Errors returned from the BookStack API are passed through; typical messages include "Resource not found", "Unauthorized", or validation errors.
  • If the node fails to detect resource or operation automatically, it defaults to getting all books, which might not be the intended behavior.

• Resolutions:

  • Verify that the correct ID is provided when required.
  • Ensure API credentials are valid and have sufficient permissions.
  • Use manual mode if automatic detection does not work reliably.
  • Check network access to the BookStack server.

Links and References

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