Thingworx Coding Best Practices!!!

Hi, 

I see this is an identical question that was already asked and answered here https://community.ptc.com/t5/ThingWorx-Developers/Thingworx-Coding-Best-Practices/td-p/613294

so I will add on top of that.

We have a section that helps, at page 70 from the Application Development Guide that is available here https://www.ptc.com/en/support/refdoc/ThingWorx_Platform/8.3/thingworx_application_development_guide

In addition to that, I'm pasting below some service coding recommendations that I created over the years.

Executing custom services might sometimes generate unexpected results and it is therefore important to understand how to develop them and how to test them before applying the changes to production. Moreover, to emphasise this, when testing a service in the Composer, the platform warns the user: “Please be careful. Only execute services and queries where you understand the impacts.”
This is because the custom JavaScript code that you’re writing is executed server-side and some errors in the code can introduce unexpected behavior of the platform if not handled properly.

To facilitate the development of custom services, ThingWorx provides a lot of snippets which are portions of code that the developer can re-use. Furthermore, the developer can access other services (wrapped services) from all the entities on the platform. More information about how a specific snippet can be used can be found in the Composer, by hovering on a specific snippet.

Some recommendations can be considered when developing custom services:
• First think about what you want your service to do and based on that, add a meaningful service name, as well as input parameters (0-n) and a result (0 or 1).
• In the script area, try to re-use as many of the already available snippets as possible in order to simplify code writing and avoid possible mistakes by using the snippets as a template;
• If you are unsure about how a snippet is supposed to be used, hover over it to view the description and test it first (before employing it in a more complex service that you will use in production).
• Breakpoints are not available as a debugging mechanism; debugging is typically done through logger.warn(message) statements that write their output in the ScriptLog.
• You can check the result of a Service also in the browser Developer Tools, accessible by pressing F12, in the Network tab. This is especially useful when debugging a sequence of services that executes in a Mashup, because you can see the service results in the context of that specific execution.
• For testing purposes, use the Logging utilities (e.g. logger.debug or info/warn/error) to check various steps inside your service and print messages in the ScriptLog. After you tested your service and you are ready to use it in production, you can remove or comment the lines of code which log test messages.
• Add sanity checks to your code to mitigate the possibility of the end user receiving an error. For example, if your code needs a couple of input parameters to run, make sure (using an IF condition) that they are not null before performing operations with them.
• Use try –catch mechanisms for portions of your code that can generate errors or throw exceptions at runtime (for example, when executing a remote service from your gateway, if it is a long duration operation it might be possible that you will receive a timeout or your gateway will disconnect)
• Try-catch can be very useful when you test custom services. This is because you can catch the error and maybe print a line in the Monitoring menu - Script to indicate which line has caused that error
try {
//your code
}
catch (err) {
logger.error(“Service error in NameofYourService “ + me.name + “ at ” + err.lineNumber + ”: “ + err
}
• It is very important to TEST your services, not only in the Composer, but also in all the places where they are used (a service might work as expected in the Composer, but in the Mashup, it might generate an unexpected result). In the Composer you’re testing with predefined values, while in a Mashup, the service might receive an unexpected input that might cause it to crash.
• Testing should involve also various validations on the client-side as well as on the server-side. For example, a service that is used in a Mashup gathers some input from the user and sends that to the gateway. You want to make sure that input entered by your user is valid so that your service executes properly and the correct information arrives at the gateway. This can be done in the UI, with a Validator widget (client-side validation) as well as inside a service (server-side validation).
• Always check the logs when testing a service to see if any error messages appear. This is particularly useful for services that you run in subscriptions (because for services for which you use the Test button, you can see the error right away).
• Detailed stack tracing for errors that happen inside the Java API is available in the ErrorLog.log file
Eg: calling the following code will result in an error:
var calculatedDateValue = dateAddMonths(dateValue,"");
In the ErrorLog.log file you will find a large stack trace that helps when debugging.
• Service context information (stack error line number) is available in the ScriptErrorLog.log file from the logs folder. This file is used only when checking the “Enable Script Stack Tracing” from the Configuration module of the LoggingSubsystem.
Eg: assuming you have service A which calls service B, and service B throws an error, in the ScriptErrorLog.log you’ll see the following line:
2018-05-25 11:14:46.177+0300 [L: ERROR] [O: S.c.t.d.e.DSLProcessor] [I: A] [U: Administrator] [S: ] [T: https-jsse-nio-443-exec-4] [message: Execution error in service script [ServiceA] :: Unable To Convert From java.lang.String to NUMBER]
at ServiceB:6
at ServiceA:2
• To read ErrorLog.log and ScriptErrorLog.log you need to have access to the server itself, since the files are not available in the Monitoring section. They are in the [ThingworxPlatform]/logs folder