Creating non-standard MadCap Flare reports – an update

This is an update to our previous article on creating non-standard MadCap Flare reports, which you can read here. MadCap Flare is constantly being improved, so we’ve updated our article to stay relevant with the latest version of Flare.

Flare reports are great, no doubt about it. They allow you to find potential issues in your project and fix them faster and more efficiently. You can use them to find broken links, pinpoint unused elements, like images, and identify undefined styles, just to mention a few.

Although you have such a wide variety of reports to pick from, it isn’t possible to cover all the scenarios. Different users look for different things, so sooner or later you’ll need data that isn’t covered by any of the built-in reports. For these cases, we’ll tell you how to generate non-standard MadCap Flare reports.

Standard MadCap Flare reports

Before we move to the procedure of creating non-standard reports, let’s have a quick look at what we can use out of the box.

Generally, we can divide Flare reports into two types: static and dynamic.

Static reports

Static reporting allows you to create custom reports based on the information contained in your project. You can find these reports in Project Organizer > Reports.

To add a new report:

1. Right-click Reports, and select Add Report File.
2. Choose a predefined template or an empty report, and select Add.
3. In the Report Editor window, select parameters according to your needs, and hit Generate.

The report is ready! If you prefer, you can open it in your browser for easier analysis. For more information on static reports, refer to MadCap Flare’s article on reports.

Dynamic reports

In Flare, dynamic reporting is just a small set of reports that display information about your project in a separate window. You can find these reports under Analysis > Summary.

When the Project Analysis window opens, you can browse reports in the Summary section.

These reports look familiar, don’t they? You’re right, the same reports are available in the static form. So what’s the difference? Content-wise, there’s really no difference between the static and dynamic versions of the reports. The main advantage of the dynamic reports is that they refresh automatically each time you change your project. So you don’t have to regenerate them over and over again. It comes in handy, for example, when you’re fixing broken links one by one, and you want to see instantly whether your fix did the job.

For more information on dynamic reports, refer to MadCap Flare’s article on dynamic reporting.

Creating non-standard MadCap Flare reports

Now, let’s move to the fun part – creating non-standard reports. You can use a combination of Flare features to find the data you need and then export it to a CSV file. You can view your CSV file in MS Excel.

What’s needed?

You need the following “ingredients” to prepare a non-standard report:

• The Find and Replace window in Flare
• A good search query
• MS Excel (or alternative software)

How to do it?

To prepare a non-standard report:

1. In Flare, go to the Home tab and select Find and Replace.

2. In the Find and Replace in Files window:
   1. Type in what you want to find.
   2. Choose where you want to find it.
   3. Select Find in source code.
   4. Select the type of search (regular text, wildcards, regular expressions).
   5. Select where you want to display your search results.
   6. Select Find All.

3. When the search is complete, go to the Find Results window, and select .

4. Save the file.
   Now, you have a CSV report that you can process in Excel. You can, for example, format the text as a table and then use filtering to extract the data you need.

As you can see, the procedure is quite simple. But the hardest part is to find the right search query and pair it with the proper search parameters.

I don’t want to be the bad news guy, but here you need to dig into the source code a bit to identify strings that will be useful. MadCap Flare reports have their own XML tags for different elements. For example, when you use a variable named “CompanyName”, the following tag is added to the topic source code:

<MadCap:variable name="Variables.CompanyName" />

If you know what tags Flare uses for specific elements, the search can become a very powerful tool for you. When you add regular expressions to the mix, you’ll become a Flare search master in no time. Of course, it’s going to take some time to learn this stuff, but it’s definitely worth the effort.

Examples of non-standard MadCap Flare reports

To give you a head start, we have two examples of non-standard reports that were useful for us in one of the projects.

Finding specific bookmarks

The standard static reports in Flare allow you to find all the bookmarks that are used and not used in your project. You can browse this report for specific bookmarks, but when you have lots of them, you may find it cumbersome. Also, the report is generated as an HTML file, which, unlike an Excel file, doesn’t offer powerful filtering and search options. In such a situation, you may use a search query based on a regular expression.

If you created your Flare project from a Word file with a TOC, all the headings in the generated TOC will receive a bookmark named _TocXXX, like _Toc229539249.

To find all the bookmarks of this type in the content:

1. In the Find and Replace in Files window, set up the search parameters as follows:

2. Select Find All.
3. In the Find Results window, select .
4. Save your report.

This report will show you:

• The places where the _Toc bookmarks were added
• The places that link to the _Toc bookmarks

If you want to find only the places where the bookmarks were added, use <a name="_Toc[0-9]+"> as the search query.
If you want to find only the places that link to the bookmarks, use #_Toc[0-9]+ as the search query.

Finding links to source files

When you choose to link the generated files to the source file while importing a Word document into Flare, a special tag that points to the source document is added in the topics’ source code.

After some time, the source file can go missing, making the links to the source file invalid. In such a case, you may want to find all the places with the invalid links.

1. In the Find and Replace in Files window, set up the search parameters as follows:

2. Select Find All.
3. In the Find Results window, select .
4. Save your report.

If you’re not sure about the source file path and name, you can:

• Search only for MadCap:sourceDocument.
  It’ll give you a list of links to all the source files (more than one file can be linked in the project) but you can do some sorting and filtering in Excel to find the right source file easier.
• Go to Project Organizer > Imports and look for the import file associated with the source file.
  If it’s there, open it and get the file path and name.

Happy reporting!

Check also our other articles, e.g. about MadCap Flare tips and tricks or managing your project and content in MadCap Flare.