Origin engineering/nasdanika.yml 1:1
Uri engineering://nasdanika

This page provides an overview of Nasdanika products.

The primary target audience of the Nasdanika product line are Java developers who use Maven.

The main theme can be expressed as “Efficient knowledge capture and dissemination” using Domain-Driven Design, Model-based Systems Engineering (MBSE) and code generation being the means to efficiently codify knowledge and then disseminate it.

Well, it’s a mouthful! Let’s elaborate a bit!

First of all, “efficiency” above means minimal requirements of human and computing resources per “unit of knowledge”. It also means hyper-local and hyper-focused experiences because humans are notoriously bad at context switching. One of approaches to minimize context switching is use of code generation using Java, e.g. generation of Bootstrap Web applications using fluent Java API. Another one is an option to author models in YAML without having to use a specialized model editor.

Computing resources-wise - no need in server components, you can use Nasdanika products on a flash drive in a bunker or in the wilderness with no network: --everything-is-hyper-local, paraphrasing the Git motto. Access to the Internet would be needed only to pull the required libraries from Maven Central or a mirror.

Sample scenario

You’ve got an idea of a new “something” - not necessarily software.

Depending on the problem at hand, how your brain is wired, and who you need to communicate your idea to, you may start with а domain model, flow model, or the engineering model.

Models

Engineering

With the engineering model you can define consumers of what you want to create - personas - and their goals. This will allow you to better understand and communicate the Why of your idea.
It will also allow you enlist help of others, e.g. potential users, to elaborate the personas and their goals - they likely know better than you what they want, unless you are building it for yourself.

Then1 you may define products and their features. You may break down products into modules. Align features to goals. This would define the What of your idea tied to the Why.

Then, define releases, issues, increments, engineers. Assign features to releases, issues to features or releases, and releases to increments. Assign issues to engineers. You may also assign responsible engineers to releases, features, and increments. This would define the How and the When both traceable to the What (features) and the Why (persona goals).

As it was mentioned above, all of that can be done on a local computer - you don’t need any server component, you don’t even need to keep it under version control, although it is a good idea. So, if you have a super-secret idea you can keep everything on an encrypted thumb drive and work on it at night in your basement. In a team environment you can use an isolated network to collaborate.

One more advantage of everything is local is that you may produce self-contained idea definitions which can be archived, copied/forked etc. It allows to establish a discovery-delivery pipeline where many ideas can be brought to high enough level of detail to allow efficient selection for delivery later. Having shared definitions of personas, goals, principles, and objectives would simplify comparison of ideas based on their benefit and cost.

There is more to it, see the engineering model documentation and a list of features for more details.

Flow

With Nasdanika Flow you can create and publish models of flows - graphs of activities performed by participants using resources and consuming and producing artifacts.

With Nasdanika Flow you can model customer journeys and team processes. Services allow to build flows “in terms” of other flows, e.g. a customer journey flow referencing an internal process as an activity. Inheritance allows to define common flows and then customize them. For example, in an IT organization there might be core development process and then technology and regions specific extensions.

The flow concepts are very similar to the concepts of a programming language, such as Java, or of a distributed system, such as a cloud application. In other words with Nasdanika Flow you can “program” or “codify” operations of an organization.

The journey package in the engineering model (work in progress) aims to provide a bridge between the flow model and then engineering model in order to allow to define flows at persona level, reference personas from participant definitions, products/features from resource definitions, etc. With that it would be possible to build persona (customer) journeys in terms of product features and services provided by the organization and its engineers.

Domain

Problem domain structure is captured in a form of EMF Ecore (meta) model using Ecore Tools, which are part of Eclipse Modeling Tools Package. You can use a diagram or a tree editor to create domain models.

Flow and Engineering models mentioned above are examples of domain models for different problem domains.

Domain models serve the following purposes:

  • Form a Ubiquitous Language - a common rigorous language between users and developers. Nasdanika HTML Ecore allows to generate documentation from Ecore models, “publish a dictionary” so to speak. It automatically generates pacakge diagrams, class context and inheritance diagrams. Documentation can be defined in annotations or loaded from external resources. Model documentation is written in Markdown and can contain embedded diagrams.
  • Generate Java code to load, diagnose, manipulate and save models. EMF Ecore provides capabilities to load models from and save to XML (XMI). Nasdanika EMF adds an ability to load models from an arbitrary storage of maps, lists, and scalars - YAML, JSON, properties files. When loading from YAML the loaded injects markers into the loaded objects to trace data elements to resource (file), line, column where they were loaded from. If a Git repository is detected then a GitMarker is injected instead with information about remotes and the commit hash. In a a model loaded from multiple resources residing in multiple Git repositories it allows to trace data elements to their source in “space” (repository, file, line and column) and time (commit).

You’ve probably heard before that “all models are wrong, but some are useful”. Models are wrong by definition because their purpose to reflect an aspect of interest of reality.

If we define usefulness as positive ROI and short time to market, then with Nasdanika approach to modeling it is easier to create a useful model because production and publication of a model requires less effort than alternative approaches as explained below.

Meta-Model creation

Use Ecore Tools.

Meta-Model documentation
Production of Meta-Model binaries
  • Nasdanika: Maven Java build publishing to a Maven repository.
  • Alternatives: Maven Tycho build generating a p2 site which needs to be hosted somewhere.
Model editing
  • Nasdanika: Any text editor to author YAML or JSON - use load specification from the generation documentation to create model instances.
  • Alternatives: An editor shall be created and published to a p2 site and used from Eclipse. Or a web server is needed to host an in-browser editor.
Consumption of Meta-Model binaries

To programmatically read or write models.

  • Nasdanika: Any Maven application - add a dependency.
  • Alternatives: Eclipse product, OSGi bundle dependency.
Consumption of model content
  • Nasdanika: Generate an HTML site from the model.
  • Alternatives: Requires Eclipse IDE and an editor/viewer or a server to host a web viewer

One area where Nasdanika approach to modeling may be useful is disposable/situational models - use a modeling approach to solve a problem which is small enough to justify investment into graphical editors, p2 hosting etc., but large enough to benefit from automation.

Metaphorically speaking, Nasdanika uses r-selection - create cheap models quickly, see which one is useful and then invest more if needed. The alternatives tend to be closer to the K end of the spectrum requiring larger up-front investment.

Use of the models

Populate the model

Once there is a domain Ecore (meta) model you can start creating model resources containing definitions of model elements. E.g. if your meta-model contains classes Organization and Engineer,
you may define organization, “Acme Corp.” with an engineer “Joe Doe”.

There are multiple ways to populate the model. Some of them are listed below. You don’t to use one particular way - they can be used in combination. Some resources in your model may be defined YAML and edited in a text editor, some other may be defined in XMI and edited with, say, a diagram editor. There resources can cross-reference each other.

YAML or JSON

You can create models in YAML, see EMF Persistence. With this approach, unlike the others listed below, you don’t need to create a specialized editor - just use a YAML or text editor and load specification pages of the generated model documentation as a reference.

Because models are defined in text, as-code, they are easy to collaborate on without the use of specialized merge tools - use traditional diff and merge as for other textual artifacts such as Java files.

This approach also allows to relatively easily load data from external systems which have no knowledge of your models’ XMI format. Data can be loaded from REST endpoints or from data exports.

Tree editor

You can generate a tree editor for your models using Ecore Tools. It is a relatively small effort, but you’ll need to build it, publish to a p2 repository (update site) and model authors will need to have Eclipse IDE and to be able to install the editor.

Diagram editor

With Eclipse Sirius you can generate visual diagram editors and with Sirius Web you can provide a web interface for editing models.

Specialized text editor

With Xtext you can create a specialized text editor with syntax highlighting, code completions, live validation and other features.

Custom resources and factories

You can also load data from external sources by implementing a custom Resource and Resource.Factory. YamlResource and YamlResourceFactory are examples of such implementation.

For example, you may create a resource to load issue information from Jira using Jira Java API.

In Domain-Driven Design terminology such resource and a resource factory would act as an Anti-Corruption Layer.

Web application

So you’ve captured quite a bit of knowledge in your models, now it is time to share it! One way to share knowledge with humans is to generate a web site. For example, this site was generated from multiple engineering models stored in multiple Git repositories with documentation generated from Ecore models “mounted” to it.

You can add dynamic read-only behavior to the generated site using Single-page applications which use model data. All issues page is an example of such an application built with Vue.js and BootstrapVue. It uses browser local storage for user preferences. This approach allows to have highly focused mini-apps injected into a static web site.

Shall you need more dynamic behavior you can use helper web services. In this case model data can be used as input to the services in addition to user-provided data putting user input into a context. E.g. a single site may have multiple mini-apps calling the same service but with different inputs.

Programmatic

Model data can also be used by computers. In Java you use the generated model classes. You may load your model from multiple sources and then save it to XMI which can be published to a binary repository or on a web site.

In non-java scenarios you may generate code in the target language. E.g. cross-referencing JSON files for a static REST API or JavaScript files to use model information in the browser. It can be done in combination with generating a static file, i.e. your site would contain both HTML and JSON/JavaScript. In this case JSON/JavaScript can be used by the mini-apps.

Products overview

This section provides a brief overview of Nasdanika products and their modules.

  • Core - foundational functionality
    • CLI - classes which allow to call execution model Command from a command line.
    • Common - common functionality such as the execution model, resource and persistence frameworks.
    • Diagram - Diagram EMF model is a level of abstraction to create diagram visualizations using Java API and then generate PlantUML and diagrams.net diagrams from it.
    • EMF - classes for working with Ecore models, e.g. classes for loading models from YAML files.
    • Exec - Ecore models and adapters to execution model participants to build code generators and to load model content from different sources.
    • Flow - Ecore flow model to capture customer journeys/business processes.
    • Ncore - Ecore model containing common classes used/extended in other models.
  • HTML - Java API’s and models for generating HTML
    • Bootstrap - Fluent Java API to generate Bootstrap 4 markup.
    • Ecore - Classes to generate documentation of Ecore models as action models (see Models/Application below).
    • EMF - Base classes for building generators of action models from Ecore model elements.
    • Flow - Generators of action models from the flow model elements.
    • HTML - Fluent Java API to generate HTML 5 markup.
    • jsTree - Java API for generating jsTree JSON.
    • Models - Ecore models to build HTML pages and applications.
      • HTML - Ecore model representing HTML elements and generation adapters.
      • Bootstrap - Ecore model representing Bootstrap 4 elements and generation adapters.
      • Application - Ecore model representing a web site/application as a hierarchy of actions. Adapters to generate HTML sites (resource models) from action models.
  • Engineering - Ecore model representing (software) engineering concepts such as an organization, engineer, product, release, feature, issue, … Adapters for generating HTML sites from engineering models.
  • TOGAF - Models representing TOGAF concepts.

Nasdanika products are Java-based, hosted on GitHub Nasdanika organization and published to Maven Central:


  1. Or before, or in parallel - totally up to you. Start somewhere, expand from there.