If you need to reference a document that resides outside of SystemWeaver, there are a number of ways you can handle this. One of them is to use a specific item as a "proxy" for the external file. This article provides a brief description of the external document reference concept and how to use it. 


Introduction

A Document Reference is a SystemWeaver item (A) that includes an external reference link (B), expressed as a URL, to a file outside of SystemWeaver. The link is saved as an attribute of type external reference. Examples of typical external documents are official documents such as standards, manuals, guidelines or concepts. They can be any file type, e.g., Word, Excel, PDF, since only a link (URI) is stored, not the files themselves. 



Below is an illustration showing how the access to the external file works. The user is logged into SystemWeaver where the path to the external document is stored. When the link is opened, the user is redirected to the real file located in the external storage system. If a user has access to the file on an external storage system, they will be able to open and view it. 




The use of external references has a number of advantages:

  • You can use/reference an external document from other SystemWeaver items.
  • All references to the proxy item (and hence the file) from other items can be traced using the References view.
  • You can use versions of the item to reference different versions of the referenced file so that it will always be clear exactly what version of the file that is being referenced.
  • You can add additional administrative information about the file in the item, e.g., a summary of the content of the file or recommendations regarding the applicability of the file.


Establishing Guidelines

If the external reference concept will be used, there should be routines established that assure that just a single SystemWeaver item type will be used as a proxy for a specific file or external files in general. (Your system's SystemWeaver Architect would be responsible for establishing the item type.) Likewise, items should get names that clearly indicate the relation to the file, like a title relevant to the content of the file. If such routines are not adhered to and multiple item types are used, many of the risks with poor information management will be introduced to the SystemWeaver world. In addition, the external location of the file has to remain stable during the lifecycle of the document reference item. Otherwise, the link will be broken. 


External Document Lists (optional)

Although optional, if there will be a significant number of documents references, it is best practice to have a complete external document list for all external documents. Then, for each particular project, for example, a project-specific document list could be created that pulls in particular documents from the complete list. This requires the use of a designated document list item type and that the lists are maintained. 

Creating a Document List (optional)

Consult with your SystemWeaver Architect to confirm if the document list item type is being used. 

  1. To create a document list for a project, for example, right-click in the structure tree where you want to add the document list, select New and then select the document list item.
  2. The New item dialog will display.
  3. In the Choose Access section, select the library to be used. The library chosen the previous time that you created an item will be selected by default (see Managing Access Rights With Libraries for more information on libraries).
  4. In the Select Item Type section, select the document list item type. 
  5. Enter a Name for the new document list.
  6. Click OK. 

Creating a Document Reference

  1. Right-click the document list item in the structure tree where you want to add the document reference item and select New and then select the document reference item. The New item dialog will display. In the below example, a document reference items called "ISO 26262" and "ISO 11469" have been added to the ISO Standards document list:


  2. In the Choose Access section, select the library to be used. The library chosen the previous time that you created an item will be selected by default (see Managing Access Rights With Libraries for more information on libraries).
  3. In the Select Item Type section, select the document reference item type. 
  4. Enter a Name for the new item.
  5. Click OK. 
  6. To add the external reference link, open the Overview view and click the external reference attribute tool  to add the URI. 
  7. Click Select file..., navigate to the external file and select it. 
  8. Enter the Display Text and click OK. 
  9. Proceed with coding any other attributes per agreed upon guidelines. 
  10. Add a textual description of the created document reference in the Description field.
  11. Release the item to ensure that the link to the external reference will not be edited. This ensures that the document will remain pointing to a specific version of the external reference. 

Opening External References

  1. Select the Document Reference item in the structure tree. 
  2. Right-click the external reference attribute and select Open external reference.

Modifying External References

Versioning of the document reference item can be used so that it will always be clear exactly which version of the file that is being referenced. If an external reference URL needs to be updated, be sure the document reference item is first released and then create a new version in which you update the external reference attribute to change the URL. 

What's Next? 

Search for 'external reference' in the Help for more information about external reference usage.