Relative vs. Absolute Paths for Related Documents

Some of you may have noticed that we released a minor update to 2.0 last week, cleverly named "build 2133".  There were a half dozen or so small fixes that went into this build, most of which people will never run into, so there isn’t any need to rush out and install this update (see the release notes for a list of what was fixed).

One item that may be worth noting is a couple of fixes for related documents that are specified using a relative path instead of an absolute path.  What’s the difference?  An absolute path starts out with a fixed location, e.g. C:\temp\MyFile.doc or \\MyCompanyServer\SharedFolder\MyFile.doc.  A relative path, on the other hand, specifies a location relative to your current location, in this case the folder that your use case model is located in.  For example, it could be specified using just the name of the file, e.g. "MyFile.doc", as long as that file is in the same folder as the use case model.  Or it could specify a folder located in the same spot as the use case model, e.g. RelatedDocs\MyFile.doc.  Note that neither one starts with a leading slash, which is how we know that it’s relative.

This is relevant to Case Complete because when you specify a related document, you can specify either kind of path.  Recall that a related document is any document external to Case Complete, such as a Word or Visio document, which you can associate with any use case, actor or package.  The kind of path you use is especially important when you are working on a team, since you want others to be able to open the document that you specify.  If you have a common shared repository of documents, (as in the \\MyCompanyServer example above), then by all means, use an absolute path.  Otherwise, you may want to consider putting them in the same folder as the use case model, or in a sub-folder.  In this case, you should also put these documents under version control just as you would for the use case model files.  When team members load the project files from the version control system on to their computer, they can locate the project wherever they want, e.g. one person may have it on the C: drive and another may have it on the D: drive.  But since the paths of the related documents are relative, it doesn’t matter where the project files are located.

As one of our customers pointed out, using relative paths also has benefits when generating Word reports.  The related documents section in the generated report uses hyperlinks to the files so that readers can easily open the related document.  Using relative paths allows you to package up the Word reports and all the related documents (into a zip file for example) and distribute to other stakeholders.  The stakeholders can unzip the files to any location on their hard drive and view the reports at their leisure and have ctrl-click access to the related documents regardless of whether they are hooked up to the network or not.  One thing to note is that you must first save the Word document before hyperlinks for relative paths will work.  Not surprisingly, you must save the report to the location implied by the relative paths.

This is getting long, so just a quick mention of how to specify a relative path in Case Complete.  If you browse to the file when adding the related document, you can edit the path to make it relative after it is added to the list (press F2 to edit).  The 2.0.2133 release adds a new context menu item to allow you to type it in directly.  You can use relative paths with the initial 2.0 release, however it will not be able to handle them if you are using automatic picture insertion in your Word reports.  Hope this information can be of some use to you.