Message Logging, Error Handling, and Return Messaging

Enterprise Administration > Implementing Windchill ESI > Implementing Windchill ESI in an SAP Environment > Understanding Windchill ESI Architecture > Message Logging, Error Handling, and Return Messaging

The processes for logging, error handling, and return messaging to Windchill PDMLink use the same concepts, but they perform different functions and are implemented differently. The following sections describe the processes and provide a summary of their respective functions.

Since theWindchill ESI services use the standard Windchill PDMLink log4 based logging mechanism, the information in the following sections applies to the EAI software components only.

EAI Logging Process

The logging architecture in the EAI components is designed to allow system administrators the ability to easily track the EAI software component processes. TheWindchill ESI business logic logs all transaction activity to log files and provides messages that specifically describe routine and functional error processing.

Error and system log entries are generated immediately after theWindchill ESI business logic reaches the following processing milestones:

• Receives JMS messages

• Sends JMS messages

• Invokes a distribution target API, including commit and rollback

• Receives a response from a distribution target API, including commit and rollback

• Handles certain types of errors

Logging can be extended to other key milestones through customization.

Log entries are recorded chronologically; to avoid confusion due to parallel processing, entries should be filtered or sorted based on the transaction number. The logging process uses the ESILog schema as an input. For more information on the logging schema, see XML Schemas.

AllWindchill ESI logs generated by the EAI software components are maintained in the TIBCO BusinessWorks process engine logs with a role designation of ESI to distinguish them from other standard TIBCO product messages. The log file size is configurable and logs can be viewed through the web-based, TIBCO BusinessWorks Administrator. For more information on how to view the logs, see the TIBCO Administrator User’s Guide.

Log files can also be exported to a text file and viewed by any text editor or exported as a CSV file into a spreadsheet program such as Microsoft Excel which can be used to filter or sort the messages. Log messages can be disabled or enabled and also configured and customized to provide different levels of details and severities.

To control the size and roll-over of these log files, you can modify the values of the Max Log Files (default = 10) and Max Log File Size (default = 1000 KB) parameters. For further information, refer to the Process Engine section of the Deployment Palette chapter in the TIBCO BusinessWorks Palette Reference.

Components of a Log Entry

The following table describes the components of a log entry, in the order in which they are placed. The fields in the log are delimited by a configurable delimiter that is set to a comma (,) by default

Field	Length	Description
Transaction Number	200	TheWindchill ESI transaction number that is being processed.
Target	25	Uniquely identifies the target where the object is being published and has the following format: <Destination>,<TargetID> where: <Destination> exists as a child of the <Transaction element in the Windchill ESI response. It takes a value of the form <SAP System ID> . <SAP Client> where SAP System ID and SAP Client are mandatory parameters that are provided while creating an SAP type distribution target in Windchill. <Target ID> takes a value of the form <TargetNumber>:<Plant>. where: <Target Number> is the number attribute on the ESITarget object representing the distribution target in Windchill and <Plant> is the plant name associated with the SAP destination. < Plant> will have an empty value if the distribution target represents a “No Plant” destination. For example: The following Target indicates an object being published to plant 1100 of SAP system PTCPROD, client 800 and represented by an ESITarget object having the number PTC_1: PTCPROD.800,PTC_1:1100 A Target that is not plant-specific might look like this: PTCPROD.800,PTC_1
Application	1	Identifies the application that originated the message. For further details, see the Application section.
Type	1	Indicates the type of message. For further details, see the Type section.
Severity	1	Indicates the severity level of the message. For further details, see the Severity section.
Message Code	5	Unique message code identifier, used as the cross reference key to the appropriate localized message text. This field is hard-coded by the developer or a customizer when invoking the Logging Service. For further details, see the Message Code section.
EAI Primary Message Text		Descriptive text such as a message description (corresponds to the Message Code). This text is localized based on the ESILog/Locale global variable. For more information see Internationalization Considerations. For example: Received ESI Response.
Descriptive Text		Any descriptive text. For example: Object Number.
Root Cause Analysis Message		Text describing possible root cause of error, or where user may find more information about the error. This text is localized based on the ESILog/Locale global variable. For more information see Internationalization Considerations. The logging of this information is enabled via a global variable ESILog/RootCause. See the Logging Flags section for more details. For example: "For more information regarding this error, please refer to the SAP Application Log (transaction SLG1)"
ERP Primary Message	300	If applicable, this is the primary API return message from the ERP system. For SAP distribution targets, this includes the following SAP message parameters, delimited by colons, with leading and trailing spaces removed: • Type (usually A, E, S, I, W, or X) • ID • Number • Text This text is not localized. For more information see Internationalization Considerations. The logging of this information is enabled via a global variable ESILog/ERPPrimary. See the Logging Flags section for more details. Since this information applies to different message types and severities, it may be repeated several times in the log. For example: S:MM:356:The material GS_700_IB4D has been created or extended
ERP Secondary Message	300	If applicable, the secondary API return message is sent from the ERP system. For SAP distribution targets, this includes the following SAP message parameters, delimited by colons, with leading and trailing spaces removed: • Type (usually A, E, S, I, W, or X) • ID • Number • Text Each secondary information entry is delimited by semicolons This text is not localized. For more information see Internationalization Considerations. The logging of this information is enabled via a global variable ESILog/ERPSecondary. See the Logging Flags section for further details. Since this information applies to different message types and severities, it may be repeated several times in the log. For example: H:MK:102:Trying to create: GS_700_IB4D 1200; S:M3:800:Material GS_700_IB4D created; H:MK:103:Trying to change: GS_700_IB4D 1200; S:M3:810:No changes made
EAI Additional Information	2500	Any pertinent information from EAI components (non-ERP). This text is not localized. For more information see Internationalization Considerations. Since this information applies to different message types and severities, it may be repeated several times in the log. For example, in the case of an error, this field might contain a stack trace.
Extra Information	2500	Additional field for customization.

Log Message Codes

The following sections provide details on the codes or numbers associated with the various fields in the log messages.

Application

The application field indicates which application is the source of the information in the log entry. There is no systematically enforced correlation between the application fields and any other fields of the log entry. The following table lists the number associated with the applications:

Application Number	Description
1	TIBCO BusinessWorks.
2	Windchill PDMLink.
3	TIBCO EMS.
4	TIBCO Adapter for SAP.
5	TIBCO Adapter for Oracle Applications.
6+	Reserved for future use.

Type

To help classify messages,Windchill ESI assigns a type to each log entry at the point in theWindchill ESI business logic where it is generated. The following table lists the message types:

Type Value	Message Type	Description
1	Functional	Provides status information on the processing of the business objects between Windchill and the Windchill ESI business logic or between the Windchill ESI business logic and the distribution target. For example, creating parts or changing BOMs.
2	Technical	Provides status information relating to technical aspects of processing. For example, failed to parse response message.

Severity

The severity level indicates the impact of the message on the system. Severity level numbers five (5) and above (except 9) can be used for customized message severity types. The following lists the current severity levels:

Severity Field Value	Severity Type	Description	Action Required by Administrator
0	Fatal	Indicates a failure occurred and that the EAI components have stopped processing.	Yes. Requires immediate attention from an EAI systems administrator.
1	Error	Indicates that a non-fatal error has occurred. The EAI components continue processing.	Yes. May require EAI systems administrator attention in the case of technical errors. May require attention from aWindchill PDMLink user for functional errors.
2	Warning	Indicates that an important or significant condition occurred but did not cause the Windchill ESIbusiness logic to stop abnormally.	Action sometimes required through standardWindchill PDMLink tools.
3	Success	Indicates that desired action was completed successfully.	None
4	Informational	Indicates that a normal processing step was performed.	None
9	Debug	Intended to track the progress of the BusinessWorks flow for debugging purposes.	None.

Message Code

The following provides details on message code related to:

• Internationalization

• Numbering scheme

Internationalization

Each message is associated with a five-digit code, for example, 40003. This helps message logging configuration by locale and distribution target.Windchill ESI provides localized message text for several supported languages. You can choose the desired logging language for each deployed BusinessWorks process engine via the global variable, ESILog/Locale. Messages, by default, are stored in the ESIMessageLookups.properties. You may configure the default Windchill ESI message texts in this file for specific distribution targets and additional locales. Message lookup keys can contain wildcards. That is, you may set a code to work for any locale and any system.

Log messages are chosen in the following order of precedence: locale, system, wildcard.

The format of an entry is: Code.System.Locale=Localized Text

For example:

41308.PT3.en_US=<Text for SAP Instance PT3 in US English>

41308.*.de_DE=<Text for all systems in German>

41308.*.*=<Default text for all systems and locales>

Numbering Scheme

Message codes are numbered according to the following scheme:

Logging Flags

As mentioned earlier, depending on site needs, you may configure which message types and severity levels are to be written into the log. You can use global variables to configure these messages.

The following table lists the flags that are stored as global variables. Messages that have a severity level of 0 (fatal messages) are always logged; there are no flags to turn this messaging off. Acceptable values for these flags are 0 (false) or 1 (true).

Flag	Description
ESILog/Functional_Debug	Enables logging of messages that are type functional and severity debug.
ESILog/Functional_Informational	Enables logging of messages that are type functional and severity informational.
ESILog/Functional_Success	Enables logging of messages that are type functional and severity success.
ESILog/Functional_Warning	Enables logging of messages that are type functional and severity warning.
ESILog/Functional_Error	Enables logging of messages that are type functional and severity error.
ESILog/Technical_Debug	Enables logging of messages that are type technical and severity debug.
ESILog/Technical_Informational	Enables logging of messages that are type technical and severity informational.
ESILog/Technical_Success	Enables logging of messages that are type technical and severity success.
ESILog/Technical_Warning	Enables logging of messages that are type technical and severity warning.
ESILog/Technical_Error	Enables logging of messages that are type technical and severity error.

The flags in the previous table determine when to log messages. There are additional flags that determine what to log. The following table describes these global variables in detail:

Flag	Description
ESILog/ERPPrimary	Enables logging of ERP primary messages. For more information, see the Components of a Log Entry section.
ESILog/ERPSecondary	Enables logging of ERP secondary messages. For more information, see the Components of a Log Entry section.
ESILog /RootCause	Enables logging of root cause messages. For more information, see the Components of a Log Entry section.

Logging Process Flow

The following figure provides a high-level view of how the logging process is invoked in the EAI software components.

Calling the Logging Service

The following sample screenshot from TIBCO BusinessWorks is a call to the logging process showing data written to the log containing both hard-coded information and runtime process data.

Return Messaging to Windchill

Windchill ESI EAI software components send a subtransaction PostResult message for every object/action/organization (including Parts, BOMs, and Documents, CNs, DocumentLinks, Process Plans and resources). The Message field of the ESIPostResult schema is a string field that contains explanatory text about the status of the object (for more information on the structure of the PostResult schema, see Implementing Windchill ESI). This field is populated with several pieces of information. The following table describes the structure of the message field. The fields are delimited using a global variable ESIMessaging/Delimiter, which is set to a double pipe (||) by default. This delimiter is also prepended to the entire message string field. This is a feature put in to allow the source application to be able to dynamically parse the message using the delimiter specified in the message.

Components of ESIPostResult Message

Field	Description
EAI Primary Message	Text generated by EAI software components that describes the object/action/status of the subtransaction. This text is localized based on the locale (from the com_infoengine_locale property) of the data in the Windchill ESI Response. For more information see Internationalization Considerations or the Implementing Windchill ESI. For example: "Successfully created part in SAP."
EAI Secondary Message	Text generated by EAI software components that tells the user of any warning or functional decision messages. This text is localized based on the locale (from the com_infoengine_locale property) of the data in the Windchill ESI Response (For more information see Internationalization Considerations or theImplementing Windchill ESI for more details). Including this information in the message is enabled via a global variable ESIMessaging/EAISecondary. For more information, see the Return Messaging Flags section. For example: "Creating document version failed but assuming functional success."
Root Cause Analysis Message	Text generated by EAI software components that indicates the possible root causes of the error or provides hints and tips on where to find additional information about the error. This text is localized based on the locale (from the com_infoengine_locale property) of the data in the ESIResponse (For more information see Internationalization Considerations or the Implementing Windchill ESI for more details). Including this information in the message is enabled via a global variable ESIMessaging/RootCause. For more information, see the Return Messaging Flags section. For example, "For more information about this error, see the SAP Internal Application Log (transaction SLG1)."
ERP Primary Message	If applicable, the primary API return message from the ERP system. For SAP distribution targets, when using SAP BAPIs, this may include the following SAP message parameters, delimited by colons, with leading and trailing spaces removed: • Type (A, E, S, I, W, X) • ID • Number • Text For SAP CCAP and CSAP remotely-enabled API function modules, this field may be the object name or internal SAP object number. This text is not localized (See the Internationalization Considerations section in the Installing and ConfiguringWindchill ESIin an SAP Environment for more details). Including this information in the message is enabled via a global variable ESIMessaging/ERPPrimary.For more information, see the Return Messaging Flags section. For example: S:MM:356: The material GS_700_IB4D has been created or extended
ERP Secondary Message	If applicable, the secondary API return message from the ERP system. For SAP distribution targets, when using SAP BAPIs, this may include the following SAP message parameters, delimited by colons, with leading and trailing spaces removed: • Type (A, E, S, I, W, X) • ID • Number • Text For SAP CCAP and CSAP remotely-enabled API function modules, this field will typically remain empty. Each secondary information entry is delimited by semicolons This text is not localized. For more information, see the Internationalization Considerations section in the Installing and ConfiguringWindchill ESIin an SAP Environment. Including this information in the message is enabled via a global variable ESIMessaging/ERPPrimary. For example: H:MK:102:Trying to create: GS_700_IB4D 1200; S:M3:800:Material GS_700_IB4D created; H:MK:103:Trying to change: GS_700_IB4D 1200; S:M3:810:No changes made
EAI Additional Information	Any pertinent information from EAI components (non-ERP). This text is not localized. See the Return Messaging Flags section for more details. For example, in the case of an error, this field might contain a stack trace.
Extra Information	An additional field for customization.

Unlike logging, return messaging to Windchill does not contain flags to determine when to send messages - messages are required to be sent for every object/action/organization. However, there are flags that determine what can be returned to Windchill PDMLink. The following table describes these flags.

Return Messaging Flags

Flag	Description
ESIMessaging/ERPPrimary	Enables returning ERP primary information to Windchill PDMLink. For more information, see the Components of ESIPostResult Message section.
ESIMessaging/ERPSecondary	Enables returning ERP secondary information to Windchill PDMLink. For more information, see the Components of ESIPostResult Message section.
ESIMessaging/RootCause	Enables returning root cause information to Windchill PDMLink. For more information, see the Components of ESIPostResult Message section.
ESIMessaging/EAISecondary	Enables returning functional decision/warning information to Windchill PDMLink. For more information, see the Components of ESIPostResult Message section.

Error Handling and Notification

Errors in theWindchill ESI system are handled in a closed-loop manner. This means that each error is logged and handled in some way.Windchill PDMLink users are actively notified and given the opportunity to view the errors, fix the cause of each of these errors, and then resubmit the transaction for further processing.

Overview of Error Handling Process

TheWindchill ESI business logic contains a custom error-handling process. This process is called in-line after an error is detected by the TIBCO BusinessWorks application. Once started, the process evaluates the type of error and determines the action needed to handle the error including whether to:

• Send a subtransaction PostResult message to Windchill PDMLink

• Send an overall PostResult message to Windchill PDMLink

• Halt the process or continue from the point where the error occurred

The logging flags determine whether an error is logged. The severity of an error is determined via the error handling codes. An error code that stops all processing will have a severity of 0 (fatal). Severity 0 errors will always be logged. An error code that continues processing will have a severity of 1 (error). Severity 1 errors will be logged if the appropriate logging flags are enabled.

Windchill PDMLink users are actively notified and given the opportunity to fix the source of failures. However, in cases where there is not enough data to provide these notifications, presenting a possible risk of inconsistencies in the data betweenWindchill PDMLink and the distribution target, a higher-level customized notification such as an email message to the administrator or a call to a pager can be sent.

Once the error is handled, the process thread for that error terminates naturally. The error handling process uses the ESIError schema as an input. It must be populated with the required information when the error-handling service is invoked. For more information on the ESIError schema see XML Schemas.

Types of Errors

Errors in the EAI components of aWindchill ESI system can be grouped into the following three types:

• BusinessWorks Processing Errors

Errors detected by TIBCO's BusinessWorks application in the EAI components, are handled by the BusinessWorks error-handling process. When these types of errors occur, normal processing stops and the error is logged in the BusinessWorks Process Engine log with information such as when, where, and what type of error occurred.

• Functional ERP Errors

Errors occurring in an ERP system are handled as part of normal processing and are not recorded by the error handling process or written to an error log. Instead, all errors as well as successes are recorded in the Transaction Management Log.

• System Errors

When engines, adapters, or servers fail, TIBCO Administrator sends an error message to the error handling process and attempts to automatically restart the failed program or alert an administrator of system performance problems.

The majority of errors are in anticipated circumstances. In these cases theWindchill ESI business logic processes the error in a prearranged way. In some cases, the code may fail in situations that were not anticipated. Errors of this type are handled in a predetermined way. In all cases, theWindchill ESI business logic calls the error handling process, which determines whether a PostResult message is sent to Windchill, whether or not to write to the log while error handling, and whether to halt the process or continue from the point where the error occurred

Checkpoints are used to store information about the status of jobs so that they can, after they fail, be restarted from that point on without causing data duplication or data corruption. Checkpoints are used in the following locations:

◦ After receiving a response from Windchill PDMLink

◦ After receiving the status of an object published to an ERP system from the EAI application

For more information about guidelines on checkpoints, see the Windchill Enterprise Systems Integration Administration Guide - SAP.

Error Handling Codes

TheWindchill ESI business logic uses a five-digit message code each time it invokes the error handling process. This code is used to look up a handling code which determines the behavior of the error handling process. Error handling has several handling codes and each code has permutations of actions which include the following options:

• Send subtransaction messages or do not send subtransaction messages

• Send overall messages or do not send overall messages

• Stop processing or continue processing

Fatal messages (severity "0") are always logged in theWindchill ESI business logic log. Error messages (severity "1") are logged when the corresponding logging flag is set to true. The 5-digit code that was originally used to determine the handling code is also used to determine the message that appears in the log.

The following table gives a high-level overview of each code:

Code/ Action	Severity	Send Sub- transactions Messages to Windchill	Send Overall Transaction Messages to Windchill	Continue Processing¹	Stop Processing
0	None²				X
1	0				X
2	0		X		X
3	0	X	X		X
4	1	X		X
5	1			X

¹ When BusinessWorks flow returns to the point where it was called, it continues to process normally. In some cases however, this may cause erroneous processing such as sending a second PostResult message. It is, therefore, recommended that these codes are used with caution.

² Reserved for internal use - used when the logging process fails.

The following table provides additional information about each error code:

Error Code Number	Windchill PDMLink Notification	Final Action
0	NoWindchill PDMLink notification	Processing stops
1	NoWindchill PDMLink notification	Processing stops
2	Windchill ESI sends a PostResult message toWindchill PDMLink for the overall release transaction.	Processing stops
3	Windchill ESI sends a PostResult message toWindchill PDMLink for the subtransaction as well as for the overall release transaction.	Processing stops
4	Windchill ESI sends a PostResult message toWindchill PDMLink for the subtransaction.	Continues processing and returns to where the error handler was called
5	NoWindchill PDMLink notification	Continues processing and returns to where the error handler was called

Summary of Logging and Error Handling Processes

The following summarizes the functions and differences between the logging and error handling processes:

• Logging occurs in regular, predetermined places in the code whereas error handling is used only when a technical error occurs.

• Logging performs its function and always returns to the point where processing last occurred, even if it was called from within the error handler. Error handling might terminate the process or return to the point from which the error was generated.

• Error handling uses an embedded call to the logging process. The logging process does not use the error handling process unless there is an unanticipated error.

• Customizable handling codes determine error handling behavior; the error handler may log or send subtransaction or overall PostResult messages, and always determines whether the process should terminate.

• Logging writes process data to the log file for easy viewing and logging messages are highly customizable according to locale and system.