Adding Custom Properties to Data Model Entities

Building Blocks > Extending the Data Model > Adding Custom Properties to Data Model Entities

Many entities in the building blocks data model have a related _AP Data Shape for the purpose of adding custom properties. For example, the job order Data Shape (PTC.JobOrder.JobOrder) has an associated PTC.JobOrder.JobOrder_AP Data Shape. The example in this topic adds a new City property to the PTC.JobOrder.JobOrder_AP Data Shape.

Adding custom properties to the data model involves multiple steps:

1. Add a field for the custom property to the _AP Data Shape.

2. Update the database information to add any database constraints for the custom property.

3. Synchronize the database information from the building blocks with the database schema.

For an example showing how to programmatically populate the new custom property using a service, see Populating a Custom Property.

Add Field to the Data Shape

1. In ThingWorx Composer, navigate to the _AP Data Shape for the entity. For this example, navigate to PTC.JobOrder.JobOrder_AP.

2. Under Field Definitions, click Add.

3. On the New Field Definition pane, specify the following:

◦ Name—The name for the property. For this example, enter City. The new name cannot match the name of any fields on the original Data Shape.

◦ Base Type—The data type for the property. For this example, select STRING. The following data types are supported:

▪ STRING

▪ NUMBER

▪ INTEGER

▪ BOOLEAN

▪ LONG

▪ TEXT

▪ DATETIME

▪ THINGNAME

▪ THINGSHAPENAME

▪ THINGTEMPLATENAME

▪ USERNAME

▪ SCHEDULE

▪ IMAGELINK

The column names in the database tables are the field names from the Data Shape in lowercase. For example, a field named MyPrimaryCity results in a column named myprimarycity. As a result, field names with the same letters but different capitalization, such as MyName, myName, and myname, are not supported on the same Data Shape.

4. Click

to add the new field definition.

5. Click Save to save the updates to the Data Shape.

Update the Database Information with any Database Constraints

If your new property requires any database constraints, complete the following steps:

1. Navigate to the manager for the entity to which you are adding the new property. For this example, navigate to the PTC.JobOrderImpl.Manager Thing.

2. Create a duplicate of that manager Thing which you can customize. For this example, name the duplicate manager Thing MyCompany.MyJobOrderImpl.Manager. For the Project value on the duplicate manager Thing, use the project for a building block that you have created. For this example, you would use a building block that is based on the PTC.JobOrderImpl building block which has a project named MyCompany.MyJobOrderImpl. For more information, see Create a New Building Block.

3. Register the duplicate manager.

a. Navigate to the PTC.Base.Manager Thing.

b. Under Configuration, edit the appropriate manager row in the DefaultGlobalManagerConfiguration configuration table and set the managerThingName value to the new duplicate manager Thing that you created in step 2. For this example, update the row for the PTC.JobOrder.Manager to set MyCompany.MyJobOrderImpl.Manager as the managerThingName.

c. Click Save to save the changes to the manager Thing.

4. Navigate to the duplicate manager Thing that you created in step 2. For this example, navigate to MyCompany.MyJobOrderImpl.Manager.

5. Under Services, find and override the GetDBInfo service.

6. In the script editor, scroll down to the entry for the Data Shape to which you added the property. In this example, look for the following entry:

"dataShapeName": "PTC.JobOrder.JobOrder_AP",
"indexedFields": []

7. Update the entry for the Data Shape with the database information for the new property.

◦ If the property is to be indexed, add it to the indexedFields array for the Data Shape, with the following properties:

▪ name—Name of the column. Required.

▪ unique—Specify if the property must have a unique value.

▪ fieldNames—Array containing the names of the columns. If only one column is specified, a single index is created. If multiple columns are specified, a composite index is created.

A single index can be created by specifying name with a single value that is the name of the column, instead of specifying a single value for fieldnames. If both name and fieldnames are specified, name is ignored and the index is created using the fieldnames values.

▪ identifier—The name of the entity in the database. If not specified, then the system automatically generates the value in the format <table_name>_<column_name1>_<column_name2>_<column_nameN>_idx. If specified, then the value must be unique for both specified values and any automatically generated values. The maximum length for the value is the maximum length allowed by the database for identifiers.

◦ If the property is to be a foreign key, add a foreignKeys array for the Data Shape, with the following properties:

▪ name—Name of the property on the current Data Shape to be a foreign key.

▪ referenceDataShapeName—The Data Shape of the referenced database table.

▪ referenceFieldName—The name of the field containing the value being referenced.

▪ onDelete—What happens, if anything, to instances of the current Data Shape when instances of the referenced Data Shape are deleted.

▪ deleteReference—What happens, if anything, to instances of the referenced Data Shape when instances of the current Data Shape are deleted.

For more information on the delete behaviors, see Setting the Delete Behavior with Foreign Keys.

◦ To specify additional database constraints for the property, add it as an entry in a fields array:

▪ name—The name of the new property. Required.

▪ length—Column length for the new property, if different than the default column length for the database.

▪ notNull—Specify if the property must not be null.

▪ defaultValue—The default value for the property.

If a database column must have a unique value, specify this using unique in the indexedFields array, rather than in the fields array.

For this example, to specify that City has a column length of 4000 characters and cannot have a null value, update the entry for the PTC.JobOrder.JobOrder_AP Data Shape as follows:

{
"dataShapeName": "PTC.JobOrder.JobOrder_AP",
"indexedFields": []
"fields": [{
"name": "City",
"length": 4000
"notNull": true
}]
},

8. Click Save to save the changes to the service.

Synchronize the Database Information and Database Schema

Synchronize the database information with the database schema. For more information, see Synchronizing the Database Information and the Database Schema.

Populating a Custom Property

The following code is an example of how to include the custom property in a service to programmatically populate the property. This code uses the CreateInfoTable service that is available on each manager Thing in the implementation design pattern building blocks to merge the PTC.JobOrder.JobOrder and PTC.JobOrder.JobOrder_AP Data Shapes into a single infotable, and populates the new City property with the value of Montreal.

Was this helpful?