Forge App
CogniRunner
AI-powered workflow validation for Jira. Validate any field — including attachments — with custom AI prompts during workflow transitions.
Built on Atlassian Forge
Open Source (AGPL-3.0)
Powered by OpenAI
Overview
CogniRunner adds AI-powered validators and conditions to Jira workflow transitions. Instead of writing complex rules or scripts, describe your validation criteria in plain English — and the AI evaluates field content against your prompt every time an issue transitions.
Validators
Block a transition if validation fails, showing the user a clear error message with the AI's reasoning.
Conditions
Hide a transition entirely if validation fails — the user won't even see the transition button.
CogniRunner works across company-managed and team-managed Jira projects, supports all standard and custom Jira field types, and can analyze the content of attached files and images.
Getting Started
CogniRunner integrates into Jira's native workflow editor. Add a validator or condition in three steps.
1
Open the Workflow Editor
Select a transition and click the Rules panel on the right side. You'll see rule categories: Restrict transition, Request input, Validate details, and Perform actions.
2
Add a New Rule
Click the + button next to "Validate details" (for validators) or "Restrict transition" (for conditions). Find CogniRunner Field Validator under Marketplace Rules.
3
Configure the Validator
Select the field to validate, write your AI prompt, and optionally configure JQL search for duplicate detection. Click Update to save.
Configuring a Validator or Condition
When you add or edit a CogniRunner rule, you'll see the configuration form with three settings.
Field to Validate
Which Jira field the AI should evaluate
Validation Prompt
Your criteria described in natural language
Jira Search (JQL)
Optional duplicate detection via JQL queries
Field Selector
The field selector dropdown shows all fields available on your project's edit/view screens, grouped by system fields and custom fields. Each entry shows the field name, its internal ID, and its type.
When you select Attachment, CogniRunner downloads and analyzes the actual content of attached files — not just the filename. See the Attachment Content Analysis section below for supported formats.
Writing Validation Prompts
The validation prompt is where you describe your quality criteria in natural language. The AI evaluates the field content against this prompt and returns a pass/fail result with reasoning.
Example Prompts
- “Check for similar issues and do not allow if it appears to be a duplicated description meaning.”
- “Make sure that no Atlassian migration is found in this attachment. Explain clearly to the user the rejection.”
- “Verify that this person is not Romanian.”
- “The components are not allowed if they're not pretty.”
- “Make sure the due date is not an odd day.”
The AI's response is always shown to the user when validation fails, so writing prompts that ask the AI to “explain clearly” will produce better error messages.
JQL Search & Duplicate Detection
CogniRunner can search Jira for similar or related issues during validation — enabling AI-powered duplicate detection. The JQL Search setting has three modes.
| Mode | Behavior |
|---|---|
| Auto-detect from prompt | CogniRunner analyzes your prompt text and automatically enables JQL search if it mentions duplicates, similarity, existing issues, or cross-referencing. This is the recommended setting. |
| Always enabled | JQL search is always active, regardless of prompt wording. The AI can run up to 3 rounds of JQL queries to find related issues. |
| Always disabled | No JQL search is performed. Validation is based solely on the field content and prompt. Fastest option. |
When JQL search is active, the AI generates and executes JQL queries against your Jira instance to find related issues. It can run up to 3 rounds of queries, each returning up to 10 results. The AI then uses these results to inform its validation decision.
JQL search adds latency to the validation (up to 22 seconds in the worst case). For simple validations that don't need cross-referencing, use “Always disabled” for the fastest response.
Attachment Content Analysis
When you select Attachment as the field to validate, CogniRunner downloads and analyzes the actual content of attached files. The AI can read documents, spreadsheets, presentations, and understand images.
Document Formats
| Format | Extensions |
|---|---|
.pdf | |
| Word | .docx, .doc |
| Rich Text | .rtf, .odt |
| Excel | .xlsx, .xls |
| CSV / TSV | .csv, .tsv |
| PowerPoint | .pptx, .ppt |
Image Formats (AI Vision)
| Format | Extensions |
|---|---|
| PNG | .png |
| JPEG | .jpg, .jpeg |
| GIF | .gif |
| WebP | .webp |
All image formats are processed via AI vision — the AI understands image content, not just metadata.
Unsupported file types are gracefully skipped — the AI receives metadata about skipped files (filename, size, type) so it can still reference them in its reasoning.
Validation in Action
When a user attempts a workflow transition, CogniRunner evaluates the configured field against your prompt. If validation fails, the transition is blocked and the AI's reasoning is displayed as an error message.
The error message always includes:
- A clear statement that AI Validation failed
- The specific reason for the failure
- When JQL search was used: references to related issue keys
- Enough context for the user to understand what needs to change
Rule Management
Each CogniRunner rule can be enabled or disabled without removing it from the workflow. Useful for temporarily pausing validation during migrations, bulk updates, or troubleshooting.
Active Rule
Disabled Rule
Admin Panel
The CogniRunner Admin panel provides a centralized view of all AI validators and conditions configured across your Jira workflows. Access it from the Jira Apps menu.
Configured Rules
All validators and conditions across every workflow, with type badges, workflow/transition names, field, and prompt preview.
Quick Actions
Edit or disable any rule directly from the table without opening the workflow editor.
Validation Logs
A scrollable history of all validation results, including pass/fail status, issue key, field, AI reasoning, and JQL queries.
Validation Logs
Every validation — whether it passes or fails — is logged with full context. Logs are available in both the Admin panel and the individual rule summary view.
Each log entry includes:
Status — PASS or FAIL badge
Issue key — Links to the Jira issue
Timestamp — When the validation occurred
Field — Which field was validated
AI reasoning — The full explanation from the AI
JQL queries — Queries executed during agentic search
Logs are stored in Forge storage with a maximum of 50 entries (FIFO — oldest entries are removed when the limit is reached).
Supported Jira Field Types
CogniRunner extracts readable text from any Jira field type and sends it to the AI for validation. All field values are converted to plain text before evaluation.
| Category | Field Types |
|---|---|
| Text | Single-line text, Multi-line text, URL |
| Rich Text | Description, Comments, and other ADF fields — full text extraction from rich content |
| Select | Select list (single/multi), Radio buttons, Checkboxes, Cascading select |
| People | User picker (single/multi), Group picker (single/multi), Reporter, Assignee |
| Date & Time | Date picker, Date/Time picker |
| Numeric | Number, Time tracking (original estimate, remaining estimate, time spent) |
| System | Priority, Status, Resolution, Issue type, Labels, Components, Versions, Sprint |
| Reference | Issue links, Parent issue, Project picker |
| Files | Attachments — with full content analysis |
| Custom | Any custom field with a readable value — extracted generically |
Limits & Constraints
| Limit | Value | Notes |
|---|---|---|
| Max attachment size (per file) | 10 MB | Files larger than 10 MB are skipped |
| Max total attachment size | 20 MB | Combined size across all attachments per validation |
| Validation timeout | 25 seconds | Forge function time limit; agentic mode budgets 22 seconds |
| JQL search rounds | 3 rounds max | Each round can execute multiple JQL queries |
| JQL results per query | 10 issues | Top 10 matching issues returned per query |
| Validation log history | 50 entries | Oldest entries removed when limit is reached (FIFO) |
| Prompt log truncation | 200 characters | Field values stored in logs are truncated for storage |
Attachments that exceed the size limit or use unsupported formats are gracefully skipped. The AI still receives metadata about skipped files and can reference them in its reasoning.
AI Infrastructure
CogniRunner's AI is fully managed — the OpenAI integration is handled by the app, not by your team. No API keys to configure, no tokens to track.
All AI processing costs are covered by the app. You install CogniRunner, configure your validation rules, and the AI just works. No OpenAI account or API key required on your end.
Open Source & Free
AGPL-3.0 licensed. The source code is available on GitHub.