GM PI Design Guideline (Draft) v1.4 - Latest on 03292011

GM PI Design Guideline

Version 1.3

Table Contents

1 Introduction..................................................................................................................41.1 Applicability of Guidelines..................................................................................41.2 SAP XI vs. SAP PI..............................................................................................4

2 Interface Patterns.........................................................................................................52.1 Decision Matrix- Framework to establish the interface Pattern..........................52.2 Interface Pattern at GM.......................................................................................7

2.2.1 Enterprise Service Pattern............................................................................72.2.2 Proxy to File (Outbound) / File to Proxy (Inbound)....................................82.2.3 IDOC to File (Outbound) / File to IDOC (Inbound)...................................92.2.4 File to File (Inbound) / File to File (Outbound)..........................................92.2.5 SOAP to Proxy..........................................................................................10

3 Integration Scenario Design Guidelines....................................................................113.1 Software Products and Components..................................................................11

3.1.1 General.......................................................................................................113.1.2 SAP Products and Components.................................................................113.1.3 Non-SAP Products and Components.........................................................12

3.2 Parties and Services...........................................................................................123.2.1 Usage of Parties.........................................................................................123.2.2 Usage of Business Services.......................................................................123.2.3 Usage of Business Systems.......................................................................123.2.4 Decision Criteria........................................................................................13

3.3 Mapping.............................................................................................................133.3.1 Overview on Value Mapping and Structure Mapping...............................133.3.2 Value Mapping..........................................................................................143.3.3 Structure Mapping.....................................................................................153.3.4 Validation Logic........................................................................................163.3.5 Decision Process........................................................................................16

3.4 Routing Approach..............................................................................................183.4.1 General.......................................................................................................183.4.2 Standard Routing Functionality.................................................................183.4.3 Extended Routing Functionality................................................................183.4.4 Decision Criteria........................................................................................19

3.5 ccBPM Usage....................................................................................................193.5.1 General.......................................................................................................19

3.6 Archiving and Deletion of Messages.................................................................213.6.1 General.......................................................................................................213.6.2 Current Restrictions...................................................................................21

3.7 Message Sizing / Packaging – Best Practices....................................................213.7.1 General.......................................................................................................213.7.2 Best Practice for Message Size..................................................................213.7.3 Message Packaging....................................................................................223.7.4 Local Message Processing using advanced adapter Engine......................23

4 SAP PI Error Handling..............................................................................................24GM PI Design and Development Guideline Page 1 of 34 02/04/2011Version .1.0 GM Confidential

4.1 Error Handling Principles..................................................................................244.2 Catagory (Classification) of Errors....................................................................24

4.2.1 Infrastructure Errors...................................................................................244.2.2 Technical Errors.........................................................................................244.2.3 Configuration Errors..................................................................................254.2.4 Functional / Data Errors.............................................................................254.2.5 Programming Errors..................................................................................254.2.6 Design Errors.............................................................................................264.2.7 Authorization Errors..................................................................................26

4.3 Error Handling...................................................................................................264.3.1 Java Stack..................................................................................................264.3.1.1 System Errors.............................................................................................264.3.1.2 Application Errors.....................................................................................264.3.2 ABAP Stack...............................................................................................274.3.2.1 System Errors.............................................................................................274.3.2.2 Application Errors.....................................................................................28

4.4 Error Logging and Tracing................................................................................284.4.1 Error Logging............................................................................................284.4.2 Error Tracing.............................................................................................30

GM PI Design and Development Guideline Page 2 of 34 02/04/2011Version .1.0 GM Confidential

Document ControlAuthor(s)

Team

Comments

Version Revision Date

Author Revision Description

1.0 02/04/2011 Rohit Goyal Initial Draft

1.1 02/21/2011 Rohit Goyal Updated based on inputs from Vic Inglese

1.2 03/07/2011 Rohit Goyal Minor Updates

1.3 03/21/2011 Rohit Goyal Updates based on Rajiv’s comments

1.4 03/24/2011 Rohit Goyal Added Error Handling Section

Approval by Role Approval Date

Approval Signature


1 IntroductionThis document describes the global Process Integration (PI) implementation guidelines to be applied at GM. It addresses SAP integration architects as well as developers implementing interfaces to SAP environments using SAP Process Integration (SAP PI).

It is assumed that readers of this document have a general understanding of the principles of SAP Process Integration.

1.1 Applicability of Guidelines

All guidelines set in this document are valid for Process Integration (PI) using the SAP NetWeaver Platform. The scope of this document is to provide guidelines on how integration scenarios should be designed and developed.

1.2 SAP XI vs. SAP PI

SAP XI is the abbreviation for SAP Exchange Infrastructure being part of SAP NetWeaver 2004. With SAP NetWeaver Release 2004s and onwards, SAP XI has been renamed to SAP Process Integration or for short SAP PI. Throughout this document SAP PI is used to name the respective product, as this is the latest version.


2 Interface Patterns

Interface Pattern is an industry wide terminology, not specific to SAP PI. The usage of interface pattern are typically based on different analogy such as the Adapter usage in PI such as

IDOC to File / File to IDOC Proxy to file / File to Proxy File to File SOAP to Proxy Enterprise Service Pattern Etc.

Or, middleware execution process such as Aggregator Canonical Data Model Content Enricher Content Filters Content Based Router Dynamic Router Message Translator Guaranteed Delivery Request / Reply Acknowledgement Etc..

Based on our understanding, interface pattern at GM is to establish how one could leverage adapters/Formats to build an interface for a given specific integration scenario. It typically drives based on technical implementation of best practices to meet the functional requirements.

2.1 Decision Matrix- Framework to establish the interface Pattern

This decision tree has been devised based on following criterion 1) Enterprise Services - SAP’s future direction to leverage Enterprise services. SAP

has delivered multiple enterprise services that one can view and analyze through ES Workplace (http://esworkplace.sap.com). It is always advisable that one should evaluate these services if it could be used for GM’s specific requirements instead of defining the custom one.


http://esworkplace.sap.com/

2) Always use SAP’s pre-delivered integration content as the first choice of the integration such as SRM Integration Content, MDM Integration Content etc. There are situations where SAP does recommend interfacing without PI between SAP to SAP and those are SAP’s delivered content and don’t require any customization.

3) Use SAP’s standard method instead of defining the custom one. Use standard method - Proxy, IDOC, Enhanced IDOC, BAPI, if it is available. If no standard methods available then use custom proxy as the alternative.

4) Non SAP Integration – Depending upon the non SAP system capability, use different method which GM’s commonly support such as - SFTP, JMS, SOAP, HTTP and JDBC.

Disclaimer - This decision tree provides best practice. Although, every interface will need to be evaluated separately and require architecture decision that may have an exception to this tree.


2.2 Interface Pattern at GM

Here are the GM interface patterns we have established so far and these patterns will cover most of the integration scenarios that are found in GM.

2.2.1 Enterprise Service Pattern

GM’s future integration strategy is to maximize the use of service oriented architecture where the applications are loosely coupled to increase the flexibility whereas the reusability and orchestration between the business processes are maximized. SAP enables businesses to adopt SOA as part of their implementation of SAP solutions. At the heart of SAP's open-standards approach to SOA is the concept of enterprise services - highly integrated Web services, architected with business logic and harmonized semantics that can be accessed and used repeatedly to enable end-to-end business processes.

In working with the Enterprise Services in SAP, the ES (Enterprise Services) Workplace (http://esworkplace.sap.com/sdn) is the central place to view consolidated information about all available Enterprise Services delivered by SAP. It provides various entry points for different roles; from Architects to Process Experts. The ES Workplace is the starting point for SOA adoption, from discovery of services to evaluation of services and development of exemplary proof-of-concept composite applications on a freely accessible hosted SAP Business Suite system landscape for business and technology justification.

With the ES Workplace, you can find Business Objects, Process Components, and their services that are necessary for a business process. You can also find all Integration Scenarios and other objects like deployment units that are necessary for semantic and technical integration of business process.

At the beginning of any integration project, the ES workplace is the first starting point for GM for identifying services which can be used. Using ES workplace, for any given integration requirement, first explore and discover if there is any pre-delivered contents from SAP that meets your data model as well as the business process that can be readily applied. Any perfect match enterprise service should be considered as the first preference for implementation for any given scenarios. Exceptions, though, could exist, if there is a serious drawback in building the interfaces using the Enterprise Services in the ES Workplace. For instance, for a high volume batch type of interfaces, using the IDOC could be preferred in terms of performance and scalability.

If there is a scenario that partially meets your business requirement, the following needs to be considered to use an existing Enterprise Service and extend it.

1) Potential reusability:


If this scenario is highly global or can be leveraged in the near future, it will make sense to extend the existing Enterprise Service to be consumed by various business processes and regions

2) Real time requirement:If this business scenario requires real time integration between systems, with the Enterprise Services being highly oriented for real time transactions, it can be preferred to spend extra time and effort to create the Enterprise Service to meet your requirement

3) Business differentiating Enterprise ServiceIf the scenario using the Enterprise Services giving you a competitive advantage, for instance, creating a killer-app that spans over multiple SAP and Legacy Systems that simplifies your business process, the additional time and effort required for the development can be easily justified.

4) Development costExtending an existing Enterprise Services or creating an Enterprise Services usually requires more time and effort compared to traditional approaches using BAPI, IDOC or RFC interfaces. If the reusability of the given Enterprise Service is very low in nature, it might be more economical to use traditional approaches using BAPI, IDOC or RFC to create this one-off solution

Note - SAP has delivered 1000’s of services which could potentially use for GM’s existing / future requirements. It is always advisable that one should evaluate these services if it could be used instead of defining the custom one. For More information on those services, please refer following link - h ttp://esworkplace.sap.com/

2.2.2 Proxy to File (Outbound) / File to Proxy (Inbound)

Following’s are the recommendation for Proxy based scenarios Proxy is the preferred mechanism then IDOC /BAPI /RFC method as it

integrates with ECC in native XML format with PI. Proxies improves the performance over IDOC and No adapter needed to convert in SAP’s proprietary format such as IDOC/BAPI’s.

Use standard proxies as much as possible. Custom proxies should be used only when you didn’t find any standard IDOC, extension of an IDOC, BAPI’s available.

Custom proxies are preferred then custom IDOC or Custom BAPI’s. Proxies are the base of SAP’s enterprise service oriented Architecture. Mostly

SAP’s services are implemented using proxies underneath to integrate with SAP environment




Proxies could address both Asynchronous and Synchronous requirements depending upon requirement and application you are integrating with. Therefore proxies can address Real time / Near real time / batch job requirements. Although with Proxy to File based pattern, you could only do Asynchronous scenario because of File (Non SAP system) based system.

Proxy to File (outbound) pattern has been identified for 4 GSFt interfaces, where those were earlier implemented based on File to File pattern. E.g. Disbursement (AP) SAP to WPCS, Account Reconciliation SAP to eARMS, Trial Balance SAP to eTBR, AR SAP to WPCS.

File to Proxy (Inbound) pattern has been identified for 1 GSFt interface, where this was earlier implemented based on File to File pattern. E.g Direct Receiving PRIMO to SAP

2.2.3 IDOC to File (Outbound) / File to IDOC (Inbound)

Following’s are the recommendation for IDOC based scenarios IDOC is the preferred mechanism when there is no standard proxy available

but standard IDOC /extension of an IDOC could be possible. Convert standard BAPI into an IDOC, in case, you didn’t find another

standard method such Proxy, IDOC, extension of an IDOC Most of the SAP’s functionality has been encapsulated in the form of

IDOC’s/BAPI’s specially before SAP introduces proxies. IDOC’s are intended to use Asynchronous communication for Near Real-

time / Batch job equiements File to IDOC (Inbound) pattern has been identified for 2 GSFt interfaces.

2.2.4 File to File (Inbound) / File to File (Outbound)

This pattern should be avoided to use with SAP environment. It is highlighted as a pattern for the reason, as GM is currently using many of the interfaces in this category. Followings are the recommendation for File Based interfaces-

This pattern could be leverage only in case where SAP backend offers a standard ABAP report to upload and download files in the required format (and no standard proxy, IDOC, Extension of an IDOC, BAPI/RFC available/could be possible). This is primarily the case for the ERP modules HR, FI and CO.

This pattern can only address batch job requirements. There will be no possibility that you could leverage near-real time requirements without changing interfaces.

This pattern should be carefully evaluated while using for PI interfaces.


2.2.5 SOAP to Proxy

Following’s are the recommendation for Proxy based scenarios This pattern is meant for synchronous requirements (Real time only). Being

this pattern is synchronous in nature, it is recommended to use low volume requirements

This pattern should be used when SAP services needs to be published for other Non SAP environment to consume.

Proxies are preferred mechanism then BAPI or RFC’s. Always try to use standard method in following preferred sequence Proxy, BAPI and then RFC’s.

2.2.4.1 SOAP to RFC (BAPI)

Use this method when standard BAPI/RFC is available to integrate with.


3 Integration Scenario Design Guidelines

3.1 Software Products and Components

3.1.1 General

This section outlines which products and components are to be used to accommodate interface developments in SAP PI. For details on the naming of products and components refer to the naming conventions document. A threefold product structure will be used for integration scenarios where a central product will be used to store common objects which are neither sender nor receiver specific. The following picture shows which development objects have to be placed in which components:

Figure: SLD Components for PI Interfaces

3.1.2 SAP Products and Components

The System Landscape Directory (SLD) contains all SAP Products and Components pre-delivered. These products and components are used for Process Integration Content delivered by SAP. These software components contain only SAP namespaces and should not be modified by the customer. For GM specific interface development, GM versions of the original SAP components need to be created holding GM-specific namespaces. GM PI Design and Development Guideline Page 11 of 34 02/04/2011Version .1.0 GM Confidential

(Non-) SAP System Component

(Non-) SAP System Component

NamespaceActionsMessage InterfaceMessage TypeData TypeData Type EnhancementsExternal DefinitionsImported IDocs & RFCsCommunication Channel Template

NamespaceIntegration ScenarioActions (ccBPM)Integration ProcessInterface MappingMessage MappingImported ArchivesMapping Template

NamespaceActionsMessage InterfaceMessage TypeData TypeData Type EnhancementsExternal DefinitionsImported IDocs & RFCsCommunication Channel Template

Common Component

Sender Product Receiver ProductCOMMON Product

3.1.3 Non-SAP Products and Components

Non-SAP Products and Components don’t come pre-delivered in the SLD and therefore need to be created by the customer.

The change management process needs to be followed for the creation and modification of products and software components.

Products and Software Components in the SLD need to follow the naming conventions as outlined in the GM PI Naming Convention document. Change requests for the creation of products and components will be reviewed for adherence to the naming conventions, and will be rejected if they don’t adhere to the standards.

3.2 Parties and Services

3.2.1 Usage of Parties

Parties should be used for B2B scenarios to represent GM’s business partners. Therefore a communication party will represent a company. As defined in the naming conventions, parties should be created using the company name, and specific identifiers such as DUNS numbers can then be maintained for these parties.

3.2.2 Usage of Business Services

A business service represents an abstract unit describing a sender and/or receiver of messages. Business services should be used in cross-company processes where the system landscape or Business Systems are not known. In these cases Business Services have to be assigned to a party. In general, they should not be used in internal communication where we know the system involved. One exception to this rule is when Web Services are made available or are being called through PI. In this case, a Business Service can be used in order to allow the Web Services to be handled independent from a specific system.

3.2.3 Usage of Business Systems

Business Systems represent actual application systems in a system landscape. Business Systems should be used for all internal communication except for Web Services made available on PI. Business Systems have to be defined in the System Landscape and should be named either using the actual vendor’s product name or the name under which the system is commonly known within GM.


In case of SAP Systems, business systems are usually associated with a unique logical system name which is used in IDoc communication.

3.2.4 Decision Criteria

Figure: Decision Diagram for Business System Usage

3.3 Mapping

3.3.1 Overview on Value Mapping and Structure Mapping

Figure: Value Mapping vs. Structure Mapping (Source: SAP Training TBIT40)


Structure mapping is the transformation from one message structure into another. Value Mapping is the transformation of a values representation.

Typically a mixture of structure mapping and value mapping will be needed in integration scenarios.

3.3.2 Value Mapping

During message transformation, it might become necessary to convert the value of a source message element into an acceptable value for the corresponding target element.

For example, the State Pennsylvania may have the code “PA” in the sending system, but might be represented by the value “PENNSYLVANIA” in the receiving system. In order for the receiving system to interpret the State specified in the inbound message correctly, the code must correspond to the correct value maintained in the receiving system.

The above problem can be generalized to state that certain objects are represented by different codes in different applications and therefore a value translation needs to be carried out at runtime. The data that has to be covered by such value translations is business related and thus has to be maintained by the responsible business group within a business system. As PI is not an application system, it will not hold value mapping data, but rather call a service from within a PI mapping to get the valid value translations. The Web Service can reside on any system either the sending / receiving system or any other system that is capable of providing Services. This service can be called using either SOAP, JDBC or RFC based. SOAP call is preferred mechanism.


Figure: Value Mapping Service

3.3.3 Structure Mapping

Structure Mappings are mappings that translate from one systems structure to another systems structure. Within PI there are four different mapping methods as follows – 1) Message Mapping2) Java Mapping 3) XSLT Mapping4) ABAP Mapping

Always consider message mapping as first option. If a message mapping alone is not sufficient, it can be extended with user defined functions and initialization blocks.

If the mapping requirements are too complex for the message mapping tool, consider using Java mapping. When implementing Java mappings, special consideration of the XML parser to be used is necessary. The most widely used XML parsers are SAX and DOM which both have their advantages and disadvantages. DOM allows random access to the document but it is rather memory intensive, especially for large documents. SAX


on the other hand is memory efficient and can parse messages of any size, but allows only sequential, not random access to the document.

In GM Environment, XSLT and ABAP Mapping are discouraged to use. For exception cases, one should review with Architect /Designer for an approval.

3.3.4 Validation Logic

There are two types of validation logic could be possible during interface processing – A) Integration Logic related Validation –

Check message (incoming) completeness E.g. All mandatory fields are populated, Format should be as desired (Tab delimited, comma separated etc), Value of the fields are populated as expected (e.g. Date field is expected in MMDDYYYY)

Default value population- Static default value should be populated Cross –reference related validations Transformation logic related validations

Recommendations - SAP PI should be used for Integration Logic related Validation

B) Business Logic related Validation Master Data Missing in Backend System (e.g. ECC)

E.g Material is not available in ECC for goods movement interface Configuration Missing

E.g. Validity of Accounting period for GL Account, Cost Center is not valid for a given combination of plantRecommendations - SAP ECC (or Backend System) should be used for Business Logic related Validation

3.3.5 Decision Process


Figure: Decision Diagram for Mapping Usage


3.4 Routing Approach

3.4.1 General

Routing in PI consists of two parts: logical routing which is used to determine the logical receiver(s) and to branch messages if more than one receiver has been determined, and technical routing which is used to determine the physical location to which a message is to be sent.

Logical routing determines the logical receiver(s) of a message for a given logical sender, and consists of the following two steps:

Receiver determination during which a receiver system is assigned to the sender interface of a sender

Interface determination during which a receiver interface in the receiver system is specified

3.4.2 Standard Routing Functionality

Standard routing functionality allows defining receivers based on sender and message, receiver pre-identification by the sending application or defining receiver based on payload values. For all these options, the receiver name needs to be known at configuration time. If the receiver is not known during configuration time, the extended routing functionality can be used, where a receiver can be determined within a mapping.

3.4.3 Extended Routing Functionality

The extended receiver determination allows determining the receiver based on payload values within a separate mapping. Requiring an extended receiver determination as a manual definition of all conditions is not a practical solution.


3.4.4 Decision Criteria

Figure: Decision Diagram for Routing

3.5 ccBPM Usage

3.5.1 General

Use ccBPM when it is necessary. Before one use ccBPM, evaluate with designer / Architect, if it is must to use for given GM’s specific requirement.

The usage of ccBPM (also Integration Process) may sometimes be required if integration scenarios go beyond simple send / receive scenarios. Indicators for the usage of ccBPMs are:

Necessity for stateful message processing (correlation between messages)

Bridging of communication modeGM PI Design and Development Guideline Page 19 of 34 02/04/2011Version .1.0 GM Confidential

Complex error handling / monitoring requirements (e.g. Deadline Monitoring)

Multi Mappings (n:1 and n:m)

Time controlled message processing

Serialization of different message types

Message Collection

Some situations where ccBPMs have been required in the past can be handled with PI standard functionality within the current version. This includes especially complex content based routing and message splitting.

ccBPMs tend to be less efficient than standard message processing, and there are a couple of indicators that discourage the use of an Integration Process. The main indicators are:

High volume of messages

High Frequency of messages

Large Messages


3.6 Archiving and Deletion of Messages

3.6.1 General

Within PI there are two ways to handle messages once they have been processed. Messages can either be deleted from the database permanently, since the task of transferring the data has been successful and the data is available in the sending and receiving system, or messages can be archived. Archived messages are deleted from the database but only after being transferred to a special archive from which they can be retrieved again.

In general it should be sufficient to delete messages once they have been successfully processed as PI is not the book of record and does not hold any application data, however archiving configuration is based on specific interfaces so archiving can be configured on request if an integration scenario has special (potentially legal) requirements. Typically such requirements should only be present in B2B and not in A2A scenarios.

3.6.2 Current Restrictions

With the current release stack the following restrictions for Archiving do exist:

Retention Periods can only be defined overall and not per interface Archived messages cannot be accessed through Message Monitoring but only

through specific transactions Searching for archived messages is limited to the message ID

3.7 Message Sizing / Packaging – Best Practices

3.7.1 General

There are few methods for increasing the performance of message processing of very large messages.

3.7.2 Best Practice for Message Size

Optimized Message size can improve the through put. This below diagram typically observes when measuring the message throughput for different message sizes.


(SAP Source: - SAP PI Sizing and Performance Tuning)

Recommendations – Use reasonable message sizes to improve performance, to avoid memory

overflows and to increase overall system stability.

At design time, consider that the message throughput is much higher for larger messages due to the necessary processing overhead for a single message. On the other side, the memory consumption is higher for processing larger messages.

The best practice is to keep the average message size in the range of 1 MB to 5 MB

3.7.3 Message Packaging

Message packaging technique is used to group together asynchronous messages in packages and then process each message package in one logical unit of work. Packaging can be created either in sender system or central Integration Engine. Packages can be received and saved in the receiver system. They are then processed as individual messages.

Use message Packaging in the Integration Server in the following cases: Intended for small asynchronous messages Best results when using proxies Leads to throughput improvements


Factors affecting Packaging Message Size Frequency System Load - number of present messages that could be packed together and

waiting

(SAP Source: PI Sizing Guide)

3.7.4 Local Message Processing using advanced adapter Engine

Processing messages locally using the Advanced Adapter Engine (AAE) can increase performance considerably, since the Integration Server is bypassed. With this, Message processing services do not go between ABAP and Java stack and eventually improves the performance. However usage of advanced adapter engine has certain restriction – - Cannot configure dynamic receiver determination- Cannot use integration processes as communication component - Cannot configure mapping based - message splitting

In addition to this, following adapter types are not supported in current release– IDOC, XI, HTTP, RNIF, CIDX, and WS.

With SAP PI7.3, there will be major shift from dual stack to AAE. IDOC and HTTP adapter will be included as part of advanced adapter engine along with message split functionality.


4 SAP PI Error HandlingSAP PI Error Handling section primarily focused to provide overall guidelines around Error Handling Principles, Categorization (Classification) of Errors, Handling Errors (System and Application) within Java and ABAP Stack, Error Logging and Tracing mechanism within PI Infrastructure. These guidelines should be used by developers to design PI interfaces to address error handling needs at GM.

4.1 Error Handling Principles

At GM, following principals should be used for Error Handling- 1) Exception/Alternate Flows should be defined in Blue Prints/Use Cases with

explicit requirements on what should be displayed and next actions2) All error messages shown to users will be based on their locale except the

standard SAP Error codes 3) All errors codes will follow a pre-defined error codes pattern except the standard

SAP Error codes 4) Include error and exception handling requirements as Non Functional

Requirement (NFR)o End user error messages must be informative and include what the end

user should do next….o Exception and Failure Handling Components of the solution shall

gracefully handle and not suppress exceptions, failures, or interrupts. o Systems/Applications should distinguish between

Users Errors Client side technical/system errors (client can be front end or

service consumer) Server side technical/system errors

4.2 Category (Classification) of Errors

4.2.1 Infrastructure Errors

Infrastructure Errors are errors on the PI environment which are not related to a specific integration scenario but rather do have a technical reason. Technical reasons can either be related to the PI system itself or to hardware and operating system problems. Infrastructure errors will be handled by the PI infrastructure team.

Examples

Downtime of Adapter Engine or J2EE EngineHardware FailureTablespace full


4.2.2 Technical ErrorsTechnical Errors are errors in an Interface which are solely caused by technical reasons such as connection problems etc. Technical errors can be resolved by the administration and support group without involving the Business as the data sent is valid and the reason for the error is not business related.

Examples

Timeout during communicationOutdated Cache Content

4.2.3 Configuration ErrorsConfiguration errors are related to incorrect configuration in PI leading to an abortion in the processing of the data. Configuration errors are typically encountered during the development and testing phases and can be fixed by the developer or configurator of the particular integration scenario.

Examples

Wrong quality of service configuredReceiver Agreement missing

4.2.4 Functional / Data ErrorsFunctional errors are errors in an Interface which are related to the data being sent. Functional errors can be data being sent in the wrong XML format, wrong data elements such as unknown material numbers etc. The most common functional error is a failure when executing a mapping due to the source structure or source data being wrong.

Examples

Wrong or incomplete message being sentMissing entries in Value MappingMapping throwing exception intentionally

4.2.5 Programming ErrorsProgramming Errors are errors where the programming of an interface differs from the actual intended functionality. These errors might either be encountered during string testing and subsequently being fixed, or may go unnoticed for a long time until a certain


set of potentially rare circumstances causes them to become active. If such errors are encountered during the productive lifecycle of a program, they are also referred to as “Bugs”.

Examples

Programming errors in Mappings

4.2.6 Design ErrorsDesign Errors are errors where the design of an interface differs from the actual intended functionality. These errors might either be encountered during string testing and subsequently being fixed, or may go unnoticed for a long time until a certain set of potentially rare circumstances causes them to become active. If such errors are encountered during the productive lifecycle of a program, they are also referred to as “Bugs”.

Examples

Mapping of wrong structure / data

4.2.7 Authorization ErrorsAuthorization errors will occur if the user id used in message processing does not have sufficient authorizations to execute a task. This can be users in connections from a sending system to PI as well as users in connections from PI to a receiving system.

Examples

Error when sending IDoc to SAPError when calling RFC

4.3 Error Handling

4.3.1 Java StackThe Following errors can be handled by SAP PI

4.3.1.1 System ErrorsSystem Errors will be triggered by messaging system during message transfer such as due to a failed server. These errors can be detected when a message is being transferred, using the exception class ‘SystemFaultException’, so that system can display the error message. The full


name of the exception class for system errors is: ‘com.sap.aii.proxy.xiruntime.core.SystemFaultException’

4.3.1.2 Application ErrorsIn the Enterprise Service Repository (IR), one can define the fault messages to handle application errors.

The proxy generation functions generate exception classes for fault messages in the Enterprise Services Repository. If an application triggers an exception using an exception class such as this, the proxy runtime automatically converts it to a fault message. Using the fault message, the application records an application error (for example, Requested Customer Profile Unknown).

Exception classes for application errors are derived from the basis exception class ApplicationFaultException. The full name of the exception class for application errors is: com.sap.aii.proxy.xiruntime.core.ApplicationFaultException.

Structure of Fault Message

In the fault structure, STANDARD contains fields essential for forwarding the errors. The structure ADDITION can be used freely by the application.

4.3.2 ABAP StackThe Following errors can be handled by ABAP Stack


4.3.2.1 System ErrorsSystem errors will be catch during the transmission of a message using the exception class CX_AI_SYSTEM_FAULT. One can distinguish system errors using error codes; these are managed and documented centrally for all systems. The application can display an error message using the attributes CODE and ERRORTEXT of the exception class.

4.3.2.2 Application Errors

Fault Messages (As described in earlier section) are provided to handle application errors in ABAP stack too. Exception classes for application errors are derived from the basis exception class CX_AI_APPLICATION_FAULT. One can use this exception class to determine an error situation - independently of the exact error - or in a CATCH branch, to catch all the errors that have not yet been handled.

4.4 Error Logging and Tracing

4.4.1 Error LoggingUse a standard framework to insert a logging statement within the code to produce informative logs at runtime. Logs are useful for troubleshooting or error analysis scenarios. The simplest form of logging from a java code is to use System.out.println or to use printStackTrace() but these statements are imbedded within the code and cannot be turned disable easily. The framework offers similar logging capability but provides the following added benefits:

An easy to use API Performance – the switching on of the logging mechanism does not effect

performance Easy to maintain – the log insertion is decoupled from the execution code Switching on or controlling the amount of output is configurable at runtime

without modifying source code.

There are four steps to enable logging in an application

1) Identify a source code area (for example, a class Node) and represent it with a Location object:

Location loc = Location.getLocation("<package>.Node");

2) Assign a severity level to the source:

loc.setSeverity(Severity.WARNING); //default: Severity.NONE

3) Specify an output destination:GM PI Design and Development Guideline Page 28 of 34 02/04/2011Version .1.0 GM Confidential

loc.addLog(new ConsoleLog());

loc.addLog(new fileLog(“//logs//output.log”));

Note: Use either format or both to write to both locations.

4) Write out the actual message with specified severity:

loc.entering(methodname);

loc.debugT(methodname, message);

loc.fatalT(methodname, message);

Step 2 and 3 Should be configured externally so that users can control the output without the need to modify the source code and recompile again.

Example:

package com.sap.fooPackage;

import com.sap.tc.logging.*;

public class Node {

private static final Location loc =

Location.getLocation("com.sap.fooPackage.Node");

public void announce(Object o) {

String method = "announce(java.lang.Object)";

loc.entering(method);

try {

// do something...

loc.debugT(method, "Connecting to …");

} catch (Exception e) {

loc.fatalT(

method,

"Error processing object {0}",

new Object[] { o });

}


loc.exiting();

}

}

Steps 2 and 3 are not shown at this point, so you should therefore assume that the severity level assigned to this is Severity.ALL (accept all severity levels and output everything) and the output has been piped to a ConsoleLog (terminal).

4.4.2 Error TracingTrace level should be set correctly which enables message trace to be visible in message monitoring transaction (SXMB_MONI).

There are three methods that can be called to write trace information:

Method Usevoid addInfo(String message); Adds a message message to the mapping trace

with the trace level info.void addWarning(String message);

Adds a message message to the mapping trace with the trace level warning.

void addDebugMessage (String message);

Adds a message message to the mapping trace with the trace level debug.

The Integration Trace level must be set appropriately for trace information to appear in the trace log. Valid Trace level are:

Pipeline Mapping Trace0 No trace1 addWarning()- Entries written to trace2 addWarning()and addInfo()- Entries written to trace3 addWarning()and addInfo()and addDebugMessage()- Entries written to trace

Tracing can be set at the Integration Engine level or at the message level by setting an entry in the Message Header.

Integration Engine setup

Use the following configuration settings:

Go to Integration Engine Configuration (SXMB_ADM)Select Category RUNTIMEGM PI Design and Development Guideline Page 30 of 34 02/04/2011Version .1.0 GM Confidential

click Specific ConfigurationChange or Add Parameter TRACE_LEVEL and set value to 1,2 or 3

Message Header Setup

Set one of the following in the message header:

<SAP:Logging>1</SAP:Logging><SAP:Logging>2</SAP:Logging><SAP:Logging>3</SAP:Logging>

Example:

MappingTrace trace;trace = container.getTrace();

// Write to trace trace.addInfo("A mapping error has occurred. Table: COMP, Key: SrcComp = 1200, RtnField: SAPComp");

Example Output from SXMB_MONI



Documents

GM PI Design Guideline (Draft) v1.4 - Latest on 03292011