This topic explains how to map a Modeler UML model into ThingWorx.

A modeler package stereotyped with <<TWX Project>> maps to a ThingWorx Project.

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.

A Modeler Class stereotyped with <<TWX Thing>> maps to a ThingWorx Thing.

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.

A Modeler Attribute optionallystereotyped with <<TWX Property>> maps to a ThingWorx Property when defined on a <<TWX ThingShape>>, <<TWX ThingTemplate>>, <<TWX Thing>>.

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.

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.

A Modeler Class stereotyped with <<TWX DataShape>> maps to a ThingWorx Data Shape.

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.

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 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.

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:

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.

The above way of modeling leads to the following mapping to ThingWorx.

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.

These mappings are described in the “Basic Mapping” section above.

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”.

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: