Best practices

Caching data that takes time to retrieve is a useful way to speed up performance. Examples are data from resources external to the synchronization process, such as RTSM data, data from user databases, and data from files.

Caching comprises the following operations:

1. Connecting to the external resource.

2. Loading the data from the resource and storing it in a data structure in memory, which typically has a much shorter access time. The data in memory is called cache data.

3. Using the data in the custom process.

4. Disconnecting from the external resource.

5. Removing the cached data from memory.

Typically, connecting to and loading from the external resource are the most time-consuming steps.

When implementing caching, consider the following aspects:

• Avoiding is better than fixing, so try to minimize dependency on external resources:

  • When contemplating using external data, contemplate whether it is really necessary or not.
  • If data is available or derivable from an internal resource, don't use an external resource.
  • If data is available or derivable from a number of external resources, use the minimum number of resources.
  • If data is available or derivable through a number of different APIs, use the API with the fastest performance.

• Cache only data that is likely to be reused. CI data is likely to be reused, and should be cached in most situations. It is not recommended, however, to always cache all available CI data. If your script only uses events associated with a certain type of CI, for example, you could apply a filter to cache relevant events only. Try to find a balance, however, between caching only data that would be reloaded against increasing code complexity, which could decrease process performance due to the need to evaluate numerous if and case conditions.

• Connecting to an external resource needs to be done only once. The best place to connect to resources containing data used throughout the script is in the script class's init() method. Disconnect in the destroy() method. Code inside the process() method can then directly access the resource.

• Loading the data will usually be done while using the code, because different data is needed in different places. However, if you reuse the same data over and over again, you could use the init() method to connect, load the data to a local array, and disconnect right away.

• Having a resource open and storing data in memory uses system resources. To optimize resource usage you may want to connect the first time data is accessed and disconnect after loading in the process() method; this is just as fast, as long as you connect only once. Keep in mind, however, that it is always better to optimize script performance for absolute time than to minimize system resource usage.

• After finishing debugging, remove any logging code which is not necessary in the production environment from the script to avoid unnecessary overhead.

• Do not use APIs known to have slow performance characteristics in performance critical code. Most notably, pay attention to the performance of APIs when inserting custom scripts in the event pipeline.

• Access the RTSM using its JAVA API, which has a better performance than other APIs such as SOAP-based web services APIs.

• It is not permitted to use shell functions such as System.exit(). Shell function calls cause the JVM, which executes the Groovy script, to be stopped and restarted.

• Perform time-consuming processes in background threads wherever possible.

Running problematic scripts can lead to performance issues, even if the code executes. In-depth testing and debugging is necessary to produce robust scripts that are safe to use in your production environment.

• Use the Groovy Console during script validation and testing (see Groovy console).

• When debugging the script, include plenty of logging statements allowing you to track the behavior of the code. HPE recommends encapsulating the logging of debug information in a debug() method, making it easy to remove or deactivate logging in the production environment (see Improving performance). Exceptions are calls to the init() and destroy() methods. HPE recommends logging these using an info() method so you can track successful loading and unloading of your script, in both debugging and production environments.

• Use comments and verbose variable names to facilitate future script maintenance.

• If an exception gives rise to a run-time error, the process could be disrupted. Catch exceptions by using try/catch blocks, and provide an elegant exit in the exception handler.

• When connecting in the init() method, check the validity of the database handle before accessing the resource. If the resource was disconnected for reasons outside the control of the script, handling this exception properly allows you to recover the connection by reconnecting.

• Use ? when referencing object properties to avoid a NullPointerException when the object evaluates to null. When referencing a property using ? the whole expression containing the reference evaluates to null, rather than throwing an exception.

  Example:The following code snippet will still work if the assignedUser object evaluates to null.:
  if (event.assignedUser?.userName) {...}

• Avoid using def statements wherever possible to enhance the transparency of the script and facilitate future script maintenance. HPE recommends declaring the actual object type instead of using a def statement, making it easier to find the properties and methods of the instanced object. Another advantage of a transparent script is that it is easier to debug. Note, however, that are cases in which using the def statement is justified. As an example, consider the backward compatibility of a script containing a function having an argument of a class type that was not available in a previous version. If the argument is declared as type def the script will still load in the previous version, even though the class is not defined in that version. In this case, adding a comment specifying the actual object type of the argument in question.

• Use the internal script error feature to preempt process disruptions caused by scripts experiencing run-time problems. If a script class has a public method named getInternalScriptError() and the method returns a value of 10 or higher, the script is skipped by the platform service executing the script. To use this feature, insert the following code:
  int internalScriptError = 0;
def int getInternalScriptError() { return internalScriptError; }
def setInternalScriptError() { internalScriptError++; }
  This code causes the member variable internalScriptError, which holds the script error level, to be initialized to 0, and enables the programmer to increase the error level by calling the setInternalScriptError() method whenever an error occurs. If, for example, the setInternalScriptError() method is called whenever an attempt to connect to the database fails, the script is skipped after 10 tries, and no longer uses process time.

The OMi administration screens that are used to configure scripts on the platform are useful to manage the script, but are not sufficient to edit, maintain, test and debug scripts. You must rely on an external editing tool to create a more versatile editing environment

• Line numbering and a text search function are useful for matching log file references to code lines. Neither of these is available in the script form included in the OMi Console, so an external editor is useful during script development.

• For most scripts a simple tool such as Notepad++, vi or GNU emacs is sufficient.

  • Notepad++ is a freeware improvement on Notepad featuring line numbering and Java syntax highlighting, as well as an optional auto indent plug-in. You can get Notepad++ from http://notepad-plus-plus.org/download/.
  • vi is a visual text editor developed for UNIX, and is installed on UNIX systems. Several free and open source software implementations of vi exist; for more information, see http://en.wikipedia.org/wiki/Vi.
  • GNU Emacs is an extensible, customizable text editor featuring syntax highlighting, full Unicode support, and many optional extensions. You can get GNU emacs from http://www.gnu.org/software/emacs/.
• For more involved scripts requiring syntax checking use the Groovy console. For details about installing and using the Groovy console, see Groovy console.
• For large event forwarding scripts such as the Service Manager adapter script it could be useful to turn to more comprehensive script editors, for example Eclipse or IntelliJ.

Script templates and examples are available in the directories where scripts can reside. Starting a new script from a template rather than from scratch makes it easier to follow the script format rules and make it less you forget something.

Be careful with copy-and-paste from emails, PDF files or Microsoft Word documents.

• Using copy-and-paste could result in invalid code because of extra line breaks or because of line breaks being treated differently by the Groovy engine. The Groovy engine does not require a semicolon to end a statement, and will sometimes treat a line break as the end of a statement. Unintentional line breaks could therefore lead to unintentional code behavior.

• If you do copy and paste code, inspect it line by line and rejoin statements split across two lines, which the Groovy engine may unintentionally interpret as two separate statements.