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-Centered Success:

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 Track Reuse.

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 Proficiency Formatter

Shows proficiency-related information: - User proficiency status - Role progression - Proficiency 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

Proficiency System

The proficiency system tracks user progression through Candidate, Contributor, and Publisher.

Proficiency Entity Configuration

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

Built-in Proficiency 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 proficiency items
  • Total: Total proficiency items required
  • Completed: Timestamp when all proficiency items met
  • Created: Record creation date
  • Changed: Last modification date

Adding Custom Proficiency Fields

Add boolean fields to create proficiency checkpoints:

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

  8. "Achieves 90%+ accuracy rating"

  9. Configure settings:

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

  12. Default value: Usually unchecked

  13. Repeat for each proficiency you want to track

Role-Based Proficiency Groups

Organize proficiency items by role using field groups:

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

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

Publisher proficiency items: - Reviewing others' work - Approving content for publication - Setting Content Standard expectations - Analyzing reports

Proficiency 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 proficiency 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.

Proficiency Approval Workflow

Nomination with leadership approval is the default. Completing a checklist proposes the role; the learner's Knowledge Leader confirms on the proficiency approval form. Automatic promotion (auto) is a site setting on Structure > Knowledge > Proficiency > Roles.

Proposing Advancement

  1. Coach reviews learner's proficiency progress
  2. When ready, coach opens proficiency 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 proficiency 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 proficiency requirements

Revoking Rights

Leaders can revoke Contributor or Publisher on /user/{user}/proficiency/revoke. The Drupal role is removed. The proficiency checklist, exam flag, and proposal history remain.

Article-state rights

  • Candidate: Work in Progress and Not Validated; Internal audience
  • Contributor: also Validated
  • Publisher: also External audience (partner, customer, public)
  • Leader: External plus archive and delete of External articles
  • Publisher cannot archive or delete External articles

The site template or another module attaches audience and a content-moderation workflow to the article bundle. This module enforces rights when those fields are present.

Process Alignment

Process Alignment Review samples whether knowledge linking practices were followed.

Process Alignment Entity Configuration

  1. Navigate to Content > Knowledge > Process Alignment (/admin/content/knowledge/alignment)
  2. Click "Manage fields" (if available)

Built-in Process Alignment 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

Process Alignment 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 Process Alignment Tracking

Set up automatic Process Alignment record creation:

Via Custom Module

Create a custom module that:

  1. Listens for incident closure events
  2. Checks if knowledge was linked
  3. Creates Process Alignment 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.alignment')->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 Process Alignment entity
  4. Configure field values
  5. Save rule

Process Alignment Reporting

Configure reports to track Process Alignment:

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

Content Standard Checklist

The Content Standard Checklist is a coaching sample of six checks on a knowledge article. It is not a test score. Technical accuracy is reuse-is-review.

Content Standard Checklist Configuration

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

Built-in Fields

  • Entity: The article being sampled
  • Coach: The coach who recorded the sample
  • Correct: Number of checks met
  • Total: Total checks (six)
  • Status: Published/Unpublished
  • Created: Sample date
  • Changed: Last update

The Six Checks

The module ships these boolean checks. Keep all six:

  1. Complete — Issue, Environment, Cause, and Resolution are present on the article. Those sections come from the site template.
  2. Content Clear — A reader can follow the article without guessing.
  3. Unique — The article does not duplicate another article.
  4. Title Relates to Article — The title matches what the article is about.
  5. Metadata Correct — Metadata matches the article.
  6. Hyperlinks Valid — Links resolve and point at the right targets.

The listing and form show checks met (for example 4 of 6). Do not treat Quality::getScore() as a pass/fail grade. Trends belong in the analytic namespace.

Recording a Sample

  1. A coach opens a closed or reused article
  2. The coach records a Content Standard Checklist sample
  3. Each of the six checks is marked met or not met
  4. The listing shows checks met
  5. The worker can list samples on their coaching samples page

Configure in Structure > Knowledge > Content Standard Checklist > Settings

Permissions

Configure granular permissions for each role.

Permission Strategy

Role: Authenticated User

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

Role: Knowledge Candidate

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

Role: Knowledge Contributor

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

Role: Knowledge Publisher

✓ Access knowledge
✓ Post knowledge
✓ Skip knowledge approval
✓ Edit own knowledge
✓ Edit other's proficiency
✓ View any proficiency
✓ Create new Content Standard Checklist entities
✓ View learner proficiency
✓ View follower proficiency
✗ Administer knowledge

Role: Knowledge Manager

✓ Administer knowledge
✓ Access knowledge reports
✓ Edit other's proficiency
✓ Administer Process Alignment entities
✓ Administer Content Standard Checklist 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 - Proficiency entities - Process Alignment entities - Content Standard Checklist 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 alignment rates - Check quality score trends - Audit proficiency progressions

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

Backup Strategy

Include in regular backups: - Database tables (knowledge, knowledge_proficiency, 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, proficiency items, Process Alignment, and Content Standard Checklist 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.