BookStack icon

BookStack

Consume BookStack API
Join our community

Actions56

Overview

This node integrates with the BookStack API to manage book-related resources such as books, pages, chapters, and shelves. It supports creating, updating, deleting, copying, moving, retrieving single or multiple resources, and exporting content. The node can operate in two modes:

  • Automatic mode: Users provide a natural language description of their request (e.g., "Create a new page about API documentation"), and the node attempts to parse and determine the appropriate resource and operation automatically.
  • Manual mode: Users explicitly select the resource type (e.g., Book) and operation (e.g., Create) and provide the necessary parameters.

Use cases:

  • Automatically creating a new book or page by describing it in plain text.
  • Manually creating or updating books, pages, chapters, or shelves with specific names and descriptions.
  • Retrieving or deleting existing resources by ID.
  • Copying or moving resources between shelves or books.
  • Exporting book content in various formats.

This node is beneficial for automating content management workflows in BookStack, especially when integrating with other systems or enabling non-technical users to interact via natural language.

Properties

Name Meaning
Tool Description Choose how to determine the resource and operation:
- Set Automatically
- Set Manually
Request Description (Shown if Tool Description = Automatic)
Describe your request in natural language (e.g., "Create a new page about API documentation"). The system will parse this to select resource and operation automatically.
Resource (Shown if Tool Description = Manual)
Select the resource type:
- Book
- Page
- Chapter
- Shelf
- User
- Role
- Attachment
- Tag
Operation (Shown if Tool Description = Manual)
Select the operation:
- Create
- Delete
- Get
- Get Many
- Update
- Copy
- Move
ID (Required for Get, Update, Delete operations)
The ID of the resource
Name (Required for Create and Update on Book, Page, Chapter, Shelf)
The name of the resource
Description (Optional for Create and Update on Book, Shelf)
The description of the resource
HTML Content (For Create and Update on Page)
The HTML content of the page
Book ID (Required for Create on Page, Chapter)
The ID of the book this resource belongs to
Chapter ID (Optional for Create on Page)
The ID of the chapter this page belongs to

Output

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

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

If the operation involves binary data (e.g., exporting content), the node handles it accordingly, but this is not detailed in the provided code.

Dependencies

  • Requires connection credentials to the BookStack API, including:
    • Base URL of the BookStack instance.
    • An API token and secret for authentication.
  • The node uses HTTP requests authenticated with these credentials.
  • No additional external dependencies are required beyond the BookStack API access.

Troubleshooting

Common Issues

  • Incorrect or missing credentials: The node requires valid API tokens and base URL; invalid credentials will cause authentication failures.
  • Invalid resource IDs: Operations requiring an ID (Get, Update, Delete) must have a valid resource ID; otherwise, the API will return errors.
  • Malformed natural language requests: In automatic mode, ambiguous or unsupported request descriptions may lead to incorrect resource or operation detection.
  • Missing required fields: For example, creating a book requires a name; omitting required properties will cause validation errors.

Error Messages and Resolutions

  • Authentication errors: Check that the API token and base URL are correctly configured in the node credentials.
  • Resource not found: Verify that the provided resource ID exists in BookStack.
  • Validation errors: Ensure all required fields (like name for creation) are provided.
  • Parsing errors in automatic mode: Simplify or clarify the request description to help the node detect the correct operation and resource.

Links and References

Discussion