Adding Custom Properties and Data Shapes
Adding Custom Properties and Data Shapes
The Operator Advisor data model can be extended to add business-specific data to the model that is not provided out-of-the-box. This is accomplished in the following ways:
• Adding custom properties to existing Operator Advisor entities by updating the _AP data shape associated with the Operator Advisor entity.
• Adding new entities to Operator Advisor by creating custom data shapes and the services to manage them.
Adding Custom Properties to _AP Data Shapes
Most entities in the Operator Advisor data model have a related _AP data shape for the purpose of adding custom properties. For example, the job order data shape (PTC.SCA.SCO.JobOrder) has an associated PTC.SCA.SCO.JobOrder_AP data shape.
Use the following procedure to add a custom property to an Operator Advisor entity. The example adds a new Location property to the PTC.SCA.SCO.JobOrder_AP data shape.
1. In ThingWorx Composer, navigate to the _AP data shape for the entity. For this example, navigate to PTC.SCA.SCO.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 Location.
◦ Base Type—The data type for the property. For this example, select STRING.
4. Click Check mark icon to add the new field definition.
5. Click Save to save the updates to the data shape.
6. Navigate to the database thing configured for your system, for example, PTC.SCA.SCO.PostgresDatabase.
7. Under Services, execute the AddColumn service with the following inputs:
◦ For dataShapeName, search for and select the _AP data shape to which you added the new field definition. For this example, search for and select PTC.SCA.SCO.JobOrder_AP.
◦ For fieldName, enter the name of the new field definition. For this example, enter Location.
◦ For dbInfo, enter the database information for the new column:
▪ name—The name of the column being added to the database for the new property. Required
▪ length—Column length for the new column, if different than the default column length for the database.
▪ unique—Specify if the column must have a unique value.
▪ notNull—Specify if the column must not be null.
For this example, enter the following:
{"name":"Location","length":4000}
The following code is an example of how the custom property can be included in a service to programmatically populate the attribute. This code uses the CreateInfoTable service to merge the PTC.SCA.SCO.JobOrder and PTC.SCA.SCO.JobOrder_AP data shapes into a single infotable, and populates the new Location attribute with the value of Montreal.
var jobOrderDataShapeName = "PTC.SCA.SCO.JobOrder";
var productionManagerThingName = Things["PTC.Factory.LaunchPointConfigurationThing"].GetProductionOrderManagerThingName();
var jobOrders = Things[productionManagerThingName ].CreateInfoTable({
dataShapeName: jobOrderDataShapeName
});

var jobOrder = {};
jobOrder.ID = "" + 121;
jobOrder.WorkType = 1;
jobOrder.Description = "test";
jobOrder.Location = "Montreal";
jobOrders.AddRow(jobOrder);

var newJobOrders = Things[productionManagerThingName ].CreateJobOrders({
JobOrders: jobOrders
});
Including Custom Properties in a Mashup
The following steps provide a best practice for using including properties in a mashup.
1. Add a custom property to the _AP data shape, and execute the AddColumn service, as described in the previous section. For this example, we continue with the custom Location property added to the PTC.SCA.SCO.JobOrder_AP data shape in the previous section.
2. Create a new data shape with field definitions from both the main entity data shape and the _AP data shape.
For this example, create a new data shape named MyJobOrder. Add field definitions for ID (from the PTC.SCA.SCO.JobOrder data shape) and Location (from the PTC.SCA.SCO.JobOrder_AP data shape).
3. Navigate to the PTC.SCA.SCO.ProductionOrderUtils thing.
4. Under Services, add a new service to create instances of the data shape created in step 2. For both the input and output parameters, use an infotable of the new data shape.
For this example, add a new service named CreateMyJobOrder, with an infotable of the MyJobOrder data shape for both the input and output parameters. In the service editor, enter code similar to the following:
var productionManagerThingName = Things["PTC.Factory.LaunchPointConfigurationThing"].GetProductionOrderManagerThingName();
var newJobOrders = Things[productionManagerThingName].CreateJobOrders({
JobOrders: myJobOrders
});

//Put new job orders in a new info table of MyJobOrder in order to filter the return attribute, this is not required.
var params = {
infoTableName : "InfoTable",
dataShapeName : "MyJobOrder"
};

var result = Resources["InfoTableFunctions"].CreateInfoTableFromDataShape(params);
var tableLength = newJobOrders.rows.length;
for (var x=0; x < tableLength; x++) {
var row = newJobOrders.rows[x];
result.AddRow(row);
}
5. Using the new service in a mashup results in creating new instances of the entity with the custom property present. In this example, using the CreateMyJobOrder service in a mashup results in new job orders being created with the ID property populated in the PTC.SCA.SCO.JobOrder database table, and the custom Location property populated in the PTC.SCA.SCO.JobOrder_AP database table.
Adding Custom Data Shapes
To add new entities to Operator Advisor, create a new data shape for the entity with the necessary services to manage instances of the data shape.
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.
3. Click Save to save the new data shape.
4. Navigate to the database thing configured for your system, for example, PTC.SCA.SCO.PostgresDatabase.
5. Under Services, execute the CreateTable service with the following inputs:
◦ For dataShapeName, search for and select the new data shape created in step 1.
◦ For dbInfo, enter a JSON array containing the database info for the 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—Name of the column. Required.
▪ unique—Specify if the column must have a unique value.
▪ 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.
▪ unique—Specify if the column must have a unique value.
▪ notNull—Specify if the column must not be null.
▪ 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.
For more information, see Adding or Removing 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
}
]
}
6. Navigate to the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
7. Under Services, click Add and create the necessary services to manage entities of the new data shape. Use the existing CRUD services for Operator Advisor entities as models.
◦ A create service. For this example, enter CreateMyObjects as the service name. In the service editor, enter the following code:
var insertParams = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Insert(insertParams);
◦ A delete service. For this example, enter DeleteMyObject as the service name. In the service editor, enter the following code:
var params = {
UID: UID,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Delete(params);
◦ An update service. For this example, enter UpdateMyObjects as the service name. In the service editor, enter the following code:
var params = {
infoTable: MyObjects,
dataShapeName: "MyObject"
};

var result = Things[me.GetDatabaseThingName()].Update(params);
◦ A service to retrieve an individual instance of this data shape. For this example, enter GetMyObject as the service name. In the service editor, enter the following code:
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. For this example, enter GetMyObjects as the service name. In the service editor, enter the following code:
var params = {
filter: filter,
dataShapeName: "MyObject",
offset: offset,
limit: limit
};

var result = Things[me.GetDatabaseThingName()].Query(params);
8. Click Save to save the new services on the default production order manager (PTC.SCA.SCO.DefaultProductionOrderManager).
Was this helpful?