Thing Services
Thing services are functions that a Thing can perform. Each Thing can have one or more services. You can define services at the Thing Shape, Thing Template, or Thing level. A simple example of a service is a query written for a database Thing.
There are several implementation methods, or handlers, for services depending on the template you use. Script, SQL Query, and SQL command are examples of handlers. Additional handlers may be available depending on the specific functionality of a Thing, such as edge Things.
The specific implementation of a user-defined service is done via a server side script (currently through SQL or JavaScript). The service can then be invoked through a URL, a REST client capable application, or by another service in ThingWorx.
When you create a new service, you can define input properties and an output. Inputs and outputs can be any of the standard ThingWorx data types. Each service can also have individual run time permissions defined in the service definition. A service is not required to have inputs or outputs, but usually there is one or both. For example, if you want to send a delivery schedule to a truck, the truck Thing may have a service with an input named DeliverySchedule and a type of XML. The service could take the incoming data and put a Thing property of the truck into a Data Table.
If you want to send the output directly to a mashup widget, you should choose an output of type INFOTABLE. If you choose to output an infotable, you will need to select a Data Shape. The Data Shape tells the application which columns and data types will be returned so it can render the data. You can choose any number of inputs based on your requirements. For example, your output could be a SQL query against a database that returns data to a mashup. The service is automatically part of the REST API of the ThingWorx application server (the same as all definitions within your model). You can use the service through a REST call from another application or in a mashup.
When calling a service, if you define the output as an infotable, you can ask for the result set as HTML, JSON, or XML using a URL call and the Accept URL parameter (for more information, see REST API). Because of this flexibility, and the ability for the mashup environment to be able to easily consume an infotable, it is recommended that you use this format as the default design pattern. Specific needs, such as an XML schema output, can be addressed as required.
Once you have defined your script function interface, you can implement the service by clicking the Handler column for the service. This will bring you to the service implementation editor. In the implementation editor, you choose the handler (SQLQuery or Script). SQLQuery is only available for a database entity. The Script implementation is a server-side Java Script engine.
With SQLQuery, you simply write a query in the syntax you would normally use for the source database. You can use service inputs as parameters in the query like you would with prepared statements. If your output property is an infotable, you don't need to manipulate the results. The query result will appear in the infotable and will be available as output.
The script handler is a powerful way to use all the data, Things, and services on the server to meet the needs of your application. You can perform calculations and lookups, call services, or access properties from other things in the model. Once you select script as the handler, you will be presented with a number of script helpers. You can see the inputs for the script, properties, services, and events of the Thing you are currently editing, which can be pasted into the script window with a double click. You can also browse the properties, services, and events of any other entity in your system. You can combine all the model capabilities within your service.
If the script is called from a web page or URL, it will run in the context of the logged-in user. If the user does not have access to the run time services, properties, or events of any entity in the script, the script may fail.
The script implementation editor also has syntax helpers and code snippets to make the creation of a script easier.
By default the script timeout setting on the ThingWorx platform is 30 seconds. If a script runs longer than this, the platform terminates the execution. A ThingWorx administrator can configure the script timeout in the basic settings section of the platform-settings.json file.
Asynchronous Services
Asynchronous services will create and execute in their own thread. They cannot have a return value because when you run them, the thread is created and runs independently on the platform. If called from within another service, the calling service will not wait for the async service to complete. This can be very useful for long running services, especially ones on timers that update background data structure or perform system maintenance tasks.
If async is chosen in the New Service editor, the option to Queue Calls is displayed. This option is for remotely bound services that will queue the service executions if the Remote Thing is not connected. ThingWorx will queue each attempt at service execution and then execute them in order when the Remote Thing becomes connected again.
Statistics for Services
The Utilization Subsystem collects metrics for JavaScript services that are terminated due to a timeout. For details, see Statistics on Script Execution Terminated Due to Timeout .