Displaying items by tag: state machine
Tutorial: How to create a full-stack React Bootstrap UI from your EA model in under 10 minutes
How to create a full-stack React Bootstrap UI in under 10 minutes
A tutorial and reference on designing a complete web application and generating it with CodeBot UX
by Matt Stephens, Parallel Agile
This article was originally published here: https://medium.com/parallel-agile-blog/create-a-full-stack-react-bootstrap-ui-in-under-10-minutes-d0eec3077618
CodeBot from Parallel Agile is a full-stack application generator, which can also host your generated application in the cloud. Give CodeBot a domain model and UI wireframes, and it’ll create:
- a React web UI
- a MongoDB database
- a Node/Express.js REST API, optionally secured using JWT
- API client libraries — currently Java and JavaScript, with other languages set to be released soon, including C#, Swift, TypeScript
- JSON Schema
- Swagger/OpenAPI docs
We have more targets, platforms, architectures and languages on the way, but that’s plenty to get started with!
To whet your appetite, here’s a quick CodeBot video that shows a project being turned into a generated UI:
Getting Started
To get started designing your new application, you’ll need:
- a copy of Enterprise Architect (EA) to create the domain model and wireframes
- a CodeBot account from Parallel Agile
At the time of writing, the generated React UI isn’t in full release, but it’s available under Early Access for customers with a CodeBot license (to gain access, please email us)
There’s also a handy series of step-by-step CodeBot 101 videos that show how to get everything installed and set up — so I won’t repeat those details here:
- Creating and Activating your Account
- Installing the Parallel Agile Add In for Enterprise Architect 2
- Taking CodeBot for a Spin
VSRADS Example
In this article I’ll walk through the a much-simplified version of the “VSRADS” model shown in the above example video.
VSRADS stands for “Very Short Range Air Defence System” — it’s basically a mosquito zapper. It listens for the high-pitched whine of a mosquito flying by, calculates its position and trajectory, and zaps it with a low-frequency laser.
Our example project is a state machine simulator… given a series of states, a web page is generated to represent each one; and the state machine itself is turned into the navigation “user flow” between pages — i.e. the routes.
So let’s get started!
Step 1: Create a project with 3 top-level packages
Create a new, blank project in EA, and give it the following 3 packages (via “Add View” in the right-click menu):
This will become a familiar pattern… the “three amigos” for defining a new full-stack project
When the model is generated later, the elements in each of these packages will contribute to the generated application, as follows:
- Each wireframe is turned into a React web page
- The navigation state machine is turned into a set of routes
- Each domain class (created in the Domain Model package) is turned into a MongoDB collection and REST API create/read/update/delete endpoint
Step 2: Draw the domain model
Under “Domain Model”, create a class diagram and populate it with some domain classes.
The complete VSRADS domain model looks like this:
For this example you could just create a subset — just be sure to include Simulation Run, as we’ll be linking it to the UI and database.
Step 3: Design the UI Navigation
The idea is that you design individual screens as wireframes, and link them together via a “user flow” or navigation diagram; in this case we’ll draw the user flow as a state machine:
- Each state represents a screen or page
- Each transition (the arrows linking the states together) represents a navigation route
Navigation routes are triggered by things like clicking a link, or submitting a form — “create” or “update” actions.
To introduce the idea, here’s a “hello world” kind of example:
Each generated page will be given its own URI (/login, /view_products etc) so can be individually bookmarked. However, the “Initial” pseudo-state is used to determine which page is displayed by default— the “navigation root” or home page.
Back to VSRADS though… this is a more complex state machine:
Each transition arrow has been given a trigger, which is shown as a label in the diagram. To add a trigger, double-click on the transition:
In EA, you don’t need to select the trigger type etc, you can just enter a name, to keep it simple.
The name needs to match up with the component name in the wireframe, e.g. a button called “Target Identified” — you’ll see some examples of this in the next section.
Usually, the trigger name is also prefixed with an event type, such as on click: or on create: . However, “on click” is the default, so can be omitted.
It’s also worth noting, if the button name is the same as the target page, then CodeBot will figure it out, so you then don’t even need to give the transition a name.
The following event prefixes are supported:
- on click— e.g. “on click: Login”
- on create — e.g. “on create: Target”
- on update — e.g. “on update: Target”
The events all take place in the “source page”, i.e. the page that the transition arrow points from. The trigger will, as you’d expect, result in the app navigating to the “target page”.
The create and update events are triggered when a form is submitted in the “source page”.
Now that you have the overall website or application designed, it’s a good time to create a wireframe for each one.
Step 4: Design the wireframes
EA has a UI wireframe designer built-in. Because the wireframes are fully integrated into the UML model, you can link together wireframe elements, classes, states and other elements… so everything fits together in the generated project.
The VSRADS model has 8 wireframes in total. For this article we’ll focus on two of them, Set Up Simulation (the start page), and Listening for Mosquitoes.
Creating a Wireframe
Right-click on the Wireframes package and choose New Diagram:
In the new wireframe, you need to create a top-level frame which serves as the page-size boundary. This may seem less relevant for websites, but will become important when CodeBot also generates other platforms such as mobile apps. (New feature coming soon!!)
Always add a “Client Area” to represent the page boundary, and fit all the wireframe components inside it
Next, add some components to the page!
Currently with the Early Access release, CodeBot recognises a subset of all the available components. So for now, be sure to only add from the Controls and Website Controls tool palettes.
Position and size the components to match your page design. CodeBot will translate this into a responsive website layout; e.g. it’ll detect grids of label/textfield pairs, alignment of individual labels or buttons, etc.
You can also supply hints to influence how the page is generated. In EA, this is done via tagged values — you can find these on the Tags tab in the Properties panel:
In the above screenshot, the Set up Simulation title has been given a tag called css class, with the value h1 (“Heading 1”). To add more than one CSS class, separate them with spaces.
The generated website uses the popular React-Bootstrap project, meaning you can specify any “Bootstrap-standard” CSS classes here.
Another useful tag is variant. This conforms to the Bootstrap 4 colour variants:
For example, the Run Simulation button is given the “primary” variant (the exact case doesn’t matter) via a tagged value, so will be rendered in the page with a solid-blue background:
In this way, it’s possible to adhere to Bootstrap’s design language—the “primary” variant represents the main or default action, etc.
For future platforms even if they don’t use Bootstrap, CodeBot will adapt the same “Bootstrappy” tagged values to the target platform, so you’ll only have to draw the wireframes once in order to get a generated website, mobile app, desktop app etc.
Just to illustrate another page in the same UX design, here’s the Listening for Mosquitoes wireframe:
The Image component can display any image type normally supported in web browsers (jpeg, gif, png). Just include a url tag with the complete URL where the image can be loaded from.
Step 5: Define actions on UI elements
In the previous screenshot, the Run Simulation button also has a tag called action, with the value create.
As long as the button resides in a container panel with form components (text fields etc), when the button is clicked, the form will be submitted to the generated REST API. What happens next depends on the value of the action tag:
- create (create a new record in the database)
- update (update the current record)
The form elements do need to be linked to a particular domain class, though; so let’s do that next.
Step 6: Link UI elements to the domain model
There are two ways to associate UI elements with a particular domain class:
- Use the domain tag
- Draw a dependency relationship from the UI element to the domain class
Which one you use is entirely up to you; the effect on the generated code is exactly the same. It’s more of a stylistic choice, as some people appreciate the visual aspect of seeing a link on the diagram, while others prefer the detail to be tucked away.
Domain tag
Click on the form component you’d like to link, and add a tag as follows:
The domain tagged value uses the form:
Class Name.attribute name
e.g. Simulation Run (the domain class), a dot, then name (the attribute name).
As a time saver, you can also just add the domain class name to the parent container panel:
The “child” form components are then auto-linked to the domain attributes, by matching each component name with an attribute name.
Once this linking-up is done, then when the generated form is submitted, it’ll automatically call the correct REST API endpoint for that domain class.
Dependency arrow
As an alternative to the domain tag, simply drag the relevant domain class from the package explorer onto the wireframe. Then draw a dependency arrow from the container panel to the class:
You can also link the individual text fields to the class, if preferred.
To emphasize again, this has exactly the same effect as using the domain class; which you use is just a personal preference.
Step 7: Generate the application
If you have the CodeBot add-in installed in EA, right-click on the root (“Model”) package in the package browser. Then choose:
Specialize > Parallel Agile > Generate Project
If you can’t run the add-in for any reason (e.g. you’re on a Mac using a Windows VM), another way to run CodeBot is as follows:
- Make sure you’ve selected the root (“Model”) package, then from EA’s ribbon menu, choose:
Publish > Export-XML -> Export XML for Current Package - Login into the CodeBot Web Console at parallelagile.net, and choose Upload XMI:
CodeBot will detect that the model contains wireframes, and automatically generate a Bootstrap-React project. You can find it in the downloaded zipfile, in the UX/React folder.
Step 8: Run the React app!
You can optionally elect the generated application to be hosted — just make sure the “Publish to our cloud service” checkbox in the above screenshot is ticked.
In this case, CodeBot will automatically build the React app, and then publish the full website, REST API and database to our secure cloud service.
To access the hosted website, click the blue Visit Website button (visible in the above screenshot).
The Set up Simulation page will load in a separate tab:
When you enter some form details and click Run Simulation, the following series of events take place:
- Due to the action tag and the linked domain class, the React app submits the form to the REST API
- The REST API validates the form data against the generated JSON Schema (based on the domain class and attributes), then creates the new record in the MongoDB database
- Due to the on create: Run Simulation trigger on the navigation state machine, the React app will detect that a “create” just happened linked to the Run Simulation button. So (as the trigger is on a transition), the browser navigates to the next page, Listening for Mosquitoes:
In closing…
CodeBot UX radically shortens the iterative feedback loop when developing new software. When domain modeling, you can now quickly create a working prototype, use the prototype to elicit new or changed requirements, feed the updates back into the model, rinse and repeat…
… often several times in the same workshop session, with the customer or domain expert right there in the room (or on the same Zoom call).
CodeBot UX is available now for Early Access customers. To request access, please email us at: This email address is being protected from spambots. You need JavaScript enabled to view it. — we’ll welcome your feedback!
CodeBot UX is available to early access users
FOR IMMEDIATE RELEASE: November 23, 2020
Urvashi Prakash Parallel Agile
This email address is being protected from spambots. You need JavaScript enabled to view it.
No Code App Generator, CodeBot UX is available to early access users
November, 2020, Los Angeles, CA: Parallel Agile’s full-stack application generator, CodeBot UX, is now available to early access users. With CodeBot you can already generate full-stack applications from a domain model, while its newly engineered UX components allow users a smoother and far more nuanced and centralized approach towards app generation.
Codebot UX supports Enterprise Architect UML models including class diagrams, state machines and wireframes. From these, CodeBot generates a database schema, API documentation, server-side code, client-side code including domain classes, CRUD functions and usage examples. While supporting both SQL and non-SQL databases, CodeBot also generates all three layers of the MVC framework.
CodeBot can also automatically host your generated web application in the cloud, at the click of a button.
According to Matt Stephens, Director of Development for Parallel Agile: "Our ability to link screens to an auto-generated database access API and to drive UI navigation from state machines effectively makes MBSE models executable, fulfilling a vision originally set out in 2002 when Steve Mellor wrote Executable UML".
With this early access release, the following React UI components are ready for users to try out: Panel, Button, Label, Text field, Table and Video Player.
CodeBot UX initially targets React, but will soon build equivalent user interfaces for React Native, Vue.js and Angular. Video illustrating CodeBot UX (MBSE: CodeBot for Software Intensive Systems) is available on YouTube.
Doug Rosenberg, Parallel Agile CTO, states: "CodeBot UX’s ability to generate working screens from wireframes to full stack code generation and automatically host the working application, introduces a new model-driven development paradigm where CodeBot effectively serves as a UML compiler, producing running applications directly from UML or SysML models."
More about the company:
Parallel Agile addresses the underlying technical issues with integrating work done by large teams in addition to the management issues – specifically enabling large teams of developers to collaborate efficiently and reduce schedule time on projects. The company offers training in UML, SysML, MBSE, and Agile development in addition to its full-stack application generator, CodeBot.
Early Access Program
Parallel Agile’s early access program allows CodeBot licensees to gain access to a growing range of new features and capabilities. New CodeBot customers can request early access when they purchase their license.
CodeBot UX is available immediately for early access users.
For more information on CodeBot, please visit www.parallelagile.com or email us at: This email address is being protected from spambots. You need JavaScript enabled to view it.
###
Automated FMU Generation from UML Models
Automated FMU Generation from UML Models
Introduction
The simulation of cyber-physical systems plays an increasingly important role in the development process of such systems. It enables the engineers to get a better understanding of the system in the early phases of the development. These complex systems are composed of different subsystems, each subsystem model is designed with its own specialized tool sets. Because of this heterogeneity the coordination and integration of these subsystem models becomes a challenge.The Functional Mockup Interface (FMI) specification was developed by an industry consortium as a tool independent interface standard for integration and simulation of dynamic systems models. The models that conform to this standard are called Functional Mockup Units (FMU).
In this work we provide a method for automated FMU generation from UML models, making it possible to use model driven engineering techniques in the design and simulation of complex cyber-physical systems.
Functional Mockup Interface
The Functional Mockup Interface (FMI) specification is a standardized interface to be used in computer simulations for the creation of complex cyber-physical systems. The idea behind it being that if a real product is composed of many interconnected parts, it should be possible to create a virtual product which is itself assembled by combining a set of models. For example a car can be seen as a combination of many different subsystems, like engine, gearbox or thermal system. These subsystems can be modeled as Functional Mockup Units (FMU) which conform to the FMI standard.The Functional Mockup Unit (FMU) represents a (runnable) model of a (sub)system and can be seen as the implementation of an Functional Mockup Interface (FMI). It is distributed as one ZIP file archive, with a ".fmu" file extension, containing:
- FMI model description file in XML format. It contains static information about the FMU instance. Most importantly the FMU variables and their attributes such as name, unit, default initial value etc. are stored in this file. A simulation tool importing the FMU will parse the model description file and initialize its environment accordingly.
- FMI application programming interface provided as a set of standardized C functions. C is used because of its portability and because it can be utilized in all embedded control systems. The C API can be provided either in source code and/or in binary form for one or several target machines, for example Windows dynamic link libraries (".dll") or Linux shared libraries (".so").
- Additional FMU data (tables, maps) in FMU specific file formats
The inclusion of the FMI model description file and the FMI API is mandatory according to the FMI standard.
Tools
Enterprise Architect is a visual modeling and design tool supporting various industry standards including UML. It is extensible via plugins written in C# or Visual Basic. The UML models from which we generate our FMU are defined with Enterprise Architect.Embedded Engineer is a plugin for Enterprise Architect that features automated C/C++ code generation from UML models.
We further used the FMU SDK from QTronic for creating the FMI API. It also comes with a simple solver which we used to test our solution.
Running Example
Our basic example to test our solution is called Inc. It is a simple FMU with an internal counter which is initialized at the beginning and it increments this counter by a specified step value, each time it gets triggered, until a final to value is reached or exceeded.State Machine
The state machine contains just an initial pseudo state which initializes the state machine and a state called Step. The Step state has two transitions, one transition to itself, in case the counter is still lower then the to value, if this is the case, the inc() operation will be called and we are again in the Step state. If the value is equal or greater to the to value, it reaches the final state and no further process will be done.Class diagram
The class diagram consists of two parts. The left part with the Inc class is project specific. It holds three attributes: counter, step and to. All attributes are of type int. The initial value for the counter is 0, for the step it's 5 and for the to value it's 50. The FSM classes on the right are the mandatory classes for the Embedded Engineer to be able to generate the state machine code.Some specific implementation code also exists in various places. In the state machine you can see, that we have some guards on the transitions. These guards are actually code that will be used to generate the code for the state machine:
me->counter < me->to
and
me->counter >= me->to
The property me represents a pointer to an instance of the Inc class.
And finally the implementation of the inc() operation is also provided:
me->counter = me->counter + me->step;
Manual Code Generation
First we manually created our reference Inc FMU, the following steps where taken:- UML models were defined in Enterprise Architect (class diagram and state machine diagram)
- C code was generated from the previously created models (with the Embedded Engineer plugin)
- The FMI model description xml file and the FMI API were created by hand
- The (compiled) FMI API was packaged together with the model description file into a FMU file. This was done with a batch script.
Automatic Code Generation
Now we want to automate the creation of the FMI model description file and the FMI API. For this purpose we wrote our own Enterprise Architect plugin. To be able to generate semantically correct FMI model description and FMI API artifacts, we attached additional information to the UML models. This was achived through the definition of various UML stereotypes for UML class attributes and methods. Since the FMI defines its own data types we also had to map the data types used in the UML models to the corresponding FMI data types. With these challenges addressed we were able to implement our FMU generation plugin.Future Work
Our work comprises a fundamental prototype that is only a start and could be improved in various ways. The following list describes some issues that could be tackled.- One limitation of the current implementation is that we are not able to provide initial values for the FMU. Consequently, to test different configurations of our FMU, we always have to set the default values in the UML models and regenerate the FMU for the simulator again. Hence, future work includes creating new stereo types for initialization of FMU settings/variables and testing these bindings.
- We used the FMU SDK simulator for this project. Other (more powerful) simulators should be tested too. Furthermore, co-simulation with other FMUs needs to be tested.
- In our project we restricted ourselves to just look at discrete functions by using the event system of the FMU. To continue the journey we also have to consider continuous functions.
- More complex examples should be considered to test the capabilities of the automatically generated code. By creating more complex examples the practical limitations of modeling a FMU with a class diagram and a finite state machine need to be discovered. Questions like "What can be implemented?" and "What can not be implemented?" need to be answered.
- The automated code generation process could be reduced to a one-click functionality to directly generate the ".fmu" file without any additional compilation and packaging step necessary.
Acknowledgement
Screencast
Creating and Simulating (also validating) a state machine using Enterprise Architect
Recently I have been reverse engineering a state transition (officially a state machine but I prefer the term state transition model) to understand the complex life-cycle of our application’s central object.
I had seen a demo on model simulation but the focus was more on a generated model from source rather than a hand fashioned UML model. This post is a walk through on the process and hopefully some takeaways from what I’ve learned.
Understanding complex systems
I came into a project that is well down the road to completion but sorely lacking in any concrete documentation which was becoming a pain point for everyone – and particularly for me – the new analyst tasked with helping out.
One of my first tasks was to document some ‘light’ form of a state model to get an idea of all of the possible scenarios and break down some of the complexity. I’ve iterated through several versions (or styles) of the state model trying to provide a simpler view of states and state transitions but the model was just very complicated and the diagrams were too busy. Understanding it myself was hard enough and trying to validate each of the scenarios was proving far too time-consuming.
States and multiple sub-states – too many paths!
My main problem was due to having states and multiple sub-states being dependent on single transitions. For example, we had something like this
OBJECT (super state life-cycle)
-- sub item1 (sub state life-cycle)
-- sub item2 (sub state life-cycle)
-- shipping item (sub state life-cycle)
-- other items (sub state life-cycle)
So for every transition, we could have movements of one or all of the sub-states, and depending on what states they were in, we could also have super-state changes.
I threw together a quick example of what things (sort of!) looked like in our world – its a horribly rushed example but gets across the point.
Model simulation and simulation variables!
So I got to the point where I’d modelled enough states and sub-states that it was very difficult to validate the accuracy – so I decided to use a bit of smarts and try out model simulation.
I setup my workspace to get the simulation controls ready. It looks somewhat like this.
With this setup we can kick off model simulations to run through transitions, select the required ‘trigger’ to choose paths and even save triggers to define pre-defined scenarios to run through. Note: I’ll post a separate article on how to do each step in more detail.
All of this is nothing new? Well that's get into some simulation variables to track what's going on at each point.
First of all, I’ve run through a created scenario manually (interpreted in EA language) by manually selecting the triggers as they come up. You can then save these as a trigger set and select to signal the triggers automatically – now we can fly through our models after defining our criteria.
The above shows a simulation in action as it goes through the path I defined manually and you can see the trigger sequence waiting to be fired to progress the simulation further.
What I end up at the end is a list of states / decisions / elements that I have passed through in the console log and a list of triggers that were fired.
For me this wasn’t all that useful – just a flat list of states and sub-states at a single level wasn't;t really enough – plus there was more detail I wanted to capture that would make these even more useful.
Enter simulation variables
I stumbled on simulation variables when trawling through some EA help file about getting my simulations to work and instantly through of a use (more on that soon).
Given I am reverse engineering a model and not trying to do and model-driven development, I feel I can use simulation in this way but I certainly appreciate this is a hack job and not their intended purpose (sorry everyone!).
I added an operation to each state called ‘updateVars’ and added a behaviour to each to assign simple variable.
EA uses JavaScript notation when performing UML model simulations, so we can just assign variables as we need them. Now you see why I had the variable window open before right?
Protip: To avoid cluttering up your diagram with all your updateVars on each state element – hide the operations from the diagram in the diagram properties. Un-tick the ‘Operations’ box under Show Compartments.
So now that I have added simulation variables to my model, I can see what the states and sub-states are at any given point in the model – either by pausing or setting simulation break points (another great feature!).
Writing to simulation console
Although simulation variables were interesting they didn't really offer me much over what I had before – just a different way of viewing the same state/substate information. What I really wanted was to be able to use this concept to show other important things that are going on at certain steps.
Another cool feature Sparx have included here is being about to output to the simulation console so you can supplement the standard list of element names with your own text.
So at certain steps, I have UI actions or account deductions, that I wanted to bring into my model and highlight to my stakeholders where and when these were actually occurring. Strictly nothing to do with a state machine but I'm not here to win UML medals – just provide my stakeholders something they can understand!
So on one of the updateVars actions I can add another line like this:
The magic words here are Trace() which allow you to output a string to the console log. What does it look like in the simulation console? I'm glad you asked – it looks something like this.
I ended up adding custom Trace() events for each state so I could better represent state /sub state movements and also record important events along the model.
Hopefully you followed along with me on this and I’ve had some interest regarding doing a screencast on the topic so please let me know in the comments if you’re interested and I’ll get one together.
This was an overview article to demonstrate the main features and I will come back and go through some of the steps I rushed through in more detail in the next post.
State Machine Simulation in Enterprise Architect
This paper introduces Enterprise Architect's simulation capabilities for State Machines by means of an example model.
State Machine simulation can help you to verify that the run-time behavior of your designed system conforms to specification. In this paper, we explore an example 'Digital Clock' system model and bring to life several aspects of Enterprise Architect's State Machine simulation support.