Services
In the ThingWorx environment, all Things have services (functions) and property values. Property values are manipulated through service calls. There are generic services for all Things, such as GetPropertyValues(), GetStringPropertyValue(), and SetPropertyValues(). These services are provided automatically on all Things that are based on one of the RemoteThing Thing Templates and provide the basic functionality needed to manage and manipulate properties.
There are two kinds of services:
• "Local" services that execute on the Thing on the ThingWorx Platform. The list of Inherited Services for the Thing are examples of "Local" services.
• "Remote" services that execute on your device. A service that you have written in your application and added to the Thing that represents it in ThingWorx Composer is an example of a "Remote" service.
Both types of services are invoked in the same way, but only custom remove services need to be registered on the edge (within your application).
A VirtualThing can define services and make those services available to be executed from the ThingWorx Platform. Since the AlwaysOn connection enables bi-directional communication, the ThingWorx Platform can invoke these services on demand.
Defining a Service on a VirtualThing
A service on a VirtualThing is simply a method with the proper ThingWorx annotation applied to it. For example, take a simple method that adds two numbers:
public Double Add(Double p1, Double p2) throws Exception {
return p1 + p2;
}
Using annotations, you can expose this method as a remote service. The annotation includes the name of the ThingWorx Platform, the name and base types for the parameters of the service, and the base type of the result.
// The following annotation allows you to make a method available to the
// ThingWorx Platform for remote invocation. The annotation incluides the
// name of the server, the name and base types for its parameters, and
// the base type of its result.
@ThingworxServiceDefinition(name="Add", description="Add two numbers")
@ThingworxServiceResult(name="result", description="The sum", baseType="NUMBER")
public Double Add(
@ThingworxServiceParameter(name="p1", description="First param", baseType="NUMBER" ) Double p1,
@ThingworxServiceParameter(name="p2", description="Second param", baseType="NUMBER" ) Double p2)
throws Exception {
return p1 + p2;
}
 |
If your VirtualThing uses annotations to define properties, services, or events, call VirtualThing.initializeFromAnnotations() in your constructor (shown below). If you do not call this method, the annotations are NOT applied to your Thing.
public SimpleThing_1(String name, String description, ConnectedThingClient client) { super(name, description, client); super.initializeFromAnnotations(); } |
Once your application is ready to run, you can verify that it connects and binds to the ThingWorx Platform by following these steps:
1. Log in to ThingWorx Composer. If you have not created a Remote Thing on the platform for your application, create it now, using one of the RemoteThing Thing Templates, using the name, SimpleThing_1, If you have created this Thing, navigate to it.
2. Display the Properties page for the Thing. If the value of the isConnected property is set to true, the connection was successful.
3. If you added a service to your application, display the Services page and follow these steps:
a. At the top of the Services page, select Browse Remote Services. Under Available Services, locate the name of the service you registered in your application.
b. Click the arrow to the right of the service name to place it in the list of services to be added to SimpleThing_1.
c. Select Create Services. Your service now appears in the list of services for SimpleThing_1.
d. At the top of the screen, click Save to save the change.
e. Click Save. You can now test the service.
f. Click Test.
g. If your service takes inputs, supply the values when prompted.
h. Click Execute Service. This action causes the ThingWorx Platform to send a message, over the AlwaysOn connection, to the VirtualThing in the client application. The SDK then invokes the service and returns a result.
|
|
If the service fails, make sure you saved Simple1 after adding the new service.
|
4. From ThingWorx Composer, verify the result of the service.
Using this mechanism, the remote application can expose complex functionality to the ThingWorx Platform. In addition, the ThingWorx Platform can invoke these services based on user input, system events, property changes, or calls from its other services.
 |
Use the same steps to define services for an EdgeThingShape. Refer to Defining Services for an ETS.
|