Configuring KPI Calculation
KPIs and KPI elements are calculated for equipment during scheduled shifts. For KPI elements and KPIs to be calculated, perform the following configurations:
2. On each piece of equipment for which KPIs are to be calculated:
 |
As a best practice, configure KPI calculation before configuring the statuses for the equipment. KPI calculation for a piece of equipment begins once the equipment status is no longer Not Configured. If KPIs are calculated for a piece of equipment before the KPI elements are defined, the KPIs are calculated without meaningful data.
|
 |
By default, ThingWorx Apps supports calculating KPIs for up to 500 equipment things. If this limit is exceeded, then the list of all equipment things that are configured for KPI calculation is sorted alphabetically by name. The first 500 are then selected for KPI calculation.
This limit can be changed by overriding the GetKPIElementsFromTimeInfo service on the default KPI manager (PTC.SCA.SCO.DefaultKPIManager), and changing the MAX_ITEMS value. Increasing this value can have a negative impact on performance.
|
Defining Sites, Shift Schedules, and Shifts
Shifts are grouped in shift schedules. Each site (factory or other facility) can have multiple shift schedules. The time zone applicable for the start and end times of a shift is defined on the site.
Shift schedules can be created for multiple purposes. For example, individual shift schedules can be defined for weekday, weekend, and holiday shifts. If certain equipment runs 24 hours a day, create a shift schedule with a single 24-hour shift.
|
|
Within a shift schedule, do not overlap shifts. The end time of one shift and the start time of another shift can be the same value without overlapping. For example, Shift1 can end at 18:00 and Shift2 can start at 18:00 without overlapping. If Shift2 instead starts at 17:45, then Shift1 and Shift2 overlap. The system does not prevent creation of overlapping shifts. If the current time falls within multiple shifts, the KPI calculation services querying for the current shift return only the first shift encountered.
|
Sites, shift schedules, and shifts are all created from the shift manager thing (PTC.SCA.SCO.DefaultShiftManager) in ThingWorx Composer, using services found on the Services page.
1. Create one or more sites by executing the CreateSites service.
a. On the Inputs pane, click Sites to open the Sites input table.
b. From the Sites input table, click Add, and enter the information for each site. While ID, Name, and Description are all optional, at least one of these fields must be populated for the site to be created.
▪ UID—The unique internal identifier for the site. This value is autogenerated when the site is created.
▪ ID—An identifier for the site. This value could be an identifier used in an external system.
▪ Name—Name for the site. For example, Montreal, or West Campus.
▪ Description—Additional information for the site.
▪ TimeZone—The time zone applicable for the site, specified as an offset from the UTC (Coordinated Universal Time). Valid values are specified as plus or minus HH:mm, between -12:00 and +14:00, with the :mm portion of the value equal to :00, :30, or :45. For example, for the Eastern Time Zone, specify -04:00; for India Standard Time, specify +5:30.
|
|
• As a best practice, specify the time zone for each site. If no time zone is specified for the site, then the time zone set on the ThingWorx server is assumed.
• The TimeZone field does not adjust for Daylight Savings Time. To manually adjust for Daylight Savings Time, edit the TimeZone value for the site to the appropriate UTC offset for the site location.
|
c. Click Save to save the input table.
d. Click Execute. The service output displays the sites created, including their UIDs. Note the UID for each site, to specify on the shift schedules associated with each site.
e. Click Done.
2. Create one or more shift schedules by executing the CreateShiftSchedules service. Each site can have multiple shift schedules associated with it, but each shift schedule can be associated with only one site.
a. On the Inputs pane, click ShiftSchedules to open the ShiftSchedules input table.
b. From the ShiftSchedules input table, click Add, and enter the information for each shift schedule. While ID, Name, and Description are all optional, at least one of these fields must be populated for the shift schedule to be created.
▪ UID—The unique internal identifier for the shift schedule. This value is autogenerated when the shift schedule is created.
▪ ID—An identifier for the shift schedule. This value could be an identifier used in an external system.
▪ Name—Name for the shift schedule. For example, Weekdays, Weekend, or Holiday.
▪ Description—Additional information for the site.
▪ SiteUID—The UID of the site with which this shift schedule is associated. The shift schedule must be associated with a site for the site’s time zone to be applicable for shifts in the shift schedule.
c. Click Save to save the input table.
d. Click Execute. The service output displays the shift schedules created, including their UIDs. Note the UID for each shift schedule, to specify on the shifts associated with each shift schedule.
e. Click Done.
3. Create one or more shifts by executing the CreateShifts service.
a. On the Inputs pane, click Shifts to open the Shifts input table.
b. From the Shifts input table, click Add, and enter the information for each shift. For calculating KPIs, the StartTime and EndTime fields are required.
▪ UID—The unique internal identifier for the shift. Autogenerated.
▪ ID—An identifier for the shift schedule. This value could be an identifier used in an external system. Optional.
▪ Name—Name for the shift. For example, Morning, 9 to 5, or Overnight. Optional.
▪ Description—Additional information for the shift. Optional.
▪ StartTime—The start time for the shift. Valid values are specified in the format HH:mm, between 00:00 and 24:00. Required for KPI calculation.
▪ EndTime—The end time for the shift. Valid values are specified in the format HH:mm, between 00:00 and 24:00. Required for KPI calculation.
▪ ShiftScheduleUID—The UID of the shift schedule with which this shift is associated. If no ShiftScheduleUID is specified, the shift is assumed to be in the "default" shift schedule. As the "default" shift schedule is not associated with a site, the time zone set on the ThingWorx server is assumed.
|
|
The SiteUID and Category fields are not currently used.
|
c. Click Save to save the input table.
d. Click Execute. The service output displays the shifts created, including their UIDs.
e. Click Done.
Associating Equipment to Shift Schedules
Associate each piece of equipment for which KPIs are to be calculated with a shift schedule.
1. In ThingWorx Composer, navigate to the thing representing the piece of equipment , for example Asset_Asset1.
2. Under Properties and Alerts, search for the ShiftScheduleUID property.
3. Click Set value, and enter the UID of the shift schedule applicable for this piece of equipment.
4. Click 
.
.5. Click Save to save the piece of equipment.
| | If no ShiftScheduleUID is specified on a piece of equipment, the system assumes that the equipment is using the "default" shift schedule. As a best practice, always associate equipment for which KPIs are to be calculated with a shift schedule. |
Defining KPI Elements for Equipment
On each piece of equipment for which KPIs are to be calculated, define the following KPI elements:
• PRI (planned run time per item)
• PQ (produced quantity)
• GQ (good quantity)
For more information on the KPI elements and how they are used in KPI calculation, see Calculating KPIs.
1. In ThingWorx Apps, on the Equipment tab of Configuration and Setup, click the name of the piece of equipment to open the configuration pages.
2. In the configuration menu, click Additional Properties.
3. From the list of additional properties, select the plannedRunTimePerItem_PRI property, and click 
.
.4. Specify a static value for the property if appropriate.
OR
Change the type of the property from Static to Bound, and bind the property to a connected server tag. For example, bind the property to a KEPServerEX tag associated with a sensor on the physical piece of equipment.
For more information, see Additional Properties.
5. Click OK.
6. Repeat steps 3 through 5 for the producedQuantity_PQ and goodQuantity_GQ properties.