Importing External Files

As part of your overall architecture, you might import external files such as the following into your Flare projects:

  • Microsoft Word
  • Microsoft Excel
  • HTML
  • Atlassian Confluence
  • Adobe FrameMaker
  • DITA

This is necessary when you have legacy files that you want to leverage in your Flare projects. The legacy files are converted to topics and other Flare files. See Importing.

Simple diagram showing the import of external files into a project.

Basic Methods for Importing

When you import these types of files, you can use one of the following methods:

  • One-Time Import After importing the files, you thereafter make any edits within Flare Desktop.
  • Easy Sync You can maintain a connection between the legacy files and your Flare project. So after making future changes to the external files, you can reimport them back into Flare Desktop using this connection.

SharePoint and External Resources

Another way to leverage external files is to use the SharePoint or external resource integration features in Flare Desktop.

  • SharePoint Flare Desktop supports integration with Microsoft SharePoint, including SharePoint Online (or SharePoint 365). From Flare Desktop you can access, edit, and synchronize SharePoint files. See SharePoint Integration.

    SharePoint is like a scaled-down version of a source control tool, with the ability to check out and check in files. Many organizations use a source control tool to manage files that are part of products and will be shipped to customers, while using SharePoint mostly for internal files to be shared among colleagues. For more information see www.sharepoint.microsoft.com.

  • External Resources The External Resources window pane lets you select and maintain groups of external files that you want to share among Flare projects. The paths of these files are written to the registry so they will be available for all your Flare projects.See External Resources.

    External resources can be virtually any local or network files to which you have access (e.g., images, PDF files, Flare project files). From the External Resources window pane, you can easily bring external files into a project (i.e., a copy of the file is added to your Flare project) and keep them synchronized with the source files through mappings.

    The external resources feature is ideal for shared files that you expect to change over time (e.g., logo images, PDFs, stylesheets), as opposed to, say, a template file that is simply copied into your project and changed only in that project.

A diagram showcasing SharePoint or external resource files integrated with a project.

External Files Versus SharePoint/External Resources

Importing external files is different from using SharePoint or the external resources feature in the following ways.

Importing External Files

External files that are imported the regular way are converted to formats that can be edited in Flare Desktop.

The import file process requires you to reimport external files if they have been changed outside of Flare Desktop.

SharePoint or External Resources

The files that are brought into a Flare project via SharePoint or the external resources feature are not converted; they remain in their original format.

A synchronize feature lets you keep the SharePoint or external resource files up to date with their copies in the Flare project.

What the MadCap Documentation Team Does

All of our files are native to Flare Desktop, so we do not import external files. However, if we did import external files, we would use the following guidelines and tips, especially for Word or FrameMaker files:

  • We would clean up the source files. For example, we would probably remove styling from those source files so that the import process is as smooth as possible.
  • For Word imports, we likely would open the Word documents and apply "Private" field codes to the appropriate headings where new topics will be created after the import. This lets us control the file names that are produced as a result of the import. See Specifying Custom File Names for Word Imports.
  • For FrameMaker imports, we would follow the guidelines described in the following: Importing FrameMaker.
  • We would do one-time imports instead of maintaining a connection between the source files and the Flare project. In the long run, editing the imported files within Flare Desktop is easier, better, and helps to avoid possible issues with reimports.