Explanation Overview

Explanations are accessed via Configuration and Administration > Power Data > General > Explanations.

An Explanation provides a standard view of Oracle Transportation Management process results such as the running of actions, creation of new records, etc. Explanations can be used to diagnose algorithm behavior, report errors, trace agent activity or report on the success and failure of a background process.

Following are two sample use cases for explanations:

• Service Provider Selection: When choosing a service provider for a shipment, Oracle Transportation Management planning modules could collect the rating and itinerary information evaluated during the execution of the algorithm. A user could view the explanation to determine precisely how the least-cost provider was chosen, drilling down into rating engine results associated with each provider.
• Event Notification: A number of contacts can register interest in an event. When the event occurs, Oracle Transportation Management loops through each contact and identifies them via a specified communication method. Each method may produce errors from lack of data or formatting difficulties. For example, an email contact may be missing an email address; a stylesheet may be missing for an XSLT transformation. A user could view the notification explanation to see which recipients were properly sent the notification and which had problems.

The general structure of an Oracle Transportation Management explanation is illustrated below:

 

Explanation Header

An explanation is identified by the process it is explaining. The process type is selected from an enumeration of Oracle Transportation Management processes that support explanations. The process message is a descriptive summary of the process and it includes information to identify which instance of a process was run such as Tendering Shipment S-102394 to REDSTAR, as an example. To further identify the process, the explanation holds the time the user initiated the process along with the User ID.

Note: Almost all of the elements of an explanation are designed for a standard, internationalized view of Oracle Transportation Management process results. To support client-specific views, the explanation includes a results object. This object contains structured summary data generated by a particular process. Java callers can access this data directly to retrieve object-oriented result data based on the process type.

Issue

Each explanation consists of a set of independent issues which occurred during the execution of the process. These issues may reflect iterations of an algorithm or multiple errors. For example, in the Service Provider user case, each evaluated service provider can be represented by an issue. For the Notification use case, each recipient can be identified by an issue. Alternatively, only those recipients that Oracle Transportation Management could not notify due to errors could be issues of interest.

Each issue contains a severity code (i.e. informational, warning, error) and a description message. The description is highly dependent on the context of the explanation. In the Service Provider use case, the description would list which service provider is under consideration; for lifetime notification, the recipient information.

Cause

When an issue traces normal execution of an algorithm or reports on an error, it reflects a thread of execution as seen by a user. At particular points of execution, Oracle Transportation Management collects information into a cause. This information includes the code module collecting the information, a summary message, a detail message and an error code.

For the Service Provider use case, the cause stack could be configured to list rating engine debugging information, allowing users to understand the cost of each provider. For the Notification user case, the cause stack maps the Java call stack to an understandable format for the user. Assume, for example, a Message Center notification for shipment domain.S1234 fails because there is no appropriate stylesheet in the domain. From a user's perspective, the cause stack could be:

• Unable to notify domain.JCASA of SHIPMENT DGANO.S1234 - CREATED
• Unable to route notification to MESSAGE CENTER
• Missing Stylesheet: domain.SHIPMENT_EVENT_BY_MESSAGE_CENTER

The cause stack does not necessarily reflect a true (i.e. machine) thread of execution. It may reflect a process that is executed across multiple threads, like agents. An order failure, for example, could produce a cause stack like:

• Unable to process order ORD-1234
• Failure in agent: ORDER - MOD
• Failure in action:  FULL IMPACT FLOW
• Order is on an executing shipment

Diagnostic

For issues which represent an Oracle Transportation Management exception, the explanation contains an additional diagnostic. This diagnostic includes a technical message along with a stack trace of the exception. It is intended for use by advanced users and technical support.

Data Diagnostic

The explanation mechanism provides special support for tracking and translating Oracle RDBMS errors into diagnostics. If Oracle Transportation Management throws a SqlException, the explanation automatically maps the exception message into a diagnostic for the user and stores the Oracle error code and SQL statement within the diagnostic. When displayed, the user interface can access the error cause and suggested action given in the Oracle Error Messages manual.

Not all Oracle error codes are supported by diagnostic mapping. Oracle Transportation Management supports the following classifications of errors:

• SQL parsing or evaluation errors - to support diagnosis of user-defined Saved Query SQL
• Resource errors - out of memory, extents
• Primary key, foreign key, constraint errors
• VPD policy errors
• Communication, connection errors

Message

Each message listed in the structure of an explanation (e.g. process, issue description, cause summary) supports internationalization. The message is represented by a property key and a list of Java Object parameters. The property key points to a message in the explanation.properties file, similar to the translation.properties file used for Oracle Transportation Management label translation. The naming conventions for each property key are:

Type of Message	Property Key
Process	process.<Process Type>.< UID>
Issue Description	issue. < UID>
Cause Summary	cause.summary.< UID>
Cause Detail	cause.detail.< UID>
Diagnostic	diagnostic.< UID>
Data Error	data.error.< UID>
Data Suggestion	data.suggestion.< UID>

 

Note: < UID> is a unique identifier for that message key.

The explanation.properties file is structured identically to translation.properties and leverages all utilities written for label translation.

Message Parameters

A translated message may support the replacement of macros by data parameters. For example, assume we have a message which is determined by a level of service and an item.

In English, the message may be:

EXPEDITED service is required to transport SHOES.

In Portuguese, this would be:

Message format macros are used to insert the message parameters into the final localized message.

For English, the properties file would store:

{0} service is required to transport {1};

for Portuguese:

Persistence

Oracle Transportation Management supports the persistence of explanations to the database and provides methods to create, remove, update and load a stored explanation. Oracle Transportation Management uses this capability to:

• Store results of asynchronous processes such as published actions, integrations and recurring processes. These results are retrieved when notifying users of completed actions or displaying current status on demand.
• Log errors and abnormal events. Based on properties, a customer can log explanations based on process type and/or severity.

The dynamic tables used by explanation persistence are partitioned for automatic cleanup of expired data. Any tables keeping a reference to an explanation handle the removal of referenced data.

You can view all explanations in the database using the Explanations menu link under Power Data > General.