Modeler to ThingWorx mapping
This topic explains how to map a Modeler UML model into ThingWorx.
Basic Mapping
Mapping a Project
A modeler package stereotyped with <<TWX Project>> maps to a ThingWorx Project.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX PackageVersion
|
Sets the “packageVersion” attribute in ThingWorx
Defaults to 0.0.0 when not set
|
1.5.2
|
Mapping Thing Shape, Thing Template, and Thing
A Modeler Class stereotyped with <<TWX ThingShape>> maps to a ThingWorx Thing Shape.
A Modeler Class stereotyped with <<TWX ThingTemplate>> maps to a ThingWorx Thing Template.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX BaseThingTemplateText
|
The base Thing Template of this Thing Template (when the Thing Template does not inherit from another modeled Template)
Defaults to GenericThing when there’s no inheritance and is left blank
|
“Wiki
“VirtualSwitch”
any other predefined ThingWorx Thing Template
|
A Modeler Class stereotyped with <<TWX Thing>> maps to a ThingWorx Thing.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX Id
|
Optional ThingWorx ID
|
MyThing001
|
|
TWX Active
|
Specifies whether the Thing is Active in ThingWorx
{TRUE or FALSE}, defaults to FALSE
|
Set to TRUE to activate in ThingWorx
|
|
TWX BaseThingTemplateText
|
The base Thing Template of this Thing (when the Thing does not inherit from a modeled Template)
Defaults to GenericThing when there is no inheritance and is left blank
|
“Wiki
“VirtualSwitch”
any other predefined ThingWorx Thing Template
|
Mapping Implemented Shapes and Base Thing Template
A modeler Realization Dependency between a <<TWX Thing>> or <<TWX ThingTemplate>> and a <<TWX ThingShape>> maps to a ThingWorx Implemented Shape for the (dependent) Thing or Thing Template.
A Modeler Generalization between a <<TWX Thing>> or a a <<TWX ThingTemplate>> and a a <<TWX ThingTemplate>> maps to a ThingWorx Base Thing Template for the (dependent) Thing or Thing Template.
Mapping Properties
A Modeler Attribute optionallystereotyped with <<TWX Property>> maps to a ThingWorx Property when defined on a <<TWX ThingShape>>, <<TWX ThingTemplate>>, <<TWX Thing>>.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX ReadOnly
|
Specifies if the Property is read only in ThingWorx
TRUE or FALSE, defaults to FALSE
|
Mapping Services
A Modeler Operation optionally stereotyped with <<TWX Service>> maps to a ThingWorx Service when defined on <<TWX ThingShape>>, <<TWX ThingTemplate>>, or <<TWX Thing>>.
The Service body can be set either in Modeler or in ThingWorx; when set in ThingWorx, the body appears within the generation markers to allow the code generator to reverse it into Modeler.
When a Modeler operation has a return type, it maps to a ThingWorx Service with the result variable defined for that type. When a Modeler operation has no return type, it maps to a ThingWorx Service without the result variable.
Services can be overridable and overridden. A server is overridable when its Binding property is set to At Runtime in Modeler, and there is no definition of the same service (by Name) in any of the implemented shapes and base templates. A service is overridden when its Binding property is set to At Runtime in Modeler, and there is a definition of the same service (by Name) in one of the implemented shapes or base templates.
The <<TWX Service>> stereotype allows to achieve better control on the Service.
Mapping Service Parameter
A Modeler Parameter optionally stereotyped with <<TWX Parameter>> maps to a ThingWorx Service Parameter.
The <<TWX Parameter>> stereotype allows to achieve better control on the Parameter.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX RelatedDataShape
|
When the parameter type is set to INFOTABLE, use this tag to specify the associated DataShape Modeler object
|
A reference to MyDataShape object
|
|
TWX RelatedDataShapeText
|
When the parameter type is set to INFOTABLE, use this tag to specify the name of an associated DataShape object that is in ThingWorx but not in the model
|
The name of a predefined ThingWorx DataShape
|
Mapping a Data Shape
A Modeler Class stereotyped with <<TWX DataShape>> maps to a ThingWorx Data Shape.
Mapping a Data Shape Field
A Modeler Attribute optionally stereotyped with <<TWX Field>> maps to a ThingWorx Field when defined on a <<TWX DataShape>>. The <<TWX Field>> stereotype allows to achieve better control on the Field.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX PrimaryKey
|
Specifies if the Field is the DataShape primary key in ThingWorx
TRUE or FALSE, defaults to FALSE
|
Mapping Events and Subscriptions
A Modeler Attribute stereotyped with <<TWX Event>> maps to a ThingWorx Event when defined on a <<TWX ThingShape>>, <<TWX ThingTemplate>>, or <<TWX Thing>>.
The Attribute is typed by the DataShape that the Event sends as data. The DataShape can be any of the following:
• A <<TWX DataShape defined in the model
• A DataShape defined only in the ThingWorx. In this case, the type of the attribute in the model is specified as text in the Modeler.
A Modeler Operation stereotyped with <<TWX Subscription>> maps to a ThingWorx subscription when defined on a <<TWX ThingShape>>, <<TWX ThingTemplate>>, or <<TWX Thing>>.
The operation has neither modeled parameters nor return type.
|
Tag Definition
|
Meaning
|
Example Value/Usage
|
|---|---|---|
|
TWX Source
|
Specify the associated Thing, when it is a Modeler object.
Leave it blank to subscribe a self-event
|
Reference to MySender
|
|
TWX SourceText
|
Specify the name of associated Thing, when it is an object in ThingWorx but not a Modeler object.
Leave it blank to subscribe a self-event
|
Timer1s, a Thing name of a ThingWorx (not Modeler) object
|
|
TWX SubscribedEvent
|
Specify the Event the subscription receives when it is a Modeler object
|
Reference to MyEvent
|
|
TWX SubscribedEventText
|
Specify the name of the Event the subscription receives, when it is an object in ThingWorx, but not a Modeler object
|
Timer, an event of a ThingWorx (not Modeler) object
|
|
TWX SubscribedProperty
|
Specify the Property whose change triggers the ThingWorx predefined DataChange event, and such property is defined in the model.
Leave blank when any event other than DataChange is subscribed by this Subscription
|
Reference to a Property defined in Modeler
|
|
TWX SubscribedPropertyText
|
Specify the Property whose change triggers the ThingWorx predefined DataChange event, and such property is not defined in the model.
Leave blank when any event other than DataChange is subscribed by this Subscription.
|
Name of a Property defined in ThingWorx but not in Modeler
|
|
TWX Active
|
Specifies whether the Subscription is Enabled in ThingWorx
TRUE or FALSE, defaults to FALSE
|
Set to TRUE to enable in ThingWorx
|
Composite Structure Mapping
Composite Structure mapping enables deployment of reusable sets of Things, connected together, sharing similar properties and behavior, without having to define the connections for each of them. Composite Structure mapping is based on the modeling capabilities offered by UML Composite Structures. Composite Structure mapping can be used in conjunction with the Basic Mapping.
Consider the Controller example below:
An example representation of a potential equivalent physical object:
The following diagram is Structure Diagram showing the same model. This diagram is built automatically from the model represented above; the class diagram shown above and the structure diagram shown below represent the same objects in two different ways. Each of the inner rectangular objects represents a part in UML.
UML can model the method objects communicate. This method is often called as the interface.
An interface represents a coordinated set of operations and signals that entities can exchange once they are connected. Conversely, if two entities support the same interface, they are interchangeable. Thus, several different Controllers (for example, PI, PID, Smith-predictor) can be connected with different keyboards (arrows only, arrows + function keys, hexadecimal) when all those controllers and those keyboards support the same interface. This helps in standardizing large arrays of entities that are designed to be compatible with each other.
Our example interfaces are intentionally limited:
In the above diagram, we define an IKbToCtrl interface that is able to receive signal SUpDown. This interface is the one used by the keyboard to communicate to the controller; in this example the keyboard can change the set point of the controller by sending an increment value (positive or negative).
We also define an IeCtrlToDisp interface that is able to change the value of a display. This interface is not based on a signal, rather it is based on an operation that an entity (the controller) can call another entity (the display) passing one or more parameters.
After defining the interfaces, we must apply those interfaces to the entities. To do this, we must:
• Define ports where interfaces are applied, and
• Define the direction of each applied interface
Ports represent attach points that can be connected with wires. Two ports can be connected if they support the same interface when it is clearly defined which entity sends the information and which entity receives it.
In the example below, we define ports, apply interfaces and specify their direction as shown:
A Required Interface is applied to a port, that is, that port can be connected with anything that provides the same interface. A Provided Interface is applied to a port, that is, that port can be connected with anything that requires that interface.
Therefore, in the example, the CtrlPort of the keyboard can be connected to the KbPort of the controller. Similarly, the DispActualPort and the DispSetPort of the controller can be connected to the CtrlPort of the displays. Note that the information on the diagram does not specify which display shows the set point, and which shows the actual measure, as the objects have not been connected.
The following diagram shows how the structure diagram looks after the objects are connected.
The above diagram shows the controller port designated to output the actual measure value is effectively connected to the actual measure display, rather than the set point display, and vice versa.
The above example provides an example for a reusable template for replicating the same switchboard multiple times. For example, if you need to control a temperature and its level separately, you may need two switchboards that are structurally identical, but have different parameters..
You can instantiate multiple switchboards with the help of a hierarchy object, like the following diagram:
In this example, the two compositions (the lines with the black diamond) instantiates the two switchboards, one intended for controlling the temperature, the other for its level. You can use the same hierarchy to instantiate multiple switchboards.
A hierarchy is not limited to instantiate only switchboards; it can instantiate any other object designed with the same process that you have designed the switchboard, for example, a “phase indicator”, “programmable logic controller”, or any other object modeled in terms of parts, interface and connections.
Mapping to ThingWorx
The above way of modeling leads to the following mapping to ThingWorx.
UML Parts are Things
The UML parts are mapped to ThingWorx Things. Each part generates a single Thing. The name of the Thing is the concatenation of the names of the owning hierarchy and all the nested parts ensuring the Thing names are unique.
UML Class (with Stereotype) are Thing, Shapes, Thing Templates
These mappings are described in the “Basic Mapping” section above.
Mapping UML Ports
A Port on a <<TWX ThingTemplate>> maps to an overridable service that returns the Thing name of the entity connected to the port. Note that the Thing name is known only when the Thing Template is instantiated into a Thing; this is why the service is overridable. The service is overridden on the instantiated Thing to return the relevant Thing name.
The name of the service is the name of the port prefixed with “_Get”.
Mapping UML Interfaces
A UML Interface on its own maps to nothing in ThingWorx. However, a UML interface required on a port (of a Thing Template) maps as follows:
Interface Operations
Each Operation on the interface generates a corresponding service in the Thing Template. The Thing Template user code should call this operation whenever the intent is to call the corresponding operation on the connected Thing.
The implementation of the service is autogenerated and automatically delegates the call to the operation on the connected Thing (whichever Thing will be actually connected in an actual design).
The name of the service is _<PortName>_<InterfaceOperationName>:
The user has to define UML operations (that is, a ThingWorx Services) with assigned name and compatible signature to reflect the actions to perform when the call is triggered:
Interface Signal Receptions
Each UML Signal Reception on the interface generates a corresponding Event in the Thing Template that requires the interface. The idea is that when the user code generates the Event, it is automatically transmitted to the Things connected on the other side of the link:
In turn, each UML Signal Reception on the interface generates a corresponding Subscription in the Thing that provides the interface. The idea is that when an event comes in on that particular Thing, the generated reception automatically transfers the event to user code at the receiving side:
The user has to define UML operations (that is, a ThingWorx Services) with assigned name and compatible signature to reflect the actions to perform when the event is received.
The operation name should be <PortName>_<SignalReceptionName>:
