Skip to main content

Convert Story to Defect

Backlog items (stories) convert to defects when work reveals bugs or issues rather than new features. Conversely, defects convert to backlog items when the issue requires feature development rather than a fix.

Who converts between stories and defects: Team members request conversions when discovering work is miscategorized during development. Scrum masters coordinate conversions to ensure proper sprint planning and velocity tracking. Product owners approve conversions that impact sprint scope or priorities. Project admins may need to adjust workspace configurations to enable smooth conversions.

Permission requirement: Converting between stories and defects requires edit permissions on the item (typically Team Member role or higher). If Type fields are required in the target asset type, you may need Project Admin permissions to temporarily adjust field requirements. Conversions delete the original item and create a new one, preserving relationships and history. Specific permissions depend on your organization's role configuration.

When to Convert​

Convert backlog items to defects or vice versa in these situations:

  • Story reveals a defect: During development, you discover the work is actually a bug fix rather than a new feature.
  • Defect requires feature work: A reported defect needs new functionality rather than fixing existing code.
  • Categorization error: A work item was created with the wrong type and needs reclassification.
  • Portfolio restructuring: Changing how you categorize work for reporting or tracking purposes.

What Happens During Conversion​

When you convert a backlog item to a defect (or vice versa), Agility handles the transition carefully:

  • Common fields preserved: Data in fields shared between backlog items and defects (Title, Description, Status, Estimate, Owner, Priority, Sprint) is copied to the new asset.
  • Relationships maintained: Tasks, tests, dependencies, links, and attachments are moved to the new asset.
  • History retained: The original item's change history is preserved in the new asset.
  • Original deleted: After successful conversion, the original backlog item or defect is deleted automatically.
  • Type-specific fields lost: Fields unique to the source type (e.g., Story Type on backlog items, Defect Type on defects) are not transferred if they don't exist on the target type.

Convert Backlog Item to Defect​

Follow these steps to convert a story or backlog item into a defect.

  1. Click the hamburger icon Hamburger Icon > Product > Backlog.
  2. Locate the backlog item you want to convert to a defect.
  3. Open the Edit menu on the right side of the backlog item.
  4. Select Convert > Convert To Defect.
  5. On the Convert page, review and edit the data as needed. Pay attention to defect-specific fields like Defect Type, Resolution, and Verified By.
  6. Click Convert, then click OK to confirm.

The backlog item is now a defect. All tasks, tests, and relationships are preserved.

Convert Defect to Backlog Item​

Follow these steps to convert a defect back into a story or backlog item.

  1. Click the hamburger icon Hamburger Icon > Product > Backlog.
  2. Locate the defect you want to convert to a backlog item.
  3. Open the Edit menu on the right side of the defect.
  4. Select Convert > Convert To Story (or the appropriate backlog item type).
  5. On the Convert page, review and edit the data. Add values for story-specific fields like Story Type if they are required.
  6. Click Convert, then click OK to confirm.

The defect is now a backlog item with all relationships intact.

Troubleshooting​

Convert option missing from Edit menu

The Convert option requires edit permissions on the backlog item or defect. If Convert is missing: (1) You may lack edit permissions—check your project role. (2) The item may be closed—reopen it before converting. (3) The item may be in a closed sprint or project—reopen the container first. (4) Your organization may have disabled conversions through customization. Verify the item's status and your permissions, or contact your Project Admin.

Data lost after converting between story and defect

Type-specific fields don't transfer during conversion because they don't exist on the target asset type. For example, Story Type (on backlog items) and Defect Type (on defects) are separate fields with no automatic mapping. Other type-specific fields like Resolution (defects only) also don't transfer. To minimize data loss: (1) Document important type-specific field values before converting, (2) Manually re-enter them after conversion, or (3) Use custom fields that exist on both asset types for critical data.

Can't convert defect that has tasks and tests

Defects with tasks and tests can be converted—the system transfers all relationships to the new backlog item. If conversion fails, the issue is likely: (1) A required field validation error on the target type, (2) Permission issues, or (3) The item is in a closed state. Check error messages for specific guidance. Tasks and tests are preserved during conversion, maintaining all work breakdown and verification criteria.

Type Field Errors During Conversion​

If you receive a "Type" error when converting between backlog items and defects, it's because the Type field differs between the two asset types and required fields aren't populated.

Why This Happens:

  • The Type field for backlog items (Story Type) is separate from the Type field for defects (Defect Type).
  • There is no automatic mapping between these fields during conversion.
  • If the target asset type has a required Type field and it's empty after conversion, the save operation fails with an error.

Solution—Temporarily Remove Required Status:

To work around this issue:

  1. Click the hamburger icon > Admin > Projects > select your project.
  2. Navigate to Workspaces > Project Workspace.
  3. Find the Defect Type field (or Story Type if converting the other direction).
  4. Uncheck the Required option for that field.
  5. Click Save to apply the change.
  6. Return to the backlog and complete the conversion (following steps above).
  7. After conversion, assign the correct Type value to the converted item.
  8. Return to project workspace settings and restore the Required status for the Type field.

Prevention Tips:

  • Pre-populate Type fields before converting by manually adding a value to the target Type field if possible.
  • Review required fields—check which fields are required in the target asset type before starting the conversion.
  • Use templates—create defect or story templates with default Type values to standardize conversions.

Feature Request:

A similar enhancement request exists in the Digital.ai Agility IdeaSpace to improve the conversion experience:

Vote or comment on this feature request to support improved Type field handling during conversions.

Best Practices for Converting Work Items​

  1. Review before converting: Check the item's relationships, tasks, and tests to ensure they make sense in the new context.
  2. Update Type fields after conversion: Immediately assign the correct Story Type or Defect Type to maintain data integrity.
  3. Notify team members: If the item is assigned or has watchers, inform them of the conversion to avoid confusion.
  4. Adjust estimates if needed: Converting between types may require revisiting size estimates, especially if the scope changes.
  5. Update sprint planning: If the item is in an active sprint, discuss with the team whether it should remain or be moved.
  6. Preserve history: Take advantage of the retained history by reviewing the original item's change log after conversion.
  7. Use sparingly: Conversions should be occasional corrections, not a regular workflow. Create items with the correct type initially.
  8. Document the reason: Add a comment or history note explaining why the conversion occurred for future reference.
  9. Check required fields: Before converting, verify which fields are required in the target type to avoid errors.
  10. Consolidate when possible: If converting multiple related items, consider whether they should be merged into a single defect or story.