When developing code-based customizations using Verint Community, it is important to implement appropriate application telemetry to enable review of plugin functionality and exceptional behavior. Verint Community provides services to enable logging, exception handling, and tracing.
Logging
Sometimes it's useful for background processes to log process details not related to exceptions. In this case, plugins can use the EventLog API . The event logs API enables plugins to write logging data to the Verint Community event log (available in Administration > Monitoring > Events and sent to other logging systems (console, Open Telemetry) based on Environment Configuration's Logging section). To write an event log entry, use the Write method.
Telligent.Evolution.Extensibility.Apis.Get<Telligent.Evolution.Extensibility.Api.Version1.IEventLog>().Write("{plugin} executed at {datetime}", new Telligent.Evolution.Extensibility.Api.Version1.EventLogEntryWriteOptions
{
Category = "MyPlugin",
EventId = 1234,
EventType = "Information",
MessageParameters = ["MyPlugin", DateTime.UtcNow]
});
When specifying a message, named placeholders can be used to reference the message parameters included in the EventLogEntryWriteOptions. The values are placed into the placeholders in order (so MyPlugin -> {plugin} and DateTime.UtcNow -> {datetime}). Event log entries are not intended to be translated.
The EventLog API is throttled, allowing a maximum of 100 log entries per minute across all usage.
Exception Handling
Plugins are .net classes and can throw .net exceptions to identify exceptional issues and there are many solutions to process logging. Verint Community provides support for integrating exception handling and process logging, enabling a consistent error and process handling experience for administrators and community members.
Exception Rendering
When an exception bubbles up from a plugin to a user, either via UI rendering or when handling a REST request, Verint Community will interpret the exception to return an error response to the accessing user. To prevent information disclosure security vulnerabilities, exceptions, by default, are replaced with a generic error message in UI and REST responses.
Error messages returned from APIs (REST and Scripting Error collections) are safe to render to end-users. The messages they include avoid information disclosures and support translation into the accessing user's language.
Exception Logging
Some exceptions are caused by user error, for example, entering "abcd" where a number was expected. Other exceptions may identify a configuration issue. Issues that occur that should be reviewed and corrected are good candidates for logging.
Verint Community includes an exception log (available in Administration > Monitoring > Exceptions). Any exception that bubbles up to the end-user is reviewed by Verint Community to see if it should be logged based on its associated IExceptionCategory (the default is "Unknown" and is logged). If the exception is loggable, it is saved to the exception log before being rendered to users or cancelling an action.
Custom Exception Types
To enable custom messages to be rendered to the UI, thrown exceptions must implement IUserRenderableException . This interface can be applied to a custom Exception implementation to identify to Verint Community that the exception can provide an appropriate, safe, and ideally translated message to a user. The interface defines one member, GetUserRenderableMessage() which returns a string. The results of this method will be returned through the UI and shown to the user or be placed in the Errors collection of REST responses (depending on how the API, and indirectly the plugin, was accessed) and scripting API responses.
To also define the HTTP status code that should be sent with the message when encountering the exception as part of a web request, implement IHttpUserRenderableException .
To define the associated IExceptionCategory (either an existing of a custom category) which controls whether the exception should be logged or not and how a generic error would be shown to end-users, a custom Exception type can implement ICategorizedUserRenderableException .
Tracing
Verint Community includes support for tracing application flow through both platform-defined and custom trace points. Tracing data is made available to configured consumers in Environment Configuration via the Tracing section. Custom code can participate in tracing using the TracePoint API . Each TracePoint is defined around code being traced -- the enclosed code is timed and exceptions related to the execution of the enclosed code are included in the trace automatically. A trace point consists of a description (which should be short and programmatic) and optional tagged data which is sent with the trace point:
Telligent.Evolution.Extensibility.Version1.Tracing.TracePoint.Record("sample.execute", (tracepoint) =>
{
tracepoint.Tag("key", "value");
// TODO: Do traced work.
});
The TracePoint API includes overrides to support returning values from traced code and running asynchronous traced code.