External Documents

In the following I describe a new feature introduced with ARIS 7.2 which allows attaching extended descriptions to objects and other database elements.

Currently descriptions can be defined using text attributes. Although text attributes support various text and paragraph formatting, they are not designed to store large amount of information thus the handling of documents consisting of many pages can become quite cumbersome. In addition, text attributes do not allow embedding images or hyperlinks for example.

Alternatively, one can attach links to objects and other database elements in ARIS. These links can for example point to documents stored on a file server, a web server or a document management system (DMS). However, these are only loosely coupled which has some drawbacks. Just to mention two: when you create a definition copy of an object then both objects will still point to the same document. Thus changes to the document will show up at both objects, which is usually not what you want. Another drawback is when you create a new version of an object and later on change the document than the archived version will point to the changed document and not to the state of the document when the version was created.

Introduction of a new attribute

Therefore for ARIS 7.2 we introduced a new attribute named “Documentation” (with API name AT_DOCUMENTATION). It supports storing documents in the format DOC and DOCX and is allowed for most database elements like objects, models, connections, groups, etc. Since the attribute has been newly introduced note that you have to adapt your existing method filters, otherwise you won’t see it.

Attaching an existing document is straight forward: just press the import button : it will pop up a file selection dialog which allows you to select a DOC or DOCX document from your file system. Note that a copy of the document is stored into the attribute, so changes to the original document will not be reflected in the one attached to the object.

After import, the attribute editor will show a preview of the document:

The preview can only show a clipped part of the document. If you want to see the whole document, just press the view button . This will start MS Word externally to show the full document. Note that the document is opened read-only in order to prevent unintended changes to the document.

If you want to edit the document, just press the edit button . This will again start MS Word but now the document can be changed. MS Word will directly communicate with the ARIS Business Server, which allows you to close ARIS Business Architect/Designer while continue editing the document in Word. Whenever you save the document from within Word, your changes will be saved immediately into the ARIS database. Since this is done directly via the Business Server you have to press the refresh button    in order to update the attribute editor’s preview of the document.

Extension of Report API

The Report API has been extended to allow the creation, retrieval and change of external documents: just search the ARIS Script Help for “createExternalDocument“, “getExternalDocument” and “setExternalDocument”.

Summary

With the introduction of the new documentation attribute in ARIS, you now have three options how to add comprehensive descriptions to your objects and models:

1. If you only have a few lines of text, add them directly to the description attribute. You can use basic formatting functionality like bold text or numbered lists.
2. If you want to add images and advanced formatting elements to your documentation, you can now add a MS Word document to your object using the new document attribute.
3. If you store your documentation on a document management system (DMS) or a file server, you can link those documents to your object or model using one of the link attributes.