SOFTware is HARD

Astah Unexplored & New Features

2024-08-08T17:54:00.000+08:00

I'm currently trying out the reverse-engineering in Astah and am pleasantly surprised by the available features.

My sample files are taken from "Full Stack Development with Spring Boot 3 and React"

I tried importing the downloaded files from GitHub. Remember to check the "include sublayers" to add files from various subdirectories.

Code to Diagram feature

Feeling lazy, I used the "Auto Create Class Diagram" function to generate "Simple" class diagrams.

Accessing the "Auto Create Class Diagram" feature

With a bit of a clean-up and elimination of classes that are irrelevant, the auto-generated class diagrams look great!

Auto-generated Class Diagram

Auto-Generated Class Diagram

The latest feature allows a Definition Note to be automatically created as an UML note. Definitely a most welcomed feature!

Right-Click on a model element (Class) to see the available options for "Show Definition Note". The available Definition Notes are automatically "picked up" as options to show or elide.

Accessing the "Show Definition Note" feature

I've hidden the <<Definitions>> stereotype for aesthetic purposes. One can see the note for the class as well as the operation.

Class Diagram with (auto) Notes

Another useful feature is to be able to "park" the UML Diagrams under the various elements for better organization.

In this instance, I've created a Sequence Diagram to depict the flow for the getCars operation "parked" under the Operation and a Class Diagram to depict the class structure under the Class

Diagram Organization

UML Sequence Diagram

UML Class diagram

Useful Hacks in Using Astah

2023-08-01T20:04:00.003+08:00

MindMap Hack

I've been using Astah (download here) more recently for the MindMap feature and felt to share this wonderful "hack" with you.

I jotted some points in NotePad and wish to quickly transfer them into Astah as a MindMap.

The easiest way to retain the hierarchy is to use [TAB].

Therefore I could easily transform this

Hierarchical List of Points

Into

Same List of Points in MindMap

Here is how it's done:

Select all text in NotePad (or equivalent) and Copy (Ctrl-C)
Go to Astah and create a New MindMap Diagram
Click on Mindmap0 or whatever existing topic and Paste (Ctrl-V)

Like magic, the MindMap is created and the hierarchy is retained.

UML Deployment Diagram

You wish to draw professional-looking diagrams using AWS/ Azure icons. Is that possible & easy to do in Astah?

AWS Deployment

Believe it or not, the above is drawn in Astah!

Here is how it's done:

Go to Tools -> Project Settings -> Set Icon for Stereotype (See Custom Icons for Stereotypes Diagram)
Choose Add File and multi-select whatever icons you wish to use
The stereotype name would be the name of the image (by default) and each entry is of Classifier kind

Custom Icons for Stereotypes

To actually use what has been created, you now need to do the following:

Depending on what you intend to create, you can create each UML element (icon) to be a Component or a Node - I prefer to use Node most of the time for flexibility. (See Created Nodes diagram)
Add a Stereotype to each Node (based on the new ones created earlier)
Create a UML Deployment Diagram and add the Nodes into the diagram
Do note that some are Nodes within Nodes. E.g. EBS within Web (See Node within Node diagram)
Select all Nodes and right-click to apply to all Nodes
Select Icon Notation -> Customized Icon
The Nodes now have got a new look!
Link them as required

Created Nodes

Node within Node

Using Astah to Understand & Appreciate Published Standards

2022-06-29T00:25:00.002+08:00

I'm usually a visual person, hence reading and understanding standards (implementation protocols, etc.) can be quite challenging.

In trying to understand and appreciate OIDC (Open ID Connect) from the OIDC website, I used Astah to model my understanding and summarised by understanding in a couple of diagrams. What was more challenging is that there are several flows in OIDC and each can be slightly different. My goal is to not only understand the protocol, but to appreciate how it is applied in my implementation.

Fortunately, Astah makes it relatively easy for me to create high-level models that might not have any implementation elements. Remember I'm not implementing OIDC protocol and am modeling the flows in order to better understand them. As such, I'm not exactly interested in creating UML Classes, writing Operations, Attributes, Associations, etc., other than what is instrumental in creating the desired diagrams.

Some of the Sequence Diagrams are here:

Authorization Code Flow (with PKCE)

Authorization Code Flow

Implicit Grant Flow

Hybrid Flow

Even more interestingly, what I'm implementing is a Broker Architecture rather than a direct Application-to-IDP (ID provider) integration, I.e., I have an OIDC-compliant broker to "proxy" the OIDC protocol with the IDP.

The Interaction Diagrams look like this:

Normal OIDC Interaction Diagram

Broker-Architecture OIDC Interaction Diagram

Astah - How wonderful you are!

2021-06-21T21:01:00.001+08:00

I started using JUDE in the early days of UML modelling and have continued using Astah until now. In the day and age of Agile development, emphasizing "communication over documentation", is UML (and related UML tools) still relevant?

I'll give a resounding YES! to the question. While we should do away with extensive documentation, we should still be able to communicate our intent in forms of architecture, design, workflow, processes, etc.

In the course of my work in an end-user environment, I use Astah extensively to communicate with development teams, users, vendors and even senior management.

I find it's often a lot easier to use a tool like Astah to draw UML (or pseudo-UML) diagrams than pen-and-paper (or even napkins!). For instance, I can easily move things around, redraw and append/ update the diagram using the tool but not with paper.

Some examples of diagrams I'd used in the course of work are below. I used Astah for the following:

Share my thought process, concepts and linkages using Mindmaps (see Pros & Cons Mindmap)
Design Event-Driven Architecture (EDA) Topic Hierarchy using Mindmap (see Topic Hierarchy)
Depict in a UML Class diagram how the ERP and CRM synchronizes data (see ERP-CRM Entity Sync)
Share system-to-system Integration Architecture (including Events, Web and API) in UML Class diagram (see Integration Architecture)
Share flow/ sequence design using UML Sequence diagram (see Sequence Diagram)
Share high-level block diagrams using UML Class diagrams with non-IT folks (see CRM Blocks)
Share high-level UML Class diagrams for Enterprise Application Portfolio and Integration Architecture (see High-level AS-IS)

If you:

are reasonably adept at UML
prefer a lightweight & cross-platform UML tool over using pen-and-paper
enjoy communicating your intent, architecture, design without extensive documentation

You should give Astah a try here!

1. Pros and Cons Mindmap

2. Topic Hierarchy

3. ERP-CRM Entity Sync

4. Integration Architecture

5. Sequence Diagram

6. CRM Blocks

7. High-Level AS-IS

Template for IT Ops runbook

2020-12-01T15:02:00.002+08:00

https://github.com/SkeltonThatcher/run-book-template/blob/master/run-book-template.md https://www.atlassian.com/software/confluence/templates/devops-runbook https://medium.com/@shawnstafford/ops-runbook-16017fa78733

Astah Productivity: How to quickly create UML Classes from Objects in UML Sequence Diagram

2019-08-13T18:55:00.000+08:00

I usually begin modelling from a UML Sequence Diagram in order to have a sensing of a list of classes/ objects. However, the downside with starting with the Sequence Diagram is that the classes are not created automatically.

Other than having to manually create classes to link to the object (lifeline) which is rather tedious, I finally found a great ~~(undocumented?)~~ feature in Astah that allows me to create a class (automatically) from an object (lifeline) in the Sequence Diagram!

BEFORE: the usual steps to creating classes from Sequence Diagrams.

Create lifelines and messages as required

For lifeline objects that need to be created as a Class, click on the object. The properties panel should show the base class as <<Unspecified>>

As the class has not been previously created, we need to create a new Class (usually) with the same name as the object. Click on New and rename the Class

Press close on the dialog box. The lifeline object is now an instance of the new class

Remove the original lifeline object name (if required)

Repeat for each lifeline object

**AFTER: a much better way to do things!**

Create lifelines and messages as required
For lifeline objects that need to be created as a Class, click on the object

Rename the object with a preceding colon (to denote that the object is an instance of a Class)

A prompt pops up "Do you want to create a new <<Name_Of_Class>> for the type?". Choose "Yes"

A new class is created with the name and the original lifeline object name automatically disappears.

Repeat for each lifeline object

Excel & SharePoint

2018-11-23T18:19:00.000+08:00

Objective

I needed to prepare an Excel file for importing into SharePoint.

Excel

First, I need an Excel formula to populate a short name (255 characters) from a much longer name ( found in "col").
The length of the short name is constrained by SharePoint's "single line of text" field.
The challenge is to find acronyms within col or if am acronym can't be found, to truncate col to 255 characters.
Example:

GNU is Not Unix (GNU) => GNU
This is another name => This is another name

This is the formula to use.

= IF(ISNUMBER(FIND("(";[col]));MID([col];FIND("(";[col]) + 1; FIND(")";[col]) - FIND("(";[col])-1);LEFT(CLEAN(TRIM([col]));255))

Importing into SharePoint

The only error free way to do this is to use Excel to export into SharePoint.

Create an Excel table and select it
Go to "table tools" tab and choose the "export table to SharePoint list" option within "export".

Unified Data Modelling for RDBMS and NoSQL

2018-08-14T14:01:00.001+08:00

The logical model metadata

The physical model metadata

Note that Blue denotes the RDBMS metadata while Green denotes the NoSQL metadata.

SharePoint Document Library Folders & Tagging

2018-08-14T14:01:00.000+08:00

Although I'm aware of the downside of using folders in Document Libraries, I still think it's one of the best ways to categorise files.

This is especially true when migrating from file-shares to SharePoint. Furthermore, it's a great hassle to individually tag metadata or column information for each file that I wish to dump into SharePoint.

To workaround this issue, the solution is to use automatic tagging in conjunction with the use of folders. See here

However, if you structure your Document Libraries with many folders and different levels, you will quickly end up with a different problem: Having to set-up the rules (mapping) for each folder using SharePoint.

The easiest way to get around this is to edit the rules directly. This file can be found in the hidden Forms folder as client_LocationBasedDefaults.html. By opening the Document Library using Windows Explorer, you will be able to edit the file. Do so with great care!

Software Architecture Modelling Using C4

2018-08-14T01:12:00.000+08:00

UML appears to be dying in the light of the Agile development movement.

working software over comprehensive documentation

Many have wrongly interpreted this to mean no documentation.

I recently read up C4 model for software architecture that describes the software architecture of a system from different depth & perspectives and for a different audience. The author promotes the use of a common vocabulary to describe software architecture using simple-to-understand diagrams.

I attempt to do similar in this post using the same case study as that of the C4 article.

The differences are:

I do not wish to go into Class (the 4th C) as that requires too much implementation details
I replace the 4th C with Concept as I personally find the Conceptual model more relevant and important in appreciating the business domain.

Using Astah, I figured out how I can model the 4C software architecture efficiently using UML.

Mind-Mapping

I started with a Mind-map to have a good idea of the Context and the main Concepts.

Mind-map

In using Astah, I first create the above Mind-map to capture the system Context and main Concepts.

Next, I performed the following steps:

For every Human Actor and External System, convert into a UML Actor by selecting them and right-clicking (Convert to UML Model –> Actor)
For every use case/ feature (sub-topic of Actors), convert into a UML Use Case (Convert to UML Model –> Use Case)
For every concept, convert to a UML Class (Convert to UML Model –> Class)

Context Diagram

Next task is to create the Context Diagram.
This proved to be rather easy as the Actors were already created in the earlier step.
I created a UML Use Case Diagram and added a UML Subsystem to depict the SuD.

Context Diagram

(Optional) Context Diagram (Level 1)

Call me old-school if you like! I still appreciate the usual UML Use Case Diagram with Actors and associated Use Cases to depict what each Actor does with the SuD in a little bit more detail. This is optional and would be considered a (more detailed) next level of the Context Diagram (Level 1).

Use Case Diagram (Context Diagram Level 1)

Conceptual Diagram (Personal Preference)

At this point, I deviate from C4 in creating a diagram that captures high-level domain concepts. I find the information/ conceptual model useful in describing the SuD in terms of the data/ information it captures. This diagram is commonly known as the Domain Model and is depicted using a UML Class Diagram. In keeping with the 4 Cs, I will call this the Conceptual Diagram.

Conceptual Diagram

Container Diagram

The next perspective in C4 is the Container Diagram which is modeled using the UML Deployment Diagram where every Container is depicted by a UML Node. Constraints are placed on each relationship as necessary.

Container Diagram

Component Diagram

This is followed by the Component Diagram. Note that the C4 Component Diagram still uses the UML Deployment Diagram (rather than the UML Component Diagram) in order to depict both UML Nodes as well as UML Components.

Component Diagram

I hope this post helps to reconcile C4 and UML. At the same time, C4 is likely the way to go forward in documenting software architecture in a lean and minimalistic manner.

The challenge, however, is that the UML diagrams are certainly not as verbose as those used in C4. At this point, the only viable solution is to depict the description in UML Notes attached to each element.

Setting Default Column Values for Document

2018-04-06T12:27:00.000+08:00

I had the requirement to map the default column values of documents to the nested folder structure it is created/ uploaded into.

As an example, a document uploaded into \Document Library\2018\Jan\DeptABC would have default column values accordingly:

Year: 2018
Month: Jan
Dept: DeptABC

The column values (metadata) make searches effective and rather than to have users provide the metadata as a distinct step, we determine the metadata based on the logical (directory) location of the document.

To manually configure this, go to [Library Settings] -> [Column default value settings]

See here.

However, if there are too many columns to configure, a quicker way to do so is to edit the mapping file directly. This file is found in the root of the library: "Forms\client_LocationBasedDefaults.html". It is an XHTML file that isn't too difficult to comprehend. Do be careful and backup the file before editing.

How to depict (Professional-Looking) Logical Network Diagrams in Astah

2017-08-11T23:13:00.001+08:00

I have always had to create (professional-looking) UML diagrams using Visio-like icons. You’ve got to admit that showing a bunch of boring UML boxes hardly interests anyone less technical (like anyone whose designation has the words “manager” or “director”).

This is actually possible in Astah!

I’ve created a template for future projects that allows me to produce logical network diagrams that look like the following:

To create this diagram, you need to do the following:

Assign various icons to stereotypes. I created the following for my use:

Create a new UML Deployment Diagram
Every element in the diagram is created as a Node
The nodes are subsequently assigned the appropriate <<stereotype>>. E.g. Internet is <<internet>>, WebZone FW is <<firewall>>, Web LB is <<loadBalancer>>
Ensure the “Icon Notation” is set to “Customized Icon” for each node
Instead of the boring boxes, the corresponding icons automatically gets displayed!

AWS Schema

2017-07-31T00:51:00.000+08:00

From revising AWS Solution Architect..

SharePoint Schema

2017-07-31T00:49:00.000+08:00

From my research, I’ve made some notes as to the structure of SharePoint 2013.

SharePoint OOTB Workflow

2016-11-23T14:32:00.000+08:00

Recently, I had the chance to play with SharePoint lists and Document Libraries. I also had the challenge of using SharePoint without the use of Designer.

In creating a List or Document Library and associating it with a Workflow, my challenge was to create a View such that I could filter it based on the Workflow status.

Thanks to the wisdom of the internet crowd, I chanced upon this article here

The status of each workflow is stored as a numeric value but displayed as a string description as follows:

NotStarted = 0
FailedOnStart = 1
InProgress = 2
ErrorOccurred = 3
StoppedByUser = 4
Completed = 5
FailedOnStartRetrying = 6
ErrorOccurredRetrying = 7
ViewQueryOverflow = 8
Canceled = 15 (to be confirmed)
Approved = 16
Rejected = 17 (to be confirmed)

To filter, compare the value against a numeric constant. For example:

show only those that are in progress: = 2
show only those that are not completed: < 5
show only those approved: = 16

Agile Requirements

2016-09-27T10:38:00.000+08:00

Capture user stories in the form of:

As a <user role/type> I want <some action/ feature/ goal>, so that < benefits from/ reasons for it>

Capture acceptance tests in the form of:

GIVEN (some context/precondition) [ AND (some more context/precondition) ...]
WHEN (event/action performed by user)
THEN (expected outcome - what should happen to satisfy user requirement from the user story statement above).

See https://www.infoq.com/articles/standardize-requirements-scrum

Web Application Security Issues & Solution using UML

2016-07-14T16:03:00.001+08:00

I was once involved in reviewing our company’s application architecture to identify security risks and recommend possible mitigation solutions.

Since every organisation has its own unique constraints, available resources, and risk appetite, the solution herein might not apply to other organisations.

Nevertheless, this post showcases what one can do with UML to document and explain (pictorially) security flaws in application architecture.

The as-is architecture follows.

A detailed explanation follows:

The system (under design) is a Java Enterprise Application that is deployed in AppSvr (Application Server) within the Internal zone.
The deployed application consists of both HTML-based as well as SOAP-based services.
The 2 WebSvr’s ([Apache] Web Server) in the DMZ act as proxies.
There is a load-balancing appliance used to balance requests to the web servers. A request pool has been created on the appliance (WebPool).
The (public) user would access the URL endpoint of the appliance for every request.
Similarly, other applications (Others) deployed on both the WebSvr and AppSvr would access the SOAP web services through the load balancer.
Note that the public.softwarehard.sg is a public URL that is used by both the (public) user as well as other applications (SOAP-based services).

The security issue in this architecture is that the SOAP-based services are exposed to the public. What is worse is that these services are not secured by any form of authentication.

Having reviewed the existing architecture, the available resources and constraints, I proposed a solution that suited our risk appetite and incurred minimum changes to all applications.

With the use of another load balancing appliance (which we happened to have), we created another endpoint to access the SOAP web services.

This solution allowed us to

mitigate the security risk
minimise changes to all applications
capitalise on the load-balancing appliances

Prototype Application Development Using Astah

2016-02-22T22:03:00.001+08:00

I had the opportunity to develop a prototype for a client and used Astah to capture the salient specifications as well as the requirements analysis.

Mindmap

To first understand the requirements,

I used a mindmap to guide the user through the mean features of the application. What worked well in this instance was a role-based model (similar to use case modelling), i.e. list out all the roles involved in interacting with the application.
Next, the features or use cases for each role gets listed out (“as a <role>, I want to be able to <feature>”)
The final mindmap served as a form of an agreement on the scope of work.
The final mindmap looked like the following:

Use Case Modelling

Using Astah, I was able to easily convert the Mindmap into a set of Actors and Use Cases for further analysis. The model follows:

Domain Model

As the prototype had dependencies on an existing application, some of the domain objects were deliberately taken from the the existing application and fused into the new one.

In order to better understand the application requirements, I needed to grasp the information and data that is captured and used by the application. At the same time, the domain concepts had to be understood and captured. This is best modelled in the form of a Domain Model (UML Class Diagram). A partial view follows:

Boundaries/ Interfacing

I was highlighted to a need to integrate with a 3rd party service and decidedly captured the flow for this integration in a UML Sequence Diagram as follows:

Summary

This is just a sample of what I usually do with Astah for application development and if you are looking for an agile, lightweight and easy-to-use tool, I highly recommend Astah as compared to many of the more heavyweight and feature-laden tools.

Understanding ITIL Service Management the UML way…

2015-05-14T16:48:00.001+08:00

I originally had a great deal of difficult reconciling the differences amongst ITIL Change Management, Incident Management, and Problem Management. Having researched on the subjects and understanding them better now, I’ve tried to put the concepts together using a UML class diagram to capture my understanding and to keep it imprinted.

Similarly, I wanted to differentiate the various categories of changes (Standard, Emergency, Normal) using an easy to understand & self-explanatory manner – a UML Activity Diagram!

Modelling the Life Insurance New Business Process

2015-03-08T23:43:00.001+08:00

This is a simplified diagram that captures the business process for a Life Insurance new business workflow. The high level process is captured using an UML Activity Diagram.

How Much Detail Do You Need to Capture in UML for Code Development?

2014-07-08T01:22:00.001+08:00

I had a mini-experiment to document my design in UML for a developer to write the corresponding code. The background and assumptions are:

The application is an insurance quotation system
Design is based on MVC, in particular, ASP.NET MVC
Web caching is used
The basic MVC application framework is in place (with sample codes)
The developer is an intern from a local university
What is designed to be developed is one of the modules in the entire application – this particular module is a dashboard

Without going into the details of the use case document, I created the basic tenets: certain basic sequence of events as well as the View-Of-Participating-Classes (VOPC).

The mini-experiment proved to be a success to my surprise.

The following UML Sequence Diagrams capture the basic flow for the initial web request:

The following UML Sequence Diagram depicts the sequence of events for subsequent access:

Finally the VOPC UML Class Diagram follows:

Reduce the Integration Mess!

2014-07-08T00:57:00.001+08:00

Sometime ago, I was reviewing the alerts and notifications sent from various applications and systems. We needed to capture and store the content of the messages. I took the opportunity to re-architect the entire landscape by documenting the as-is, as well as the to-be.

The UML Communication Diagram – an unsung hero – was used for this purpose.

The as-is integration mess:

The to-be design – looking a lot better:

Incident Response Process

2014-07-08T00:19:00.001+08:00

Recently, I had been dealing with other areas of IT including operations & governance. The following Activity Diagram documents how a typical institution might have to respond to security incidents.

Review: Search for Truth - Home Bible Study

2014-05-02T01:32:00.002+08:00

A mindmap review of the powerful Bible study material.
Flash version can be found here

Review: The 5 Love Languages

2013-10-20T01:52:00.001+08:00

A mindmap review of the excellent book.
Flash version can be found here