AP 7.

00 Development guideline for implementing Tax Engine user exit for exchange of custom fields with External Tax Engine.
VERSION 1.0 JULY 2012

CHANGE LOG
Change Version 1.0 Name Sandeep Divakaran Date July, 2012

Version Date Editor Modification

CONTENTS
Change Log.....................................................................................................................2 Contents .........................................................................................................................3 1 Motivation to run the configurator on VMC ...................................................5 2 Developing Tax Engine User Exit...............................................................................6 2.1 Setting up Java..............................................................................................6 2.2 Setting up Eclipse...................................................................................6 2.3 Downloading the tax engine-libraries ....................................................................6 2.4 Setting up the eclipse project..................................................................................7 2.5 BAdi implementation to enable passing of custom input fields from ABAP to Tax Engine JAVA............................................................................................................7 2.5.1 Using transaction properties to supply custom input fields to be exchanged with External Tax Engine...............................................................................................8 2.51.1 Customizing setting............................................................................................8 2.5.1.2 BAdi implementation to fill the runtime values to the custom fields.....9 2.5.2 Using pricing attributes to supply custom input fields to be exchanged with External Tax Engine.......................................................................................................9 2.5.2.1 Customizing setting...........................................................................................9 2.5.1.2 BAdi implementation to fill the runtime values to the custom fields. ..........9 2.6 Creating and registering Tax Engine user exit....................................................10 2.6.1 Extend the exit adapter class. ...........................................................................10 2.6.2 Overriding the methods of the adapter class...................................................10 2.6.2.2 Overriding the method preProcessRequest of the adapter class................10 2.6.2.3 Overriding the method postProcessRequest of the adapter class..............12 2.6.2 Registering of user exit.......................................................................................13 2.7.5 APIs to enable retrieval of custom fields from Tax Engine.............................13 2.7.5.1 Retrieving custom fields in an ABAP context................................................13 2.7.5.2 Retrieving custom fields in a non-ABAP context..........................................14 2.7 Creating a jar from the Tax Engine user exit.......................................................14 2.8 Uploading the Tax Engine user exit......................................................................14 2.9 Deleting uploaded Tax Engine User Exit..............................................................15 Debugging.....................................................................................................................15 3.1 Set VMC in Debug Mode .......................................................................................15 3.2 Attach Eclipse Java Debugger..............................................................................16 4 VMC logging and tracing overview..........................................................................16 4.1 Prerequisites..........16 4.2 Using VMC logging and tracing ...........................................................................17 4.2.1 Use........................................................................................................................17 4.2.2 Features ...............................................................................................................17 4.2.3 Activities ..............................................................................................................18 4.3 Displaying Log Messages..................................................................................18 4.3.1 Use........................................................................................................................18 4.3.2 Procedure.........................................................................................................18 4.4 Displaying and Changing Log Settings................................................................19 4.4.1 Use........................................................................................................................19

4.4.2 Procedure.............................................................................................................20 4.4.3 Result....................................................................................................................20

1. Motivation to run the Tax Engine on VMC

The VM Container technology enables a Java VM to be integrated in the ABAP work process (see Architecture of the SAP NetWeaver Application Server, section Technical Components). Formerly the Tax Engine was executed within a server infrastructure called IPC. Now it is run on the SAP VM Container. The execution of applications on the Java VM integrated in the ABAP work process is only intended for components developed by SAP. The VM container technology in connection with a Java VM integrated in the ABAP work process provides the following advantages: Reliability and maintainability as in the ABAP environment The integration of the Java VM into the ABAP work process enables strict isolation between active user sessions, which guarantees a large degree of robustness and maintainability. One work process can only process one user request at a time, which means that even if one entire Java VM crashes, only the one user active at this time is affected. Close ABAP/Java communication (in-process) Since the ABAP and Java VMs run in the same work process, a quick and efficient communication path can be implemented between the two languages, which mean that the security and speed of the communications is significantly increased. For more information see SAP JCo and VM Container. Administration and Sharing of Resources While a request is being processed a Java VM works exclusively for one user. There is a pool of VMs dynamically assigned to the work processes. These VMs can access shared data in the shared memory. Java shared closures Java objects can be moved across process boundaries and shared by processes. This enables an efficient session failover to be implemented. At the same time shared closures offer the option of reducing the memory consumption of the entire system through process-wide caching. Shared class pool Java classes only have to be loaded into the memory once, the same as for ABAP PXA, and they can be used by all the processes in the system. This reduces the memory consumption and the start time of further processes. High Supportability Since the JTS uses existing SAP kernel technology, the monitoring functions of the CCMS can be used. For the reason, the familiar SAP statistics can also be used (see Statistics in the VM Container).

 Debugging Each user can dynamically switch to and fro between normal operation and debugging.
5

2. Developing Tax Engine User Exits

This chapter describes how to develop Tax engine user exits and how it can be used to exchange custom fields with External Tax Engine in AP 7.00.

2.1 Setting up Java

The tax engine user exits shall be compiled with the J2SE 1.4.x or a compatible java compiler of version 1.4.x. Also the used libraries must be compatible with J2SE 1.4.x. The java development kit is available for download using http://java.sun.com/downloads. A standard installation of the JDK is sufficient

2.2 Setting up Eclipse

Eclipse 3.0 or 3.1 is recommended and can be downloaded using http://www.eclipse.org/downloads. A simple unpacking of the downloaded file is all that is needed to install eclipse. The eclipse-IDE manages the files in projects and the projects in workspaces. A workspace contains all administrative data of eclipse. Project files, like java source files, may lie also in that workspace but can also be outside.

2.3 Downloading the tte engine - libraries Following steps will download the tte engine libraries:
Start your SAP GUI, log in and start transaction /SAPCND/UE_DEV. Create a folder to place the classes. Check the 'download' section, type the above folder (or use F4 to navigate there) and press F8 to download the classes into the already created folder, lets call this folder $TTE_CLASSES$ for further references. The class files can be found in $TTE_CLASSES$/lib_api.

Transaction /SAPCND/UE_DEV also allows to upload classes to path com.sap.taxes.userexit.external 6

2.4 Setting up the eclipse project

Assumptions: Eclipse is installed Workspace is created, Project is set up for developing user exits for the Tax Engine.

All you have to do is including the $TTE_CLASSES$/lib_api to your projects libraries. This folder includes all needed libraries from com.sap.taxes.* in addition to pricing and configuration classes.

2.5 BAdi implementation to enable passing of custom input fields from ABAP to Tax Engine JAVA
There are two ways to pass custom input fields from ABAP to Tax Engine JAVA so that it can be passed from Tax Engine to External Tax Engine: Using transaction properties to supply custom input fields to be exchanged with External Tax Engine. Using pricing attributes to supply custom input fields to be exchanged with External Tax Engine.

2.5.1 Using transaction properties to supply custom input fields to be exchanged with External Tax Engine 2.51.1 Customizing setting

In the above customization, transaction properties have to be defined, mentioning the transaction property types and the values these transaction property

types could take. These transaction property types would be the internal field names used when mapping of custom exchanged fields.

2.5.1.2 BAdi implementation to fill the runtime values to the custom fields.
The BAdi BADI_TTE_DOCUMENT has to be implemented where the custom fields would be set with their internal field names to their corresponding values. The internal field name should be the same as the transaction property type defined in customizing earlier. BAdi BADI_TTE_DOCUMENT has method TTE_INPUT_DOC_CHANGE which has parameter CT_TRANPROP of type TTEPDT_TRANPROP_COM_TT. The type TTEPDT_TRANPROP_COM_TT is a table type with line type: ITEMID TRANSPROPERTYTYP TRANSPROPERTYVAL CHAR 32 CHAR 4 CHAR 30

Using the above data, the custom fields could be filled with appropriate values at runtime. Also, it should be noted that the internal field name would be the same as the transaction property type.

2.5.2 Using pricing attributes to supply custom input fields to be exchanged with External Tax Engine 2.5.2.1 Customizing setting
The pricing field catalogue has to be extended to incorporate the custom field names. This would be the internal field names.

2.5.1.2 BAdi implementation to fill the runtime values to the custom fields.
The BAdi CRM_COND_COM_BADI has to be implemented where the custom fields would be set with their custom internal field names to their corresponding values. The custom internal field name should be the same as the transaction property type defined in customizing earlier. BAdi CRM_COND_COM_BADI has method ITEM_NAME_VALUE which has parameter CT_ITEM_NAME_VALUE of type PRCT_ATTR_NAME_VALUES_T. The type PRCT_ATTR_NAME_VALUES_T is a table with line type: ATTR_NAME SEQ_NUMBER ATTR_VALUE CHAR 30 NUMC 2 CHAR 50

Using the above data, the custom fields could be filled with appropriate values at runtime. Also, it should be noted that the custom internal field name would be the same as the pricing attribute name.

2.6 Creating and registering Tax Engine user exit

Within the above created project you can create user exits for Tax Engine. The tax related apis to be used in implementing Tax Engine user exit would be found at com.sap.taxes.userexit.*.

2.6.1 Extend the exit adapter class.

Create a class extending the class ExtTaxEngineUserExitAdapter. It contains the following methods: preProcessRequest postProcessRequest

2.6.2 Overriding the methods of the adapter class 2.6.2.2 Overriding the method preProcessRequest of the adapter class
The method preProcessRequest would be called by Tax Engine just prior to the call to External Tax Engine. This could be overridden to provide the mapping of custom fields to be used by Tax Engine and also transform the custom fields before passing it over to the External Tax Engine. The following parameters are part of the method signature of method preProcessRequest: parameter tteInDoc of type ITteInputDocumentUserExit parameter tteInItem of type ITteInputItemUserExit parameter inToExtFldMapper of type IExtTaxInputFieldMapper parameter extFldValueSupplier of type IExtTaxDirectInputValueSupplier

Parameter Type ITteInputDocumentUserExit has the method: getInputItems() This can be used to retrieve all the input items

Parameter Type ITteInputItemUserExit has the methods: getItemID() This can be used to get the item id of the relevant item as a string

getTransactionProperties() This can be used to get the transaction property container as a type ITransPropertiesUserExit. ITransPropertiesUserExit has method get(String type) to get specific transaction property type - value as a type ITransPropertyUserExit giving the property type name as string. Further, ITransPropertiesUserExit has methods: getTransPropertyTyp() This can get the relevant transaction property type as string. getTransPropertyVal() This can get the relevant transaction property value as string.

Parameter type IExtTaxInputFieldMapper has the method: setInternalToExternalFieldMap(String intFldName, String extFldName) This can be used to set the which custom internal field is mapped to which custom external field by providing the field names for the custom internal field and the custom external field as strings.

Parameter type IExtTaxDirectInputValueSupplier has the method: setExtFldValue(String extFldName, String value) This can be used to set a specific custom field value for an custom external field name, by providing the custom external field name and the specific value for the custom external field as strings.

The above mentioned parameters and methods can be used to transfer custom fields into External Tax Engine. There are two types of mapping mechanisms provisioned: Input Field mapping This can be used to provide mapping of which custom internal field would be mapped to which custom external field by specifying the custom field names in the mapping. Parameter inToExtFldMapper (type IExtTaxInputFieldMapper) of method preProcessRequest can be made use of to achieve this. Direct Value Setting This can be used to provide a specific value to be set into a custom external field by specifying the custom external field name and the custom external field value. This is especially useful if you would want to transform the value provided by the custom internal field in some way in the user exit before passing it over to the External Tax Engine. Parameter extFldValueSupplier (type IExtTaxDirectInputValueSupplier) of method preProcessRequest can be made use of to achieve this.

2.6.2.3 Overriding the method postProcessRequest of the adapter class

The method postProcessRequest would be called by Tax Engine just after the call to External Tax Engine returns with results. This could be overridden to provide the mapping of custom fields to be used by Tax Engine when retrieving the result from External Tax Engine. The following parameters are part of the method signature of method preProcessRequest: parameter tteOutDoc of type ITteOutputDocumentUserExit parameter tteOutItem of type ITteOutputItemUserExit parameter extToInFldMapper of type IExtTaxOutputFieldMapper

Parameter Type ITteOutputDocumentUserExit has the method: getOutputItems () This can be used to retrieve all the input items

Parameter Type ITteOutputItemUserExit has the methods: getItemID() This can be used to get the item id of the relevant item as a string

Parameter type IExtTaxOutputFieldMapper has the method: setExternalToInternalFieldMap ((String extFldName, String intFldName) This can be used to set which custom external field is mapped to which custom internal field by providing the field names for the custom external field and the custom internal field as strings.

The above mentioned parameters and methods can be used to transfer custom fields from External Tax Engine into Tax Engine. This can be done only via Output field mapping mechanism. This can be used to provide mapping of which custom external field would be mapped to which custom internal field by specifying the field names in the mapping. Parameter extToInFldMapper (type IExtTaxOutputFieldMapper) of method postProcessRequest can be made use of to achieve this.

2.6.2 Registering of user exit

The maintenance view TTEV_USREXIT_REG is provided for user exit registration. Here, the following fields need to be mentioned: Exit Type This should be the type of user exit. In this case, the value would be ETP External TaxEngine Pre and Post Processor. Exit Name This should be the fully qualified name of the customer java class that implements the user exit.

2.7.5 APIs to enable retrieval of custom fields from Tax Engine

The custom fields given back by External Tax Engine can be retrieved from Tax Engine in both the ABAP and non-ABAP context as described below:

2.7 5.1 Retrieving custom fields in an ABAP context

Following pricing APIs could be used: PRC_PD_ITEM_SHOW This has the parameter ES_ITEM_WRK of type PRCT_ITEM_WRK. The type PRCT_ITEM_WRK contains a component DYNAMIC_RETURN of type PRCT_ATTR_NAME_VALUE_T. The type PRCT_ATTR_NAME_VALUE_T is a table type of line type PRCT_ATTR_NAME_VALUE: ATTR_NAME CHAR 30 SEQ_NUMBER NUMC 2 ATTR_VALUE CHAR 50 PRC_PD_ITEM_INPUT - This has the parameter ET_ITEM_RET of type PRCT_ITEM_RET_T. The type PRCT_ITEM_RET_T is a table type of line type PRCT_ITEM_RET_COM. The type PRCT_ITEM_RET_COM has the component DYNAMIC_RETURN of type PRCT_ATTR_NAME_VALUE_T. The type PRCT_ATTR_NAME_VALUE_T is a table type of line type PRCT_ATTR_NAME_VALUE: ATTR_NAME CHAR 30 SEQ_NUMBER NUMC 2 ATTR_VALUE CHAR 50

2.7 5.2 Retrieving custom fields in a non-ABAP context

The following pricing RFC could be used: SPC_GET_PRICING_DOCUMENT_INFO - This has the parameter ET_ITEM_RET of type PRCT_ITEM_RET_T. The type PRCT_ITEM_RET_T is a table type of line type PRIT_ITEM_RET. The type PRIT_ITEM_RET has the component DYNAMIC_RETURN of type PRCT_ATTR_NAME_VALUE_T. The type PRCT_ATTR_NAME_VALUE_T is a table type of line type: ATTR_NAME CHAR 30 SEQ_NUMBER NUMC 2 ATTR_VALUE CHAR 50

2.7 Creating a jar from the Tax Engine user exit

The above created user exits and the helper classes have to be packed into a jar-file. A manifest should be added to the META-INF-folder to identify the creation date and the version by using the VMC-administration. Hint: You should add the sources to the jar-file. Doing this you can always download the matching sources for error analysis, debugging and you can use the system as your source code repository for your user exits. Eclipse provides a jar packager that easily allows to create the needed jar-file. You can start the packager using the context menu of the project and choosing Export =>JAR file and you reach the wizard for creating jar-files. For convenience save your entries in the project. Lets call the jar-file for simplicity customer_tte_userexits.jar (can be named arbitrarily).

2.8 Uploading the Tax Engine user exit

Uploading the customer_tte_userexits.jar file to the database is done via transaction /SAPCND/UE_DEV. This task requires advanced authority settings. Following authorization objects are concerned: S_CTS_ADMI Administration Functions in Change and Transport System S_DATASET Authorization for file access S_DEVELOP ABAP Workbench S_GUI Authorization for GUI activities S_TCODE Transaction Code Check at Transaction Start S_VMC_TRAN Transport of Java Development Objects

The libraries upload needs: A modifiable workbench request which must be already existing An ABAP package created by the customer beforehand The path to customer_tte_userexits.jar. The uploading is triggered by the execute button or pressing F8. The jar-file shall only contain customer coding. Uploading any other class belonging to a package com.sap.* than to package com.sap.taxes.userexit would possibly overwrite existing classes and therefore lead to an unexpected behaviour of SAP applications running on VMC. If you upload user exits to an (ABAP) package that was already used for uploading user exits, all Java classes previously uploaded to the package are deleted and replaced by the new Java classes contained in the jar-file. The VMC can cope with hot-deployment of Java-classes. No server restart is necessary. If you upload an empty jar-file, you delete the previously uploaded Java classes. The transport of Java classes is as transparent as the transport of ABAP code.

2.9 Deleting uploaded Tax Engine User Exit

As already said in the previous chapter you delete already uploaded user exits by repeating the upload with an empty jar-file. This is the only way of deleting uploaded user exits. 9

3 Debugging
3.1 Set VMC in Debug Mode
The logical application server is usually hosted on different servers and load balanced via the message server. To debug the VMC the user has to know on which host his work process run. In the SAPGUI menu System -> Status the Server name (first part) is displayed. On the next page (3rd button) also the corresponding IP address is given. Switching between hosts of one server can be done via transaction sm51. Run transaction sm52 to display the available VMCs. This window will later show the servers running virtual machines and also the debug state and port of each one. A VMC work process switches into debug mode when a program flow from ABAP to Java (RFC function module) is passed and ABAP was in debug mode (with /h). Debugging RFCs from the WebUI is quite hard and has to be reworked!

While running the transaction (e.g. order processing) each call to pricing will hold and with a step-into debugging into the RFC module (F5) a VMC debug port will be activated. This VMC will stay attached as long the ABAP transaction runs.

3.2 Attach Eclipse Java Debugger

After a VMC work process has an open debug port, which can be viewed with transaction sm52, the eclipse debugger can be attached to it. Because attaching the debugger to the VMC will run directly the code, the java breakpoint must be set before attaching. Attaching eclipse works as follow: Open menu Run->Debug Create a new Remote Java Application Configuration Enter as host the server where the VMC work process is running on Enter the debug port as the one VMC work process debug port shown in transaction sm52 Click on Debug

The debugging view will normally popup automatically and a successful attachment will show all working threads of that VMC work process. Because debugging real RFC-calls is quite hard the following chapter explains tracing and logging concepts. 10

4 VMC logging and tracing overview

4.1 Prerequisites
With the VMC System Administration (transaction SM53) you can monitor all the settings in the environment of the SAP Virtual Machine Container (VMC) and carry out administration tasks. The transaction is intended for use by administrators, SAP consultants, and SAP support. You need authorization for the transaction. This is configured in authorization object S_VMCADMIN. Profile S_VMCADMIN_1 gives display and change authorization. Profile S_VMCADMIN_2 only gives you display authorization.

The profile S_VMCADMIN_2 suffices to change the log levels and changing jarm-settings. Thus this profile is the minimum prerequisite to work with tracing and logging! In transaction SM52 you can see an overview of all the running Java VMs in the VM Container

4.2 Using VMC logging and tracing 4.2.1 Use

Logging and tracing are invaluable tools for handling any problems that may occur in programs. Users can look up in log files what the exact problem is. Administrators and developers can identify from the traces what the cause of the problem is and how it can be solved.

4.2.2 Features
The VMC logging and tracing system is called up by Java programs to output messages that enable errors to be found later and to reproduce the program flow. These Java programs can be components of the VMC environment itself, or even applications that use the VMC to execute Java code. The Java program uses a log controller object created earlier to write the message. There are two types of log controllers. _ Categories to write the log messages. These correspond to logical components such as /system/database, the parts of the name are separated by a forward slash (/). _ Locations to write traces for developers and administrators. The names of locations correspond normally to

Java class names or packages, the parts of the name are separated by a point. When you choose Log Administration=>Log Display on the left-hand side, a new tree appears. 11 This contains the hierarchical structure for the locations. Beneath this the categories are listed. Each message has a Severity level that together with the log controller setting determines whether the message is output or not. This allows you to restrict the number of messages to those of real interest. Each log controller can enter separate settings. The path-like names of the log controllers enable them to be uniquely arranged in the tree, as settings are passed downwards in the tree. For instance, if a location is configured in such a way that it only outputs traces with a severity of at least WARNING, this is also valid for all the subordinate locations, unless these have their own settings.

4.2.3 Activities
You can view the log messages in the log administration in SM53, and you can also display and change the log settings. The sections below contain more details:

4.3 Displaying Log Messages 4.3.1 Use

You can display all VMC log messages in the VMC Administration (SM53). The log viewer has been developed for this purpose. It combines all the logs written by VMC logging and tracing and allows you to select messages according to the log controller, severity, time, and so on. 12 Normally, messages are written to text files located in the $DIR_HOME directory, and they can be read directly or in transaction AL11. Older logs or traces are located in the logs subdirectory. Applications that run on the VMC normally use files: vmc_w<WORK PROCESS ID>.trc for tracing, and files vmc_w<WORK PROCESS ID>.log for logging.

This directory also contains diverse trace files whose names begins with dev_.As you can configure which log controller writes to which file, there is no default log controller and file.

4.3.2 Procedure
In the left frame of the VMC administration (SM53) choose Log Administration =>Log Display. Select a log by choosing in the top left of the hierarchical structure the available locations and categories as the sources of the messages for which you want to see the logs. If a node of a tree is selected or deselected, all the nodes of the subtree are automatically selected/deselected too. Use the filter settings to further restrict the amount of messages found. To search specifically for errors you can for instance hide messages with a severity smaller than WARNING and restrict the time period. Errors that occurred in a specific session may be traced more easily if messages from this session only are displayed. You can restrict the number of hits in the lower left area according to the following criteria: Severity: Severity of the message. Displays only messages with the selected or higher level of severity.

 Log Name: Displays only log messages with this name (for very specific searches). User: Displays only log messages that were created under the user specified. Client: Displays only log messages that were written in this client. Session: Displays only log messages from this session. You can view the session IDs of the active sessions if you choose Sessions in the initial screen of the VMC system administration and then look in the column Session ID. Thread: Displays log messages from this thread only (for very specific earches) Messages by Date/Time: Displays only log messages written after this date and time. Messages up to Date/Time: Displays only log messages written before this date and time. Choose the icon Update Log Messages. The requested log messages are now displayed in the top right area. A maximum of 1000 messages can be retrieved at one time. If more than 1000 messages exist, this is indicated in the status bar and you can scroll through them using the scrolling buttons in the function key menu bar. The messages last transferred are listed in the table. You can sort them, search them, or export them to a file. If a single line display in the table is not sufficient, you can view individual messages in detail by double-clicking on them.

4.4 Displaying and Changing Log Settings 4.4.1 Use

You can change the severity level for single log controllers in the productive system at any time using the VMC Administration (transaction SM53). Choose Log Administration =>Log Configuration. Here you can specify which log messages get recorded by the system. If you display the log messages, you can restrict the number of hits (see Displaying Log Messages). You can find all the options for setting the VMC log system in the configuration file logging.xml, in subdirectory cfw/conf/vmc_runtime/base (for the configuration delivered by SAP) or in cfw/conf/vmc_runtime/custom (for customer configurations). Among other things, here you can specify which messages, and in what detail are written to which files. Changes to this configuration should only be made be experienced administrators and only in the custom directory. They only become active when the VMC is started or reset.

4.4.2 Procedure
In the left frame of the VMC administration (SM53) choose Log Administration=>Log Configuration. The screen appears where you can configure the log settings according to your wishes. You can select any location or category you like and change their severity settings. Any changes and their effects on lower-level nodes are immediately visible in the tree displayed. You can also insert log controllers unknown up to now, by entering the full name in the input field and copying the relevant setting.

4.4.3 Result
The changes you made are effective immediately, but they are not saved they are valid only until the VM is restarted or reset.