Business Objects

Working with relational data

Overview

The apps are always built around a data which is displayed or manipulated from the user. A common approach to work with structured data is to use a relational database. Dynamics Mobile Apps can work with structured data stored in a relational database.

However, instead of accessing the database "directly", it uses a concept for Business Object.

A business object is a piece of data, which has a well-known structure. Every business object has a name and list of members ( or fields). You can also think of the business object as a table in a database.

If our app needs to store information about customers, most probably we will need a business object Customer. Our business object customer might have members Name, Address, Phone, Email and Age.

If we want to store structured data in terms of tables in our app, we need to define a business object.

Defining a Business Object

Let's assume we want to use a Customer business object in our application, because we want to store and retrieve information about our customers.

Let us also assume that we want our customer object to have the following fields:

Field name

Data Type

First Name

string

Last Name

string

Age

number

In order to define this business object, we need to create a new file called Customer.bo.json in our Business Object folder. Follow these steps:

Open your app with Visual Studio Code
Navigate to src/Business Object folder from the Explorer
Right-click over it and select New file
Give the file a name: Customer.bo.json
Press ENTER to confirm the file creation.

Once the file is created, we need to paste the following JSON content inside:

{
    "Customer": {
        "name": "Customer",
        "label": "Customer",
        "pluralLabel":"Customers",
        "pageSize": 300,
        "searching": true,
        "properties": {
            "DMS_ROWID": {
                "type": "Binary",
                "isIdentity": true,
                "isPK": true,
                "label": "Id",
                "sorting": false,
                "searching": false,
                "uiType": "Default"
            },
            "firstName": {
                "type": "String",
                "label": "FirstName",
                "required": true,
                "sorting": true,
                "searching": true,
                "uiType": "Default",
            },
            "lastName": {
                "type": "String",
                "label": "LastName",
                "length":100,
                "required": true,
                "sorting": true,
                "searching": true,
                "uiType": "Default",
            },
            "age": {
                "type": "Int32",
                "label": "Age",
                "length":100,
                "required": true,
                "sorting": true,
                "searching": true,
                "uiType": "Default",
            }
         }
 }

The upper JSON content defines our Customer business object. This JSON is called Business Object Definition.

Every business object must have DMS_ROWID attribute defined, which is a physical primary key. DMS_ROWID is actually a guid stored in binary format and generated automatically by the system when a new business object instance is stored.

Once we have our business object defined, we can select all customers from the database it in the following way in our app:

import { View } from '@dms';
import { Customer } from '@dms-bo';

@View()
export class MyView {

 public async load(): Promise<void> {

   //execute database query 
   const allCustomers = await Customer.query().executeSelect();
   
   //work with the returned array of customers
   allCustomers.forEach(customer=>{
     console.log(`customer ${customer.firstName}`);
   })
 }
}

The SDK has generated a TypeScript declaration for the Customer business object, from the JSON definition.

We can create new business object instances easily:

import { View } from '@dms';
import { Customer } from '@dms-bo';

@View()
export class MyView {

 public async commit(): Promise<boolean>{

   //create in-memory instance
   const customer = new Customer();
   customer.firstName = 'myFirstName';
   customer.lastName = 'myLastName';
   customer.age = 26;
   
   //insert it into the database
   await customer.add();
   
   //update it
   customer.firstName = 'newName';
   await customer.update();
   
   //delete it 
   await customer.delete();
   
 }
}