{"id":207,"date":"2026-04-03T13:08:14","date_gmt":"2026-04-03T18:08:14","guid":{"rendered":"https:\/\/www2.dataunfold.com\/?post_type=docs&p=207"},"modified":"2026-04-03T13:10:56","modified_gmt":"2026-04-03T18:10:56","password":"","slug":"widgets","status":"publish","type":"docs","link":"https:\/\/www2.dataunfold.com\/?docs=widgets","title":{"rendered":"Widgets"},"content":{"rendered":"\n

# Deep Guide: Widgets in DataUnfold<\/strong><\/p>\n\n\n\n

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.<\/p>\n\n\n\n

## Overview \u2705<\/strong><\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Widgets depend on:<\/p>\n\n\n\n

– Ingested files (evidence)<\/p>\n\n\n\n

– Tags and smart-tags (to identify what to extract)<\/p>\n\n\n\n

– Post-processing and widget rebuild actions (to aggregate and produce final answers)<\/p>\n\n\n\n

## Widget concepts & vocabulary \ud83d\udd0d<\/strong><\/p>\n\n\n\n

– **Tag**<\/strong>: Named field used as evidence (event-scope or project-scope). Widgets commonly consume *event-scope*<\/em> tags as evidence and store results in a project-scope tag.<\/p>\n\n\n\n

– **Tag proof \/ Evidence**<\/strong>: Extracted items stored per file that are used to compute widget answers.<\/p>\n\n\n\n

– **Generate\/Regenerate**<\/strong>: Action to build or rebuild the widget’s answer from available evidence.<\/p>\n\n\n\n

– **Scope**<\/strong>: Widgets are project-scoped (they summarize across files), while timeevent tags are tied to individual files.<\/p>\n\n\n\n

– **Placeholder \/ Variable**<\/strong>: A widget’s `variable` (unique name) used by other actions and templates to reference the widget’s latest answer.<\/p>\n\n\n\n

## How to add a widget (UI steps) \u2733\ufe0f<\/strong><\/p>\n\n\n\n

1. Open a project and go to the **Widgets**<\/strong> or **Actions**<\/strong> area.<\/p>\n\n\n\n

2. Click **Add Widget**<\/strong> (or **Create Widget**<\/strong>).<\/p>\n\n\n\n

3. Fill required fields:<\/p>\n\n\n\n

   – **Name**<\/strong>: user-visible label (e.g., “Total Contract Value”).<\/p>\n\n\n\n

   – **Variable**<\/strong>: short unique identifier (e.g., `total_contracts`) used in templates and actions.<\/p>\n\n\n\n

   – **Description\/Prompt**<\/strong>: What the widget computes (you can use tags and variables here).<\/p>\n\n\n\n

   – **Filter\/Query (optional)**<\/strong>: Restrict evidence to files matching tags, date ranges, or other criteria.<\/p>\n\n\n\n

4. Configure triggers and refresh behavior (manual, on upload, scheduled).<\/p>\n\n\n\n

5. Save the widget.<\/p>\n\n\n\n

## Widget configuration options (detailed) \u2699\ufe0f<\/strong><\/p>\n\n\n\n

– **Variable\/Name**<\/strong>: Choose stable short variable names for reuse in templates\/actions.<\/p>\n\n\n\n

– **Description \/ Prompt**<\/strong>: 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.<\/p>\n\n\n\n

– **Filters**<\/strong>: Limit which files\/timeevents are considered (by tags, file types, date ranges, or collections).<\/p>\n\n\n\n

– **Refresh Triggers**<\/strong>:<\/p>\n\n\n\n

  – Manual: user clicks *Regenerate*<\/em><\/p>\n\n\n\n

  – Automatic on file ingestion: re-run when new files are processed<\/p>\n\n\n\n

  – Scheduled: run on a schedule (if available)<\/p>\n\n\n\n

– **Dependencies**<\/strong>: Some widgets can depend on other widget outputs (be careful to avoid circular dependencies).<\/p>\n\n\n\n

## Common widget types & examples \ud83e\udde9<\/strong><\/p>\n\n\n\n

1. **Numeric aggregation**<\/strong> \u2014 e.g., “Total Contract Value”<\/p>\n\n\n\n

   – Evidence: `Amount` smart-tag extracted per file<\/p>\n\n\n\n

   – Output: single number (sum)<\/p>\n\n\n\n

   – Description example: “Sum the values of the `{amount}` tag across all files that have tag `contract` in this project.”<\/p>\n\n\n\n

2. **Count metrics**<\/strong> \u2014 e.g., “Number of Contracts”<\/p>\n\n\n\n

   – Output: count of files or matched evidences<\/p>\n\n\n\n

3. **List extraction**<\/strong> \u2014 e.g., “All Named Parties”<\/p>\n\n\n\n

   – Output: deduplicated list of party names extracted from files<\/p>\n\n\n\n

4. **Text summary**<\/strong> \u2014 e.g., “Case Summary”<\/p>\n\n\n\n

   – Output: short paragraph summarizing the main findings from the evidence<\/p>\n\n\n\n

5. **Structured JSON output**<\/strong> \u2014 when you need stable machine-readable output for further automation<\/p>\n\n\n\n

   – Request JSON with specific keys in the description\/prompt to ensure consistent parsing<\/p>\n\n\n\n

## Using widgets in workflows & templates \ud83d\udd17<\/strong><\/p>\n\n\n\n

– Reference a widget in templates and actions via its `variable` (e.g., `{total_contracts}`).<\/p>\n\n\n\n

– Use widget outputs in generated DOCX templates, exports, and other actions to automatically populate reports.<\/p>\n\n\n\n

## Regeneration & Scheduling \ud83d\udd04<\/strong><\/p>\n\n\n\n

– Manual regenerate: used to re-run aggregation immediately (useful while reviewing evidence).<\/p>\n\n\n\n

– Automatic regenerate on ingestion: recommended when you want widgets to stay up-to-date as new files arrive.<\/p>\n\n\n\n

– Scheduled runs: use for nightly rebuilds when heavy work or many files exist.<\/p>\n\n\n\n

## Troubleshooting widgets \u2014 checklist & common fixes \ud83d\udee0\ufe0f<\/strong><\/p>\n\n\n\n

If a widget does not produce the expected answer:<\/p>\n\n\n\n

– Check evidence: Are there `tag_proof` entries for the widget’s required tags? If not, confirm ingestion succeeded.<\/p>\n\n\n\n

– Confirm filters: Ensure the widget filter\/query is not overly restrictive.<\/p>\n\n\n\n

– Verify post-processing: Confirm the post-processing service is running and processing the `generatewidget` actions.<\/p>\n\n\n\n

– Inspect task queue & logs: Look at active tasks and post-processing logs for errors or timeouts.<\/p>\n\n\n\n

– Avoid circular dependencies: If widget A depends on widget B and vice versa, rebuild will fail or behave unpredictably.<\/p>\n\n\n\n

Common error situations and responses:<\/p>\n\n\n\n

– “No evidence found”: Re-check tagging \/ smart-tag detection rules and upload a few test documents with the target content.<\/p>\n\n\n\n

– “Output format invalid”: Make the description specify a strict output format (e.g., “Return a single integer” or JSON with keys).<\/p>\n\n\n\n

– “Widget stuck in pending state”: Check message queue, post-processing and websocket services.<\/p>\n\n\n\n

## Best practices & tips \ud83d\udca1<\/strong><\/p>\n\n\n\n

– Start small: create simple widgets first (count or sum), validate the evidence extraction, then add complexity.<\/p>\n\n\n\n

– Use strict expected output formats when using widgets in automation (e.g., JSON with explicit keys).<\/p>\n\n\n\n

– Name variables clearly and include a description for team members.<\/p>\n\n\n\n

– For numeric values ensure the tag extraction normalizes formatting\/currencies before aggregation.<\/p>\n\n\n\n

– Document widget behavior in the project description or a shared README if used by multiple team members.<\/p>\n\n\n\n

## QA Checklist for widgets \u2705<\/strong><\/p>\n\n\n\n

– [ ] Widget saves successfully and appears in the widget list<\/p>\n\n\n\n

– [ ] Widget variable name is unique and stable<\/p>\n\n\n\n

– [ ] Evidence exists for at least one matching file (verify `tag_proof` rows)<\/p>\n\n\n\n

– [ ] Regenerate returns a valid result (right type and format)<\/p>\n\n\n\n

– [ ] Automatic regeneration triggers when new files are ingested<\/p>\n\n\n\n

– [ ] Actions that consume the widget variable populate templates correctly<\/p>\n\n\n\n

– [ ] No errors or timeouts in post-processing logs<\/p>\n\n\n\n

– [ ] Edge cases tested (no evidence, multiple evidence items, malformed data)<\/p>\n\n\n\n

## Example: Create a “Total Contract Value” widget (step-by-step) \ud83e\uddfe<\/strong><\/p>\n\n\n\n

1. Add widget: Name = “Total Contract Value”, Variable = `total_contract_value`.<\/p>\n\n\n\n

2. Description: “Sum the numeric values in the `{contract_value}` tag across all files tagged with `contract`. Return a single number (no currency symbol).”<\/p>\n\n\n\n

3. Filters: Tag = `contract`.<\/p>\n\n\n\n

4. Trigger: Regenerate automatically on ingestion.<\/p>\n\n\n\n

5. Test: Upload two sample contracts with values $1000 and $2,500. Regenerate and confirm output `3500`.<\/p>\n\n\n\n

## Admin notes (service-mode implications) \ud83d\udee1\ufe0f<\/strong><\/p>\n\n\n\n

– Widgets are generated by post-processing service; ensure that service is properly configured and healthy in service-mode deployments.<\/p>\n\n\n\n

– For heavy projects, prefer scheduled regeneration to avoid spikes in processing.<\/p>\n","protected":false},"excerpt":{"rendered":"

# 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 \u2705 Widgets are project-level summaries and analytics that aggregate evidence extracted from files. Widgets can compute numeric metrics (totals, averages), […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"doc_category":[5,10],"doc_tag":[],"class_list":["post-207","docs","type-docs","status-publish","hentry","doc_category-getting-started","doc_category-projects"],"year_month":"2026-04","word_count":1024,"total_views":0,"reactions":{"happy":0,"normal":0,"sad":0},"author_info":{"name":"dataunfold","author_nicename":"dataunfold","author_url":"https:\/\/www2.dataunfold.com\/?author=1"},"doc_category_info":[{"term_name":"Getting Started","term_url":"https:\/\/www2.dataunfold.com\/?doc_category=getting-started"},{"term_name":"Projects","term_url":"https:\/\/www2.dataunfold.com\/?doc_category=projects"}],"doc_tag_info":[],"_links":{"self":[{"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/docs\/207","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=207"}],"version-history":[{"count":1,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/docs\/207\/revisions"}],"predecessor-version":[{"id":208,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=\/wp\/v2\/docs\/207\/revisions\/208"}],"wp:attachment":[{"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=207"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_category&post=207"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/www2.dataunfold.com\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_tag&post=207"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}