Skip to content

Configuration Guide

This guide provides detailed configuration instructions for the Knowledge module. It covers all aspects of setting up and customizing the module for your organization's needs.

Table of Contents

Initial Configuration

Global Settings

Navigate to Configuration > Knowledge (/admin/config/knowledge/settings) to configure global module settings.

Statistics Settings

Control how knowledge statistics are calculated:

  • Maintain entity statistics: Enable/disable automatic statistics tracking
  • Enabled: Real-time statistics (recommended)

  • Disabled: Manual statistics calculation (for very high-volume sites)

  • Statistics calculation frequency:

  • On every save (default, most accurate)
  • Hourly cron
  • Daily cron

Display Settings

  • Default knowledge per page: Global default (can be overridden per field)
  • Date format: How timestamps are displayed
  • Show statistics: Display knowledge counts and statistics
  • Enable charts: Show visual charts in reports (requires Charts module)

Workflow Settings

  • Content moderation integration: Enable if using Content Moderation
  • Auto-moderate knowledge based on article status
  • Restrict knowledge visibility based on moderation state

Content Types Setup

Decide which content types will participate in knowledge management:

Typical setup: - Articles/Documentation: Target content (gets knowledge field) - Support Tickets/Issues: Incident content (gets knowledge field) - FAQ: Target content (gets knowledge field)

Knowledge Types

Knowledge Types define the relationships between entity types. This is the foundation of your knowledge management system.

Planning Knowledge Types

Before creating knowledge types, map out your content relationships:

Knowledge Type Target Entity Incident Entity Purpose
Support to Article Article (node) Support Ticket (node) Link support cases to help articles
Issue to Solution Solution (node) Issue (node) Connect problems to solutions
Training to Material Material (node) Training Session (node) Link sessions to materials

Creating a Knowledge Type

  1. Navigate to Structure > Knowledge > Link (/admin/structure/knowledge/link)
  2. Click "Add knowledge type"
  3. Configure:

Basic Settings

  • Machine name: Unique identifier (e.g., support_to_article)
  • Cannot be changed after creation
  • Use lowercase and underscores

  • Must be unique

  • Label: Human-readable name (e.g., "Support Ticket to Article")

  • Can be changed anytime

  • Appears in admin interfaces

  • Description: Explain this knowledge type's purpose

  • Helps content editors understand when to use it
  • Appears on field configuration pages

Entity Type Settings

  • Target entity type: The entity type being documented
  • Usually node for articles
  • Can be any content entity type

  • Must have bundle support (content types)

  • Incident entity type: The entity type representing the incident

  • Usually node for support tickets
  • Can be any content entity type
  • Must have bundle support

Example Configuration

Label: Support Ticket to Article
Machine name: support_to_article
Description: Links support tickets to knowledge base articles. Use when resolving a ticket with existing or new documentation.
Target entity type: node
Incident entity type: node
  1. Click "Save"

Managing Knowledge Type Fields

After creating a knowledge type, you can add custom fields:

  1. Click "Manage fields" for your knowledge type
  2. Add fields relevant to your workflow:

Suggested Fields

For support workflows: - Resolution time (Number field): Time spent resolving - Resolution quality (List field): Excellent, Good, Fair, Poor - Customer feedback (Text field): Customer's response - Internal notes (Text area): Private notes

For documentation workflows: - Documentation status (List field): Complete, Needs update, Obsolete - Review date (Date field): When to review next - Subject matter expert (Entity reference): SME responsible - Related articles (Entity reference): Other relevant content

For training workflows: - Training effectiveness (Number field): 1-5 rating - Participant count (Number field): Number of attendees - Follow-up required (Boolean): Needs follow-up - Certification issued (Boolean): Certificate provided

Knowledge Type Permissions

Each knowledge type can have custom permissions:

  1. Go to your knowledge type's "Permissions" tab
  2. Configure per-type permissions:
  3. Create knowledge links of this type
  4. Edit knowledge links of this type
  5. Delete knowledge links of this type
  6. View knowledge links of this type

This allows fine-grained control. For example: - Only support team can link support tickets - Anyone can link issues to solutions - Only trainers can link training materials

Field Configuration

After creating a knowledge type, add a knowledge field to your content types.

Adding a Knowledge Field

  1. Navigate to Structure > Content types
  2. Select a content type (e.g., "Article")
  3. Click "Manage fields"
  4. Click "Add field"
  5. Select "Knowledges" from the "General" category
  6. Enter field label (e.g., "Knowledge Links", "Support Tickets", "Related Issues")
  7. Click "Save and continue"

Storage Settings

These settings are configured once and cannot be changed after knowledge links exist.

Knowledge Type Selection

  • Knowledge type: Choose which knowledge type this field uses
  • Must match your content architecture
  • Example: "Support Ticket to Article" for an Article content type

Frequency Thresholds

These define time periods for statistics:

  • Short frequency (days): Default 15
  • Recent activity window
  • "New" or "hot" knowledge

  • Example: Links created in last 15 days

  • Medium frequency (days): Default 90

  • Recent history window
  • Regular usage tracking

  • Example: Links created in last 3 months

  • Long frequency (days): Default 365

  • Historical tracking
  • Long-term trends
  • Example: Links created in last year

Choosing values: - High-volume sites: Shorter periods (7, 30, 180) - Low-volume sites: Longer periods (30, 180, 730) - Match your content lifecycle

Example Configuration by Industry

Software support: 

Short: 7 days (urgent issues)
Medium: 30 days (monthly cycle)
Long: 90 days (quarterly review)

Healthcare: 

Short: 30 days (monthly review)
Medium: 90 days (quarterly audit)
Long: 365 days (annual compliance)

Education: 

Short: 14 days (two-week modules)
Medium: 120 days (semester)
Long: 365 days (academic year)

Field Settings

These settings can be changed anytime.

Display Settings

  • Links per page: Number of knowledge links to display
  • Default: 50
  • Range: 1-1000
  • Consider page performance with high numbers

Anonymous User Settings

Control anonymous user interaction:

  • Anonymous posters may not enter contact information
  • Best for: Internal systems, authenticated-only sites

  • Security: Highest

  • Anonymous posters may leave contact information

  • Best for: Public support systems
  • Allows optional email/name

  • Security: Medium

  • Anonymous posters must leave contact information

  • Best for: Public sites requiring accountability
  • Requires email/name for anonymous users
  • Security: Medium-High

Note: Anonymous users must also have the "Post knowledge" permission.

Form Display Configuration

Control how the knowledge field appears on content edit forms:

  1. Click "Manage form display"
  2. Configure the knowledge field widget
  3. Available options:
  4. Position: Drag to reorder
  5. Label: Show/hide the field label
  6. Widget: Usually "Knowledge default"
  7. Weight: Display order

View Display Configuration

Control how knowledge links display on content:

  1. Click "Manage display"
  2. Configure for each view mode (Default, Teaser, Full content, etc.)
  3. Available formatters:

Knowledge Default Formatter

Shows complete knowledge link information: - List of linked content - Statistics (counts, frequency) - Links to view/edit/delete - User information - Timestamps

Settings: - Show statistics - Links per page - Display format (flat list, threaded)

Knowledge Competency Formatter

Shows competency-related information: - User competency status - Role progression - Competency scores

Settings: - Show progress bars - Display role badges - Show completion percentage

Shows direct links to knowledge entities: - Permanent links to knowledge - Useful for exports or reports

Settings: - Link text - Icon display - Open in new window

Competency System

The competency system tracks user progression through knowledge management roles.

Competency Entity Configuration

  1. Navigate to Structure > Knowledge > Competency (/admin/structure/knowledge/competency)
  2. Click "Manage fields"

Built-in Competency Fields

These fields are automatically provided:

  • User: The learner being tracked
  • Roles: Multi-value field tracking progress per role
  • Candidate
  • Contributor
  • Publisher
  • Custom roles (add via custom fields)
  • Correct: Total correct competencies
  • Total: Total competencies required
  • Completed: Timestamp when all competencies met
  • Created: Record creation date
  • Changed: Last modification date

Adding Custom Competency Fields

Add boolean fields to create competency checkpoints:

  1. Click "Add field"
  2. Select "Boolean"
  3. Name your competency, for example:
  4. "Can create accurate knowledge links"
  5. "Understands citation vs. direct knowledge"
  6. "Follows article quality standards"
  7. "Completes links within 24 hours"

  8. "Achieves 90%+ accuracy rating"

  9. Configure settings:

  10. On label: "Competency achieved" or "Yes"
  11. Off label: "Not yet achieved" or "No"

  12. Default value: Usually unchecked

  13. Repeat for each competency you want to track

Role-Based Competency Groups

Organize competencies by role using field groups:

Candidate Competencies: - Basic system navigation - Creating simple knowledge links - Following standard procedures - Requesting help when needed

Contributor Competencies: - Creating complex knowledge links - Identifying reuse opportunities - Maintaining link accuracy - Mentoring candidates

Publisher Competencies: - Reviewing others' work - Approving content for publication - Setting quality standards - Analyzing reports

Competency Calculation

The system automatically calculates:

Per Role: - Correct: Boolean fields marked true for that role - Total: Number of boolean fields for that role

Overall: - Correct: Sum of correct across all roles - Total: Sum of total across all roles - Percentage: (Correct / Total) * 100 - Completed: Set when percentage reaches 100%

Coach and Leader Assignment

Manual Assignment

Assign coaches and leaders via user profile:

  1. Edit a user account
  2. Find these fields:
  3. Knowledge Coach: Select a user who will mentor this person
  4. Knowledge Leader: Select a user who will approve promotions

Coach responsibilities: - Guide day-to-day learning - Propose promotions - Answer questions - Monitor progress

Leader responsibilities: - Approve promotions proposed by coaches - Set competency standards - Review overall team performance - Make final decisions on advancement

Automatic Assignment via LDAP

If using the Knowledge LDAP submodule:

  1. Navigate to Configuration > Knowledge > LDAP
  2. Configure:
  3. LDAP server: Select configured server
  4. Leader attribute: LDAP attribute containing leader DN
  5. Coach attribute: LDAP attribute containing coach DN

  6. Sync frequency: How often to update

    • On user login
    • On user save
    • Via cron (hourly, daily)

  7. Test the configuration

  8. Save settings

Users will automatically get their coach/leader from LDAP attributes.

Competency Approval Workflow

Proposing Advancement

  1. Coach reviews learner's competency progress
  2. When ready, coach opens competency entity
  3. Coach clicks "Propose for [Role]"
  4. System records:
  5. Proposed timestamp
  6. Proposing coach
  7. Role being proposed for
  8. Leader receives notification (if configured)

Approving Advancement

  1. Leader reviews proposal
  2. Verifies competency achievements
  3. Clicks "Approve for [Role]"
  4. System records:
  5. Approved timestamp
  6. Approving leader
  7. Role granted
  8. User permissions update automatically
  9. User receives notification (if configured)

Rejection or Deferral

Leaders can: - Reject proposal with feedback - Request additional evidence - Set conditions for re-proposal - Assign additional competency requirements

Adherence Tracking

Adherence tracking ensures knowledge linking best practices are followed.

Adherence Entity Configuration

  1. Navigate to Structure > Knowledge > Adherence (/admin/content/knowledge/adherence)
  2. Click "Manage fields" (if available)

Built-in Adherence Fields

  • Learner: User being evaluated
  • Incident: The support case or incident
  • Knowledge: The linked knowledge entity
  • Article: The target article
  • Linked: Was article linked? (Yes/No/NA)
  • Reused: Was article reused or created?
  • Accurate: Was article accurate?
  • Improve: Should article be improved?
  • Required: Was article required?
  • Found: Could you find appropriate article?
  • Disposition: Incident outcome
  • Created: Record creation date
  • Changed: Last modification date

Adherence Evaluation Criteria

Configure these settings to match your organization's standards:

Linking Requirements

Define when knowledge linking is required:

Required scenarios: - All customer-facing incidents - Incidents lasting >X minutes - Escalated incidents - Billing issues - Product defects - Training requests

Optional scenarios: - Internal questions - Quick troubleshooting - Administrative tasks - System maintenance

Accuracy Standards

Define what makes a knowledge link accurate:

  • Resolves the stated problem
  • Uses current product version
  • Follows company standards
  • Verified by customer
  • No corrections needed

Quality Standards

Define when articles need improvement:

  • Outdated screenshots
  • Missing steps
  • Unclear instructions
  • Poor formatting
  • Incorrect information
  • Missing troubleshooting

Automated Adherence Tracking

Set up automatic adherence record creation:

Via Custom Module

Create a custom module that:

  1. Listens for incident closure events
  2. Checks if knowledge was linked
  3. Creates adherence record automatically
  4. Flags exceptions for review

Example hook:

/**
 * Implements hook_entity_update().
 */
function mymodule_entity_update(EntityInterface $entity) {
  if ($entity->getEntityTypeId() == 'node' && $entity->bundle() == 'support_ticket') {
    if ($entity->get('field_status')->value == 'closed') {
      \Drupal::service('mymodule.adherence')->createRecord($entity);
    }
  }
}

Via Rules Module

If using the Rules module:

  1. Create a rule triggered on incident status change
  2. Add condition: Status equals "Closed"
  3. Add action: Create adherence entity
  4. Configure field values
  5. Save rule

Adherence Reporting

Configure reports to track adherence:

  1. Create Views for adherence data
  2. Group by:
  3. User (learner)
  4. Team
  5. Time period
  6. Disposition
  7. Calculate:
  8. Adherence rate
  9. Average accuracy
  10. Improvement needs
  11. Gap analysis

Quality Assessment

Quality assessment provides structured reviews of knowledge articles.

Quality Entity Configuration

  1. Navigate to Structure > Knowledge > Quality (/admin/structure/knowledge/quality)
  2. Click "Manage fields"

Built-in Quality Fields

  • Entity: The article being reviewed
  • User: Reviewer
  • Correct: Number of criteria met
  • Total: Total criteria
  • Status: Published/Unpublished
  • Created: Review date
  • Changed: Last update

Adding Quality Criteria

Add boolean fields for each quality checkpoint:

Content Quality Criteria

  1. Accuracy
  2. "Information is factually correct"
  3. "Matches current product version"

  4. "No contradictions present"

  5. Completeness

  6. "All necessary steps included"
  7. "Prerequisites clearly listed"

  8. "Expected outcomes described"

  9. Clarity

  10. "Language is clear and concise"
  11. "Terms are defined"
  12. "Instructions are unambiguous"

Format Quality Criteria

  1. Structure
  2. "Uses appropriate headings"
  3. "Steps are numbered"

  4. "Formatting is consistent"

  5. Visuals

  6. "Screenshots are current"
  7. "Images are clear and relevant"

  8. "Diagrams enhance understanding"

  9. Organization

  10. "Logical flow"
  11. "Related content linked"
  12. "Table of contents present (if needed)"

Compliance Criteria

  1. Standards
  2. "Follows style guide"
  3. "Uses approved terminology"

  4. "Meets accessibility standards"

  5. Metadata

  6. "Tags are appropriate"
  7. "Categories correct"
  8. "Audience identified"

Quality Scoring

The system automatically scores using:

Score = 100 * ((correct - incorrect) / total)

Where: - correct = criteria marked Yes/True - incorrect = criteria marked No/False - total = all criteria fields

Score Interpretation

Configure thresholds for your organization:

Score Status Action Required
90-100 Excellent Approve for publication
75-89 Good Minor improvements, then publish
60-74 Fair Significant revision needed
50-59 Poor Major revision required
<50 Failing Complete rewrite recommended

Quality Review Workflow

With Content Moderation

Integrate quality reviews with Content Moderation:

  1. Article is submitted for review (Draft → Needs Review)
  2. Quality review is created
  3. Based on quality score:
  4. High score: Automatically approve (Needs Review → Published)
  5. Medium score: Request changes (Needs Review → Draft)
  6. Low score: Reject (Needs Review → Archived)

Configure in Structure > Knowledge > Quality > Settings

Manual Review Process

Without Content Moderation:

  1. Reviewer creates quality entity
  2. Completes quality criteria
  3. Reviews calculated score
  4. Adds notes/feedback
  5. Notifies author
  6. Author revises article
  7. Re-review if necessary

Permissions

Configure granular permissions for each role.

Permission Strategy

Role: Authenticated User

✓ Access knowledge
✓ View own competency
✗ Post knowledge (require training first)

Role: Knowledge Candidate

✓ Access knowledge
✓ Post knowledge
✓ Edit own knowledge
✓ View own competency
✗ Skip knowledge approval

Role: Knowledge Contributor

✓ Access knowledge
✓ Post knowledge
✓ Skip knowledge approval
✓ Edit own knowledge
✓ View own competency
✓ View learner competency (if coach)
✗ Edit other's competency

Role: Knowledge Publisher

✓ Access knowledge
✓ Post knowledge
✓ Skip knowledge approval
✓ Edit own knowledge
✓ Edit other's competency
✓ View any competency
✓ Add quality entities
✓ View learner competency
✓ View follower competency
✗ Administer knowledge

Role: Knowledge Manager

✓ Administer knowledge
✓ Access knowledge reports
✓ Edit other's competency
✓ Administer adherence entities
✓ Administer quality entities
✓ View unpublished entities
✗ Administer knowledge types (restrict to admins)

Advanced Permissions

For fine-grained control:

  1. Per-type permissions: Different permissions per knowledge type
  2. Field-level permissions: Use Field Permissions module
  3. View-based access: Control what users see in lists
  4. Organic groups integration: Permissions per group

Advanced Configuration

Integration with Other Modules

Search API Integration

Already required, but configure for better results:

  1. Create search index for knowledge entities
  2. Include fields:
  3. Incident reference
  4. Target entity reference
  5. User
  6. Timestamps
  7. Custom fields
  8. Configure relevance
  9. Add facets for filtering

Views Integration

The module provides Views data for: - Knowledge entities - Knowledge types - Competency entities - Adherence entities - Quality entities

Create custom views for: - Dashboards - Reports - User pages - Content displays

Charts Integration

Create visual reports:

  1. Create a View of knowledge data
  2. Add Charts display
  3. Configure:
  4. Chart type (bar, line, pie)
  5. X-axis: Date, user, type
  6. Y-axis: Count, score
  7. Add to dashboard

Performance Optimization

For High-Volume Sites

  1. Disable real-time statistics:
  2. Use cron-based calculation

  3. Update statistics hourly or daily

  4. Add database indexes: 

    CREATE INDEX idx_knowledge_dates ON knowledge (created, changed);
CREATE INDEX idx_knowledge_entity ON knowledge (entity_type, entity_id);

  5. Use caching:

  6. Enable Views caching
  7. Use render caching for knowledge displays

  8. Configure Page Cache and Dynamic Page Cache

  9. Limit query results:

  10. Set reasonable "links per page" values
  11. Use pagination
  12. Implement infinite scroll for large lists

Backup and Maintenance

Regular Maintenance Tasks

Daily: - Check error logs for knowledge-related issues - Monitor statistics calculation performance

Weekly: - Review adherence rates - Check quality score trends - Audit competency progressions

Monthly: - Archive old adherence records - Clean up duplicate knowledge links - Review and update quality criteria - Audit permission assignments

Backup Strategy

Include in regular backups: - Database tables (knowledge, knowledge_competency, etc.) - Configuration (knowledge types, field config) - Custom fields and field data - Views configurations - Permission settings

Use Drush for exports:

# Export all knowledge configuration
drush config:export --include-dependencies knowledge

# Backup database
drush sql:dump > knowledge-backup-$(date +%Y%m%d).sql

Next Steps

After configuration:

  1. Test with sample data: Create test knowledge links, competencies, adherence, and quality records
  2. Train users: Provide training on workflows and best practices
  3. Monitor usage: Check reports regularly during initial rollout
  4. Iterate: Adjust configuration based on user feedback
  5. Review the User Guide: Learn how to use configured features

For troubleshooting or advanced customization, see the API Documentation.