Customizing Operator Advisor > Extending the Operator Advisor Data Model > Adding Custom Entities to the Operator Advisor Data Model
Adding Custom Entities to the Operator Advisor Data Model
Adding new entities to the Operator Advisor data model involves multiple steps:
Create a Data Shape for the New Entity
To create a Data Shape for the new entity, complete the following steps:
1. In ThingWorx Composer, create a new Data Shape. For this example, name the Data Shape MyObject.
2. Under Field Definitions, click Add and specify new field definitions for each property to be included on the Data Shape.
a. Designate one field as the primary key by selecting the Is Primary Key checkbox for that field.
b. Set the Base Type of the primary key field to LONG. If the primary key field is a LONG data type, then the values for this field are autogenerated, and the logic for incrementing the value is handled by the database. If a different Base Type is selected, then you must handle the logic for primary key uniqueness.
To align with the Operator Advisor data model, add a UID field, with a Base Type of LONG, and the Is Primary Key checkbox selected.
3. Click Save to save the new Data Shape.
* 
When the database table is created for the Data Shape, the database table name is the Data Shape name, minus any prefix, in all lower case. For example, if the Data Shape is named ABC.MyObject, then the database table name is myobject. Because prefixes are not included in the database table names, multiple Data Shape names that would result in the same database table names, such as ABC.MyObject and PTC.SCA.SCO.MyObject, are not supported.
Similarly, the column names in the database table are the field names from the Data Shape in lowercase. For example, a field named MyPrimaryLocation results in a column named myprimarylocation. 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.
Update the Database Information to Include the New Data Shape
Update the database information to include your new Data Shape. You can accomplish this by adding the database information to the existing Get<entity>DBInfo service for the data model entity with which your new entity logically belongs, or by creating a new Get<entity>DBInfo service for your entity. For example, if your new entity is logically a part of the job order database schema, add the database information for your new Data Shape to the GetJobOrderDBInfo service.
If you choose to create a custom manager for your new entity, create a new Get<entity>DBInfo service for your entity.
Adding the Database Information to an Existing Service
To add the database information for the new Data Shape to an existing Get<entity>DBInfo service:
1. Navigate to the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
2. Under Services, navigate to and override the Get<entity>DBInfo service for the entity. For example, the GetJobOrderDBInfo service or the GetWorkDefinitionDBInfo service.
3. In the script editor, add an entry for your new Data Shape as an array, similar to the existing Data Shape entries. Include the database information for your Data Shape:
▪ dataShapeName—Name of the Data Shape for which the new database table is being added.
▪ indexedFields—Columns to be indexed. Indexing assists with faster searches and sorting. Multiple indexed fields can be defined in an array. Each element in the array can contain the following properties:
▪ name—(Required) Name of the column.
▪ unique—Specify if the column must have a unique value.
▪ 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_name>_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.
▪ fields—Any column for which some additional specification is needed. Multiple fields can be defined in an array. Each element in the array can contain the following properties:
▪ name—Name of the column. Required.
▪ length—Length of the column, if the column is a String, and a length other than the database default length is needed.
▪ notNull—Specify if the column must not be null.
* 
If a column must have a unique value, specify this using unique in the indexedFields array, rather than in the fields array.
▪ foreignKeys—Any foreign key column definitions for the new database table. Multiple foreign keys can be defined in an array. Each element in the array must contain the following properties:
▪ name—Name of the column 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.
▪ 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_name>_fk. 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.
▪ 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.
For example, for the new MyObject Data Shape to have no indexed fields, a foreign key, and setting the length of the Location field to 4000 characters, enter the following:
{
"dataShapeName": "MyObject",
"indexedFields": [],
"foreignKeys": [{"name":"WorkDefinitionUID", "referenceDataShapeName":"PTC.SCA.SCO.WorkDefinition", "referenceFieldName":"UID"}],
"fields": [
{
"name": "Location",
"length": 4000
}
]
}
4. Click Done, then click Save to save the updated service.
Creating a New Service to Get Database Information
To create a new service to get the database information for your Data Shape:
1. Navigate to the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager), or to the custom manager for your entity if you have created one.
2. Under Services, click Add to add a new service. Name the service Get<entity>DBInfo, replacing <entity> with the name of your Data Shape. For example, GetMyObjectDBInfo.
3. Set the output type for the service to JSON.
4. Using one of the existing Get<entity>DBInfo services as a model, enter the database information for your Data Shape. See step c in the previous section for the database information to specify.
5. Click Done, then click Save to save the new service.
6. Override and edit the GetDBInfo service.
7. In the script editor, add an entry for the new service.
▪ For example, if you are overriding the GetDBInfo service on the default production order manager, add an entry for the GetMyObjectDBInfo service similar to the following:
Array.prototype.push.apply(dbInfo.dbInfo, me.GetMyObjectDBInfo().dbInfo);
▪ For example, if you are overriding the GetDBInfo service on a custom manager, add an entry for the GetMyObjectDBInfo service so that the service code appears similar to the following:
var dbInfo = {
dbInfo: []
};
Array.prototype.push.apply(dbInfo.dbInfo, me.GetMyObjectDBInfo().dbInfo);
var result = dbInfo;
8. Click Done, then click Save to save the updated service.
Create CRUD Services
Create the CRUD services necessary for managing instances of the new Data Shape.
1. Navigate to the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager), or to the custom manager for your entity, if you have created one.
2. Under Services, click Add and create the necessary services. Use the existing CRUD services for Operator Advisor entities as models.
◦ A create service:
▪ Enter a service name. For this example, enter CreateMyObjects.
▪ For the service input, add an input named MyObjects, with a Base Type of INFOTABLE. For Data Shape, select your Data Shape.
▪ For the service output, select INFOTABLE, and choose your Data Shape.
▪ In the script pane, enter code similar to the following:
var insertParams = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Insert(insertParams);
◦ A delete service:
▪ Enter a service name. For this example, enter DeleteMyObject.
▪ For the service input, add an input named UID, with a Base Type of STRING.
▪ For the service output, select INFOTABLE, and choose your Data Shape.
▪ In the script pane, enter code similar to the following:
var params = {
UID: UID,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Delete(params);
◦ An update service:
▪ Enter a service name. For this example, enter UpdateMyObjects.
▪ For the service input, add an input named MyObjects, with a Base Type of INFOTABLE. For Data Shape, select your Data Shape.
▪ For the service output, select INFOTABLE, and choose your Data Shape.
▪ In the script pane, enter code similar to the following:
var params = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Update(params);
◦ A service to retrieve an individual instance of this Data Shape:
▪ Enter a service name. For this example, enter GetMyObject.
▪ For the service input, add an input named UID, with a Base Type of STRING.
▪ For the service output, select INFOTABLE, and choose your Data Shape.
▪ In the script pane, enter code similar to the following:
var params = {
UID: UID,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].GetEntity(params);
◦ A service to retrieve multiple instances of this Data Shape, optionally including filter, offset, and limit input parameters. If no input parameters are specified, all instances of MyObject are returned:
▪ Enter a service name. For this example, enter GetMyObjects
▪ For the service input:
▪ Add an input named filter with a Base Type of JSON.
▪ Add an input named offset with a Base Type of INTEGER.
▪ Add an input named limit with a Base Type of INTEGER.
▪ For the service output, select INFOTABLE, and choose your Data Shape.
▪ In the script pane, enter code similar to the following:
var params = {
filter: filter,
dataShapeName: "MyObject",
offset: offset,
limit: limit
};

var result = Things[me.GetDatabaseThingName()].Query(params);
3. Click Save to save the new services on the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
4. Under Configuration, add an entry for the new Data Shape and new creation service to the ServiceConfigurationSettings table. This allows instances of the new Data Shape to be created using the creation service when data is imported into Operator Advisor. Each Data Shape should be specified only once in this configuration table.
For more information, see Importing Data from Other Systems.
Synchronize the Database Information and Database Schema
Add the new entity to the database by synchronizing the database information with the database schema. For more information, see Synchronizing the Database Information and the Database Schema.
Was this helpful?