Data Class Business Object

Data Class Introduction

Data Classes define the data model of your business application. You can use Data Classes to model the different concepts or entities that are part of your business, like Persons, Legal Entities or Addresses, and to model the relationship among them.

Data Classes are at the core of the Platform's Data Modeling capabilities: they provide a way to represent your business data and to define the data that is relevant for your applications.

Data Classes contain Properties, representing atomic data that compose the object, and Functions, representing expressions that can be executed on the data contained in the Data Class. Concepts required for complex data modeling are supported, such as defining relations between different objects through:

• Composition, Aggregation and Association of multiple objects

• Inheritance, that is, the definition of subcategories of a more generic object

  Inheritance is the most commonly used term in documentation. However, for clarity purposes, we sometimes refer to child (Data Classes inheriting properties from another Data Classes) and parent (Data Classes from which another Data Class inherits properties) Data Classes.

Data Modeling example: Consider that your data model contains persons and that, for each person, you need to keep track of their name, surname and the list of their previous and current addresses. A possible way to represent this using Data Classes is by creating a Person Data Class, composed of name, surname and a list of addresses, where each address is an Address Data Class, containing information such as street, street number, city, and country. In some situations, you may want to have a utility function to get the full name (name followed by surname) of a person. This utility should be part of the Person Data Class.

Now, assume that your data model needs to handle employees, as special types of persons that also have a salary defined. In order to reuse the data structure already defined by the Person Data Class, you can just define an Employee Data Class that inherits from Person, and which contains the additional salary information.

This situation can be represented using a data class diagram:

Data Class Editor

The Data Class Editor allows creating and developing Data Classes.

Open the Data Class Editor by double clicking on a Data Class Business Object, or by right-clicking and choosing Open in Editor from the context menu.

The Data Class Editor is composed of different areas:

1. Header: The header background color indicates whether you are in edit mode (gray) or read-only mode (red). When hovering the Data Class BO id, a copy icon is displayed, which allows copying the BO id. Various actions are possible, including:
   • Undo: allows undoing your latest action
   • Redo: allows redoing your latest action.
   • Validate: allows validating your edits on the Data Class. The Validate icon is instantly updated upon your changes, thus providing immediate validation feedback (see also the Validation section below):
     • red: highlights an error, the Data Class or part of it is invalid.
     • yellow: highlights a warning, the Data Class is still valid but action is required.
     • green: the Data Class is valid.
   • Edit Labels: allows displaying an overview and further editing the Labels used in the current Business Object through the Translations Tool.
2. Left sidebar: contains Dependencies, Inheritance, and Validation information.
3. Central area: modeling area, containing the content of the Data Class. The central area of the Data Class Editor is composed of a filtering field, and three tabs:
   • Properties tab: allows creating and modifying the Data Class properties.
   • Functions tab: allows creating and modifying the Data Class functions and static functions.
   • Inheritance tab: allows defining Data Class inheritance, by setting parent Data Classes.
4. Right sidebar (also referred to as components library): library containing all the items that can be added to the selected tab. The available items depend on the selected tab in the central area (Properties, Functions, Inheritance).

Dependencies, Inheritance, and Validation Sidebar

The left sidebar of the Editor contains details about the relations between the current Data Class Business Object and other Business Objects in the Solution, as well as validation information. The three sections can be expanded and collapsed.

The Dependencies section displays the dependencies among Data Class Business Objects:

• The Uses section lists the Business Objects on which the current Data Class depends.

• The Used by section lists the Business Objects that depend on the current Data Class.

  Note that, starting from Appway 11, Label Business Objects are no longer shown as dependencies in the Data Class Editor. You can see Label dependencies from the Label Business Object library.

The Data Classes that inherit from this Data Class section lists the Data Classes inheriting (that is, child Data Classes) from current Data Class.

The Validation section contains validation messages for the current Data Class. The Data Class Editor supports instant validation: every time an action that triggers a validation issue is performed, the panel is updated with the corresponding information to allow quicker response.

The header indicates the total number of validation messages in the Data Class. Type of messages are:

• Error: (red icon) the issue requires immediate action, and makes the Data Class (or part of it) invalid.
• Warning: (yellow icon) the issue requires immediate action, but the Data Class can be still used to create a working Data Model.
• Info: (gray icon) the issue does not require immediate action, but consider fixing it to have a Data Class that complies with best practices.

Components Library Sidebar

The right sidebar (also referred to as components library) contains the elements that can be used to compose the Data Class. Such components change based on the tab selected in the central area (Properties, Functions, or Inheritance). Use the Filter search field to find the desired element.

Drag and drop components (primitive types, other Data Classes, functions, among others) to the central area to build the current Data Class.

Shortcuts in the Data Class Editor

The following table provides and overview of all shortcut keys specific to the Data Class Editor.

Tab	Shortcut	Operation
Properties	CTRL-E	Add property
Functions	CTRL-E	Add function
Functions	CTRL-shift-E	Add static function
All Tabs	CTRL-shift-F	Focus on Filter field

Adding Properties

When the Properties tab is selected, you can view, add and modify the properties of the Data Class. A property is a unit that composes the data represented by the Data Class. A property can be either a Primitive Type (String, Integer, and so on) or a Data Class itself to model more complex data in a modular way (e.g. the Addresses of a Person).

To add and edit properties, do the following:

1. Drag properties from the components library on the right side to the Data Class in the central area. You can either drag the exact type you need, or the generic Property item, and choose the exact type later. In the components library, you can find:

   • The most used primitive types
   • The generic Property component
   • Data Classes and Primitive Types from the current Package, and the Packages declared as dependencies that provide at least one visible Data Class.

2. In the Configuration tab, set a human-readable name for the property. If unset, the Name field is filled with the name of the Data Class. You can change the property name as many times as required, until the Data Class is saved.

   Important! After saving, the property name is fixed and can no longer be changed.

3. Set any other configurations in the Configuration tab:

   • Description: a short, human-readable description used for documentation purposes (the description is displayed under the property name in the property preview) .
   • Collection Type: whether the property is:
     • Single Element: when there is only one element for each instance of the Data Class
     • Indexed Collection: when the Data Class contains a indexed list
     • Named Collection: when the Data Class contains a list of items, each identified by a unique string.
   • Type: the type of the property (a Primitive Type, such as String, or Integer, or a Data Class itself). The property type is automatically guessed based on the property name.
   • Choice Type (Boolean Primitive Types only):
     • Choice between two options: In the UI, the user will be able to choose between two options (e.g., Yes/No). The two options can be defined through a Catalog Values Data Rule.
     • Single affirmative choice: In the UI, the user will be able to select a confirmation checkbox. No Catalog Values Data Rule is to be set in this case.
   • Format ("Numeric" Primitive Types only): Select a Format Business Object to determine your number formatting.

4. A Context menu is also available for each property to perform operations such as Copy, Paste, Delete or View Dependencies.

   Consider the following information:

   • Double-clicking on a property opens the corresponding Business Object.
   • When using the Script Language, you can access Data Class properties by using the dot notation. For example, the Name property of a Data Class `$p` of type Person would be accessed as `$p.name`.

5. Order the properties of a Data Class by dragging and dropping them. Data Class properties often have a logical order. For example, a Person Data Class would probably start with the properties firstname and lastname. Ordering of properties is not just a mean to keep your Data Classes well-organized, but it has clear implications on how the Data Class is used in the context of Data Logic approaches and for Data Classes generated with the WebServices extension. Consider the following information:

   • When the Data Class is used in Data Logic and is not unfolded, the order defined in the Data Class is the order in which the properties appear on the final screen in the Workspace.

   • When the Data Class is unfolded in a Data Logic Business Object, the order in which properties appear in the Editor comes from the Data Class and can be modified in Data Logic.

   • For Data Classes that have been generated from a SOAP service via WebServices extension, the order of the properties is used when the object is serialized when using TranslateTo or SoapConvertToXML script functions. Data Classes generated via WebServices extension display a specific icon to help you recognize them immediately.

     Important! Be aware that changing the property order in Data Classes generated through the WebServices extension may change the order used in the Data Class serialization, and introduce errors in integration.

Adding Functions

When the Functions tab is selected, you can view, add and modify functions to the Data Class. A Function is an expression, written in Appway Script Language that can be executed when working with the Data Class.

To add and edit Functions and Static Functions, do the following:

1. Drag them from the Components library on the right to the central area. Each function type will appear in a different area according to its type (static or not):

   • Functions require you to have an instance of the Data Class to be executed. The pseudo-variable $this can be used in the script to refer to the current Data Class. Example (snippet):
   Copy

   
       Person $p := NewObject(Person, �John�, �Doe�);
   
       PRINTLN($p.getFullName());
   
   

   • Static Functions can be executed even if you did not instantiate the Data Class (for example, using NewObject() ). They are generic functionality that are bound to the object type only. Example (snippet):
   Copy

   
       PRINTLN(Person.getLegalAgeToVote());
   
   

2. Set a human-readable name for the function. The Name field is displayed in the Configuration tab when clicking on the function header or on the menu icon. You can change it as many times as required, until the Data Class is saved. After saving, the function name is fixed and can no longer be changed.

   Double-clicking on the Function opens the Script Editor directly (see further information on the Script tab below).

3. Set any other configuration in the following tabs:

   • Configuration tab:

     • Description: a short, human-readable description of what the function does, used for documentation purposes (the description is displayed under the property name in the property preview, and in the Interactive Script Editor) .

   • Return Type tab

     • Returns Value checkbox: determines whether the function returns any values. Leave it unselected if it returns Nothing. Otherwise, select it and set the following:
     • Description: single-line description field of the return value used for documentation purposes (the description is displayed in the Interactive Script Editor).
     • Collection Type: Single, Indexed Elements or Named Elements.
     • Type: the type of the property (a Primitive Type, such as String, or Integer, or a Data Class itself). The function type is automatically guessed based on the function name.

   • Parameters tab (list of parameters accepted by the function). Each parameter has:

     • Name: a human-readable name for the parameter.
     • Description: single-line field for documentation purposes. An expression to set the default value can also be defined (the description is displayed in the Interactive Script Editor).
     • Collection Type: Single, Indexed Elements or Named Elements.
     • Type: the type of the property (a Primitive Type, such as String, or Integer, or a Data Class itself).
     • Default Value: optional expression evaluated when assigning a default value to the parameter, when it is not specified explicitly.

   • Script tab: Contains the information gathered from the other tabs. It is pre-filled based on the selections done in the UI, and the code that is executed by the function.

     The Parameters, and Return Type tabs support the user to change the function UI without the need to write code. The Script tab provides the same functionality to more experienced users, and allows defining the function content. Therefore, the content of these tabs is always kept in sync. If the code in the Script tab is invalid, the Parameters and Return Type tabs are not displayed. In this situation, you need to fix any issues in the Script tab before being able to use the other tabs.

Finally, consider the following:

• A Context menu is also available for each property to perform operations such as Copy, Paste or Delete.
• Data Class functions do not support ordering. Functions are automatically sorted alphabetically.

Working with Inheritance

In some cases, a Data Class needs to be an extension of another Data Class. This is a common scenario when one Data Class is used to model a generic concept/entity (e.g. Person) and a more specific subset of that concept/entity is then used in the data model (e.g. Employee). In situations like these, you can make the specific Data Class (parent) inherit from the generic one (child). Inheritance is also a mean for you to create data models that can be easily extended and developed.

Child Data Classes inherit all of their properties and functions from their parents. You can add new properties and function, if needed.

The Inheritance tab allows you to define the parent Data Classes from which the current Data Class inherits. Data Classes can be expanded to view the entire hierarchy of inheritance by clicking on the orange section containing the parent Data Class. You can also use the filter field to filter by Data Class.

You can add one or more parent Data Classes by dragging them from the component library on the right, as one Data Class can have multiple parents. A context menu is also available for each parent Data Class to perform operations such as Copy, Paste, Delete ,View Dependencies, and Delete All Missing Properties (see below). Moreover, consider the following information:

• When a Data Class has one or more parents, the properties and functions that it inherits from such parents are visible in the Properties and Functions tabs and distinguished by a different color background.

• Properties that come from a parent class can be reordered in the same way as standard properties. If an inherited property has been ordered in the child Data Class, and it is then deleted from the parent, such property no longer exists in the child Data Class. In this situation, the property is shown in a gray background. You can fix this situation either by adding the missing property back to the parent, or by removing the property from the current Data Class using the context menu. If a Data Class contains two or more missing inherited properties, you can also delete all of them at once by clicking on the Delete All Missing Properties button.

  The Data Classes that inherit from this Data Class section on the left sidebar allows you to investigate the inheritance tree on the other direction (that is, displaying Data Classes that inherit from the current one).

In some erroneous situations, you may a cycle in the inheritance structure (a Data Class that, through other parents, is inheriting from itself), or you may have parent Data Classes that no longer exist because they have not been imported yet, or have been deleted. All these situations are highlighted and described in the Inheritance tab and a shorter info message is also displayed on the Validation section on the left sidebar.

Adding Behaviors

Behaviors have been designed specifically to be used with App Tasks (e.g., Data Gathering) and allow providing semantic information at Data Class level, to ensure that the final representation of the Data Class in a Data-Driven UI is coherent with the data contained in the Data Class. In other words, a Behavior defines the way in which a Data Class behaves when it is represented in an automatically-generated UI. When the Data Logic is translated in a Data Driven UI, controls are rendered as form elements by default. However, in some situations, specific Data Classes need to be shown in a different way. For example, an Address in a list of addresses could be shown using a more compact UI element than a full list of form elements.

See App Tasks: Common Configuration documents for further information.

Related Sources

• Data Class Best Practices