Installation Guide

This guide provides detailed instructions for installing and setting up the Knowledge module on your Drupal site.

Prerequisites

Before installing the Knowledge module, ensure your Drupal site meets these requirements:

System Requirements

Drupal: 10.3 or higher, 11.x, or 12.x
PHP: 8.3 or higher
MySQL: 5.7.8+ or MariaDB 10.3.7+ (standard Drupal requirements)
Composer: Required for dependency management

Recommended Modules

While not required, these modules enhance the Knowledge module's functionality:

Views UI: For creating custom reports (Drupal core, usually enabled)
Field UI: For configuring knowledge fields and types (Drupal core)
LDAP: Required only if using Knowledge LDAP submodule
Search API: Already required, but configure for better knowledge search

Installation Methods

Method 1: Composer (Recommended)

Composer is the recommended installation method as it automatically manages dependencies.

Step 1: Require the Module

From your Drupal root directory:

composer require drupal/knowledge

This command: - Downloads the Knowledge module - Downloads all required dependencies - Updates your composer.json and composer.lock files

Step 2: Enable the Module

Using Drush:

drush en knowledge -y

Or using Drupal Admin UI:

Navigate to Extend (/admin/modules)
Find "Knowledge" in the module list
Check the box next to it
Click "Install" at the bottom of the page
Wait for installation to complete

Step 3: Verify Installation

Run this command to verify the module is enabled:

drush pm:list --type=module --status=enabled | grep knowledge

You should see: - Knowledge (knowledge) - Knowledge fields (knowledge_field)

Method 2: Manual Installation

If you cannot use Composer, follow these steps:

Step 1: Download Dependencies

You must manually download and install these modules first:

Autocomplete ID (^1.5): https://www.drupal.org/project/autocomplete_id
Charts (^5.0): https://www.drupal.org/project/charts
Moderation Note (^1.0-beta5): https://www.drupal.org/project/moderation_note
Search API (^1.0): https://www.drupal.org/project/search_api
Token (^1.13): https://www.drupal.org/project/token

Extract each module to your modules/contrib directory.

Step 2: Download Knowledge Module

Download the Knowledge module from https://www.drupal.org/project/knowledge
Extract to modules/contrib/knowledge

Ensure the directory structure is:

modules/contrib/knowledge/
  knowledge.info.yml
  knowledge.module
  src/
  modules/
  ...

Step 3: Enable Required Modules

Enable dependencies first, then the Knowledge module:

drush en autocomplete_id charts moderation_note search_api token -y
drush en knowledge -y

Or use the admin UI at /admin/modules.

Method 3: Development Installation

For developers or contributors:

Step 1: Clone the Repository

cd modules/custom
git clone https://git.drupalcode.org/project/knowledge.git
cd knowledge

Step 2: Install Dependencies

composer install

Step 3: Enable the Module

drush en knowledge -y

Post-Installation Configuration

After installing the module, complete these setup steps:

Step 1: Verify Permissions

Navigate to People > Permissions (/admin/people/permissions)
Scroll to the "Knowledge" section
Assign appropriate permissions to your roles
Recommended starting permissions:

For Authenticated Users: - Access knowledge - Post knowledge - Edit own knowledge - View own competency

For Content Editors: - Access knowledge - Post knowledge - Skip knowledge approval - Edit own knowledge - View own competency

For Administrators: - Administer knowledge - Administer knowledge types - Access knowledge reports

Click "Save permissions"

Step 2: Create Your First Knowledge Type

Navigate to Structure > Knowledge > Link (/admin/structure/knowledge/link)
Click "Add knowledge type"
Fill in:
Label: "Support Ticket to Article" (or your use case)
Description: "Links support tickets to help articles"
Target entity type: node (or your article type)
Incident entity type: node (or your ticket type)
Click "Save"

Step 3: Add a Knowledge Field

Navigate to Structure > Content types (/admin/structure/types)
Select your target content type (e.g., "Article")
Click "Manage fields"
Click "Add field"
Select "Knowledges" from the dropdown
Enter label: "Knowledge Links"
Click "Save and continue"
Configure storage settings:
Knowledge type: Select the type you created
Short frequency: 15 days (default)
Medium frequency: 90 days (default)
Long frequency: 365 days (default)
Click "Save field settings"
Configure field settings:
- Links per page: 50 (default)
- Anonymous linking: Choose appropriate option
Click "Save settings"

Step 4: Configure Display

Click "Manage display" tab
Ensure the Knowledge Links field is visible
Select display formatter (usually "Knowledge default")
Configure formatter settings if needed
Click "Save"

Step 5: Run Database Updates (if updating from older version)

If you're upgrading from a previous version:

drush updb -y
drush cr

Or use the admin UI:

Navigate to Reports > Available updates (/admin/reports/updates)
Click "Run database updates"
Review and apply pending updates

Enabling Optional Features

Knowledge LDAP Submodule

If you need LDAP integration for automatic leader assignment:

Prerequisites

Install the LDAP module first:

composer require drupal/ldap:~4
drush en ldap_servers ldap_user -y

Enable Knowledge LDAP

drush en knowledge_ldap -y

Configure LDAP Integration

Navigate to Configuration > Knowledge > LDAP Settings
Configure LDAP server connection
Map LDAP attributes to leader fields
Test the connection
Save settings

Troubleshooting Installation

Common Issues

Issue: "Module Knowledge requires module X which is missing"

Solution: Install missing dependencies first:

composer require drupal/[missing-module]
drush en [missing-module] -y

Issue: "Database schema update required"

Solution: Run database updates:

drush updb -y

Or via UI at /admin/reports/status (click "Run updates")

Issue: "Composer require fails with version conflicts"

Solution: Try adding --with-all-dependencies:

composer require drupal/knowledge --with-all-dependencies

If still failing, update Drupal core first:

composer update drupal/core "drupal/core-*" --with-all-dependencies

Issue: "Access denied to knowledge administration pages"

Solution: 1. Clear cache: drush cr 2. Rebuild permissions: drush php:eval "node_access_rebuild();" 3. Check user permissions at /admin/people/permissions

Issue: "Field storage settings cannot be changed"

Solution: This is expected behavior after data exists. To change: 1. Export existing knowledge data 2. Delete all knowledge entities 3. Delete the field 4. Re-create field with new settings 5. Re-import data

Verifying Installation

Run these commands to verify everything is working:

# Check module status
drush pm:list --type=module --status=enabled | grep knowledge

# Verify database tables exist
drush sqlq "SHOW TABLES LIKE 'knowledge%';"

# Check for configuration
drush config:status | grep knowledge

# Clear cache
drush cr

Expected output: - Module shows as "Enabled" - Multiple knowledge* database tables exist - Configuration shows no warnings - Cache clears successfully

Getting Additional Help

If installation issues persist:

Check Drupal logs: Navigate to Reports > Recent log messages (/admin/reports/dblog)

Enable debugging: In settings.php, temporarily enable:

$config['system.logging']['error_level'] = 'verbose';

Check PHP error logs: Location varies by server setup
Review requirements: Visit Reports > Status report (/admin/reports/status)
Search issue queue: https://www.drupal.org/project/issues/knowledge
Ask for help: Create a new issue with your installation details

Next Steps

After successful installation:

Review the Configuration Guide for detailed setup instructions
Read the User Guide to understand how to use the module
Configure permissions appropriate for your organization
Create test knowledge links to verify functionality
Set up reporting to track knowledge management metrics

Uninstallation

If you need to remove the Knowledge module:

Warning

Uninstalling will permanently delete: - All knowledge entities - All competency records - All adherence records - All quality reviews - All knowledge fields and their data

Original content (articles, incidents) will be preserved, but the connections between them will be lost.

Backup First

Before uninstalling:

# Backup database
drush sql:dump > backup.sql

# Export configuration
drush config:export

# Export knowledge data if you might need it later
drush views:data:export knowledge --destination=/path/to/export

Uninstall Steps

Remove knowledge fields from all content types:
Go to each content type's "Manage fields" page
Delete knowledge fields
Disable the module:
```
drush pm:uninstall knowledge -y
```
Remove via Composer (if installed that way):
```
composer remove drupal/knowledge
```
Clean up:
```
drush cr
drush sql:sanitize
```

Upgrading

Between Minor Versions (e.g., 1.0 to 1.1)

# Update via Composer
composer update drupal/knowledge

# Run database updates
drush updb -y

# Clear cache
drush cr

# Verify
drush pm:list --type=module | grep knowledge

From Drupal 10 to Drupal 11

The Knowledge module is compatible with both Drupal 10.3+ and Drupal 11+. Follow standard Drupal core upgrade procedures:

Update Drupal core first
Test on a staging environment
Update the Knowledge module
Run database updates
Test thoroughly before deploying to production

Migration from Other Knowledge Management Systems

If migrating from another system, create custom migrations:

Create migration configuration files
Use EntityKnowledge and EntityKnowledgeType destination plugins
Map source data to knowledge entity fields
Test on a copy of production
Run migrations with drush migrate:import

See the API Documentation for details on migration plugins.