Migrating to Jira? Use Rovo + Automation to Convert HTML Descriptions to Jira Markdown

[#1]

If you've ever migrated data into Jira from systems like TFS (Team Foundation Server), Azure DevOps, or other platforms, you've likely encountered a frustrating problem: your carefully formatted descriptions land in Jira as raw HTML strings that look nothing like they should.

Here's a practical approach to solving this using a Rovo agent and Jira Automation—no scripting or external tools required.

The Problem

When exporting data from external systems, description fields often come across as raw HTML:

<div><p>As a <strong>user</strong>, I want to...</p><ul><li>Item 1</li><li>Item 2</li></ul></div>

Instead of the nicely formatted text your users expect, they see angle brackets and HTML tags cluttering up their work items. Manually cleaning up hundreds or thousands of migrated issues isn't realistic. Sure, you could program a solution, but why bother if a quicker option is available?

The Solution: Rovo Agent + Jira Automation

The approach involves two components:

1. A Rovo agent that skillfully converts HTML to Jira's markdown format
2. An automation rule that triggers the agent and updates the description field

The best part? You can use Rovo itself to help you build the automation rule.

Step 1: Create the Rovo Agent

First, create an agent specifically for HTML-to-markdown conversion.

Navigate to your Rovo agents and create a new agent. The key is in the prompt—you need to be specific about which markdown format to use, because Jira's markdown behaves differently depending on context.

The Gotcha: Tune For Context

Here's something I discovered through trial and error: while Rovo is excellent at converting HTML to markdown out of the box, the output that works perfectly when you invoke the agent directly (from the Jira UX) doesn't always work within automation.

The issue concerns how Jira Automation's smart values (using the Mustache library) handle certain characters. Headings using # symbols, for example, can break when passed as the smart value {{agentResponse}}.

The solution is to create two scenarios in your agent:

Scenario 1: Default (for ad-hoc use from Jiras' UX)

Here is the prompt for this scenario:

---- PROMPT START ----

You are an expert assistant for transforming HTML strings into markdown that renders well in Jira long text fields. You have deep knowledge of HTML, CSS, and the markdown format supported by Jira. Your primary task is to convert the Description field (when provided as an HTML string) into Jira-compatible markdown, ensuring the output is clean, readable, and visually appealing within Jira.
These are your references for the Markdown used by Jira:

https://support.atlassian.com/jira-software-cloud/docs/markdown-and-keyboard-shortcuts/

When you transfer HTML tables, use this page as a reference: https://confluence.atlassian.com/bitbucketserverm0930/markdown-syntax-guide-1431541351.html

By default, respond only with the converted markdown string—do not add any introductory or trailing text. If the user specifically requests an explanation, provide a detailed breakdown of how the HTML was converted to Jira markdown, including the handling of formatting, lists, links, and other elements. Always respond to user requests concisely and accurately.

---- PROMPT END ----

Note that the prompt includes specific instructions on how to treat specific formats (like tables). These were added to overcome errors. So it's important to test your agent with inputs that reflect your data.

Also, the last section requests that the agent not add text before or after the converted text. Rovo tends to be too chatty this way, and these instructions help keep the response from overflowing into chatty territory.

Scenario 2: For Automation

When the agent is invoked through automation, headings need to use the old-style wiki format (h1., h2., etc.) instead of # symbols. This format is more compatible with smart values in automation.

Add a second scenario with instructions like:

---- PROMPT START ----

Because you are now running inside an automation rule, when you convert headings, please use the notation explained here: https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=headings

This will avoid that your response will be broken by subsequent steps of automation.

Otherwise, follow all the instructions in your default scenario

---- PROMPT END ----

Step 2: Create the Automation Rule

Here's where it gets interesting—you can use Rovo to help create the automation rule itself.

Give Rovo this prompt:

We need an automation rule that:

1. Is triggered manually from work items
2. Checks if the description field contains HTML
3. If it does, invokes the agent that can translate HTML to markdown using the appropriate scenario
4. Updates the description with the response from the agent

Rovo will generate most of the rule structure for you. It understands:

• Setting up manual triggers
• Creating conditions to detect HTML (looking for HTML tags like < and >)
• Calling an agent action
• Using {{agentResponse}} to capture the output

You'll need to manually configure which agent to use, but the heavy lifting is done.

The Complete Rule Structure

1. Trigger: Manual trigger from work items
2. Condition: Check if description contains HTML (e.g., contains <div> or <p> or similar HTML markers)
3. Action: Use Rovo agent
   • Specify that it's invoked via Jira Automation (to trigger the correct scenario)
   • Tell it to convert the description of the current work item to Jira Markdown
4. Action: Edit issue

Set Description = {{agentResponse}}




Results

Before running the automation, you have raw HTML cluttering your descriptions. After? Clean, properly formatted Jira content—headings, lists, tables, and all.

The table conversion was particularly tricky. Without specific instructions pointing the agent to Jira's table formatting documentation, tables would break. With the right references in the agent prompt, even complex tables render correctly.

When to Use Each Scenario

• Ad-hoc conversion: When you're working on a single issue and want to copy-paste the result, use the agent directly. The # heading style works perfectly here.

• Bulk conversion via automation: When processing multiple issues, the automation rule with the old-style heading format (h1., h2.) ensures consistent results.

Summary

Migrating data into Jira doesn't have to mean accepting ugly HTML in your descriptions. With a Rovo agent configured with the right prompts and scenarios, plus a simple automation rule, you can clean up migrated content at scale.

Key takeaways:

• Be specific about which markdown references the agent should follow
• Create separate scenarios for ad-hoc use vs. automation
• Use old-style wiki heading format (h1., h2.) when working through automation
• Let Rovo help you build the automation rule itself
• Test with a variety of representative examples before running at scale. HTML is vast, and your data may have edge cases beyond what I encountered—tables, nested lists, special characters, or formatting combinations that need additional handling