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 base 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 opens 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, write a query in the syntax you 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 appears in the infotable and is available as output.
It is not a good practice to use a string in '--[[]]' and '[[]]' format in a SQL query for a Database Thing. Instead, if you want to use a string in the SQL query service, insert that string in the Input variable and then pass that value in the SQL.
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, You can paste these inputs 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 runs 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, 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 create and execute in their own thread. Asynchronous services 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 the ones on timers that update the background data structure or perform system maintenance tasks.
If you choose async in the New Service editor, the Queue Calls option appears. This option is for remotely bound services that queues the service executions if the Remote Thing is not connected. ThingWorx queues each attempt at service execution, and then executes them in order when the Remote Thing is 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 .
Executing Services from Thing Templates and Thing Shapes
In ThingWorx 9.3 and later, you can execute services from Thing Templates and Thing Shapes. In these cases, you may need to specify an implemented Thing to execute the service from. In the Execute tab, in the Implementing Thing field, select a Thing.
Was this helpful?