A service is only robust if it can be run and supported confidently in production: failures need to be diagnosable quickly, logs need to say something useful without drowning the signal, and releases need to be predictable.
Logging is essential for building robust and maintainable services. Consistent, meaningful log messages make a service’s behavior traceable, helping developers understand what happened, when it happened, and under which conditions.
When problems occur, logs provide valuable context for diagnosing failures, identifying the source of errors, and distinguishing between application issues, infrastructure problems, and unexpected user input. Good logging therefore reduces troubleshooting time, supports reliable operations, and makes it easier to improve the service over time.
The Designer allows you to log custom messages to the xUML Service Log or the xUML Transaction Log using the log() and report() functions.
What a Custom Log Message Should Contain
Log messages should make it easy to identify
-
where something was logged
-
why something was logged
-
what business items the log refers to (process, process step, order number, IDoc reference, …)
The process ID is available as a persisted variable id in every process step of a Designer model.
Also, the getTransactionId() function returns the process ID as per default if it has not been overwritten by the developer using the setTransactionID() function.
The log() function (that logs into the xUML Service Log) requires the following parameters:
|
Parameter |
Description |
|---|---|
|
level |
The log level can be one of the following string literals: Fatal, Error, Warning, Info, Debug. This is to define the severity of the log entry. |
|
type |
The log type is a string literal used to group log entries. Usually it contains the application name where the error occurred ( |
|
code |
The log code is a string literal, usually containing an error number ( |
|
description |
The description is a string literal containing custom log information. You can include relevant details such as your process name, process ID, references to business items, and other context. Use the concat() operation to combine these into a single message, like |
|
details |
This is an optional parameter where the developer can provide an additional error object of complex type (class or array). The contents of this object will be flattened and appended to the description. |
The same applies to the report() function that logs into the xUML Transaction Log. You should define your project’s log-message schematics so they remain consistent and easy to read throughout the project.
Convention for Level, Type, and Code
Agreeing on a project-wide convention for how type and code map to each log level keeps messages consistent and makes them easy to filter later, e.g. in OpenSearch:
|
Level |
Type |
Code |
Purpose |
|---|---|---|---|
|
Error |
Business reference, e.g. |
The business item involved, e.g. IDoc number, customer ID. |
Pinpoints which business object or field caused the failure. |
|
Warning |
Business reference, e.g. |
Can be dynamic where useful. |
Flags a business condition that did not fail the process in general but leads to errors. |
|
Info |
The process class / process name |
The process ID |
Enables filtering in OpenSearch and logging key decisions taken during the process. |
Refer to Logging in the PAS Modeling Guidelines for more information about logging and a distinction between service and transaction log.