Appendix A

This appendix describes the property and service functionality of the ThingWorx entities and is broken down in to:

Templates

OSIPI.OSIBaseTemplate

This template is used by the CreateThingsFromTopLevelAFElement and CreateThingTemplateFromAFTemplate services in the OSIPITemplate to create Things and Thing Templates matching the PI-AF element hierarchy. Every Thing or ThingTemplate created by those services are created from this Template. This template maintains important cross reference details between ThingWorx and PI-AF.

This template gives the following functionality:

Properties

Property Name	Description
Database	This property is the reference to the AF database.
Category	This property corresponds to the category for an element in AF.
UniqueId	The element in the asset framework is identified by a unique ID (GUID). This id is needed in various calls in the API.
OSIPIThingName	This is a reference back to the OSIPI thing that created this Thing. Needed for the services contained in this Thing to know which PI server to call.

Services

Service Name

Description

GetHistoricalData

This service retrieves the values for the PI point that is held by the target AF attribute.

Values are retrieved for the designated time period and interval.

Data is retrieved as a ThingWorx DataTable.

SavePropertyToPI

This service updates the value of the target AF attribute on the AF server with the passed in value.

OSIPITemplate

This is the basis for connectivity between ThingWorx and AF.

It defines all of the properties and services necessary to connect to the PI Data Archive and PI Asset Framework Server and retrieve these data into ThingWorx. This is achieved by wrapping the OSIsoft AF SDK with the ThingWorx .NET SDK so communication can flow between the two platforms.

This template is a remote thing template for communication with the PI system.

This template uses the OSIPI.OSIBaseTemplate.

This template gives the following functionality:

Properties

Property Name	Description
AFTimestampCalculation	AFTimestampCalculation defines the timestamp returned for a value when a summary calculation is done. Available values are described as default values.
AFSummaryTypes	AFSummaryTypes are flags to indicate which summary type calculation(s) should be performed. Available values are described as default values.
AFCalculationBasis	AFCalculationBasis defines the possible calculation options when performing summary calculations over time-series data. Available values are described as default values.
CalculationTypes	CalculationTypes define the possible calculations to be performed. PI has the ability to give raw data, interpolated data and plot data. Available values are described as default values.
WatchListOfPoints	This property is used by the OSIPI.HistoricalTagViewer mashup to only show a subset of PI points that a user wants to see. The addition and removal of points from this property all occur in this mashup. It provides a list of selected tags for all users of this mashup and does not filter by user specific selections.
PIPointType	PIPointType defines the types for PI points that are allowed in the data archive. Available values are described as default values.

Services

Service Name	Description
AddElementsForSubscription	This service enables the user to set the AF SDK to listen for attribute changes in the element referenced in the input parameter. The configuration property AFAttributeScanRate defined in the OSIPIConnector.config file sets the update frequency. The AF SDK will capture all data changes between polling intervals and send the entire set of changes to ThingWorx via the UpdatedAttributeValue event.
AddPIPointsForSubscription	This service enables the user to set the AF SDK to listen for PIPoint data changes in the PI point referenced in the input parameter. The configuration property called AFAttributeScanRate defined in the OSIPIConnector.config file sets the update frequency. The AF SDK will capture all data changes between polling intervals and update the property on this Thing that relates to the PIPoint.
AddPointToWatchList	This service is used with the OSIPI.HistoricalTagViewer mashup to allow a user to add PI points to a listing of PI points defined in property WatchListOfPoints. This mashup can be used as a basis for project integration.
AddPropertyFromPIPoint	This service will create a property that is remotely bound to the corresponding PIPoint. ThingWorx property names cannot have certain characters, thus any special characters in the PI point name will be replaced with an underscore.
BrowseSubscribedPIPoints	This service allows the user to browse PI points that have already been subscribed to via the AddPIPointsForSubscription service.
ClearAFCache	To purge unsubscribed elements and PI points, the remote AF cache can be cleared.
CreateAttributeFromPIPoint	This service allows the user to create a new attribute on an existing Asset Framework element that is referencing an existing PI point, together with its UoM.
CreatePIPoint	This service will create a new PI point on the target PI server of the default point class of ‘classic’. These are designed to be PI interface points but can be used to store data from any source.
CreateThing	This is a standard service for creating a new Thing in ThingWorx based on a ThingTemplate.
CreateThingsFromTopLevelAFElement	This service will create: A Thing for every Element in the hierarchy. A matching property for every attribute defined in each element. A network to describe the relationships of all of the Things that match the AF hierarchy. The database parameter defines which AF database you are working with and the TopLevelElementName parameter contains the element name at the first level of the AF hierarchy. This must be from the first level to work properly. Once this is called, all elements in the contained element hierarchy will be created as Things to match this model. In addition, a Network will be created that relates all of the Things in the same hierarchical configuration. It will create these Things from ThingTemplates created using the CreateThingTemplateFromAFTemplate service. Any additional attributes that have been added specifically to each unique element will also be added as properties to the Thing.
CreateThingTemplateFromAFTemplate	This service will create ThingTemplates based on the AFTemplateName parameter passed in. It will create an OSIPI.OSIBaseTemplate with properties matching the attribute names defined in the Element Template.
GetAFElements	This service retrieves all elements from the Asset Framework database specified in the input parameter. If the user wishes to return the top level element, there is a filter parameter provided. If all that is required is to return the top level elements from the passed in database string, then a filter parameter is available. The database field is required.
GetAFElementTemplates	This service retrieves all element templates from the Asset Framework database specified in the input parameter. If the user wishes to return a specific Element Template, an input parameter is required. The database field is required.
GetDatabases	This service retrieves a list of AF databases hosted on the target AF server.
GetDataByCalculationType	This service allows the user to retrieve historical data from the PI Server historian by specifying all of the points to be retrieved with their calculation type over a given time range. The calculation type field contained in the infotable input parameter called pointList, corresponds to the property called CalculationTypes which contains the enumeration that is possible for this field. pointList can contain many PI points all with different calculation types based on the need. An example, use of this service is in the OSIPI.HistoricalTagViewer mashup which can dynamically select more than one PI point with different calculation types passed into this service.
GetDataOverviewByCalculationType	This service is used by the OSIPI.HistoricalTagViewer to provide an overview trend that has an expanded time range from what is being shown. This service adds extra vertical bars at the time range that is being shown on the main trend chart.
GetInterpolatedValuesByPointName	This service allows you to retrieve interpolated data based on a start and end date. It returns the exact number of values based on the numberOfValues field.
GetPIPoints	This service will return PI points based on the query parameter. For wildcard searches, use the ‘*’ although this will return a greater amount of results and may potentially time out. If loadAttributes is true, all of the tag attributes will also be returned. This can also cause a performance hit.
GetPlotValuesByElementAttributeName	This service allows the user to retrieve plot value data based on a start and end date for an attribute name (attributeNames are stored in the description field for properties with a category of OSI Attributes). The elementUniqueID is also needed and stored as a property on the Thing called UniqueID. Intervals is used by the PlotValues call to determine how much data should be returned. This service is intended to be used with AF to be able to look up historical data based on an element and attribute. Services CreateThingsFromTopLevelAFElement and CreateThingTemplateFromAFTemplate will generate the linkage between AF and ThingWorx providing a Thing for every element and a ThingTemplate for every Element Template. Cross references are provided in terms of the properties and descriptions indicated above.
GetPlotValuesByPointName	This service allows the user to retrieve plot value data based on a start and end date for a point name. Intervals is used by the PlotValues call to determine how much data should be returned.
GetRecordedValuesByPointName	This service allows the user to retrieve recorded values based on a start and end date for a point name. MaxCount is used by the service call to determine the maximum amount of data that should be returned.
GetTimeFromSelector	This is a helper service for the mashup viewer.
InitializeSessionVariables	This is a helper service for the mashup viewer.
RemovePIPointsFromSubscription	This service enables the user to unsubscribe to PI point data changes in the PI point referenced in the input parameter.
RemovePointFromWatchList	This service is used with the OSIPI.HistoricalTagViewer mashup to allow a user to remove PI points from a listing of PI points defined in property WatchListOfPoints.
UpdateAttributeValue	This service allows the caller to set an attribute in the AF element passed into the call. AttributeNames are stored in the description field for properties with a category of OSI Attributes. The elementUniqueID is also needed and stored as a property on the Thing that references an element called UniqueID. Since the attribute could be a string, number or date, the user is required to pass the value in the appropriate parameter for the attribute type.
UpdatePropertyValuesFromAFAttributes	Upon a thing restart subscribed updates may have been missed. This service will get all the current values for the attributes and update them accordingly. It is called only on ThingStart.

Things and ThingShapes

Upon initial import of the OSISoftEntities.twx package, one initial Thing is created: OSIPIThing.

This thing is based on the Thing Template OSIPITemplate.

This thing exposes a single test service TestPointsByCalcType and utilises the test PI points ‘Sinusoid’ and ‘CDT158’.

Thing Shapes are utilised in the functionality of the templates described above to store a collection of related parameters and values.

SessionsVars

This Thing Shape is used to store user session parameters:

previousTimeframe.
newTimeframe.
previousBackwardButton.
newBackwardButton.
previousForwardButton.
newForwardButton.

Data Shapes

The following data shapes are available.

DateRange

Field Name

Description

StartDate

Datetime.

Stores the period start date.

EndDate

Datetime.

Stores the period end date.

PIPoints

Field Name	Description
createDate	Datetime. Stores the creation date.
Descriptor	String. Stores the PI point descriptor attribute.
extendedDescriptor	String. Stores the PI point extended descriptor attribute.
pointID	String. Stores the unique PI point ID.
pointName	String. Stores the tag of the PI point.
pointType	String. Stores the type of PI point.

PIPointsByCalculation

Field Name	Description
calculationType	String. Stores the method of data manipulation.
Forward	String. Stores the direction of data retrieval.
intervalCounterOrNumber	Number. Stores the number of values to retrieve or the interpolation interval.
pointName	String. Stores the target PI point name.

PointDefinition

Field Name

Description

pointName

String.

Stores the target PI point name.

pointType

String.

Stores the type of PI point.

AFAttributeUpdateEvent

Field Name	Description
attrName	String. Stores the target AF attribute name.
attrType	String. Stores the target AF attribute type.
elemName	String. Stores the target AF element name.
value	String. Stores the value to be updated.

AFDatabase

Field Name

Description

databaseName

String.

Stores the target AF database name.

AFElementTemplates

Field Name	Description
attributes	InfoTable. Stores an OSIPI.AFAttributes DataShape.
Category	String. Stores the AF category of the template.
Description	String. Stores the AF template description.
Name	String. Stores the AF template name.

AFElementsForSubscription

Field Name	Description
Database	String. Stores the target AF database name.
Name	String. Stores the name of the target AF element.
uniqueId	String. Stores the GUID of the target AF element.

AFAttributes

Field Name	Description
name	String. Stores the AF attribute name.
description	String. Stores the AF attribute description.
category	String. Stores the AF attribute category.
valueType	String. Stores the AF attribute value type.
uom	String. Stores the AF attribute unit of measurement.
value	String. Stores the value of the AF attribute.

AFElements

Field Name	Description
attributes	InfoTable. Stores an OSIPI.AFAttributes DataShape.
name	String. Stores the AF element name.
category	String. Stores the AF element category.
database	String. Stores the target AF database name.
description	String. Stores the AF element description.
parent	String. Stores the AF element’s parent element name.
template	String. Stores the AF element’s base template name.
uniqueId	String. Stores the GUID of the target AF element.

AFValue

Field Name

Description

timestamp

Datetime.

Stores the timestamp.

value

String.

Stores the value.

EnumDS

Field Name

Description

enumValue

String.

Stores the current value.

PIPointItems

Field Name	Description
BaseType	String. Stores the PI point type.
name	String. Stores the ThingWorx friendly PI point name.
Source	String. Stores the name of the PI point.
sourceType	String. Stores the PI point data type.

MultiPointAFValue

Field Name	Description
pointName1		String. Stores the PI point name.
pointName2		String. Stores the PI point name.
pointName3		String. Stores the PI point name.
pointName4		String. Stores the PI point name.
pointName5		String. Stores the PI point name.
pointName6		String. Stores the PI point name.
pointName7		String. Stores the PI point name.
pointName8		String. Stores the PI point name.
value1		String. Stores the PI point value.
Value2		String. Stores the PI point value.
Value3		String. Stores the PI point value.
Value4		String. Stores the PI point value.
Value5		String. Stores the PI point value.
Value6		String. Stores the PI point value.
Value7		String. Stores the PI point value.
Value8		String. Stores the PI point value.