Best Practices for Modeling a Multi-System Integration?

[gusikowski]

I’ve gone through some tutorials and have a decent grasp of basic UML modeling, but now I’m stepping into my first real-world project using EA and could really use some advice.
The project involves documenting and modeling a multi-system integration for a medium-sized enterprise—think CRM, ERP, and a few custom-built applications that need to interact via APIs and message queues.
I’m trying to figure out the best approach to model this architecture in EA. Specifically:

• Should I start with high-level component diagrams or a layered architecture model first?

• How would you recommend capturing data flows between systems (e.g., use sequence diagrams, or something else)?

• Any tips on how to keep the model clean and readable as complexity increases?

• Bonus: Any useful plugins or features in EA that are a must for this kind of work?

I’m using EA 16.1 (Ultimate Edition), and planning to eventually export documentation for both technical and non-technical stakeholders.
Thanks in advance—really appreciate any guidance from those with more experience.
Looking forward to contributing as I learn more!

[Sunshine]

Not used UML for a while as I've use ArchiMate as it better suites my needs as an Enterprise Architecture. However, assuming you are looking at UML as a solution architect from what I remember there are two sets of diagrams behaviour and structural. See https://www.uml-diagrams.org/uml-25-diagrams.html with examples https://www.uml-diagrams.org/index-examples.html
Each diagram provides some value for different stakeholders so work out who are your stakeholders and what they need then choose the appropriate set of diagrams for those stakeholders.
Recommend reading a book or two on UML to help you better understand it. Here is a list most of which I've read in the past https://modeling-languages.com/list-uml-books/
Appreciating that reading books may be time consuming so suggest you use AI engine like ChatGPT/Copilot etc to help your learning by summarising vast amounts of text in UML books which I understand from recent news that the authors are being compensated for AI engines using copyrighted material.

• Should I start with high-level component diagrams or a layered architecture model first?

Depends on what stakeholders you need to bring on first.
A context diagram using information flow diagram with high level components is what I usually start with so that I can delegate detailed design of the high-level components.

• How would you recommend capturing data flows between systems (e.g., use sequence diagrams, or something else)?

You could use information flow diagrams and create class models representing the message data being passed between components.

• Any tips on how to keep the model clean and readable as complexity increases?

Think keep it simple. Low coupling and high cohersion.
From the book Enterprise Architecture at work it provides the following guidance on ArchiMate but applies equally to UML:
Reducing the visual complexity of models is primarily achieved by limiting the  number of concepts and relations that are visible in a model. Related to this, the  number of types of concepts and relations should also be limited. Having different
 views of models is one means to reduce the visual and conceptual complexity:  given a specific objective and a specific type of stakeholder, a view only includes those aspects of the model that are relevant for that situation.
...
Humans are only good at working with models that do not include more than 30 elements (Horton  1991). Even more restricting is the rule by Miller (1956), based on the capacity of  our short-term memory, which states that humans are only good at processing seven plus or minus two elements at a time.

• Bonus: Any useful plugins or features in EA that are a must for this kind of work?

A complete list of plugins can be found here https://sparxsystems.com/products/3rdparty.html
If you are working with others like BA's doing process maps or requirements in MS Word, Excel or Visio then get the Office MDG so you can import their work and hook architectual elements to them to provide traceability.
eaUtils and EAMatic are also useful to improve productivity.

I’m using EA 16.1 (Ultimate Edition), and planning to eventually export documentation for both technical and non-technical stakeholders.

Any reason you aren't upgrading to latest version of 17.1? It has new features that may be useful. https://sparxsystems.com/products/ea/17.1/

[Modesto Vega]

We are experimenting with ArchiMate to model complex data integrations involving multiple systems/applications. Essentially we are presenting integrations as Application Collaborations, and categorising them as manual or automated. Any automated integrations involve a pair of collaborations interactions, one creating the data payload and another processing the data payload. Data payloads are represented by (Application) Data Objects.

We are also experimenting with using Application Interfaces to represent the actual application component producing the data payload.

I have tried to use UML for this in the past and it becomes very easy to get lost in the weeds. Although, I fully get why they are important.

Hopefully, you find this helpful.

[Williami]

How do you determine the specific needs and expectations of different stakeholders when selecting which UML diagrams to use?
Are there any best practices or tools that can help facilitate this process?
Thank you!

[Sunshine]

The open group has a list of view points and stakeholders https://www.opengroup.org/architecture/0210can/togaf8/doc-review/togaf8cr/c/p4/views/vus_intro.htm
If you use archimate then the standard also has a list of viewpoints and suggested stakeholders https://pubs.opengroup.org/architecture/archimate32-doc/ch-Example-Viewpoints.html however, a more comprehensive list of viewpoints can be found in the archimate cookbook https://www.hosiaisluoma.fi/blog/archimate/
As archimate and UML have similar notations its not too hard to imagine doing some of those archimate viewpoints in UML.
Sparx has some wizards for view points to https://sparxsystems.com/enterprise_architect_user_guide/17.1/modeling_languages/archimate-basic-viewpoints.html and https://sparxsystems.com/enterprise_architect_user_guide/17.1/modeling_languages/umldiagrams.html

[Richard Freggi]

Hello
here's my 2c!
1c: do not let your notation drive your model documentation: pick a methodology and then document your systems, processes and data accordingly
2c: Archimate is not the best for understanding the relationships and constraints between data, processes and systems, I think it's easier and more effectively done with UML
OK I lied here's the 3rd cent: don't focus on the diagrams to understand data, processes and systems: the diagram are just small windows into the overall model... the model is the XMI file (or the combined content of EA tables).  This is very Zen but if you understand the difference between a model and diagrams your life will become much easier... at least that's my experience

Good luck!

[Modesto Vega]

1c: do not let your notation drive your model documentation: pick a methodology and then document your systems, processes and data accordingly

This is an excellent point: notation should not drive model documentation. Having said that I find the current version of ArchiMate more intuitive than UML, but I do have some UML nostalgia like almost everything I extensively used in the 19902 and early 2000s.

2c: Archimate is not the best for understanding the relationships and constraints between data, processes and systems, I think it's easier and more effectively done with UML

ArchiMate is not the best for modelling data from a logical and physical point of view. I would not recommend use it for modelling data from a logical and physical point of view. From a conceptual point of view ArchiMate can be used to model relationships between data processes and systems.