knowledge-article-lwc

# Knowledge Article LWC

Use this skill when a Lightning Web Component must retrieve and render Salesforce Knowledge article content, or accept user feedback such as thumbs-up/thumbs-down voting. It covers the correct Apex-backed retrieval pattern, Experience Cloud guest access requirements, and voting via custom Apex endpoints.

---

## Before Starting

Gather this context before working on anything in this domain:

- **Article object name**: Confirm whether the org uses the standard `Knowledge__kav` or a legacy custom article type (e.g. `FAQ__kav`). The object API name affects every SOQL query.
- **Target surface**: Determine whether the component will run inside an internal app (authenticated user, full sharing rules), an Experience Cloud site with authenticated members, or an Experience Cloud site with guest user access. Guest access is the most constrained case and drives significant design decisions.
- **Data category structure**: If the org uses data categories, identify which category groups and values articles are assigned to. Data category visibility settings control which articles are visible to which users, including guests. Missing category visibility is the most common reason articles do not appear for guest users.
- **Article fields needed**: Rich text body fields (`Body__c` on custom types, or the standard `Body` field) render HTML. Identify all fields needed upfront to avoid extra round trips.
- **Voting / feedback requirement**: If users should rate articles, a custom Apex method with `without sharing` or an explicit sharing declaration is required — there is no platform-native wire adapter for Knowledge voting.

---

## Core Concepts

### No Dedicated Wire Adapter for Knowledge

Salesforce does not provide a Lightning Data Service wire adapter specifically for Knowledge articles. There is no `@wire(getKnowledgeArticle)` equivalent in the platform wire service. All Knowledge article retrieval must go through one of two paths:

1. `@wire(getRecord, { recordId, fields })` — works for single article records when you have a record ID and the running user has read access via sharing and data category visibility. Cannot be used for search-based retrieval.
2. A custom `@AuraEnabled(cacheable=true)` Apex method that executes SOQL or SOSL against `Knowledge__kav` (or the custom article type) and returns the result. This is the standard pattern for all search-driven or list-based retrieval.

The `cacheable=true` annotation on Apex is mandatory for methods wired with `@wire`. Methods called imperatively (e.g., on button click) must NOT be annotated `cacheable=true` if they perform DML or call non-deterministic logic.

### Knowledge__kav SOQL and SOSL Queries

`Knowledge__kav` represents published article versions. The key fields and constraints are:

- `PublishStatus = 'Online'` — always filter to this value to return only live articles. Omitting this filter returns draft, archived, and online versions.
- `Language = 'en_US'` — filter by language code when the org has multi-language Knowledge enabled.
- `IsVisibleInApp`, `IsVisibleInPkb`, `IsVisibleInCsp`, `IsVisibleInPrm` — channel visibility flags. For Experience Cloud (formerly Community), `IsVisibleInPkb` must be `true`.
- `DataCategorySelections` — a child relationship, not directly queryable in a standard SOQL `WHERE` clause. Data category filtering in SOQL uses the special `WITH DATA CATEGORY` clause: `SELECT Id, Title FROM Knowledge__kav WHERE PublishStatus = 'Online' WITH DATA CATEGORY Products__c ABOVE 'All'`.
- SOSL with `FIND` supports full-text search across article content fields and respects data category visibility automatically when run in the user's context.

Guest users execute queries in the Guest User context. Sharing rules for Knowledge in guest contexts are controlled by the org-wide default for Knowledge and by Guest User data category visibility settings in Setup > Channels > Data Category Visibility.

### Experience Cloud Guest Access and Data Category Visibility

Experience Cloud guest users are unauthenticated visitors. They share a single Guest User record. For a Knowledge article to be visible to a guest user, ALL of the following must be true:

1. The Knowledge org-wide sharing default allows read access to guests (Setup > Sharing Settings > Knowledge, or the site's guest sharing override).
2. The article's `IsVisibleInPkb` field is `true`.
3. The Guest User has data category visibility for the category the article is filed under (Setup > Data Category Visibility in Experience Workspaces, or org-level Guest Category Visibility).
4. The Apex controller class must be marked `without sharing` or use an explicit `with sharing` declaration that permits guest access; otherwise the guest user context will deny the query.

Misconfiguring any one of these four conditions silently returns zero results rather than throwing an error, which makes this extremely difficult to debug without systematically checking each layer.

### Voting and Feedback via Custom Apex

The standard Knowledge `KnowledgeArticleViewStat` and `KnowledgeArticleVoteStat` objects are read-only aggregates computed by the platform. To record a user vote, use the `KbManagement.PublishingService` Apex class (available in API 30+):

```apex
KbManagement.PublishingService.rateKnowledgeArticle(articleId, rating, userId);
```

Where `rating` is an integer from 1–5. There is no direct DML on `KnowledgeArticleVoteStat`. This method must be called from a non-cacheable `@AuraEnabled` Apex method (not wired) triggered by an explicit user action. The call counts against governor limits as a DML statement equivalent.

---

## Common Patterns

### Pattern: Wired SOSL Search Component

**When to use:** A search bar LWC where the user types a query and the component surfaces matching Knowledge articles in real time or on submit.

**How it works:**

1. The LWC captures the user's search string from an input event.
2. On input change (debounced) or on form submit, the component calls an imperative Apex method (not wired, because the search string is dynamic) decorated with `@AuraEnabled(cacheable=true)`.
3. The Apex method runs a SOSL query against `Knowledge__kav` scoped to `PublishStatus = 'Online'` and the appropriate channel visibility flag.
4. The Apex method returns a `List<Knowledge__kav>` (or a wrapper DTO) to the component.
5. The component renders results using `for:each` iteration in the HTML template.

**Why not the alternative:** Using `@wire` with a reactive property for the search string works, but it fires immediately on every keystroke. An imperative call with client-side debounce gives better UX and reduces Apex invocations.

### Pattern: Single Article Display via getRecord Wire

**When to use:** A detail page component where the article ID is available via `@api recordId` from the record page (e.g., an Experience Cloud article detail page).

**How it works:**

1. Declare the component with `@api recordId`.
2. Use `@wire(getRecord, { recordId: '$recordId', fields: FIELDS })` where `FIELDS` is an array of field references imported from `@salesforce/schema`.
3. Extract field values using `getFieldValue` from `lightning/uiRecordApi`.
4. Render the body HTML using `lightning-formatted-rich-text` (not `innerHTML` — see anti-patterns).

**Why not the alternative:** A custom SOQL Apex call for a single known record ID introduces unnecessary overhead. `getRecord` is served from Lightning Data Service cache and does not count against Apex limits for simple field reads.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Single article detail page, record ID in URL | `@wire(getRecord)` with `lightning/uiRecordApi` | Uses LDS cache, no Apex limits consumed |
| Search-driven article list | Imperative `@AuraEnabled(cacheable=true)` Apex + SOSL | Dynamic input cannot be wired declaratively without complex reactive property management |
| Filtered article list (category, channel) | `@AuraEnabled(cacheable=true)` Apex + SOQL with `WITH DATA CATEGORY` | Only SOQL supports structured data category filtering |
| Experience Cloud guest users | Apex controller marked `without sharing`, guest data category visibility configured | Guest user context lacks sharing privileges; declarative visibility must be set explicitly |
| User voting / rating | Non-cacheable `@AuraEnabled` Apex calling `KbManagement.PublishingService.rateKnowledgeArticle` | No DML or LDS mutation API for Knowledge votes; platform service method is the only supported path |
| Rendering rich text article body | `lightning-formatted-rich-text value={bodyField}` | Prevents XSS from unescaped HTML; never use `innerHTML` for Knowledge body content |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Confirm the article object and fields**: Identify the article type API name (`Knowledge__kav` or custom), required fields (Title, Summary, Body, channel flags, language), and whether multi-language is enabled. Check Setup > Knowledge Settings.
2. **Determine the target surface and access model**: Identify whether the component runs on an internal app page, an Experience Cloud authenticated page, or a guest-accessible page. For guest access, check Guest User data category visibility and sharing settings before writing any code.
3. **Choose the retrieval pattern**: Use `@wire(getRecord)` for single known-record-ID detail pages. Use an imperative `@AuraEnabled(cacheable=true)` Apex method with SOSL for search, or SOQL with `WITH DATA CATEGORY` for category-scoped list views.
4. **Write the Apex controller**: Implement `@AuraEnabled(cacheable=true)` retrieval methods. For Experience Cloud guest scenarios, declare the class `without sharing` and filter `IsVisibleInPkb = true`. For voting, implement a separate non-cacheable `@AuraEnabled` method calling `KbManagement.PublishingService.rateKnowledgeArticle`.
5. **Build the LWC**: Import Apex methods with `@salesforce/apex`. Use `@wire` for cacheable methods bound to reactive properties, or call methods imperatively inside event handlers. Render body content exclusively with `lightning-formatted-rich-text`.
6. **Test Experience Cloud guest access end to end**: Preview the site as a guest user, not just as an admin. Admin previews bypass sharing and category visibility. A dedicated guest-context test is mandatory before marking complete.
7. **Write Apex tests**: Cover both the happy path and the case where no articles match (empty list return). Test `without sharing` methods explicitly. Aim for 90%+ coverage on the Apex controller.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] SOQL/SOSL queries filter `PublishStatus = 'Online'` and the correct channel visibility flag
- [ ] Rich text body fields rendered exclusively via `lightning-formatted-rich-text`, not `innerHTML`
- [ ] Experience Cloud guest scenarios: data category visibility and `IsVisibleInPkb` confirmed in Setup
- [ ] Apex controller sharing declaration is appropriate for the target user context
- [ ] Voting/feedback uses `KbManagement.PublishingService.rateKnowledgeArticle`, not DML on vote stat objects
- [ ] Apex test classes cover empty-result scenarios and achieve 90%+ coverage
- [ ] Component tested in the actual target surface (guest preview for Experience Cloud, not admin preview)

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **No wire adapter for Knowledge content** — There is no platform-provided `@wire` adapter for Knowledge articles beyond `getRecord`. Developers who search LWC docs for a dedicated Knowledge wire adapter will not find one; all search and list retrieval must go through custom Apex.
2. **Guest user silently returns zero records** — When data category visibility is not configured for the Guest User profile, SOQL queries against `Knowledge__kav` return an empty list without throwing an exception. This masquerades as "no matching articles" when the real issue is a missing visibility grant.
3. **`WITH DATA CATEGORY` clause cannot be combined with all SOQL features** — `WITH DATA CATEGORY` is mutually exclusive with aggregate functions and certain subqueries. Attempting `SELECT COUNT(Id) FROM Knowledge__kav WITH DATA CATEGORY ...` throws a compile-time error.
4. **`KnowledgeArticleVoteStat` is read-only** — There is no DML path to insert or update vote records. The only supported method to record a vote is `KbManagement.PublishingService.rateKnowledgeArticle`. LLMs frequently generate `insert` or `upsert` statements against this object, which fail at runtime.
5. **Admin Experience Cloud preview bypasses sharing** — Testing a Knowledge LWC as a site administrator in Experience Builder preview does not replicate guest user sharing or category visibility. Articles that appear in admin preview can be invisible to actual guest users. Always test in an incognito browser session against the live or preview site URL.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `KnowledgeArticleController.cls` | Apex class with `@AuraEnabled(cacheable=true)` retrieval methods and a non-cacheable voting method |
| `KnowledgeArticleControllerTest.cls` | Apex test class with happy path and empty-result coverage |
| `knowledgeArticleList/` | LWC bundle for search and list display of Knowledge articles |
| `knowledgeArticleDetail/` | LWC bundle for single article detail rendering |
| Setup checklist | Documented data category visibility and guest sharing configuration steps |

---

## Related Skills

- `admin/knowledge-setup` — Knowledge Settings, article types, data categories, and publishing workflows; required prerequisite before building LWC retrieval
- `lwc/experience-cloud-guest-access` — Broader Experience Cloud guest user sharing patterns beyond Knowledge
- `agentforce/einstein-copilot-for-service` — Einstein Article Recommendations and Copilot-driven article surfacing; distinct from custom LWC retrieval