How to create a user model using Data Dictionary

Summary

This article shows the steps involved in the creation of a user model and generating the assemblies that contain its definitions using Data Dictionary.

Prerequisites

None. You can use this article on its own.

Example material

Guide

Why create a model?

By creating a user model, you can define abstractions of real world elements, specific to your installation, and maintain relations of them in a relational schema within the Ubisense system. You can also create a package of the service or services (written with the .NET API) that update these relations and install it in different controllers using the Service Installer tool.

Designing the model

For the example in this article, we will create a module called "CarModule" that holds information about cars in the CarHasProperties relation of its CarData schema as well as the types and operations needed to support it. The design of the CarModule is as follows:

Creating the CarModule

To start, open the Data Dictionary Editor tool, available from the Start Menu > Ubisense 2.1 > Data Dictionary Editor. Right-click on the 'User model' item in the lower tree view and select 'Insert module'. On the following dialog define the name of your module and add a description for it and click OK. We will call it "CarModule" for this example. After you press OK, the new model will appear in the tree.

Adding the types to the module

We are going to add the "VIN", "Model" and "Car" types. Expand the newly created Module and right click on Types > Insert type and select the appropriate option. The definition of the types will be included in the CarModule.dll assembly when we generate it later on.

1) Car (Object type)

The Car type will be an object type. Making it inherit from UEnterprise.UserDefined is very convenient; this way it can be handled programmatically as other Ubisense objects and later (if a package containing its definition is installed in a dataset, or the model is published to the Platform) it be can be instantiated in Site Manager.

To start, expand the view of the recently created module and find Types > Insert type > Object. Give it the name "Car", add a description for it and click OK. The type Car should now appear in the model tree view. Setup UEnterprise.UserDefined and UBase.Object as ancestors of this type by right clicking the Car type and selecting "Insert ancestor" for each case.

2) VIN (Basic type)

The VIN of a Car should be a System.String as it may contain not only numbers. Choose "Basic Types" when adding it and add the following properties for the type:

3) CarModel (Enumerated type)

There are a fixed number of possible values for a Car's model, so this type should be an enumerated type. Create it by selecting "Enumerated type". CarModel will now appear in the model tree view after giving it a name and a description and clicking OK. Give the CarModel enumerator its possible values. Right-click on CarModel, select "Insert value" and enter the text in the dialog that appears for the values "COMPACT", "PICKUP" and "FAMILY".

4) The model so far

After adding the module types, the expanded model tree view should look like this:

Adding the CarData schema to the module

In a similar way as the previous steps, right click on "Schemas" and select "Insert schema". Give the new schema the name "CarData". From this point on we will define the types specific to this schema, the relations it will contain as well as the operations needed to maintain it.

1) Schema types, CarProperties (Record type)

The CarProperties record holds an instance of the Car and CarHasProperties types; right click on "CarData" and select Insert type > Record to create it. After creating the CarProperties record, select it with a right click and choose "Insert field" and create the following fields:

2) Schema relations, CarHasProperties (relation)

Add a relation with no base type called "CarHasProperties" and setup the following:

3) Schema operations

The schema operations provide the functionality needed by any client to update the relation at the server. Operations don't have to provide querying functionality, and in general should not.

Note: get_car_properties is provided as an example here, but would only be useful in practice for a dataless schema client. You should create caching schema clients and query the local cache for relations with more than one entry in the table.

To create the operations, right-click CarData > Operations and select "Insert operation". Enter the details and click OK. Do this for each of the operations. Remember to specify the correct return type. Leave the "Oneway" check box cleared. This means that all your operations will be blocking, that is they will wait for a response from the server. Oneway operations are non-blocking.

The CarHasProperties relation will be updated by 3 operations:

Notes: The "Oneway" parameter determines if the operation will wait for a response from the server (synchronous, reliable, two ways) or not (asynchronous, unreliable, one way).
This article does not cover the implementation of these operations, however, we still need to have these defined in the user model in following articles and it is good practice to declare them at this point.

4) The finished model

When fully expanded, the finished model tree view should look like this:

Generating the assemblies

1) Check the model for possible errors

Click on Model > Check model and confirm that you have no errors in your model by looking at the status window on the lower part of the screen. Most of the time, the errors are fixed by checking that the return types or arguments on the indexes or operations are OK.

2) Set the Compilation options

Once you've confirmed the model has no errors, Click on Model > Compilation Options. Browse for the directory where the Ubisense dlls are located (the default location is C:\Program Files\Ubisense 2.1\bin). Also, choose the folder where the generated assemblies will be created.

3) Generate the assemblies

Click on Model > Generate assemblies. This action will generate a dll and an xml file for both the CarModule types and the CarModule's CarData schema. The dll file contains the user model definitions and the xml file has the annotations for the elements in the model, so that a user of the dll knows what each element does.

• CarModule.dll

• CarModule.xml

• CarModule-CarData.dll

• CarModule-CarData.xml

Now you can add a reference in a .NET application to include these definitions and use them to instantiate Car, CarModel, VIN, CarProperties types or a CarData schema complete with its CarHasProperties relation, its operations and index methods.

What's next?

This article covered the steps to create a user model. Following articles cover:

• Creating a service that implements the CarData schema operations in How to implement the operations for a user-defined schema.

• Creating a schema client application that connects to the schema in How to create a client application for a user-defined schema.

• Creating a package that includes the service implementation in order to install it in a Ubisense dataset in How to create and install a service package.