The Entity Diagram

A note for techies
If you are a techie with any sort of experience with databases, you will find that the Entity diagram is very much like an entity relationship or database schema diagram. It tracks the entities, attributes and relationships in your app’s model, but can also be used to do a lot more. You may be tempted to include attributes to track an entity’s ID or foreign keys, but know that it is not necessary here. The IDs and FKs are automatically made for you, even though they don’t appear in the diagram. If you ever have any doubts, you can always check the database of the local machine where your app is running to see what the bots have included.

The elements of the Diagram

What is an entity?

An entity is an object that exists and is distinguishable from other objects. An entity may be concrete (a person or a book, for example) or abstract (like a holiday or a concept). In software development, entities are used to plan the database structure and gain insight into the system’s architecture. To keep it simple, think of entities like a table in the database.

You can create an entity by opening the ‘Items’ sidebar menu, then selecting an object from the Entities section. You can choose to include eihter a pre-built snippet, or a blank entity.

Once you have created an entity, you can then configure it’s properties in the properties panel to the right of the canvas. To learn more about the properties available, take a look at the tooltips alongside them (the question mark icon next to the title).

What are attributes?

Attributes belong to an entity, and describe characteristics. For example, an employee entity might have the attributes ‘name’, ‘height’ and ‘DOB’. Meaning if entities are the tables in a database, attributes are the columns within the table. In software development, an attribute is characterised by its datatype. For example, age can only be a number (or integer) and DOB can only be a date.

Using the Entity Diagram, you can add an attribute to an entity by first selecting the entity, then clicking on the Attribute option in the pop-up toolbar which appears. From there, you need only to select which type you want. After adding the attribute, you can use the properties to define its values.

What are relationships?

Relationships describe the connections between two entities. There are three kinds of relationships:

• one to one
• one to many, and
• many to many.

You can set a relationship between two entities using the Entity Diagram. Start by hovering over the edge of entity until you see a green border appear. From here, simply click and drag a line to the edge of the entity you wish to create the relationship with. Once you release the mouse click, you will be prompted to chose which type of relationship you want. Once the relationship is formed, you can use the properties panel to further customise the relationship.

For more information about relationships and the Source/Target Optional switches, read this article.

What are validators?

Validators are placed on attributes to ensure that the data entered conforms to a specific rule. Although an attribute has restrictions which some with it’s type, you may require additional constraints. For example, an attribute with the integer datatype can be a positive or negative number by default. However, a person’s age can only be positive. In this situation, you would use a validator to constrain the attribute to positive numbers.

Think of them like the the validation messages that appear when submitting a form. Required is the most popular one you can probably think of.

To add a validator to attribute, select the attribute you want to restrict, and in the pop-up toolbar, click on ‘Validators’ and choose the type you want.

What are enumerations?

Enumerations (a.k.a enums) are a type of attribute that contains a set of options that don’t to change, kind of like a dropdown input in a form. The literals are the individual options that the user can choose from. For example, an enum might be used to define the days of the week, with the enum literals being Monday, Tuesday, Wednesday and so on.

To create an enum in the Entity diagram, add a blank enum from the ‘Item’ sidebar. Start adding in your literals using the pop-up toolbar by selecting New Literal and add the values in the properties.

Now we have created the enum, we need to create a relationship between it and the entity. Select your entity, then add an enum type attribute. Hover on the edge of that enum attribute until a blue border appears, then click and drag a line to the edge of the enum you created earlier. This will successfully link the newly created enum to the entity.

What are snippets and templates?

Snippets and templates are pre-made pieces which you can add into your app’s Entity diagram. They are based on common data patterns that are regularly used in a lot of apps (for example, an address snippet, which adds in an entity and attributes to capture someone’s address data). The size and complexity of the snippets and templates vary depending on what they are trying to achieve.

Snippets and templates are most useful when you are building out a new diagram or expanding an existing one as they let you add in large numbers of entities, quickly. Once a snippet or template has been added to your diagram, it is all yours to edit - you can treat it just like any other entity or relationship already on your diagram.

We recommend that you have a browse of what snippets are available to you on a semi-regular basis, as the list is always growing.

Don’t see something which you think would be useful? Feel free to drop us a line and send in some feedback using the feedback portal.

Custom snippets

We also have the ability to add in custom snippets. Simply select a piece of your diagram and click the “Save as Snippet” button in the properties panel. The snippet will now show up in the “Saved” section of the side menu. Custom snippets are accessible across any of your apps on the same bot.

What are extensions?

Extensions are the pre-built functionality which you can take advantage of when building your app. You can learn more about our extensions in What is an extension?

What makes the Entity Diagram in Codebots so powerful?

Well imagine for a moment that the relationship between two entities needs to change. It may sound like a simple task, but using traditional methods, the resulting work to update this relationship could take a techie a couple of days. Codebots eliminates this effort, as the bots can update the code to reflect this change in seconds, not days.

By letting the bots do the heavy-lifting on labour intensive tasks like this, it gives your team the opportunity and time to focus on the things they love to do, like nutting out the creative and complex parts of the application.

Navigating the Entity Diagram

The menus

The Entity digram has three main control areas, with the editing canvas in the middle:

• 1: The sidebar. This is where you can view what is in your diagram and add new elements to it.
• 2: The ‘check for errors’ button. This is where you can validate your diagrams before you build. Clicking here also shows you outstanding validation issues on your diagram.
• 3: The map controls. Here you can zoom in and out on the map or use the minimap to change the focused location.

The canvas has drag and drop controls so you can re-arrange the elements on it.

The sidebar

The main menu on the left changes depending on the page you are currently on. When you are in the Entity diagram, you have three options available: overview, items, and templates.

• Overview is where you can see a list of all of the entities and enums in the diagram, along with the attributes and literals which are assigned to them. Using the search input at the top, you can search for entities and enums by their name. Clicking on an entity or enum in the list will select it in the canvas.
• Items is how you can add new entities, enums, and snippets into the diagram. You can choose to either add in blank elements, or to add one of the pre-constructed elements we provide, which are based on common patterns used in apps.
• Templates are a more complex form of snippets, closer to the structure of an entire app, rather than just a small piece. These are very helpful when you are going through the initial setup phase of building.
• Saved is how you access your saved custom snippets throughout your diagrams, it will appear after you make your first custom snippet.

The canvas menus

Once you have an element on the canvas, further menus become available for you to work with based on the what you currently have selected.

• A pop-up toolbar appears directly above the selected element. This allows you to add in attributes, extensions, literals or validators, depending on what is selected. Clicking on an option opens a sub-menu where you choose what you want to add.
• The properties panel down the right-hand side is where you can manage the properties of the selected element or delete it. You can do things like name an entity, choose which attribute it sorts by, or give it a description to make documenting easier.

Using the Entity Diagram

Add an entity

1. Go to Items sidebar
2. Under the Entities header, select the ‘Blank’ element.
3. A blank entity will appear on the canvas

Add an attribute

1. Select an entity on the canvas
2. Clicking on the Attribute option in the pop-up toolbar
3. Select the type of attribute you want
4. An attribute of that type will appear at the bottom of the currently selected entity

Add a relationship

1. Hover around the edge of one entity until an opaque green border appears
2. Click on the border and hold your mouse down.
3. Still holding your mouse down, move your cursor to the edge of the other entity
4. Once a green border appears, release your mouse
5. Select the relationship type you want to use.
6. A relationship arrow will appear between the two.

Relationships are directional, so pay attention to which entity you start and finish with

Include an enum and literals

1. Go to the Items sidebar and select a blank enum element
2. On the canvas, select the new enum
3. In the enum’s pop-up toolbar, click on the “Literal” option (add as many times as you need)
4. Go to the entity which you want to add the enum to and select it
5. Use the pop-up toolbar to add an enum type attribute to it
6. Drag a relationship between that attribute and the enum element (note: the border will be blue in this situation)

Add an extension

1. Select the entity you want to use
2. Click on the “Extension” option in the pop-up toolbar
3. Select the extension you want to use

Delete an element

1. Use the “Delete” button at the bottom of the properties panel

Deleting multiple elements

1. Multi-select entities and enums by clicking and dragging a box around them
2. After selection, you can hold down the shift key to add or remove elements
3. A list of the selected elements will appear in the properties panel
   1. Click on an element to be moved to it in the canvas window
   2. Click on the delete button in the top right of the properties panel to delete all selected elements