If you have installed DesiGen and got as far as the home screen, you may wonder where to start with using it. This tutorial will guide you towards success with creating and using your first design, in an attempt to give you insight into why we think this tool is so powerful.
Once you have learned how to use DesiGen, you will find it easier to build your own designs from scratch, without wanting to use any of the starter solution templates. A blank solution template exists for that very purpose, but to get you started we will walk through using one of the starter solutions, so that you get a faster headstart.
Step 1 - Create a System
Designs are categorised by System. This is a logical grouping of designs that will make it easier to find a particular design once you have been using DesiGen for some time.
You can use System for whatever you want, but we have found it commonplace for development teams to be responsble for more than one separate system. Sometimes this takes the form of multiple separate solutions that represent different products offered by a company. At other times, some of them might be systems that are only used internally, such as for administration of the day to day operations of a department within the company.
For now, we just need to create a container for our first design. Let's create a system called 'Testing' in which can group all of the designs we create to understand what DesiGen can do, without intending to create production-ready code.
From the home screen, click 'Create Design' and on the subsequent screen, next to the System dropdown, click the 'Manage' button. This takes us to the Manage Systems screen.
If there were any systems they would be displayed here in a list. As it is, the list is empty, because we haven't created a system yet. Click the 'Add' button to change that. Enter the name 'Testing' for the system name and click Save.
Click the 'Home' link from the menu and then click 'Create Design' to start the creation process. This time, the 'System' dropdown should be populated, so choose the 'Testing' system, enter the name 'My First Design' as the design name, and click 'Create' to create the design and navigate to it.
Step 2 - Enter requirements
The first step in the definition of a design is to enter some summary of the requirements, so that in the future we can tie this design back to the change with which it was associated. In everyday use you could enter a reference to the ticket or user story for which the design is being created, but for now we'll just enter the text 'Creation of my first design' and click 'Next'.
Step 3 - Create Data Structures
Data structures are collections of fields that we may wish to work with together. A data structure might represent all of the fields we want to put into a table in a relational database, or the properties of a document to be stored within a NoSQL data store - but it doesn't have to be persisted at all.
Let's create a data structure to help us understand the process. We can use this data structure later to understand more of the tool's features. Click 'Add' to begin the process.
Enter a name for the data structure. Let's use the name 'Person' in this example.
The Fields list shows a default field called Id. For better clarity, we might choose to rename this field. Personally I prefer to have fairly unique names for Id fields, so that SQL queries are more readable, but that is personal preference. For this demo the default name is good enough.
Let's add a couple of extra fields. Click the 'Add Field' button beneath the Fields list and add a new field with the name 'FirstName', the data type of 'Unicode String' and a length of 100 characters. We will leave the 'Required' checkbox checked, indicating that we require that a user enter a first name. Repeat the process to add a 'LastName' field with the same data type, size and characteristics.
Before we finish, let's check the 'Contains PII' checkbox to indicate that we are creating a data structure that contains personally identifiable information as defined in GDPR. We can use this checkbox to identify that this is an area of the system that brings additional risk; GDPR requires that we consider how the data is stored and manipulated, as well as how long it is to be held for before it is deleted.
Note that the 'Include Audit Fields' checkbox is checked for us. This will automatically add four extra fields for us that can be used for in-row auditing. These fields have special properties that allows us to identify their function and automatically use them for special operations, including concurrency management.
Click 'Save' to save the Person data structure.
We only need one data structure for this demo, so click 'Next' to move to the next step in the process.
Step 4 - Create Artefacts
Artefacts represent the output we are designing. We will generally have a lot of artefacts, so this is where the majority of our design time will be spent.
Artefacts are defined in a hierarchical structure; this both helps represent how they will be output and allows us to pass properties from a parent to a child, which simplifies the work we need to do at design time. Generally, a design is likely to be made up of a solution, containing several projects. Each project might contain a number of folders, with the projects or folders containing item artefacts. Think of item artefacts as the leaves of the tree structure; these cannot contain children.
You don't have to have all of these types of artefacts and there is no limit to the number of each you have, but following this general pattern will provide a lot of benefit, so that is what we will do today.
Creating all of these artefacts might sound like a lot of work - and it could be, were there not a shortcut here. Fortunately, we can add multiple artefacts at once, using one of many predefined Artefact Set Templates. In the future, you will probably want to create your own Artefact Set Templates, but today we will use one of the built in ones to get us going.
Skeleton structure
We ideally want to create as many artefacts at once as possible. Fortunately, there are several Artefact Set Templates that do exactly this for us. Click the 'Add Multiple' button to see a list of the available sets. On this next screen, we can see Artefact Set Templates are displayed hierarchically. The hierarchy of categories is intended to make finding a particular template easier.
Scroll down and fond the 'Solutions' category, and within that the 'CSLA' subcategory. Click on the 'Blazor Server Solution using CSLA' template; that's what we will use for the tutorial. With the template highlighted, the OK button appears. Click that to start the process of addition.
Each Artefact Set Template is split into batches of artefacts. Batches are used to allow us to specify some high level parameters that apply to all of the artefacts in a batch, which can include where the artefacts are to be placed and the data structure with which they are to be associated. For a solution artefact set we need do neither of these things. Solutions are created at the root of the tree of artefacts, and are not associated with a data structure. Because we don't need to specify these parameters the 'Edit Artefact Set Template Batch' screen looks a little bare, but it does at least summarise what we will be adding. Click 'OK' to start adding the artefacts.
During the creation of artefacts you will sometimes have the opportunity to edit them before they are added. This simply saves time later - rather than changing properties on them at a later date, we can do it now as we step through the wizard. Not all artefacts need editing; in some projects there are a number of default artefacts whose properties are entirely predefined and are unlikely to need to change, so we do not display them and simply add them immediately. However, there are a number of things we need to know about solutions and projects, so in this case you will be asked to edit a number of the artefacts as we go through.
This template is going to add a solution and 5 projects. Note that we have the opportunity to skip the addition of artefacts; this skips that artefact and all of its children. In this case, we want them all, so there will be no skipping today! Here is how to define the properties as we need them. Note that I include single quotes around the values to enter to delineate them, but you shouldn't enter them!
Solution
We need to give the solution a name. Enter 'MyFirstSolution' into the 'Artefact Name' textbox.
We also need to define where in the file system we will place this solution when we create it. Into the
'Output Folder' textbox enter a location on your hard disk that is appropriate for you. I am using
'C:\Temp\Demo\MyFirstSolution'. Note that we don't want a trailing backslash on this location.
Copy and paste the value you have put in the 'Output Folder' as we'll need this again in a moment.
Click 'Create' to record your choices and move to the next artefact.
Blazor Server project (the user interface project)
This next artefact is the project in which we will define the user interface. Here, enter the following values:
Name: 'MyFirstSolution.WebUI' Output Folder: 'C:\Temp\Demo\MyFirstSolution\WebUI'
This value for 'Output Folder' must be a subfolder underneath the one you defined in the previous step, so paste that value in and then add the name you want to give the subfolder for this project. Again, please be sure not to include a trailing backslash!
Click 'Create' to move to the next artefact.
User Interface Orchestration project (the code that defines the functionality of the user interface)
This next artefact is the project in which we will define how the user interface works. Here, enter the following values:
Name: 'MyFirstSolution.UIOrchestration' Output Folder: 'C:\Temp\Demo\MyFirstSolution\UIOrchestration'
Click 'Create' to move to the next.
Business Objects project (the business objects and rules)
This next artefact is the project in which we will create our business objects. Here, enter the following values:
Name: 'MyFirstSolution.Objects' Output Folder: 'C:\Temp\Demo\MyFirstSolution\Objects'
Click 'Create' to move to the next.
Data Access project (the code that interacts with the database)
This next artefact is the project in which we will place code that accesses the database. Enter the following values:
Name: 'MyFirstSolution.DataAccess' Output Folder: 'C:\Temp\Demo\MyFirstSolution\DataAccess'
Click 'Create' to move to the next.
Data Storage project (the definition of the database)
This next artefact is the project in which we will define the structure of the database. Enter the following values:
Name: 'MyFirstSolution.DataStorage' Output Folder: 'C:\Temp\Demo\MyFirstSolution\DataStorage'
Click 'Create' to move onwards. With all of the data entered, the system will add all of the artefacts. There will be a slight pause while they are all created and saved into the design, before a confirmation screen is shown.
Click 'Finish' to return to the 'Edit Artefacts' screen. You can now see all of the artefacts that were added. Not only were the solution and all of the projects created as we defined them, but a whole host of plumbing was added in as well, all without us needing to define them. Not too shabby.
Hopefully you are now starting to appreciate the power of the system - but wait, there is more. So far we don't really seem to have achieved anything we couldn't have done by creating a custom solution template for Visual Studio/.NET, but the next bit is where we start to move well beyond that.
Custom Functionality
Next we want to add in some custom functionality. This allows us to see the power of what we can achieve through the use of this tool.
We're going to add an edit of Person to the design. We will need to add artefacts in each of the projects to make that all work. Here goes.
User Interface and UI Orchestration
We will need to create some Blazor/razor components that will display a list of the existing people, and allow us to add, edit and delete them. We also need some code to make those buttons work. We're going to use the MVVM pattern here, so the code for the user interface's behaviour will go in a ViewModel. We have an Artefact Set Template for creating all of these things - let's use it.
Click 'Add Multiple' and in the selection screen find the category 'Items' - 'UI' - 'Blazor' - 'CSLA' and click on the 'Manage, List and Edit Components and ViewModel' to select it. Click 'OK' to move to the next screen.
Next we see the 'Edit Artefact Set Template Batch' screen again, but this time we can see it full purpose. This template requires that we define some more parameters - the location and data structure that I mentioned earlier.
As you can see at the top, this first batch is about the Blazor components. We need to define where those are to be placed in our hierarchy. We want them to go into the 'Components' folder that resides within the 'MyFirstSolution.WebUI' project. Click on that node in the tree to select it.
We also need to define what data structure these items are to be associated with - in other words, what fields we want to be editable via our screens. In the 'Data Structure' dropdown beneath the tree view, choose 'Person'.
Click 'OK' to move to the next step in the wizard.
Our second batch is about the ViewModel. We want to place this into the 'MyFirstSolution.UIOrchestration' project, so click on that node to select it. Use the 'Data Structure' dropdown to associate the ViewModel with the 'Person' data structure as well. Click 'OK' to move on.
Next we get the opportunity to edit the properties of each of the artefacts we are adding. for our purposes the default properties for all of these artefacts will work fine. Click 'Create' on each of the screens until we get to the confirmation to tell us they have all been added. Click 'Finish' to go back to the 'Edit Artefact' screen.
You should see all of the artefacts we added in the tree, right where we said we wanted them.
Business Objects
Next we need some business objects with which our screens can interact. These will define the rules of the system, and are reusable in other user interfaces if we choose to create them. For today's tutorial we will use CSLA business objects, as we get a lot of bang for our buck that way. Why CSLA offers a good choice for this later is something for another day. Put in a pin in that.
We're going to need 3 business objects for the edit we are delivering. First, we need an editable object whose properties we can modify, which defines all of the rules of what is valid and what is not, and which is capable of saving itself to the database. That's known as an editable root. However, we also need to display a list of all of the existing people who have already been created, and we use a readonly object for that, along with a readonly list to manage the data access for us. The list is known as a readonly root list, and the readonly object beneath it is called a readonly child.
You might be starting to realise that there is a lot that can be achieved if we have an Artefact Set Template to help us. Well, this is no exception. Click the 'Add Multiple' button again, and find the 'Items' - 'C#' - 'CSLA' category, and click on the 'CSLA Editable Root, Readonly Root List and Readonly Child' template. Click 'OK' to proceed.
Here's the 'Edit Artefact Set Template Batch' screen again, and as you can see it's asking us where to put the artefacts, and on what data structure they are to be based. Choose the 'MyFirstSolution.Objects' project as the location to add them, and the 'Person' data structure to base them upon. Click 'OK'.
Now we get a chance to edit the artefacts, and here we do need to make a few changes. By default, these artefacts contain rules that restricts the ability to create new items and save changes to existing items to a smaller audience than that able to load them. This is a security feature. For our tutorial we want to change these rules.
The first artefact is the editable root object. Change the textboxes as follows:
Authorisation:Fetch - 'Users' Authorisation:Create - 'Users' Authorisation:Edit - 'Users' Authorisation:Delete - 'Users'
This allows anyone within the role of 'Users' to carry out all of these operations. That's great, as the dummy authentication and authorisation code that our Blazor website will contain makes this true by default.
Click 'Create'.
The second artefact is the readonly root list. Here too we will make a change, for consistency.
Authorisation:Fetch - 'Users'
Click 'Create'.
The third artefact is the readonly child. Child objects don't need per-type authorisation rules applied, as the rules are already enforced by their parents, in this case the readonly root list. No changes are required to this third artefact. Click 'Create'.
Our artefacts are added for us. Click 'Finish' to see the results.
Also in this layer we need to define the contract that the data access layer must fulfil. Let's put that definition into a subfolder to keep it a bit separate.
In the 'Edit Artefacts' screen, click on the 'MyFirstSolution.Objects' project to select it, and this time click the 'Add' button, to take us to a new screen. This looks very similar to the selector for Artefact Set Templates, but instead is showing us Artefact templates, which we use for creating individual artefacts. In this screen, scroll down and find the 'Folders' category, and click on the 'Empty Folder' template and click 'Create'. When adding a single artefact the process is simpler; we go straight to the 'Edit Artefact' screen. Here we want to change a few of the properties:
Name - 'DataAccess' Responsibility - 'A subfolder for data access contracts'
Click 'Save'. We are taken back to the 'Edit Artefacts' screen, where our new folder has been placed under the node we chose before clicking 'Add'. If you clicked on the wrong node and added it to the wrong place then delete the folder that was added and do it again! Don't worry, it's an easy mistake to make.
Now we need to add the contract; this consists of an interface and a DTO class. Click 'Add Multiple'.
Within the 'Items' - 'C#' - 'Data Access' category, select the 'Repository Interface and DTO' template. Click 'OK'. At our old friend the 'Edit Artefact Set Template Batch' screen, select the 'DataAccess' folder that resides within the 'MyFirstSolution.Objects' as the location, and choose 'Person' from the 'Data Structure' dropdown. Click 'OK' and at the 'Add Artefact' screen, accept the defaults by clicking 'Create' and 'Create' again. Click 'Finish'.
Data Access and Data Storage
We just finished creating the contract that something in the data access layer must implement. Now we need to create something to implement that contract.
Click 'Add Multiple' and in 'Items' - 'C#' - 'Data Access' - 'T-SQL' click on the template called 'Repository Using Stored Procs, and Associated SQL Objects' and then click 'OK'.
The 'Edit Artefact Set Template Batch' screen is asking us for parameters for the repository implementation. The location for this is the 'MyFirstSolution.DataAccess' project, and again the 'Data Structure' dropdown should be set to 'Person' before clicking 'OK'.
The 'Edit Artefact Set Template Batch' screen is now asking us for parameters for the SQL stored procedures we will need. The location for this is 'Stored Procedures' node in the 'MyFirstSolution.DataStorage' project. Set the 'Data Structure' dropdown to 'Person' and click 'OK'.
The 'Edit Artefact Set Template Batch' screen is shown a thrd time, this time to allow entry of parameters for the SQL table in which the data is to be stored. The location for this is 'Tables' node in the 'MyFirstSolution.DataStorage' project. Set the 'Data Structure' dropdown to 'Person' and click 'OK'.
The first artefact for which properties are requested is the repository class. Note on this screen that you can specify the name by which the database is known. The default is Demo. This is the name of the connection string that will be used. It could be anything, but I generally use the name of the database.
Click 'Create' on all of the subsequent screens and 'Finish' on the confirmation. It's worth taking a moment to consider that we could have chosen to skip some of the stored procedures in that step. For example, if it makes no sense to delete an object once it has been created then you could choose not to create the stored procedure that supports deletion. Similarly, if you were adding a readonly object then you might not need those for the insert or update operations. However, we need them all today.
Summary
At this point, the addition of the artefacts for our solution is complete. We first created a skeleton using a template to create all of the projects we needed. Then we added custom functionality to it by creating the UI components, a ViewModel, some business objects, a data access contract, an implementation of the data access using SQL Server and stored procedures, and the definition of all of the objects we would need in the database.
Time to finish off the design. Click 'Next' to move away from artefacts.
Edit references
The next screen allows us to reference other documentation or information that is relevant to our design, sucj as diagrams we have created, the architechural guidelines for the department, the architecture document for the system or the requirements if they are documented separately.
We'll skip this for today. Click 'Next' to go to the next step.
Authentication
The 'Edit Authentication Changes' screen gives us the opportunity to consider whether any changes to the authentication scheme of the system need to be made. Here we should make a declaration that the authentication will be fake, as the templates create this fake authentication to allow the initial solution to be tested.
The intention here is not tht this section details every nut and bolt of the authentication scheme in use. Instead, use this step both as an aide memoire to encourage your thinking of authentication, and an opportunity to refer people to more detailed documentation on the system's authentication system. If this is documented separately then that is a good document to add as a reference in the earlier section of that name.
Enter a statement about the fake authentication scheme, and the danger of leaving it this way.
Click 'Next'.
Authorisation
The 'Edit Authorisation Changes' screen gives us the opportunity to make a note of whether any changes to the authorisation scheme of the system need to be made. As with the authentication step, we should make a declaration that as the authentication will be fake, the authorisation won't be applied correctly. It may seem tedious to type something here, but it is important that we consider this important functionality, and having this as a step within the design process acts as a useful prompt.
Enter a statement referring back to the fake authentication scheme, and the danger of leaving it this way.
Click 'Next'.
Risk Declarations
The next section gives us an opportunity to review the risks that our design might result in. Have we done anything that might make the system susceptible to a security vulnerability? Is there a risk of a data breach? Are there any additional steps that we need to take to protect our company or our users?
Click the 'Add From Suggestions' button and look at the list of preprepared risks. This isn't a comprehensive list of all of the risks your system might be susceptible to, but it's a reasonable start. Look down the list. Do you see any that apply in this situation?
There are at least two. We we are not doing proper authentication, so we should add declarations about the following:
- Authentication Bypass. Click on that and look at the potential mitigations. None of those mitigations are in place, so don't tick them. Instead, click the 'Accept' button and write a short statement about why the risk has not been mitigated. Here, I would write 'This is a test system and is not intended for production use. If we repurpose this system them we must review the authentication scheme in use, replacing it with something more appropriate.' Once you have made an appropriate declaration, click 'Save' and then 'Add From Suggestions'
- Exposure of Sensitive Data. Again, the mitigations are not in place. Click 'Accept' and then in the mitigations textbox, type something like this: 'This is a test system, and we do not intend to put this into production. Whilst the functionality includes the ability to record personally identifiable information, we will not use it to record the information of any real, living person. If the system is repurposed at a later date, this must be reviewed, as the lack of authentication is inappropriate.' Once you are happy with the declaration made, click 'Save' to save it into the design.
Once you feel you have given due consideration to all of the risks, click 'Next' to move on.
Security Categorisation
The information entered into this section is somewhat dependent upon your circumstances. I tend to use it to state, overall, what I consider the level of risk of the solution to be. In this case, the risk is of low level. Whilst we are creating a system to handle personally identifiable information, we do not intend to make use of it for real data.
Your department may take additional steps in theor design and development processes depending on the level of risk associated with a piece of work. This might include a design review, more detailed code reviews, more formal risk assessments, penetration testing of the completed system and so on. If you follow any of these practices then you should state which of them you think apply to the solution as you have designed it. Be cautious in areas where PII is being handled, and very cautious if there is any change to the authentication or authorisation of the system as a whole, or a subsection of it.
If you are not following these practices then maybe you should schedule some time to consider doing so.
Enter a statement that you think summarises the risk, and click 'Next'.
Data Retention Policy
The data retention policy should always be considered for any system. There are two reasons for this:
- GDPR requires that PII should be held for as short a time as possible. It may only be held while it is required, and must be deleted or obfuscated once the purpose for which it was captured has ended.
- Systems that capture data indefinitely are likely to fail. If the system only captures a small amount of data then this might not be a problem, but if the system is successful - which is usually the hope when it is developed - then it might capture much more data than you initially intended.
This section gives you the opportunity to consider whether either of these is a risk. If a data retention policy has already been defined then has it been implemented as part of the design? Is there a separate task to implement this at a later date? If not, speak to your product owner about adding one.
Knowing that a data retention policy is needed but not yet implemented is fine, as long as you have taken steps to record that it needs to be done in the future.
Once you have summarised your thoughts on the data retention policy, click 'Next'.
Processing
The final screen exposes a number of useful features.
Create Document
You can export the design to a Word document, so that it can be reviewed by other people who cannot access DesiGen. You might save it in a separate location so that you can refer back to it if you choose to stop using DesiGen in favour of another, similar system.
It is wise to keep the document somewhere. It is common for auditors to ask for this sort of evidence that you have implemented - and are following - appropriate security practices, and this can include legal and regulatory auditors, such as the government agency assigned to implementing and policing GDPR in your country. Some day, you may be very grateful that you have this evidence.
Update Status
This feature allows you to manage the status of the design, such as marking it as ready for design review, or ready for development.
Generate Code
This is the killer feature of the system. Once the design is complete (including having been discussed with one or multiple team members) then you can generate code from your design. This is a really quick way to get started on the features you have designed. Whilst it is unlikely that any solution you generate will work out of the box, it certainly can speed up the delivery of a working prototype to have code generated as much of it as you can.
Generating the code from this tutorial will not deliver a working application. It will need further development, as there are missing relationships and namespaces that will result in it failing to compile. Have a look at one of the tutorials in the 'Generation to Execution' section of the site for more details on the steps you are likely to need to take to turn the skeleton code generated from this design into a working prototype on which you would be able gather feedback, were this a real design.