Ellie User Guide - the basics

Owned by Juha Korpela
Last updated: Nov 15, 2023 by Juha Korpela

Getting started

Ellie runs in the cloud; no installation is required. Just open your favorite web browser and navigate to your organization’s Ellie instance. Usually, the URL is in the form of https://yourorganization.ellie.ai .

There are two options for logging in:

  1. Log in with your Ellie account: you can have an Ellie account created based on your email address. Enter your email address as your username, your Ellie password, and click Login. If you don’t know your password or have forgotten it, you can also reset your Ellie account’s password from the login page by clicking on the Reset password button.

  2. Log in with your SSO provider: if your organization has enabled Azure Active Directory or Okta user management in Ellie, you can use the Login using Microsoft or Login using Okta button to log in with your Microsoft/Okta credentials. Note that usually your Microsoft/Okta account is entirely managed by your own IT department; if either of these login options is used in your organization, you cannot change your account details or reset your password from Ellie. If you’re unsure whether or not the Microsoft or Okta account login has been enabled in your organization, please check with your own Ellie admins.

The login view, showing the Microsoft SSO option.

Accessing models

Data models in Ellie can be accessed from the front page under the Models header. The list shows the models that have recently been updated; you can see the full list of models by clicking on either the Models header or the View all models button below the list. Clicking on a model name on the list of recently updated models takes you directly to that particular model.

Model names in blue are conceptual models, whereas model names in grey are logical models.

Clicking the blue plus icon next to the header allows you to create new conceptual or logical models.

The model list on the main page.

The Conceptual Modeling Canvas

When you open an existing conceptual model or create a new one, you will be directed to the Conceptual Modeling Canvas.

On the top of the view, you’ll see the basic black navigation/search bar that is used everywhere in Ellie. Click on the Ellie logo in the top-left corner to navigate back to the main page.

Toolbar

Under the navigation/search bar, you’ll see the toolbar. From left to right, the toolbar has:

  • Undo/Redo buttons: these will allow you to undo and redo any actions you have done on the canvas.

    • NOTE: if multiple users are using the same canvas at the same time, you can only undo or redo your own actions!

  • The T button for textboxes: click and drag new textboxes to the canvas from here. Textboxes can be resized and the text in them edited freely on the canvas.

  • Zoom functionalities: you can use the -/+ zoom functionalities from the toolbar, or alternatively you can simply use mouse scroll for zooming in and out. The Fit To View functionality automatically zooms and moves the canvas so that the entire model fits your current screen.

  • Model status: you can use this to set the model status from “Work in Progress” to other values.

    • NOTE: currently, the model status is informational only - the status is shown to everyone, but it doesn’t control workflows or access levels to the model.

  • Convert button: this allows you to convert the current conceptual model into a new logical model. The logical model will be created with the exact same entities and relationships as the conceptual model. The new logical entities will be automatically pre-filled with attributes based on the attribute information of your conceptual entities, they will be named after the conceptual entities, and they will be automatically linked with the conceptual entities. You can then modify this logical model as you like - the conversion is intended to provide you with a simple starting point going forward. You can convert the same conceptual model as many times as you like; each conversion will create a new logical model.

  • Export button: use this to download the model’s contents as files. The options are:

    • Export entities: downloads a CSV file containing all the model’s entities with their metadata

    • Export attributes: downloads a CSV file containing all the attributes that belong to the entities in the model, and their metadata

    • Export relations: downloads a CSV file containing all the relationships between the entities in the model

    • Export PDF: downloads the model diagram as a PDF file.

On the right-hand side of the canvas, you’ll find the sidebar. You can expand & collapse the sidebar by clicking on the arrows in the middle of the sidebar’s edge. The sidebar contains the following:

  • Search or Create Entity: this allows you to search for existing entities in the Glossary to be added to the canvas, or to create new entities and add those to the canvas, provided that you have edit access to the model. If you only have read access, you won’t see this field. See below for more details on adding entities!

  • Model info: this section shows you the model name, its ID (that you can use e.g. for API calls), and its description (once you expand the section by clicking on the arrow). The name and the description can be edited here if you have edit access to the model.

  • Last edited: this shows you the model’s edit history. You can expand the section to see who has edited the model and when.

  • Relationship types: when expanded, this section shows you what the different “crow’s feet” mean in the relationships. This section is purely informational and the types can’t be edited.

  • Entity types: this section shows you the entity types that your organization uses. These are the various colors you can set for the entities if you have edit access. The entity types are customizable; if you have admin-level access to your organization’s Ellie, you can edit these types and colors. See here for more information.

Adding entities to a model

When you have edit access to a model in Ellie, you can use the Search or Create Entity functionality on the Conceptual Modeling Canvas to add entities to a model. There are two possibilities: either you add existing entities to the model, or you create new entities and add those. Both are done with the same functionality.

For example, if you type “Customer” in the field, and your organization already has an entity with that name in the Glossary, you can select the entity from the search result list, click on it, and it will be added to the canvas. If you type “Customer2” in the field, and that entity name doesn’t exist yet, you can press Enter to create that entity immediately in the Glossary and at the same time add it directly to the canvas.

Note that the search will search for matches from the entire Glossary when you start typing - you don’t need to type the full entity name, just typing “cust” gives you the option to add the “Customer” entity (if it exists).

New entities created this way will be automatically assigned to the default entity type in your organization. The default type setting can be adjusted by your admins according to this guide.

Drawing relations

When you are done placing entities into your model, you can start drawing lines that will indicate a relationship between the entities. Just click on the border of a source entity, and, while holding the left mouse button down, drag your cursor until you reach the border of another entity. The relationship type will be drawn as a “one-to-many” relationship by default, but you can of course change this after you’ve drawn the relationship.

  1. When you right-click on the end of a relationship line at the border of an entity, you will get to change the relationship type.

 

  1. Click on the

T in the top bar to add a free-format text box, excellent for further explaining the relationship between these two Entities, or for adding to-do notes or other additional text on the model canvas.

You can also add descriptions directly to relationship lines: Click on a relationship line, in the exact place you want to have a relationship label. This creates an elbow. Now, right-click on the newly created elbow, and select Description from the context menu.

Type a description for this elbow, and it will be shown on the canvas. By default, the text will be displayed on top of the elbow, but you can drag and drop the text to four different positions around the elbow: left, right, top, or bottom.

In the example below, the description “is sent” is added to the elbow in the relationship between “Customer” and “Invoice” entities.

Changing entity Size

When you move your mouse cursor on top of an entity, corners appear. Click and drag on the corners in order to resize the entity.

Relationship types and cardinalities

When you first draw a relationship between two entities, it will be drawn as a “one-to-many” relationship.

The notation used in Ellie to denote the cardinality of a relationship is the so-called “crow’s feet” notation. In this notation, the three prongs (the “foot”) mean “many”, and a straight line means “one”. This way, the above relationship is interpreted as “there can be many B for one A, and one A for each B”.

This is often quite enough to make the point, but you can also use more detailed cardinalities by choosing a different relationship type. For both “one” and “many”, you can choose “optional” and “mandatory” relationship types.

The example below uses “one-mandatory” and “many-optional” relationship types, and is interpreted as “there can be many B or no B at all for one A, and there must always be one and only one A for each B”.

Entity Subtypes

Entities can have subtypes. Let’s look at an example of a travel agency industry to illustrate subtyping in Ellie.

Hotel Booking and Flight Booking are subtypes of Booking. Customer and Booking Notification are related to the main entity Booking, and Flight Booking and Hotel Booking have their own relationships.

This kind of notation is used by e.g. Len Silverston in his Universal Data Models books, and by Graeme Simsion in his book Data Modeling Essentials.

In our experience, people can understand this notation quite intuitively. You can find a more detailed explanation of subtypes in Ellie from our Modeler’s Corner blog post subtypes in data modeling.

Entity types

The idea of entity types in Ellie is to make models more readable, faster to build, and easier to add information about the nature of the data you are seeing. This is based on the notion that there are certain similarities between data entities, even across different industries. We have seen that a simple categorization of entities helps here. This should be considered a “best practice style” that can be used on top of a normal conceptual model.

The entities are by default divided into six classes: Master data, Contract, Transaction, Reference, Transaction header, and Transaction detail.

You can find more information on Ellie’s Entity types from our Modeler’s Corner blog post on entity types. Note that the entity types are also completely customizable - your own organization’s Ellie admin can change the type options and their colors by following this guide.

Setting an entity type

Right-click on an Entity. Choose the Entity type from the context menu, and you’ll see a list of the available types and can select a new one. Note that this changes the entity’s type in the Glossary, not just on this particular model’s canvas - the change will be visible on all models that contain this entity!

User management

Ellie has two ways to manage users:

  • Email-based accounts: this is the default option, where each user gets an Ellie account based on their email address. They log in with an email+password combination. Admins can directly manage these users and their privileges in Ellie.

  • SSO integration: on request to support@ellie.ai, a customer organization can integrate their Ellie user management with their internal SSO provider. The options currently available are Okta and Azure Active Directory. With the SSO integration, user management in Ellie happens with SSO user groups: each group is assigned a role in Ellie, and the membership of these groups is managed within the customer’s own user management system. When this option is in use, Ellie admins can’t make changes to users or their privileges within Ellie; SSO options can be changed with a support request to Ellie, and the individual memberships are handled outside Ellie. You can find more details on the Okta integration here.

User roles and their privileges in Ellie

Ellie has three levels of users: Admin, Write, and Read.

They have the following privileges:

  • Read: can read all content (models, Glossary items) but can’t modify anything

  • Write: can modify existing content and create new content (models, Glossary items), except for Collections where this has been separately restricted to specific Write-access users

  • Admin: can modify all existing content and create new content (models, Glossary items) everywhere in a subdomain, and in addition can perform admin tasks:

    • manage email-based users and their privileges

    • change organization settings on entity types

    • access and generate API tokens

    • set Collections to restricted status and modify these restrictions to cover specific Write-access users

Adding new email-based users

Admin-level users can add new email-based users the following way:

  1. Click on the cogwheel icon on the Dashboard (frontpage)

  2. Then click on Users

  1. Click on the + Create users button

  2. Create as many users as you like - all you need to do is have their name and valid e-mail address.

  3. Define the role of each user, a role can be either Admin, Write, or Read.

  4. If the user has an existing Ellie account for the given email address (in any organization), they can use their existing password to log in. If the account is new, the admin can either copy-paste the generated password from the user management screen, or the user can reset their password from the login screen. Note: for security reasons, the admin can’t access any passwords after the initial user creation.

The Logical Modeling Canvas

Logical Models in Ellie are meant for designing more technical data structures for your individual data products. Often, they could be structured according to e.g. a Star Schema model. The logical models can be converted from existing conceptual models, and the logical entities themselves can be linked with conceptual entities to maintain a semantic understanding of the data content.

Creating logical models

The steps to create a Logical Model (or LM for short) or a Conceptual Model (or CM for short) are the same.

You can create a CM or an LM from the Dashboard by clicking on the + sign right next to Models on the left.

Or you can navigate to the Model List View, where on the sidebar, you have three buttons: New Collection, New Logical Model, New Conceptual Model.

After clicking on the New Logical Model button, you will be navigated to a form where you can set the name and the description of the logical model.

After typing in a valid name for the model (duplicate names are not allowed), the Create Logical Model button will be enabled. After that, you are transported onto the Logical Modeling Canvas where the editing of the model will now commence.

Overall, the LM canvas functions very much like the CM canvas. The main differences are in how entities are added, and the lack of a separate sidebar here.

Adding logical entities to the canvas

Click on the Add Entity button in the top-right corner of the canvas to start adding entities to your logical model. The logical entities are not part of the Glossary - they exist only within the scope of a single logical model - so they can’t be searched for or reused.

When the Add Entity button is clicked, a modal opens where you can give the entity a name and add attributes to it. You can also mark attributes as primary (PK) or foreign (FK) keys, and link the logical entity with existing conceptual entities in the Glossary.

You can add as many attributes as you like by pressing Enter on your keyboard when typing an attribute name: this creates a new attribute row, and you can keep typing your next attribute. Use the checkboxes to mark attributes as PK/FK.

When you’ve added some attributes, you can use the checkbox on the left to select one or more of them, and then delete the selected attributes by clicking on Delete selected attributes at the top.

Press Create Entity at the bottom to create the entity on the canvas, or Close (or the X in the corner) to cancel.

Editing logical entities

Here is what a logical entity will look like on the LM Canvas. It will be placed in the center of the Canvas, so if you create multiple entities, they will appear on top of each other - move them around if needed!

You can edit the entity by clicking on the Edit button, or you can click on the trashcan icon to delete the entity.

The entity edit modal that opens from the Edit button is similar to the modal when creating new logical entities, and allows you to do the same actions.

Editing model info

This is a simple dialog where you can change the name and the description of the logical model. You will immediately see the changes when you press Save.

Just like in a Conceptual Model, you can also create relationships between Entities in a Logical Model.
Let's show that by creating a secondary Entity and connecting the two.

By hovering your mouse over the edge of an Entity, it will change into a crosshair, and you can press your left mouse button down and start dragging toward the edge of another Entity to create a Relationship.

A dashed line will appear between the two Entities, and after you release the left mouse button, a One to Many Relationship will be formed.

 

If you right-click on the relationship’s “crow’s foot” symbol, you will be able to change the Relationship Type or Delete the Relation. If you click on Relationship Type, you will see a sub-context menu with the usual Relationship arrows.

When your Logical Model has at least one Entity or more, you will see that the Export button is enabled.

 

You can use it to

  • Export Entities

  • Export Attributes

  • Export Relations

These will come out in the .CSV format

The format of the filename will be

{OrganizationName}-{ModelName}-{TypeOfExport}-{DateInYYYYMMDDFormat}.csv

Such as

exampleOrganization-New Logical Model Created For Tutorial 2-entities-2022-01-31.csv
exampleOrganization-New Logical Model Created For Tutorial 2-relationships-2022-01-31.csv
exampleOrganization-New Logical Model Created For Tutorial 2-attributes-2022-01-31.csv

Use these in the application of your choice.

You can also use the Model Export API to export logical model data, just like you can do with the conceptual model data. You can find more information on the APIs here.

Hints, tips & best practices for creating good models

 

You can contact us by e-mailing support@ellie.ai.