Technical Documentation

Backoffice user permissions

To enable your back-office users to use the package, you need to allow access to the two new sections created when the package was installed. This is done in the Users section.

For each user group, go to Sections and add Database Extension Kit and Database Extension Kit Admin from the list of available sections.

Defining entities and properties

Creating an entity definition

To define a new entity, go to the Database Extension Kit Admin section of the Umbraco backoffice interface.

Click on the three-dot icon next to the Entities tree title and the context menu for Entities will appear. Click Create to start creating a new entity definition.

The new entity definition dashboard will appear.

In order to create a new entity definition, you need to set the entity name name and add at least one property to it.

When a new entity definition is created, a table is also created with the same name in the underlying Umbraco database, using Umbraco aliasing rules.

Adding a property

A property should have a unique name within its parent entity definition. For each property, a column is created in the underlying database table. The column name is equal to the property alias, which is shown on the Umbraco UI and created according to Umbraco aliasing rules.

Click Select editor to choose the property editor type. Properties are added using the standard set of Umbraco property editors, extended by a new type - the Foreign Key property editor.

For further reference on property editors, please go to the relevant Umbraco documentation page: https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors

Validation is set using the standard Umbraco approach.

The make the property visible in list view, check the Displayed in list view checkbox.

After each property is added, you will see it added to the end of the entity definition dashboard.

To finish creating an entity definition, click the Save button in the bottom of the dashboard.

Important notice: Once an entity definition is saved, its name cannot be modified.

If two or more properties with the same aliases are added to the entity, an error message will be shown and the entity definition will not be saved.

Foreign key property editor

The Foreign key property editor is used to establish parent-child relationships between entities.

When the Foreign Key property editor is selected, a new context form appears, showing the existing foreign keys and allowing you to create a new one. For each entity definition used in a parent-child relationship, there should be a separate foreign key created.

When a new foreign key is created, you will get a dropdown list of existing entity definitions to choose from.

Modifying entities

An entity can be modified in different ways:

• New properties can be added

• Existing properties can be modified

• Existing properties can be removed

The entity name cannot be changed.

Modifying properties

Existing properties can be modified using the entity definition dashboard. To modify a property, click on the Settings wheel icon next to the property and Property settings form will appear.

The property name can be changed, but the alias will remain the same, because it is linked to the database field name.

The property type can only be changed within the same database data type, so the list of available property types is filtered accordingly, based on the initial data type.

Deleting properties

A property is deleted by clicking the Delete icon next to the property on the entity definition dashboard. After clicking, a confirmation dialog will appear.

Deleting a property also deletes the underlying database table column and its contents. Be careful.

Deleting entities

When an entity definition is deleted, the underlying database table and its contents are deleted too. Be careful.

To delete an entity definition, click the three-dot icon next to the entity in the Entities tree and select the Delete option in the context menu.

A confirmation dialog will appear. If you click Yes, the entity definition, its underlying database table and all its contents are deleted irreversibly.

If the entity was a member of a parent-child relationship, used as the data source of a foreign key property in another entity, the property in the other entity is deleted, too.

Class model generation

Database Extension Kit allows you to generate the class model in your project which corresponds to the entities.

To enable or disable this feature, add the following setting into appsettings.json:

"DatabaseExtensionKit": {
    "ModelGenerator": {
      "GenerateModel": false,
      "ModelsFolderPath": "/Models"
    }
  }

By setting GenerateModel to true or false, the class model generation is enabled or disabled. The ModelsFolderPath is where the classes are saved, relative to your project tree.

Managing data

The data contained in the entity model created using the Database Extension Kit is managed in the Database Extension Kit section of the Umbraco backoffice interface.

The Database Extension Kit section contains the Entities tree on the left, which lists all the entity types that exist in the entity model created using the package. The entity types and their contents do not overlap with the standard Content section of the Umbraco UI.

Data list view

Clicking an entity type in the Entities tree shows the records of the selected entity type in the right dashboard, organized in a paged list view of 10 records per page.

The list view shows up to five properties marked as Displayed in list view in the property definition, ordered as given in the entity definition.

The list is sorted by clicking the property heading and according to the internal data type.

Filtering the list view

The list is searchable by all textual fields as well as all other Displayed in list view fields.

Reordering and sorting

Reordering can easily be performed by clicking the Reorder button and performing a series of drag and drop actions to move each list item to its desired place. The order of each item in the list is stored in the Sort Order column. By clicking the Save button, the current order of list elements is saved.

The list view can be sorted per column, by clicking on the respective column heading. The list is sorted using the default sort order for the selected column, based on the data type of the column.

Actions

Creating a new record

A new record of the selected entity type is created by clicking the Create button above the list view. Clicking the Create button will open the new entity form in place of the list view.

Modifying a record

Modifying a record is done by clicking the highlighted value in the list view, usually in the first column in each row. This opens the edit form for the selected record.

Copying a record

To copy a record, click the Copy icon next to the record in list view.

Deleting a record

To delete a record, click the Delete icon next to the record in list view. A confirmation popup will appear.

The deleted record is not permanently deleted. Instead, it is moved to the Recycle bin.

Recycle bin

The Recycle bin keeps all your deleted records, so you can restore them or purge them permanently.

The Recycle bin is located in the Entities tree, as the last item in the tree.

Once opened, it shows a dropdown where you can filter by entity type.

After selecting the entity type, you will get a list view showing all the deleted records of selected type.

The possible actions are:

• purge the entire Recycle bin by clicking Delete all

• restore a record by clicking the Restore icon next to it

• delete a record permanently by clicking the Delete icon next to it

Notifications

Db Extension kit exposes 5 additional notifications using the existing Umbraco mechanism. In order to hook into the notification pipeline, you will need to register a notification handler with Umbraco. This can be done in the Startup class:

public void ConfigureServices(IServiceCollection services)
{
    services.AddUmbraco(_env, _config)
        .AddBackOffice()
        .AddWebsite()
        .AddComposers()
        .AddNotificationHandler<DbExtEntityPreLoadNotification, ApplicationPreLoadHandler>()
        .Build();
}

DbExtEntitySavedNotification

Notification is triggered after an entity is saved to a database. The notification includes an Item property, which is of type ObjectOm.

In this example we implement a notification handler that sends an email to a user after his job application is saved to the database.

public void Handle(DbExtEntitySavedNotification notification)
{
    if (notification.Item.Name == “Application”)
    {
        var email = notification.Item.Properties.FirstOrDefault(x => x.Alias == “email”).Value;
        SendEmail(email);
    }
}

DbExtEntityPreSaveNotification

Notification is triggered before an entity is saved to a database. The notification includes an Item property, which is of type ObjectOm.

In this example we implement a notification handler that sets the application date to the current timestamp, before it is saved to the database.

public void Handle(DbExtEntityPreSaveNotification notification)
{
    if (notification.Item.Name == “Application”)
    {
        var applicationDate = notification.Item.Properties.FirstOrDefault(x => x.Alias == “applicationDate”);
        applicationDate.Value = DateTime.Now;
    }
}

DbExtEntityPreLoadNotification

Notification is triggered before an entity is displayed in an edit form. The notification includes an Item property, which is of type ObjectOm and DocumentType property which is of type DocumentTypeDisplay.

In this example we implement a notification handler that converts all entity Job properties to a label before displaying it in a form.

public void Handle(DbExtEntityPreLoadNotification notification)
{
    if (notification.Item.Name == “Job”)
    {
        foreach (var prop in notification.DocumentType.Groups.FirstOrDefault().Properties)
        {
            prop.Editor = Aliases.Label;
            prop.View = "readonlyvalue";
        }
    }
}

DbExtListPreLoadNotification

Notification is triggered before an entity collection is displayed. The notification includes entity name and list of the entities which are of type ObjectOm.

In this example we implement a notification handler that removes the phone value before displaying a list of Application entities.

public void Handle(DbExtListPreLoadNotification notification)
{
    if (notification.ObjectName == "Application")
    {
        foreach (var item in notification.Items)
        {
            var phone = item.Properties.FirstOrDefault(x => x.Alias == "phone");
            phone.Value = null;
        }
    }
}

DbExtPreSearchNotification

Notification is triggered before a search is performed. The notification includes an Search property, which is of type SearchObject and Item property which is of type DocumentTypeDisplay.

In this example we implement a notification handler that modifies search filter – “Application status” and sets a list to a specific value – “shortlisted”

public void Handle(DbExtPreSearchNotification notification)
{
    if (notification.Item.Name == ObjectTypes.Application)
    {
        var allFilters = notification.Search.Filters;
        var statusFilter = allFilters.FirstOrDefault(x => x.Alias == “applicationStatus”);
        if (statusFilter != null)
        {
            statusFilter.Value = JsonConvert.SerializeObject(new List<string> { “shortlisted” });
        }
        HandlerHelper.setListForProperty(notification.Item, “applicationStatus”, new List<string> { “shortlisted” });
    }
}

Permissions

Database Extension Kit allows users to assign desired permissions at the entity level for each User Group.

To define entity permissions, go to the Database Extension Kit Admin section of the Umbraco backoffice interface and click on the three-dot icon next to the desired entity. Select 'Permissions' from the context menu.

Now click on the User Group for which you want to set permissions. There are three permissions that can be set for an entity: Browse node, Delete and Update.

Browse node permission

If this permission is not set, the user won’t be able to browse entities. Instead, the error will be displayed.

Delete permission

If this permission is not set, the user won’t be able to delete an entity.

Update permission

If this permission is not set, the user won’t be able to create a new entity or edit an existing one.

Import & Export Data

Import data from a CSV file

Database Extension Kit allows users to import CSV files into their data model.

To import data, go to the Database Extension Kit section of the Umbraco backoffice interface, click on the three-dot icon next to the desired entity and select “Import” from the context menu.

Select a CSV file and upload it. It is important that the CSV file contains column names that are the same as property aliases.

This feature is not available in the free version.

Export data to a CSV file

Users can download a CSV file by selecting the desired entity in the Db Extension Kit section and clicking the "Export" button when the list is displayed.

Telemetry statistics

Since version 1.0.1, our Database Extension Kit package has been collecting telemetry data. This provides us with insights to which Umbraco and package versions being used, so that we can make informed decisions on how to focus our future development efforts. The data is sent anonymously, no personal or sensitive data is collected.

What type of data is being captured?

An example of the data captured is as follows.

{
    "umbraco_id": "0403E47E-EFE7-4CF2-8E97-148681DAFC10",
    "umbraco_version": "13.0.0",
    "package_id": "DatabaseExtensionKit",
    "package_version": "1.0.1"
}

How to disable telemetry?

If you would prefer to opt-out and disable the telemetry feature, add this option in your appsettings.json file:

{
  "DatabaseExtensionKit": {
    "DisableTelemetry": true
  }
}