This part of the User’s Guide is intended to highlight common questions and challenges new users to IT Architect Assistant tend to run into along with supporting guidance.
Within each IT Architect Assistant asset / architecture there is a set of shared/reused elements. Not all element types are reused across the architecture but most are, including:
What does it mean for an element type to be shared across the architecture? For one, any element of such a shared type must have a unique name within the architecture itself. Thus if you attempt to “create” a new element within an architecture whose name is a duplicate of a same type element already present within the architecture, you are presented with an Error (duplicate name). Note: This most often occurs when adding a new element using a default icon on a diagram (from the diagram specific palette). In this scenario the element is assigned an initial default name.
If you know you are going to reuse an existing element, use the list available in the appropriate Existing element palette instead. Explicitly grabbing an existing element will directly reuse that element within the current artifact instance. Should you set the name field resulting in a duplicate name error and you determine your intent is to reuse an existing element by that name, click on the corresponding select from existing button or link to get the opportunity to bind to an existing element.
The other impact is starting to reuse an element on a different diagram and then reverting to a mindset of think this is a drawing tool. For instance, you make a copy of a diagram within the same architecture. Note at the start there are two separate diagram but each contain the same set of base architecture elements. Then you decide to rename one more more elements in the copied diagram, starting to reuse the look-and-feel, but intending to capture different content. Renaming an element in the second diagram ALSO renames the element in the original diagram. The name is part of the architectural element (not an artifact of the drawing icon). So quickly you could start to mess up the original diagram thinking you are saving time! What is the best way to accomplish the desired replace element in a copied diagram, but retain the structure (connections, etc)? The easiest approach is to drag a new element onto the diagram (unconnected) and fill in its meta-data attributes. Then select the element in the diagram that you wish to replace with this new item, and click on the select from existing button or link and bind to the newly creating element. Then delete the “free standing” new element to retain the desired structure.
When explicitly creating elements or when implicitly creating as part of a cross-diagram “paste” operation (e.g. when using Resource > copy from menu), initially the newly name item is only known in the front-end (Browser Javascript). Thus, correcting names such as reusing shared elements in the editor prior to saving, will prevent temporary named elements from being added to the architecture model. However, anytime a save occurs (either explicit or auto-save) and named element present in the current editor will be saved to the back-end model.
So what does this mean and how does it impact your architecture/solution model? Let’s take a concrete example. In a AOD IT System View instance, you create a new Logical Node and name it Messaging Hub. Later (after a save) you realize that this node really should reuse an already existing Logical Node named Messaging Engine. To fix this, you select the Messaging Hub element on the diagram, click Select from existing from the bottom of the Attributes panel and then select Messaging Engine from the selection list. Then you click Save. You have fixed this diagram so it, like other artifacts instances are all referencing the Messaging Engine Logical Node. But the back-end/model still has a [now] unused Logical Node named Messaging Hub. This is what is known as an ophaned element.
What is the implication of this orphaned element? For one thing it will appear in all lists and menus within the architecture as an available Logical Node for reuse. If you have lots of orphans that you don’t ever intend to actually reuse within the architecture, then those lists become cumbersome and confusing. Also, if you export to a Word document, these “unused” elements will show up as Architecture-wide elements. You can remove these orphan elements via the Manage orphans panel (you will have to have explicit write-access to the architecture to actually delete orphans). Note, there are scenarios when you don’t want to do this “clean-up” such as when you import a set of elements via Excel import that you intend (eventually) to use within your architecture. Even so, you will likely want to at least review the list of orphaned elements prior to an Export (at least either MS Word or MS Excel).
Many times, particular in a pre-sales setting, our architectures are very lean and focused on just a couple of artifact instances. And in those settings, model consistency (same named elements, i.e. shared/reused elements, where appropriate) is easily eye-balled and you probably don’t care about orphans unless you are sharing an export document. However, in most other settings, it can be hard to make sure you are consistently representing the architecture across all of the artifact instances.
A best practice is to create a full MS Excel export of the model and review the contents. Here you may discover that you have multiple names for what is intended to be a common element, e.g. two Logical Components, one named DataLake and another named Data Lake. (Note that space makes a difference!) Such a review can point out the need to reconcile names across the architecture. To correct this, you can use the Co-relationship button to locate the artifact instances where the incorrect name(s) is/are used and then you can change them using the “Select from existing” button/link within those artifact instances. Note, after you reconcile the elements, you will have created an orphan. Prior to reconciling, each of the name variants would have been referenced in the architecture and thus wouldn’t have shown up as an orphan!
The User Interface is a single page web application with the architecture data managed in a back-end graph database. All of the editing actions whether within a rich-text editor or the MxGraph-based diagram editor is performed via JavaScript within the Browser. Changes are only persisted upon a save operation, either explicit save or via the tool’s auto-save.
There are several subtle implications of this application design. One implication results in IT Architect Assistant automatically enforcing a single writer (Collaborators) within any specific artifact instance within an architecture. Without this restriction, “replication save conflicts” are likely. A second implication is linked to the security session. All API calls from the Browser to the back-end includes the security session token so that only authorized data access and changes are completed. Note there are a small set of scenarios in which a security session token will become invalidated, for example, after extended period of time and the w3id SSO token times out. So a scenario where this plays out is where a user keeps multiple Browser tabs open for many days; a very common occurrence. They return to a Browser tab with IT Architect Assistant loaded and still on a page within an editor (editing a diagram). They “continue” to make changes and then hit save. The save fails because the [security] session is no longer valid requiring the user to login again. Note, depending on how you are used to doing things, a great amount of work could be lost since “returning to the Browser” - because even though the tool has auto-save to help minimize the window of work between saves, the auto-save will also fail due to the invalid session. So the guide to the user, when returning to IT Architect Assistant, start by explicitly refreshing the page - which should redirect you to login if the session has timed out. Also don’t try editing multiple diagrams or architectures from multiple Browser windows on the same machine as IT Architect Assistant will only maintain a single session instance per user - so again you can manually be invalidating your session as you switch from one Browser session to the other.
For most, the user experience in creating diagrams and the ease by which one can create compelling and conforming* visuals greatly determines how one perceives how productive you can be within a tool. A key design principle for IT Architect Assistant is to deliver an intuitive and productive drawing experience while managing a simplified meta-model. This balance of delivering a modeling tool with most of the beneficial experiences of a drawing tool is one we continually strive for.
With that in mind, it is important to understand the underlying drawing engine (MxGraph framework) and how and where we can and will deliver ease of use. MxGraph (and the derived tool, Draw.io) provide a simple drawing tool. Beyond foundation tooling to adjust and manage style, productivity comes from delivering a rich set of standard element styles (icons), through a number of drawing palettes.
In IT Architect Assistant, we need to be able to associate an icon with an architectural element. Note that an icon or shape manifests itself on the drawing as a drawing element and that drawing element’s look and feel can be completely altered via the tools available in the format panel. Most notable are the edit style and edit image buttons. In most cases IT Architect Assistant provides a default (vanilla) icon for each architecture element type. When you add such an element to the diagram you are manipulating two elements: a UI element (drawing element) and an architectural element. From the discussion above, note that you can change the binding between a visible UI element and the associated architectural element via the “Select from existing” button. At the same time, the default behavior is to create an architectural element each time you add a new UI/drawing element onto a diagram.
With the introduction of v3.5, and ongoing refinement of the IBM architectural visualization standard, the tool supports user defined customized palettes to modify the “icon” associated with a UI element. This is the emerging best practice for managing UI icons along with the associated Style properties.
You can select an image file via the “Edit Image” finder dialog or add to a custom palette, the image is uploaded into the system (IT Architect Assistant) and added to the Cloud Filesystem and a file path to this uploaded file is then added into the UI element’s (on your diagram) style. (Note, with the latest UI element styles, the image will only show up if the corresponding Icon-Name data property is empty. This update is automated with use of image icons dragged from custom palettes.)
A second strategy is to copy style from known graphics. For example, the Annotation palette is provided both to create non-architectural content on a diagram, but also is available to copy the style to be applied to the UI element associated with an architectural element. Select the “Edit Style” on a drawing element and copy the contents of the Style, then select the “Edit Style” for the drawing element you wish to change and paste the copied style contents. In a similar way you can also copy the style from other palettes available other places.
The third strategy is to build and maintain or just reuse content from one or more assets established primarily as a reusable element library. The intent here it to capture reusable “packages” that include architectural element (type), Name, Description, icon/visualization, and possibly additional attributes. An excellent example of this is the Icon Library- IBM Cloud Architecture Center that you can find via Search in IT Architect Assistant. Here 1 or more AOD IT System View instances provide access to reusable content that one can copy from using the “Resource > Copy from xxx” approach. Note this approach is powerful beyond delivering a set of reusable elements for your diagrams. It can also be used to capture a reference set of other elements, such as typically used Architectural Decisions, Non-Functional Requirements, perhaps even Use Cases. Managing a reuse library help you and your team to consistently use the same artifacts across multiple architectures!
Currently, there are a couple of places where multiple diagrams are dependent on other diagrams, beyond just potentially sharing reused/common architecture elements. One of these linkages is the Usage Scenarios. Currently all Usage Scenarios are tied to an underlying AOD. Further, within the Usage Scenario, the scenario “steps” are bound to one or more connectors. (Note, a backlog item will allow steps to be tied to any architecture element in the future.) Typically, updates to these now dependent diagrams are handled iteratively. But, note that removal of a connector (even if another is redrawn between the same elements) in the base AOD, means that the association of any steps within a Usage Scenario based on the AOD will now be removed. Thus beware the changes you make in your AODs may impact any dependent Usage Scenario Diagrams.
Another, linkage, is supported in the Operational Model. Here when you create a Prescribed Operational Model view, you can choose to link it to an existing Logical Operational Model view. [There are restrictions to this and only one such linked pair is supported per architecture.] The linkage triggers a number of synchronization and validation checks which will automatically retain any changes to placement of Prescribed Nodes and Actors within OMLocations consistent across the two diagrams. There will be times, however, you will find you are fighting the synchronization functionality and therefore want to unlink the diagrams. The way to do this is make a copy of either the LOM or POM (not both). Then delete the original copy. The two remaining diagrams will no longer be linked together.