dotCMS / dotCMS/core

[DOCS] dotAI: Document new provider configuration UI

Open
#37,505 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

dotCMS : AI Team : Scout
Dominant language
Java
Stars
970
Forks
486
Avg merge
3d 33m
Merged PRs (30d)
170

Description

Problem Statement

dotAI's provider configuration moved from a hand-authored JSON textarea to a structured settings UI (#36826, shipped in #37048): per-capability cards (Chat / Embeddings / Image), dynamic field rendering driven by provider metadata, a "Test Connection" flow per capability, and a generic "Additional properties" escape hatch for provider fields not yet modeled in the form.

Public documentation still describes (or omits) this configuration surface as it existed before the redesign. It needs to reflect the current portlet, screen by screen, and also close the gap left by #35597: the underlying providerConfig JSON contract itself was never fully documented for API/Postman/automation users who configure dotAI without touching the UI.

Solution

Update the public dotCMS documentation for dotAI provider configuration to describe the new portlet and the JSON contract it saves under the hood.

Acceptance Criteria
  • New provider configuration UI documented: per-capability cards (Chat, Embeddings, Image), enabling/disabling a capability independently, provider selection and which capabilities each provider supports
  • "Test Connection" flow documented per capability, including what a failure looks like
  • Dynamic field behavior documented: required vs. optional fields per provider, requiredUnless cross-field validation (e.g. Azure's model/deploymentName), and how a SECRET field behaves once saved (masked, read-only until edited)
  • "Additional properties" escape hatch documented for provider-specific fields not modeled in the UI
  • Per-site configuration documented (each site can configure its own providers/credentials)
  • providerConfig JSON contract documented: structure (chat, embeddings, image, settings blocks), at least one complete example
  • Field mapping reference for customers still migrating from the pre-LangChain4J individual App secrets to providerConfig (carried over from #35597)
  • Old individual-field / free-form JSON textarea documentation removed or clearly marked as superseded
Links
  • UI implementation: #37048
  • Original UI request: #36826
  • Supersedes: #35597

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the UI implementation linked in #37048, then review the current public dotAI provider documentation and the migration gap from #35597. Document the capability cards, validation, connection testing, per-site behavior, and providerConfig structure with a complete example; remove or mark superseded guidance when every acceptance criterion is covered.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.