Skip to content
Nappai Documentation

OpenKM Documents

This component allows you to manage documents within your OpenKM Document Management System directly from your Nappai automation workflows. It acts as a bridge, enabling you to perform essential file operations such as uploading new files, retrieving existing ones, changing names, moving folders, and managing document versions.

How it Works

The OpenKM Documents component connects your workflow to your OpenKM server. It uses a secure credential you configure in Nappai to authenticate and interact with your document repository.

Once connected, you can instruct the component to perform specific actions on files. For example, you can upload a file from a web link to your OpenKM folder, rename an existing file, or check out a document for editing. The component handles the communication with the OpenKM server, ensuring that your documents are updated correctly.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type OpenKM and fill in the required fields (Base URL, Username, and Password) for your OpenKM instance.
  3. In your workflow, select the saved credential in the Credential input field of this node.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • Upload: Uploads a new document to OpenKM from a public URL or data URI.
  • Download: Retrieves a document from OpenKM and makes its content available for further use in your workflow.
  • Get Properties: Retrieves metadata (such as title, author, and custom properties) for a specific document.
  • Rename: Changes the name of an existing document while keeping it in the same location.
  • Move: Moves a document from one folder to another within your OpenKM repository.
  • Delete: Permanently removes a specified document from OpenKM.
  • Checkout: Locks a document for editing by the current user.
  • Checkin: Saves changes to a document and updates its version history.
  • Version History: Retrieves a list of all previous versions of a specific document.

To use the component, first select the operation you need in the “Operation” field.

CRITICAL INSTRUCTION FOR THE MODEL: Operation names in the list above MUST be copied EXACTLY as they appear in “Additional Component Information” (in English). Do NOT modify them. Do NOT include this warning in the final documentation.

Inputs

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: Select the specific action you want to perform on the document (e.g., Upload, Download, Rename).
    • Visible in: All operations
  • Document UUID: UUID or full path of the document to perform the operation on. This is required for most operations to identify the specific file.
    • Visible in: Download, Get Properties, Rename, Move, Delete, Checkout, Checkin, Version History
  • Parent Folder UUID: UUID of the parent folder where the document will be uploaded. Required when uploading new files.
    • Visible in: Upload
  • File URL: Public URL of the file to download and upload to OpenKM. Required when uploading from a web link.
    • Visible in: Upload, Checkin
  • Document Name: Name to use for the document in OpenKM. If left empty, the name is automatically extracted from the provided URL.
    • Visible in: Upload
  • Destination Folder: UUID or path of the destination folder (e.g., /okm:root/archive). Required when moving a document.
    • Visible in: Move
  • New Name: New file name for the document (e.g., renamed-invoice.pdf). Required when renaming a document.
    • Visible in: Rename
  • Version Comment: Optional comment describing the changes in this version. Useful for tracking changes in the version history.
    • Visible in: Checkin
  • Increment: Version increment type: 0 = none, 1 = minor (0.1), 2 = major (1.0). Controls how the version number increases.
    • Visible in: Checkin
  • Limit: Maximum number of search results to return. Used to control the volume of data returned during searches or history retrieval.
    • Visible in: Version History, Get Properties
  • Add Search Filter: Select a filter to add to the search query. Each selected filter appears as an input field to refine your search criteria.
    • Visible in: Get Properties, Version History

CRITICAL INSTRUCTION FOR THE MODEL: Field names (display_name) MUST be copied EXACTLY as they appear in “Additional Component Information” (in English). Do NOT translate field names. Do NOT include this warning in the final documentation.

Outputs

After the component executes, it provides data you can use in subsequent steps of your workflow:

  • Success: A boolean value (True or False) indicating whether the operation completed successfully. You can use this to direct your workflow to error-handling steps if False.
  • Message: A text string providing details about the operation result. If successful, it may confirm the action; if it fails, it explains the error.
  • Data: The primary output for the operation. Depending on the operation chosen, this may contain:
    • The file content (for Download).
    • Metadata properties like title, author, or custom tags (for Get Properties).
    • A list of version history details (for Version History).

Output Data Example (JSON)json

{ “success”: true, “message”: “Document uploaded successfully”, “data”: { “title”: “Q3 Report.pdf”, “author”: “admin”, “created”: “2023-10-25T10:00:00Z”, “path”: “/okm:root/reports/Q3 Report.pdf”, “uuid”: “a1b2c3d4-e5f6-7890-abcd-ef1234567890” } }

Connectivity

This component is typically connected to:

  • Preceding Nodes: File extraction nodes (e.g., from email or web scraping) or URL providers that generate the source file content or URL.
  • Following Nodes:
    • Email Senders: To notify users that a document has been uploaded or renamed.
    • Document Reviewers: To allow manual review of downloaded documents.
    • Data Processors: To analyze metadata (like authors or creation dates) for reporting or filtering purposes.

Usage Example

Scenario: Uploading a Contract from a URL

  1. Select Operation: Choose Upload.
  2. Credential: Select your OpenKM connection.
  3. Parent Folder UUID: Enter the UUID of the folder where the contract should be stored (e.g., /contracts).
  4. File URL: Paste the public URL of the PDF contract.
  5. Document Name: Leave empty to auto-extract the name, or specify a custom name.
  6. Result: The document is uploaded to OpenKM. The Success output will be True, and the Data output will contain the new document’s UUID and path, which you can use to link the contract to a specific record in another system.

Tips and Best Practices

  • Always verify the Success output in your workflow to ensure document operations completed before proceeding to dependent tasks.
  • When using Move or Rename, ensure the target folder exists to avoid errors.
  • For Checkin, always provide a meaningful Version Comment to keep track of changes in your audit trail.
  • Use Limit with care in Version History to prevent retrieving overly large lists of versions, which can slow down your workflow.

Security Considerations

  • Ensure your OpenKM credentials are stored securely in the Nappai credentials manager. Never hardcode usernames or passwords in the workflow fields.
  • Be cautious when using the Delete operation, as it permanently removes files. Consider adding a confirmation step or logging the deletion for audit purposes.
  • When uploading files from public URLs, ensure the source is trusted to prevent uploading malicious content into your document management system.