Ellie User Guide - the basics
- Juha Korpela (Unlicensed)
- Esa Ruoho (Unlicensed)
- Stan Dmitriev
- Jari Jaanto
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:
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.
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.
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 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.
Copy button: this allows you to create a model copy in a public or personal folder in the organization. When you make a copy of a model, entities will be reused and no new entities will be created.
Share button: this allows you to share a model link with your colleagues.
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.
Sidebar
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 Glossaries as set in the folder settings 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 options: you can add existing entities from the available glossaries or create new entities directly within the model. Both actions are performed through the same search field.
For example, if you type “Customer” in the search field, and an entity with that name already exists in the organization’s glossary or the specific sub-glossary of the folder, it will appear in the search results. You can select it to add it to the canvas. If you type a new name, such as “Customer2,” that doesn’t yet exist in your current folder, pressing Enter will create that entity within the active folder's sub-glossary and add it to the canvas simultaneously.
Note: The search function will look for matches across both the organization-wide glossaries (as set in folder settings) and the current folder’s sub-glossary. You don’t need to type the entire entity name; partial matches (e.g., typing “cust”) will show all relevant options.
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.
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.
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!
Linked entities
When you use an entity from another glossary within a model, it will appear on the canvas in italic font, indicating that this is a linked entity rather than one created in the active folder's glossary. This visual cue helps distinguish entities that originate from other folders or domains.
If you hover over the name of a linked entity, a tooltip will display the folder from which the entity originates, providing quick context about its source. If you lack write access to this entity, you won’t be able to change its Entity Type on the canvas, as modifying this attribute would impact the entity’s metadata across all models where it is used.
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 Folder, 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.csvexampleOrganization-New Logical Model Created For Tutorial 2-relationships-2022-01-31.csvexampleOrganization-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.
The Physical Modeling Canvas
Ellie's Physical Modeling Canvas is designed for creating representations that closely mimics the structure of an actual data warehouse. This involves defining tables, columns, and the relationships among them using foreign key constraints. The physical model can be converted from a conceptual model, a logical model, or designed from scratch.
Future updates will include functionality for importing structures directly from existing data warehouse databases. Tables can be linked with conceptual entities to enhance the semantic understanding of the data.
Adding Tables to the Model
To add tables to your model:
Click on "Create table" located at the top right sidebar.
Enter the name of the table in the provided field and press Enter.
Editing Tables
To modify a table:
Click the Edit table icon located at the top right of the table's representation on the canvas. This action opens the table details window.
The editing interface includes the following fields:
Entity Name: Specify the name of the table.
Entity Description: Provide a description of the table.
Columns: Manage the columns within the table.
Glossary Links: Associate glossary terms with the table.
Managing Columns
Adding Columns
To add a new column: In the column editor, either click "+ New attribute" or press Enter after typing the column name.
Column parts
Each column consists of several parts:
PK (Primary Key): Indicates if the column is part of the primary key. Activating PK on multiple columns creates a composite primary key. Primary keys automatically enforce uniqueness and not-null constraints.
FK (Foreign Key): Indicates if the column is part of a foreign key constraint. This attribute is read-only and can be toggled off only for draft foreign keys (indicated by an orange color).
Name: The column's name, which must be unique within the table.
Data Type: Select from a list of predefined data types or use a custom data type. Ensure the data type is supported by your data warehouse.
Not Null: Ensures that the column cannot hold a null value.
Unique: Ensures that all values in the column are unique.
Default: Sets a default value for the column.
Description: Provides a non-exportable description to aid other modelers.
Modifying Column Order and Deletion
To reorder columns, use the six-dot icon located at the beginning of the row. Click and drag to adjust the order.
To delete a column, click the trashcan icon next to the column details.
Establishing Relationships Between Tables
Suppose you have two tables: Product and Customer. To add a foreign key constraint between these tables, you can establish a relationship starting from the table containing the primary keys and extending to the table with the foreign keys.
Creating the Relationship:
Initiate the Relationship Editor: Drag a connection from the table with the primary keys to the table with the foreign keys. This action will open the relationship editor.
After dragging a relationship editor opens.
Configure the Relationship:
In the dialog that appears the table with the primary keys is displayed on the left side and the table with the foreign keys is on the right side.
To set up the foreign key constraint, select the primary key(s) from the left and the corresponding foreign key(s) from the right.
Note: To create a composite foreign key constraint involving multiple columns select the appropriate keys from both sides. These will be combined into a single constraint.
Draft relationships and managing relationships
When transitioning from a conceptual or logical model to a physical model, all relationships are initially highlighted in orange. This signifies the presence of a relationship but the absence of enforced foreign key constraints.
Adding Foreign Key Constraints:
Ensure that all necessary data types and columns (both primary and foreign) are defined in your tables.
To modify the relationship, right-click on the relationship line and select "Edit Relationship" from the context menu. This will reopen the relationship editor where you can add or adjust foreign key constraints.
This manual aims to guide you through the process of defining and troubleshooting relationships between tables in your database model, ensuring data integrity and relational logic.
Troubleshooting Relationships:
Color Indicators: If the relationship line is marked with an orange color, this indicates an issue, such as a mismatch in data types between the primary key and foreign key. To identify the specific problem, hover your mouse over the relationship line.
Glossary
Conceptual entities from the glossary can be linked to physical model tables. Select conceptual model entity by writing its name and selecting from the list of glossary entities.
SQL generator
On the right hand side there is a SQL Generator. To generate a SQL presentation of the physical model press generate. Note: The SQL does not update automatically. Whenever you want to generate a new presentation, press Generate.
To copy the SQL from Ellie, press copy.
Currently the SQL is in Snowflake format, but we will be adding support for more databases in the future.
Importing SQL
To export SQL DDL statements from Snowflake, please follow these steps:
Log into your Snowflake account.
Click on “Create new worksheet” located in the top left corner.
If you are unable to create worksheets, please contact your company’s Snowflake administrator for assistance.
Write the following SQL statement to retrieve the DDL for the desired schema:
SELECT GET_DDL('SCHEMA', '<database>.<schema>');
For example:
SELECT GET_DDL('SCHEMA', 'ELLIETEST.PUBLIC', TRUE);
Execute the statement by pressing the play button in the top right menu bar.
Once the results are displayed, click the download button in the bottom right corner.
From the menu, select “Download as .csv”. The SQL DDL statements will be saved to your hard drive.
To import the SQL into Ellie,
Click “Create new model” and select "Physical Model".
In the dialog that opens, select “Upload a file”.
Choose the file from your hard drive containing the SQL DDL statements.
The SQL DDL statements will appear in the dialog.
Click “Create new model” to finalize the creation of the new model.
Folders and Sublossaries
Overview
Ellie’s folder structure organizes models and glossaries, allowing users to create folders and subfolders to categorize models based on projects, domains, or departments. Each folder can contain its own sub-glossary, which lets users define terms specific to the folder’s focus while maintaining access to the organization-wide glossaries. See how subfolders and subglsosaries work in practice in this video https://www.youtube.com/watch?v=t_y_Ex0PULo&pp=ygUSZWxsaWUgdGVjaG5vbG9naWVz.
Creating and Managing Folders
To create a new folder:
Navigate to the Parent Folder: Access the folder under which you want to create a new subfolder.
Click on the Create Button: Select the option to create a new folder.
Configure Folder Settings: In the folder settings, you will find three tabs:
General: Enter the folder name and an optional description.
Glossary: Set up glossary settings, including:
Whether the folder has its own glossary.
Which other glossaries to suggest entities from when modeling in this folder.
Restrictions on which glossaries can be shown in the search or create bar during modeling.
Permissions: Define who has access to view or edit the folder and its contents.
Save the Folder: Once configured, save the folder to add it to your hierarchy.
More information on the Folder settings can be found in our Folder User Guide - https://ellie.atlassian.net/wiki/spaces/ELLIE/pages/852230147/Using+Collections
Using Sub-glossaries in Folders
Each folder can have its own sub-glossary. This sub-glossary allows you to create entities specific to the models within that folder without affecting the organization-wide glossary. This is helpful for managing terms that may differ across projects or domains.
To add terms to a sub-glossary:
Open the desired folder.
Press Create button.
Press Create Entity button.
Terms added here will appear only within the folder’s sub-glossary unless used as linked entities in folders of other models.
Working with Linked Entities
Models within a folder can access terms from the organization-wide glossary or from other folders. When an entity from a different glossary is added to a model, it appears in italic font on the canvas, signaling it is a linked entity.
Viewing Source Folder: Hover over the entity name to see the folder from which it originates.
Editing Linked Entities: If you have only read access to the linked entity, you cannot change its entity type or other metadata to avoid affecting shared definitions.
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 four levels of users: Admin, Write, Contributor, and Read.
They have the following privileges:
Read: can read all content (models, Glossary items) but can’t modify anything
Contributor: can read all content, and can work in a personal folder, and can copy public assets into a personal folder. When a certain model or entity is complete in their personal folder, Contributor user can share their asset with an Admin or Write user for approval and further promotion to a public folder.
Write: can modify existing content and create new content (models, Glossary items), except for Folders 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 Folders 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:
Click on the cogwheel icon on the Dashboard (frontpage)
Then click on Users
Click on the + Create users button
Create as many users as you like - all you need to do is have their name and valid e-mail address.
Define the role of each user, a role can be either Admin, Write, Contributor, or Read.
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.
Hints, tips & best practices for creating good models
Modeler's Corner #1 Identifying Entities | Ellie Data Modeling
Modeler's Corner #2 Entity Types in Data Modeling | Ellie Data Modeling
Modeler's Corner #3 Modeling Verbs and Nouns | Ellie Data Modeling
Modeler's Corner #4 Subtypes in Data Modeling | Ellie Data Modeling
Modeler's Corner #5 Roles and Subtypes | Ellie Data Modeling
Modeler’s Corner #6 Category vs Instance | Ellie Data Modeling
Modeler’s Corner #7 Getting started with ELM & Ellie | Ellie Data Modeling
You can contact us by e-mailing support@ellie.ai.