BookStack icon

BookStack

Consume BookStack API
Join our community

Actions56

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. Specifically for the User resource with the Create operation, it enables creating new user entries in a BookStack instance.

The node supports two modes of operation:

  • Automatic mode: The user provides a natural language description of the desired action (e.g., "Create a new page about API documentation"), and the node attempts to parse this description to determine the appropriate resource and operation automatically.
  • Manual mode: The user explicitly selects the resource and operation from dropdowns and fills in the required fields.

Typical use cases include automating content management workflows in BookStack, such as programmatically adding new users or other resources based on dynamic input or descriptions.

Example: Automatically create a new user by describing the request in natural language, or manually specify user details to create a user account.

Properties

Name Meaning
Tool Description Choose how to determine the resource and operation:
- Set Automatically
- Set Manually
Request Description (Shown only if "Set Automatically" is selected) Describe your request in natural language; the system will parse it to select resource and operation automatically. Example: "Create a new page about API documentation".
Resource (Shown only if "Set Manually" is selected) Select the resource to operate on. Options include: Book, Page, Chapter, Shelf, User, Role, Attachment, Tag. Default is Book.
Operation (Shown only if "Set Manually" is selected) Select the operation to perform on the chosen resource. Options include: Create, Delete, Get, Get Many, Update, Copy, Move. Default is Get Many.
ID (Required for some operations like Get, Update, Delete) The ID of the resource to act upon.
Name (Required for Create and Update on some resources) The name of the resource.
Description (Optional for Create and Update on some resources) Description text for the resource.
HTML Content (For Page resource Create/Update) The HTML content of the page.
Book ID (For Page and Chapter resource Create) The ID of the book this resource belongs to.
Chapter ID (Optional for Page resource Create) The ID of the chapter this page belongs to.

Note: For the User - Create operation specifically, the node expects parameters relevant to user creation, but these are not explicitly detailed in the provided properties snippet. The node likely uses the automatic parsing or manual selection to gather necessary user data.

Output

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

  • json: The JSON response returned by the BookStack API after performing the requested operation. For a successful user creation, this typically includes the created user's details such as ID, name, email, and other metadata as returned by the API.
  • pairedItem: Metadata linking the output to the input item index.

If the node encounters an error 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 access to a BookStack instance with API enabled.
  • Requires credentials containing:
    • Base URL of the BookStack API.
    • An API token and secret for authentication.
  • The node uses HTTP requests authenticated via token headers.
  • No additional external dependencies beyond the BookStack API and n8n's HTTP request helper.

Troubleshooting

  • Common issues:

    • Incorrect or missing API credentials will cause authentication failures.
    • Providing incomplete or invalid parameters (e.g., missing required fields like user name or book ID) may result in API errors.
    • In automatic mode, ambiguous or poorly phrased request descriptions might lead to incorrect resource or operation detection.
    • Network connectivity issues to the BookStack server can cause request failures.

  • Error messages:

    • Authentication errors: Check that the API token and base URL are correct and have sufficient permissions.
    • Validation errors from the API: Ensure all required fields for the resource and operation are provided.
    • Parsing errors in automatic mode: Try switching to manual mode and specifying resource and operation explicitly.

Links and References

Discussion