# Deep Guide: Widgets in DataUnfold
This guide is a comprehensive, step-by-step reference for using Widgets in DataUnfold. It covers concepts, creation, configuration, triggers, common widget types, examples, troubleshooting, and a QA checklist.
## Overview ✅
Widgets are project-level summaries and analytics that aggregate evidence extracted from files. Widgets can compute numeric metrics (totals, averages), extract structured values (names, dates), or provide textual summaries driven by AI.
Widgets depend on:
– Ingested files (evidence)
– Tags and smart-tags (to identify what to extract)
– Post-processing and widget rebuild actions (to aggregate and produce final answers)
## Widget concepts & vocabulary 🔍
– **Tag**: Named field used as evidence (event-scope or project-scope). Widgets commonly consume *event-scope* tags as evidence and store results in a project-scope tag.
– **Tag proof / Evidence**: Extracted items stored per file that are used to compute widget answers.
– **Generate/Regenerate**: Action to build or rebuild the widget’s answer from available evidence.
– **Scope**: Widgets are project-scoped (they summarize across files), while timeevent tags are tied to individual files.
– **Placeholder / Variable**: A widget’s `variable` (unique name) used by other actions and templates to reference the widget’s latest answer.
## How to add a widget (UI steps) ✳️
1. Open a project and go to the **Widgets** or **Actions** area.
2. Click **Add Widget** (or **Create Widget**).
3. Fill required fields:
– **Name**: user-visible label (e.g., “Total Contract Value”).
– **Variable**: short unique identifier (e.g., `total_contracts`) used in templates and actions.
– **Description/Prompt**: What the widget computes (you can use tags and variables here).
– **Filter/Query (optional)**: Restrict evidence to files matching tags, date ranges, or other criteria.
4. Configure triggers and refresh behavior (manual, on upload, scheduled).
5. Save the widget.
## Widget configuration options (detailed) ⚙️
– **Variable/Name**: Choose stable short variable names for reuse in templates/actions.
– **Description / Prompt**: For AI-driven widgets, the description forms part of the prompt used to aggregate evidence. Include expected output format (e.g., number, short text, JSON) to improve consistency.
– **Filters**: Limit which files/timeevents are considered (by tags, file types, date ranges, or collections).
– **Refresh Triggers**:
– Manual: user clicks *Regenerate*
– Automatic on file ingestion: re-run when new files are processed
– Scheduled: run on a schedule (if available)
– **Dependencies**: Some widgets can depend on other widget outputs (be careful to avoid circular dependencies).
## Common widget types & examples 🧩
1. **Numeric aggregation** — e.g., “Total Contract Value”
– Evidence: `Amount` smart-tag extracted per file
– Output: single number (sum)
– Description example: “Sum the values of the `{amount}` tag across all files that have tag `contract` in this project.”
2. **Count metrics** — e.g., “Number of Contracts”
– Output: count of files or matched evidences
3. **List extraction** — e.g., “All Named Parties”
– Output: deduplicated list of party names extracted from files
4. **Text summary** — e.g., “Case Summary”
– Output: short paragraph summarizing the main findings from the evidence
5. **Structured JSON output** — when you need stable machine-readable output for further automation
– Request JSON with specific keys in the description/prompt to ensure consistent parsing
## Using widgets in workflows & templates 🔗
– Reference a widget in templates and actions via its `variable` (e.g., `{total_contracts}`).
– Use widget outputs in generated DOCX templates, exports, and other actions to automatically populate reports.
## Regeneration & Scheduling 🔄
– Manual regenerate: used to re-run aggregation immediately (useful while reviewing evidence).
– Automatic regenerate on ingestion: recommended when you want widgets to stay up-to-date as new files arrive.
– Scheduled runs: use for nightly rebuilds when heavy work or many files exist.
## Troubleshooting widgets — checklist & common fixes 🛠️
If a widget does not produce the expected answer:
– Check evidence: Are there `tag_proof` entries for the widget’s required tags? If not, confirm ingestion succeeded.
– Confirm filters: Ensure the widget filter/query is not overly restrictive.
– Verify post-processing: Confirm the post-processing service is running and processing the `generatewidget` actions.
– Inspect task queue & logs: Look at active tasks and post-processing logs for errors or timeouts.
– Avoid circular dependencies: If widget A depends on widget B and vice versa, rebuild will fail or behave unpredictably.
Common error situations and responses:
– “No evidence found”: Re-check tagging / smart-tag detection rules and upload a few test documents with the target content.
– “Output format invalid”: Make the description specify a strict output format (e.g., “Return a single integer” or JSON with keys).
– “Widget stuck in pending state”: Check message queue, post-processing and websocket services.
## Best practices & tips 💡
– Start small: create simple widgets first (count or sum), validate the evidence extraction, then add complexity.
– Use strict expected output formats when using widgets in automation (e.g., JSON with explicit keys).
– Name variables clearly and include a description for team members.
– For numeric values ensure the tag extraction normalizes formatting/currencies before aggregation.
– Document widget behavior in the project description or a shared README if used by multiple team members.
## QA Checklist for widgets ✅
– [ ] Widget saves successfully and appears in the widget list
– [ ] Widget variable name is unique and stable
– [ ] Evidence exists for at least one matching file (verify `tag_proof` rows)
– [ ] Regenerate returns a valid result (right type and format)
– [ ] Automatic regeneration triggers when new files are ingested
– [ ] Actions that consume the widget variable populate templates correctly
– [ ] No errors or timeouts in post-processing logs
– [ ] Edge cases tested (no evidence, multiple evidence items, malformed data)
## Example: Create a “Total Contract Value” widget (step-by-step) 🧾
1. Add widget: Name = “Total Contract Value”, Variable = `total_contract_value`.
2. Description: “Sum the numeric values in the `{contract_value}` tag across all files tagged with `contract`. Return a single number (no currency symbol).”
3. Filters: Tag = `contract`.
4. Trigger: Regenerate automatically on ingestion.
5. Test: Upload two sample contracts with values $1000 and $2,500. Regenerate and confirm output `3500`.
## Admin notes (service-mode implications) 🛡️
– Widgets are generated by post-processing service; ensure that service is properly configured and healthy in service-mode deployments.
– For heavy projects, prefer scheduled regeneration to avoid spikes in processing.
