Using the domain

Domain definition

Before you start defining your domain definition, you will need to create a profile. As with contexts, domain definitions are linked to a particular profile, allowing you to create multiple definitions representing different aspects of your business.

To start creating your domain definitions, navigate to Domain > Domain definition.

Creating domain types

Domain types represent the different types of business objects that exist in your business model.

At the top of the Domain definition screen you can see a list of domain types that have been defined for the selected profile.

To add a new domain type, click the Add button. It will allow you to create a new domain type, providing it's code and name, and optionally selecting one of the predefined business roles for the object for easier recognition. The code of the type will be used when you access your domain through programming interfaces, so it's important to use clear codes that are intuitive in your business environment. Names are only normally used as labels inside the Hyperon Studio.

The types section will also allow you to edit and delete existing domain types. To maintain coherence, it's not possible to delete a domain type if there are active objects of that type in your domain.

For the example used throughout this tutorial, we've created 3 domain types:

  • PRODUCT, representing a Life Insurance products
  • COVERAGE, representing coverages of specific risks within the product
  • DISCOUNT, representing reductions in premium

Additionally, we've created a ROOT type, to act as the main element of our domain.

Assigning components

Once you've created and selected a domain type, you can configure it's components. Components represent the relations between your types.

When you create a component, you need to set a code and name. Those have roles similar to those of types: the code will be used by programming interfaces to access a component, and name is displayed throughout the Hyperon Studio.

Each component has to have a type specified. You can select one from the combobox in the type code column. This allows you to choose a domain type for the relation.

To determine if the relation is a collection of components, check the multiple box. Leaving it unchecked designates the relation as single-component.

You can control if the particular component is displayed in the domain tree inside the Hyperon Studio - if you want it to, check the in tree box. All relations of an object can be accessed from it's details screen, but in some cases it's good to create an easier way to navigate to them.

For our example, we've created some relations in the PRODUCT type. A product has a collection of COVERAGES that represents the different risks that can be covered by the product, and a collection od DISCOUNTS - allowing us to configure discounts that can be applied to a specific PRODUCT.

In addition, we've created a single-component relation to a COVERAGE that designates the main risk covered. In case of Life Insurance, this will be the clause that covers the risk of death of the insured, and it will require some special handling inside the application, so a direct reference to it will be useful.

Setting the main type

As the domain is a tree-like model, it needs to have a designated root. To mark a type as root, select the type from the list and click the set as main button.

Root objects have some special behaviours:

  • when a type is set as main, Hyperon will automatically create an instance of this type directly under the profile.
  • this instance doesn't have its code or name, and its components are accessed directly without specifying an object in programming interfaces.
  • if the in tree box is unchecked on a component of the root type, the objects assigned to that relation are still displayed in tree, but without the grouping label.
  • any ATTRIBUTES created for the root type will not be accessible.

Creating attributes

In addition to COMPONENTS, domain types can each have a set of ATTRIBUTES. Attributes hold the detailed information about the objects, and are used both as a navigation tool and a programming interface.

ATTRIBUTES have values that can be either functions, parameters or literals. This is decided not on the type level, but on the object level. It means that for a particular attribute, some objects can have it's value given literally, while others have a parameter or a function assigned to calculate value based on context.

When creating attributes, it's good practice to decide on the general role they should have in your domain, ie. whether they should just act as accessors to certain parameters/functions, or if they should provide a handle for implementations. In the example we use in this tutorial, we will do the latter - we want our domain to answer direct context based questions, like "is this product available in the given context" or "what is the premium for this coverage in the given context", as opposed to "what are the conditions of availability for this product" or "what function is used to calculate premium for this coverage".

Both those approaches are valid in specific scenarios, but it's important to maintain consistency throughout your domain.

To create an attribute, select a type on the domain definition screen, and click the Add button.

Similar to types and components, you will have to provide a code and a name for the attribute, code being used in programming interfaces and name - to be displayed throughout the Hyperon Studio.

In addition, you are able to set a group for an attribute. Groups allow your attributes to be displayed together based on common topics they relate to.

You can also change the order in which ATTRIBUTES and groups will be displayed inside the Hyperon Studio. To do that, click the reorder button and drag your groups in the order you want. After selecting a group, you can also reorder the ATTRIBUTES contained in that group.

For our example, we've created some attributes for the PRODUCT type:

  • DISPLAYED_NAME represents the full name of the product, displayed on documents.
  • SHORT_NAME represents the shortened version of the product name, to be used on small UI components like buttons.
  • IS_AVAILABLE is an attribute that will provide a boolean answer to the question "is this product available for the given context".
  • TOTAL_PREMIUM is an attribute that will provide the total premium for the product, which in our business case it the sum of discounted premiums for each coverage.
  • TOTALBASEPREMIUM is an attribute that will provide the total premium before discounts are applied. In our business case, this is the sum of base premiums of each coverage.

Default values

You can assign default values to each ATTRIBUTE. The default value can be either a parameter, a function or a literal. Every object of a particular type that is created will automatically have the default values set for each of it's ATTRIBUTES.

In addition, whenever you create a new ATTRIBUTE with a default value, or set a default value for one, you will get a popup asking you how to apply this value to existing domain objects of the given type.

Below you can see the popup with possible options for editing an existing default value. The options differ based on the operation.

For all changes:

  • no change - the values of the attribute will not be changed for existing objects. If you ad a new attribute, the existing objects will have it's value empty, despite a default value being provided

When creating a new attribute:

  • set new value - all existing objects will have the new attribute's value set to the default

When setting a default value (there was no default value before), or changing the default value:

  • set new value only if current is empty - all existing objects that did not have a value for the attribute will have the value set to the new default
  • force setting new value, all previous individual values will be replaced - ALL existing objects will have their values for the attribute replaced to the new default value

When changing the default value:

  • set new value only if current is equal to previous - all existing objects, that had a value for this attribute equal to the previous default value will have it's the attribute's value changed to the new default
  • set new value if current is empty or equal to previous - all existing objects, that had no value for the given attribute, or had a value equal to the previous default value, will have the attribute's value replaced by the new default
  • force setting new value if current value not equal to previous, individual value will be replaced - all existing objects, that had a value NOT EQUAL to the previous default value will have their values set to the new default

As you can see, there are quite a few options to manipulate default values. It might seem redundant when creating your first domain definition, but its importance becomes evident when you have to add new ATTRIBUTES to an existing domain, with many objects already created.

Setting the right default values will speed up your work with the domain significantly. It's important to set a general policy for it to maintain consistency.

Some ATTRIBUTES will almost uniformly share the same value. In the example we use in this tutorial, PREMIUMTOTAL and BASEPREMIUMTOTAL attributes of the PRODUCT type will use the same function as implementation for every single object created - so we're setting the default value to that function. We've also set the default function for PREMIUM attribute of COVERAGES, as in our business model, this is uniformly the BASEPREMIUM reduced by the values of applicable discounts.

For ATTRIBUTES that return non-text values, it's good to set a default so that an object can be used and function in your application without the need of detailed configuration. In our example, we've set the default of all ISAVAILABLE attributes to true - this means that immediately after creation, the new object will appear and function properly within the application - the specific configuration of availability can be provided later. We've also set the BASEPREMIUM attribute of COVERAGES to 0 - this ensures that for a newly created object, the attribute will return a value, so other aspects can be configured and tested before approaching the premium configuration.

Finally, it's good practice to provide descriptions of the expected values in the fields where no other default value makes sense, using a specific markup for easy recognition of fields that need to be configured before the new object is functional. In our example, we've used the markup to describe those fields, for example <enter a="" name="" for="" the="" product="" to="" be="" displayed="" on="" documents=""> is the default value for </enter>DISPLAYED_NAME attribute on PRODUCT.