Documentation

Quick Start

Get from zero to verified in five steps:

1. Install: Jira Cloud admin installs TrueStory from the Atlassian Marketplace
2. Connect: Salesforce admin completes OAuth connection from the TrueStory settings panel
3. Index: Build your metadata index (one click, maps field labels to API names)
4. Write: Add acceptance criteria to your Jira story description
5. Verify: Click Verify and get Pass / Fail per requirement

Prerequisites

• Jira Cloud with admin rights for installation (Server and Data Center are not supported)
• Salesforce org with API access enabled
• Salesforce user with: metadata read and layout read for metadata verification, plus create and delete permissions on target objects for behavioral verification. We recommend using a dedicated integration user with least-privilege permissions.
• A Salesforce Connected App configured for OAuth. Your Salesforce admin will create a Connected App during setup using the callback URL and scopes that TrueStory provides.

Getting Started

1. Install from Atlassian Marketplace

TrueStory is an Atlassian Forge app for Jira Cloud. Search for “TrueStory” in the Atlassian Marketplace, or ask your Jira admin to install it. Once installed, the TrueStory panel appears on every Jira issue.

2. Connect Your Salesforce Org

Open the TrueStory settings panel in any Jira project and click Connect Salesforce. You'll authenticate via OAuth 2.0. The connected Salesforce user needs the following permissions:

• Metadata read: Tooling API queries for objects, fields, validation rules, and layouts
• Layout read: page layout field membership
• Create & delete temporary test records: on the target object you specify, for behavioral verification only

TrueStory does not intentionally modify existing records. However, creating test records may trigger automations (Flows, Apex triggers, Process Builder) that can interact with existing data. Test records are marked with a [TRUESTORY-TEST] identifier in a standard text field when supported by the object type, and are deleted on a best-effort basis after each test run. You can revoke access at any time from Salesforce Setup → Connected Apps.

3. Build Your Metadata Index

Go to Settings → Metadata Index and click Build Index. TrueStory describes your custom objects and fields, creating a lookup table that maps field labels to API names.

This is what allows labels like Amount or Close Date to resolve to the correct API name in your org (e.g., Amount__c, CloseDate). The index is stored securely in Forge Storage, scoped to your Jira site, and auto-refreshes when you run verification.

If multiple fields match a label, TrueStory marks the requirement as UNMAPPED and suggests candidates so you can clarify with the API name.

Writing Acceptance Criteria

TrueStory parses your Jira issue description line by line. Each line that references a Salesforce component becomes a verifiable requirement. Write in natural language:

• Amount__c is required → detects required
• Status picklist includes: Draft, Approved, Closed → detects picklist
• When Status is Closed, Revenue__c must not be blank → detects conditional_required
• A validation rule should prevent negative values in Quantity → detects validation + negative_value
• Close_Date__c should be a date field → detects field_type

Best Practices

• Use field labels or API names. Both work, but API names (with __c suffix) are more precise.
• One requirement per line for best constraint detection.
• Reference the object name if a field label is ambiguous (e.g., Opportunity.Amount__c).

Constraint Reference

TrueStory supports 19 constraint types. Each constraint is detected via regex pattern matching in the Standard tier. Fully deterministic. The Pro tier adds AI-powered analysis for unstructured stories.

Metadata precheck means TrueStory validates the component exists and is readable before attempting behavioral verification.

Understanding Results

Each requirement receives one of four statuses:

• PASS: Requirement verified. Your org matches the spec.
• FAIL: Org contradicts the requirement. The field, rule, or behavior doesn't match what the AC requires. → Fix the Salesforce configuration or update the acceptance criteria.
• PARTIAL: Verification started but couldn't complete. Usually a permission issue, API timeout, Forge execution limit, or field name mismatch. → Check Salesforce user permissions, field API names, and API limits.
• UNMAPPED: No Salesforce component detected in this AC line. Usually an ambiguous field label, a generic requirement, or a general constraint with no specific check. → Add the object name or use the API name (e.g., MyObject__c.Amount__c).

Behavioral results always take precedence over metadata results. If a behavioral test fails, the requirement is marked FAIL even if metadata checks passed.

Known Limitations

• Forge execution timeouts: Each resolver call has a platform-enforced timeout. Large orgs with many custom objects may hit this during index builds. Current Forge limits may change.
• Index size constraints: The metadata index is constrained by Forge Storage per-key size limits. Large orgs may require support-assisted scoping. Current Forge limits may change.
• Behavioral tests need DML access: The Salesforce user must have create and delete permissions on the target object.
• Validation rule formulas not directly queryable: ErrorConditionFormula is not available in Tooling API SOQL. TrueStory enriches per-record via the Metadata API.
• Flow trigger detection: Not yet supported. TrueStory checks metadata and validation rules, but does not currently verify Flow-triggered automations.

Troubleshooting

OAuth connection failed

Ensure your Salesforce Connected App allows the api and refresh_token scopes. The authenticating user must have “API Enabled” in their Salesforce profile.

Metadata index build times out

Your org likely has too many custom objects for a single index build within Forge execution limits. TrueStory constrains the index to stay within Forge Storage per-key size limits. Contact us if you need support for larger orgs.

Requirements showing as UNMAPPED

The field label in your AC doesn't match any field in the metadata index. Common fixes:

• Use the API name instead of the label (e.g., Amount__c instead of “Amount”)
• Qualify with the object name (e.g., Opportunity.Amount__c)
• Rebuild the metadata index if you recently added fields

PARTIAL: INSUFFICIENT_ACCESS

The Salesforce user doesn't have field-level security or object permissions for the fields being tested. Check the user's profile and permission sets.

PARTIAL: INVALID_FIELD

The field API name doesn't match any field on the object. Check for typos and ensure custom fields include the __c suffix.

PARTIAL: REQUEST_LIMIT_EXCEEDED

Your Salesforce org's API request limits were hit. Retry later or reduce verification frequency. Check your org's API usage in Salesforce Setup → Company Information.

Unexpected test records in Salesforce

TrueStory creates temporary records marked with [TRUESTORY-TEST] in a standard text field (when supported by the object type) and deletes them on a best-effort basis after each run. If cleanup failed (e.g., due to a timeout or trigger), search for records containing this marker and delete them manually.

Avoiding behavioral tests

Behavioral tests run automatically when your acceptance criteria trigger behavioral constraints. This includes required, conditional_required, must_not_allow, save_success, and other constraints marked as Behavioral or Metadata precheck + Behavioral in the constraint table above. There is currently no toggle to disable behavioral tests per run. If you want strictly metadata-only verification (no test record creation), write AC using only metadata constraints such as exists, field_type, picklist, or layout.

Security & Data Handling

TrueStory runs entirely within the Atlassian Forge runtime. For the Jira app, we do not operate separate servers or databases that process your data outside of Atlassian Forge. OAuth tokens are stored encrypted in Forge Storage, scoped to your Jira site. No Jira or Salesforce data is sent to third-party services outside of Atlassian Forge and your connected Salesforce org. Atlassian may generate operational logs as part of the platform infrastructure independently of our application code.

For full details on our security architecture, data handling, and compliance posture, see the Security page.

Support

For setup assistance, custom constraint requests, or enterprise support, reach out at support@revmech.ai. For security questions or vulnerability reports, contact security@revmech.ai or visit our Security page.