Customizing Equipment Status Evaluation
 |
This customization is applicable only for systems using the scheduler-based status calculation. It is not applicable for systems which have enabled subscription-based status calculation.
|
To determine the state of a piece of equipment, the system evaluates the status expressions defined on the Status page for the equipment in > . The expressions are evaluated in the order in which they appear in the Define Status table. The first expression to evaluate to true determines the state of the equipment.
The status expressions defined on each piece of equipment are the sole source of information used for evaluating the equipment state. The Thing Template for each equipment type with status implements the PTC.SCA.SCO.StatusThingShape. This Thing Shape, in turn, calls the status evaluation logic that is implemented by the CalculateStatus service on the PTC.Factory.StatusExpressionUtils Thing. Each equipment type Thing Template and equipment Thing inherits the CalculateStatus service from the PTC.SCA.SCO.StatusThingShape. This service evaluates the status expressions defined on the equipment’s Status page in > . For more information, see Specifying Status Expressions.
You can override the CalculateStatus service on a custom Thing Template or individual Thing to implement your own status evaluation logic. If you are overriding the CalculateStatus service, keep the following in mind:
• The result of any customization for CalculateStatus must be set to the result variable and must be an integer.
• If the customization does not involve the thingId and item input parameters, you can reconstruct these by using the following code:
var thingId = thingId;
var item = Things["PTC.Factory.StatusExpressionResourceProvider"].GetById({id:thingId});
var item = Things["PTC.Factory.StatusExpressionResourceProvider"].GetById({id:thingId});
• Customizations on one custom Thing Template are independent of customizations on any other Thing Template.
• Customizations for individual pieces of equipment are independent of each other. A customization on an individual piece of equipment (Thing) takes priority over any customization on the Thing Template for that equipment type.
• If the custom code used to override the CalculateStatus service explicitly uses property tags, the custom code needs to address checking data quality, if desired.
Detecting Bad Quality Data in Custom Code
If the custom code used to override the CalculateStatus service explicitly uses property tags, and you want data quality to be checked, your code needs to address this.
The IS_DATA_OK function that is used in status expressions can also be used to detect bad quality data in custom code. The function calls the GetPropertyQuality service which checks the quality of the data. This service is available on every Thing entity, inherited from the GenericThing Thing Template. This service takes a propertyName string as its only parameter, and returns one of the following string values:
• UNKNOWN
• GOOD
• BAD
• OUT_OF_RANGE
• UNVERIFIED_SOURCE
To be used in the GetPropertyQuality service, the propertyName must satisfy two conditions:
• The property must either exist on the Thing being used to execute the service, or be a remote property that is remotely bound to the Thing being used to execute the service.
• The property name must contain no dots, only double dashes, for example Channel1--DryingMachine--Status. If the property name contains dots, your custom code must address this, as shown in the following example.
In most cases, a property tag is composed of two portions, the source Thing portion and the property portion, separated by a colon (:).
The property portion must be extracted from the property tag string, and then be used in the execution of the GetPropertyQuality service. Both portions are required to implement bad quality data detection when customizing the CalculateStatus service.
Implementation Example
The following code is an example of custom JavaScript code using the GetPropertyQuality service to detect bad quality data on a specific tag.
| | The code example converts the property name, which uses dots, to use double dashes, as required by the GetPropertyQuality service. |
// The property tag to be tested for bad quality data. This tag hypothetically
// points to some value on some server
var propertyTag = "PTC.SCA.SCO.Demo.KepServer:CheeseCake.Fryer.Status";
// Split the property tag into 2 portions:
// 1. The source thing portion
// 2. The property portion
var splitResult = propertyTag.split(":");
var sourceThingName = splitResult[0]; // The source thing portion
var propertyName = splitResult[1]; // The property portion
var sourceThing = Things[sourceThingName]; // Get the source thing that has the property
// Convert the property name to a Thingworx friendly name
var propertyName_friendly = propertyName.replace(/\./g, "--");
var statusEvaluationResult;
if (sourceThing !== null) {
params = {
propertyName: propertyName_friendlyc f /* STRING */
};
var quality = sourceThing.GetPropertyQuality(params); // Calling the service (API) to check the quality
// Here do some processing according to the result of the quality check
if (quality === "GOOD") {
// Set a certain status when the quality is GOOD
statusEvaluationResult = 2; // Status "2" = "Running"
} else if (quality === "BAD") {
// Set a certain status when the quality is BAD
statusEvaluationResult = 4; // Status "4" = "Unplanned Downtime"
} else {
// Set a certain status when the quality is anything other that GOOD or BAD (i.e. UNKNOWN, OUT_OF_RANGE, UNVERIFIED_SOURCE)
statusEvaluationResult = 5; // Status "5" = "Unavailable"
}
}
result = statusEvaluationResult;
// points to some value on some server
var propertyTag = "PTC.SCA.SCO.Demo.KepServer:CheeseCake.Fryer.Status";
// Split the property tag into 2 portions:
// 1. The source thing portion
// 2. The property portion
var splitResult = propertyTag.split(":");
var sourceThingName = splitResult[0]; // The source thing portion
var propertyName = splitResult[1]; // The property portion
var sourceThing = Things[sourceThingName]; // Get the source thing that has the property
// Convert the property name to a Thingworx friendly name
var propertyName_friendly = propertyName.replace(/\./g, "--");
var statusEvaluationResult;
if (sourceThing !== null) {
params = {
propertyName: propertyName_friendlyc f /* STRING */
};
var quality = sourceThing.GetPropertyQuality(params); // Calling the service (API) to check the quality
// Here do some processing according to the result of the quality check
if (quality === "GOOD") {
// Set a certain status when the quality is GOOD
statusEvaluationResult = 2; // Status "2" = "Running"
} else if (quality === "BAD") {
// Set a certain status when the quality is BAD
statusEvaluationResult = 4; // Status "4" = "Unplanned Downtime"
} else {
// Set a certain status when the quality is anything other that GOOD or BAD (i.e. UNKNOWN, OUT_OF_RANGE, UNVERIFIED_SOURCE)
statusEvaluationResult = 5; // Status "5" = "Unavailable"
}
}
result = statusEvaluationResult;