Flexible field mapping for SAP
The tax data mapping by means of the Flexible Field Mapping and Address Mapping can be considered the heart of your system configuration and the one that you will spend the most time working with in your setup of the Integration. The field mapping table provides the ability for mapping SAP fields to the Determination request data and from the response data back to SAP without the need to write any custom code. This allows the Tax Business Analyst who configures a company’s tax policy in SAP and Determination to leverage both sides to their full potential.
Flexible Field Mappings
The Flexible Field Mapping consisted of two views, the standard view delivered by Thomson Reuters with the default field mappings delivered as part of Integration, and a custom view. The custom view allows you to add new mappings or override existing mappings delivered in the standard view. As of Integration release 6.4.1.0 the field mapping table has undergone some major changes to improve usability of the table as well as significant improvements to performance time for the processing of large invoices with line-items numbering over 1,000.
For usability the table is now combined into a single view and transaction code so that users can see both the standard mappings and their custom mappings in one table. The table itself is now presented in its entirety using the options for ALV grid so that users have more flexibility to view the table as well as being able to view it in Excel mode and download it to Excel formatted files that can be saved to your hard drive. Other field options are also provided such as filtering, insert, formatting. A new selection screen is shown first so that a user can elect to view the whole table or any combination of journey sections that they desire as a partial view of the table.
Performance improvements have been achieved that reduce the time for heavy invoice processing on documents with over 1,000-line-items. Testing has confirmed a 15X improvement on a 3,000 line invoice, reducing field mapping processing time from 15 minutes down to 1 minute. To achieve this improvement goal, the programs have been changed to utilize dynamic generated code (versus static code development) to select field mapping based on configuration done within the field mapping configuration. This is code that would be created for a specific field and base mapping. If a field mapping or base mapping changes, this code is re-created at the next tax calculating transaction. The functionality of the new mapper should not change at all and be exactly the same as the old field mapper.
Field Mapping Table
A new Combined View with default mappings has been provided.
Transaction Code:
/N/IDT/FIELD_MAP_NEW
The new combined transaction now brings you to a field mapping selection screen. If you want to view the entire table then you just need to select the
EXECUTE
button to advance to the next screen. If, however, you wish to select all the mappings for a given journey name or group of journeys then the selection screen can be used to select the desired section of the table for viewing and maintenance.As before you will not be able to change any of the rows that are marked as Standard lines as noted by the check box in the first column. These are entries that are provided as standard configuration and are supplied to the system as part of the configuration transports when you first load the Integration to your system. Lines that are not checked as standard are custom entries configured by you. They can override or add to the standard entries and are of the higher sort order starting with 100000.
This view allows you to review the preconfigured and delivered mappings provided by Thomson Reuters as well as your custom configuration mappings. This can be helpful when trying to understand a tax result or in building your own mappings. We will explain the different columns and their use in the section below.
The new combined view of the field mapping table also takes advantage of the ALV grid format which is standard within SAP. This provides other standard features by which the user can adjust or copy the table lines and functions as well as the ability to download the table to a spreadsheet document copy on your hard drive. Once you are in the change mode of the table you will see the icons as noted below that can be used to modify/copy the data.
As mentioned above this table allows for your own custom mappings as they relate to your company’s tax requirements, policy, and compliance needs. Next, we will identify the columns on this table and how they are used to map your desired fields.
Column Field | Explanation |
Journey Name | You would first establish which journey you want to use for the new mapping. In order to choose the correct journey, you would ask yourself if this field is part of what you want to send via the request data going to Determination, or is it part of the data that will be coming back on the response? Is it data at the header level of a document or is it data stored at the line level? Is this an SD order, billing, PO, LIV invoice, or FI generated document, etc. The journey name column has a drop down so that you can select from the list of possible journeys that are available. |
Source Base | This field defines the primary level of where the source data resides, i.e. document or line level in SAP, or invoice, line, and tax level in Determination. There are some special purpose source bases provided too. The drop down allows you to select the appropriate source base and only supplies the list of bases that are applicable to the journey that you selected in the prior column. |
Source Field | Here you specify the applicable source fields for the source base. The source fields on the request journey side are the available fields from the SAP tables as listed in the Appendix and all its fields. The response journey represents the Determination tax calculation OUTPUT structure. The source fields drop down first displays the list of tables that are applicable from the prior columns selected. Once you select the table then the list of fields within the table will display for your final selection. Other entries may be possible here if you elect to use the other functionality for constants, calculated fields, and other table driven or user exit examples as explained below. |
Target Base | You define what structure the field needs to assign to or retrieved from. When mapping data to Determination you can use all INPUT XML main structures of Batch, Invoice, and Line. When mapping data from the response back to SAP you can map to the Thomson Reuters provided tax data table. The target base field also has a drop-down option with bases displayed according to the prior column fields selected. |
Target Field | In this column you specify the applicable target fields for the target base. The target fields on the request journey are Determination Batch, Invoice and Line XML elements. Target fields on the response are based on the tax data table including custom appended fields by the customer. The target field column also has a drop-down selection list based first on the list of tables that are applicable from the prior columns selected. A list of tables will first display and once you select the table then the list of fields within the table will display for your final selection. |
Only if Populated Flag (OnlyIfPopu) | Used to support conditional mapping in cases where multiple source fields point to the same Determination target field. See sample below. |
Adjustment | Allows for some limited string manipulations and other type of changes to a field. See detailed use cases below. |
Simple Expression | Allows for a code expression to be added as a qualifier. Only if the expression is fulfilled the mapping will be considered. See Simple Expressions for details. |
Only if Populated Flag
This column is checked when multiple mappings from different tables are mapped to a single Determination element. This is used so that the highest sort order mapping would not override the lower sort order if that field has a value. The use of this field also provides a type of conditional logic to prevent a NULL value from being mapped to a field.
An example of its use is shown below where three different fields from SAP are mapped to the same Determination request field depending on their source module; SD, MM, or FI. In these situations, only one of the three scenarios would occur on a given transaction.
Consider this scenario based on above example. If the process is FI and the flag would not have been set for SD and MM, the prior mappings would have been taken into account, returning an empty (NULL) value to Determination. By checking the flag the SD and MM fields will be ignored and the FI document type will be mapped to Determination.
Adjustment
This column is used for any kind of adjustments that needs to be done to correct or change the field mapping from one format to another. An example of this is where we use the adjustment column to ignore the first three digits of the
ERP_Tax_Code
and use the next three digits to populate the SAP Account key. Another example would be where we need to convert a value to an amount instead of text or convert the format for a date.Options for the adjustment field include the following:
Adjustment | Explanation |
SIGN | This will reverse the position of the signage, i.e. turn 100- to -100 and vice versa. (100- is valid in SAP but not in Determination.) It moves the SAP negative sign to the right position in the request so Determination can read the value correctly. SIGN should be used for all fields of type amount or quantity in the request. It isn’t needed in the response. |
CURR_REQ_DOC | This will adjust the document currency amount on a request to Determination: used for amount like fields to adjust to the right currency decimal places based on SAP table V_CURX |
CURR_RES_AUTH | This will adjust the authorization currency amount on a response from Determination: used for amount like fields to adjust to the right currency decimal places based on SAP table V_CURX |
CURR_RES_DOC | This will adjust the document currency amount on a response from Determination: used for amount like fields to adjust to the right currency decimal places based on SAP table V_CURX |
BOOLEAN | This will turn an SAP value of X into a TRUE or ‘ ‘ (null) to FALSE for Determination. |
DATE | This is required to turn the Determination date format into the SAP date format. |
* (multiplier) | This will multiply the value by the number after the *, i.e. *1000 would convert a Determination tax rate of 0.2 to 200 which then is displayed in SAP as 20.00 %. |
String manipulation | Allows for simple string manipulations on a value, i.e. +3, (3) would move to fourth position (offset first 3) and use the next 3 values. So, for an ERP_TAX_CODE returned by Determination of A1-MWS it would only return the value MWS. |
note
When "SIGN" is used with any of the CURR adjustments the sign adjustment must follow the CURR adjustment with a comma separator between them and no spaces.
In this example you will see the three CURR adjustments used in the field mapping table.
Calculated Fields
In some cases, the field use isn’t based on the exact value in the business process, but rather augmented either via a configuration setting or code. These special fields are necessary due to Determination requirements. The two calculated source bases we use are CALC_HDR and CALC_ITEM with the below calculated fields.
Header Level | |
Source Field | Explanation |
CALC_HDR_ROLE | Indicating if this is a Seller or Buyer role, depending on the setup for US specific processing in /N//DT/US_LOGIC |
CALC_HDR_EXTERNAL_COMPANY_ID | Usually the SAP Company Code, prepend possible via configuration in /IDT/GEN_CONFIG_VALS |
CALC_HDR_UNIQUE_INVOICE_NUMBER | For uniqueness in the Determination audit database this field has to be supplied. It is a concatenation of the Company Code, Document Number, Role, and the Fiscal Year. The values are separated by a pipe value. For example: 2100|0090001798|S|2014 |
CALC_HDR-CALCULATION_DIRECTION | Indicates whether the tax calculation is based on a “gross_amount” (when blank) or a “gross_amount_plus_tax” (when “T”). It is linked to the Invoice-level field CALCULATION_DIRECTION in the tax engine request message. |
CALC_GM_HDR-EXTERNAL_COMPANY_ID | This is linked to a EXTERNAL_COMPANY_ID field at the batch level of the request message. It is a way of linking the tax calculation to a specific company in Determination’s configuration. |
CALC_GM_HDR-UNIQUE_INVOICE_NUMBER | This field is used within the Goods Movement product to populate the header-level UNIQUE_INVOICE_NUMBER field. |
Item Level | |
Source Field | Explanation |
CALC_ITEM_DET_TAX_CODE | Value based on configuration done in /N/IDT/DET_TAX_CODE for the SAP Tax Code processed |
CALC_ITEM_IS_EXEMPT | Driven by the configuration in /N/IDT/EXEMPT_SETTINGS or /N/IDT/DET_TAX_CODE |
CALC_ITEM_AMOUNT | When calculating tax, the Document Currency is used, but when the audit call is made the Company Code Currency amount will be used to store the tax liability. Additionally, the amount is adjusting for positive or negative scenarios. |
CALC_ITEM_QUANTITY | Similar to amounts SAP doesn’t use decimal notations for quantities, this value adjust for this. |
CALC_ITEM_IS_CREDIT | To account for cancellations, reversals, etc. of an original document in audit the IS_CREDIT flag has to be set to TRUE. When done so the original amounts of the business transaction are reversed by -1. |
CALC_ITEM-CREDIT_DEBIT | This field is used to populate item-level USER_ELEMENT ATTRIBUTE44 field. It is populated by the BSEG-SHKZG field from the expense/revenue line. |
CALC_ITEM-AMOUNT_PLUS_TAX | This field is used to populate item-level GROSS_PLUS_TAX field. It is populated by the BSEG-WRBTR when the tax is being calculated as “Gross” tax. |
CALC_ITEM-ROUTE_NAME | This field is populated by the current Route name and is used to populate the item-level USER_ELEMENT ATTRIBUTE45 field. |
CALC_GM_ITEM-IS_CREDIT | This field is used within the Goods Movement product to populate the item-level IS_CREDIT field. |
CALC_GM_ITEM-GROSS_AMOUNT | This field is used within the Goods Movement product to populate the item-level GROSS_AMOUNT field. |
You can see examples of the use of the calculated field function by looking at the standard field mapping table
/IDT/FIELD_MAPPING_V
and searching down the Source Field column of our standard mappings.Constants
A constant can be any value not based on business transaction data. For example, to indicate to Determination that a transaction needs to be persisted in the audit database we would need to set the XML field IS_AUDITED = true. To do so the following mapping can be used (part of standard delivered mapping already).
By entering the word "CONSTANT" in the source base field the mapping line will then replicate whatever you input in the source field as the value to be populated into the target field. This can be especially powerful and useful when used in combination with a specific route or use of conditional logic in the simple expression column. For a constant the source field can be either upper case, lower case or mixed as in a password, etc.
Use of a Constant with a Simple Expression
If you desire to have the constant value populated based on the success of a simple expression, we have added additional logic for variables to allow either header or line level fields to be used in the simple expression. (See section below on Simple Expressions then return to this explanation)
These variables will come from the Journey. In general, the sample expression uses variables defined from the source base.
For example, when using the header journey and the SAP_HEADER source base the simple expression can contain variables like &KOMK-AUDAT& as in the expression:
&KOMK-AUDAT& NE IS_INITIAL
This works because &KOMK-AUDAT& is a valid value in the source base.
In the item Journey and the SAP_ITEM source base the simple expression can contain variables like
&VBAP-MATNR& as in the expression:
&VBAP-MATNR& = 'S-1002'
This works because &VBAP-MATNR& is a valid value for each line in the source base. And it can be evaluated for each line in the source base because it works within the looping logic.
When the source base is constant this new logic uses the journey to provide meaning for the variables as in these two expressions when the source base is constant:
For the header journey:
&VBAK-XEGDR& NE IS_INITIAL
For an item journey:
&[ROW=1]HDR>VBAK-XEGDR& EQ IS_INITIAL
In both cases the meaning of the variables comes from the journey and not from the source base.
Table Driven Mappings
In some cases, the Determination tax calculation XSD definition uses complex structures which are represented in the SAP proxy as tables. To handle field mappings for these tables, a more complex approach has to be taken by first defining what table to work with, then to designate the proper field within the table and lastly to assign a value to that field. For example:
USER_ELEMENT[NAME=ATTRIBUTE42,CREATE_IF_NOT_EXIST]-VALUE
This would map a VALUE to ATTRIBUTE42 in the USER_ELEMENT structure of the XSD if it doesn’t yet already exist. See Appendix 2: References for more details.
In order to better understand how this works, let us look at a few scenarios.
Example 1: User Element/Custom Attributes
One of the most commonly used custom field mappings will be for user elements, especially now that Invoice and Line level elements can be used with the Integration. Before we go further let’s review what user elements are and how they are used in mappings. A section from the Determination help menu below explains them as Custom Attributes. See below:
You can learn more about the provided customer attributes by reviewing help documentation within the Determination tax engine.
To map a user element, you follow the following syntax:
The corresponding mapping in the Target Field would be:
USER_ELEMENT[NAME=ATTRIBUTE42,CREATE_IF_NOT_EXIST]-VALUE
Our target is the VALUE field in the first ROW of the table USER_ELEMENT. The NAME represents the attribute to be used for the mapping in the range from ATTRIBUTE1 to ATTRIBUTE40 (range 41-50 is reserved by Thomson Reuters). A control flag CREATE_IF_NOT_EXIST can be used to only add the value if none already exists. Finally, we state the target field VALUE to which the data needs to be assigned to.
Below is a resulting line level XML structure sample:
<USER_ELEMENT>
<NAME>ATTRIBUTE42</NAME>
<VALUE>TA</VALUE>
</USER_ELEMENT>
Example 2: Quantity
We need to provide the quantity sold in SAP to Determination for taxing. The data in the SAP field is KOMP-MGLME which we want to map that to the quantity amount element in Determination.
To do this we use the target field notation as below:
QUANTITIES-QUANTITY[ROW=1,CREATE_IF_NOT_EXIST]-AMOUNT
Our target is the AMOUNT field in the first ROW of the table QUANTITIES-QUANTITY. To add our value to the AMOUNT field we must point to that row with the ROW=1 pointer, additionally we can make use of the control flag CREATE_IF_NOT_EXIST to only add the amount value if none already exists. Finally, we state the target field the value needs to be assigned too.
Based on the two mappings in the above picture this would lead to the following data being sent in the line level XML structure for QUANTITIES.
<QUANTITIES>
<QUANTITY>
<AMOUNT>23</AMOUNT>
<UOM>EA</UOM>
</QUANTITY>
<QUANTITY>
<AMOUNT>11</AMOUNT>
<UOM>CTN</UOM>
</QUANTITY>
</QUANTITIES>
As one can see multiple units of measures can be sent to Determination for evaluation. See the Determination online help topic Units of Measure Conversion for more details.
Example 3: Currency Conversion
Another table-based structure is the CURRENCY_CONVERSION_STEPS XML that holds the tax exchange rate date in the response (OUTPUT XML). This field is mapped in our standard already:
The corresponding mapping in the Source Field would be:
CURRENCY_CONVERSION[ROW=1]-TAX_EXCHANGE_RATE_DATE
In the above example our source field is TAX_EXCHANGE_RATE_DATE, in the table CURRENCY_CONVERSION. We map to the first value with ROW=1. If there is no ROW in the table, it does not return any value.
Below is a sample tax level XML structure for CURRENCY_CONVERSION
<CURRENCY_CONVERSION>
<TAX_EXCHANGE_RATE_DATE>2013-11-19
</TAX_EXCHANGE_RATE_DATE>
</CURRENCY_CONVERSION>
Example 4: Registrations
Another common table-based mapping is for the use of VAT Registration numbers. Please see the Registration Number Mapping section for details on this subject.
Pointers
HDR->
The HDR-> pointer is used only for request journeys that relate to grouped transactions like creation of a sales order, billing document, or purchase order. This pointer is used in Item level request mapping to indicate that the field used is at header level, i.e. HDR->T001W-WERKS would indicate the plant from the header table to be mapped at the item level. Journeys where the use of the HDR- pointer would be applicable include:
/IDT/JOURNEY_ITEM_REQUEST
ANCESTOR->
This solution allows a user to map not only data from the <TAX> block back to SAP, but also from the <LINE> and <INVOICE> level. To do so one would use pointer of
ANCESTOR->
to indicate the position of the field is the next level up. You can string multiple pointers together to point to two levels up, i.e. ANCESTOR->ANCESTOR-> would point to the invoice level.
Pointer used in response mapping to indicate that the field used is at a higher level in the structure, i.e. ANCESTOR->ANCESTOR->CALLING_SYSTEM_NUMBER would be used to map from an invoice level field in the tax data level.
note
Level 1 would be the <BATCH>
Level 2 would be the <INVOICE>
Level Level 3 would be the <LINE>
Level Level 4 would be the <TAX> block Level
We are not supporting the BATCH level at this time; all relevant fields are also available at the INVOICE level.
ITEMS->
The ITEMS-> pointer is used for request journeys in header and item user exits.
As an example, this feature could be used in the following two scenarios:
- If you need to determine at the header level a field that is stored at the line-item level to pass that to the request.
- If you want to look at a line that is a consequence of another line like a freight charge or surcharge and you need to refer to the parent line to get some information needed to properly calculate tax on the related child line.
To accomplish either of these scenarios via ABAP programming, you can use this new field in the header called “Items”. This Items field is a pointer that allows you to get the item data needed for the above two purposes. It increases the function of the user exit and simple expressions to use for some fringe cases where this may be needed. You may never need this, but it is available if needed.
This is used by an ABAP programmer creating a field mapping user exit that they would then populate into the field mapping table.
See the Installation and Programmers Guide section “User-Exit in Field Mapper” for an example on how to use this new feature.
Simple Expressions
Simple expressions are just like a line of code, but they are added to the field mapping line as a qualifier, only if the expression is fulfilled the mapping will be considered.
The syntax of a simple expression is as follows:
Source Field | Operand | Check Value (Field)
Some requirements are:
- SAP table-field names must always be wrapped with ampersands (&)
- Values must always be wrapped with single quotes (‘)
- Operations can be stringed together by AND or OR commands
- Supported operands are:
- EQ, = Equal To
- NE, <>, >< Not Equal To
- LT, < Less Than
- LE, <= Less Than or Equal To
- GT, > Greater Than
- GE, >= Greater than or Equal To
- CO Contains Only
- CN Contains Not only
- CA Contains Any
- NA Contains Not Any
- CS Contains String
- NS Contains No String
- CP Matches Pattern
- NP Does Not Match Pattern
- IS_INITIAL Field is initial value
note
IS_INITIAL is a special command that can be used with EQ or NE to further delineate if a field has been populated or if it has been set to the initial value of blank for this transaction.
Date fields however cannot use IS_INITIAL because the original value stored in SAP is not blank for date formats but instead is initially formatted as '00000000'. If you are mapping for a date field use the example below where the date field is not equal to '00000000'. We recommend you use this format and not activate the “only if populated” flag.
Other example for operands listed above:
Expression | Explanation |
&KOMK-VKBUR& = '1030' | Only maps the field if the Sales Office value is 1030. |
&VBAK-ERDAT& NE &SY-DATUM& | Only uses the mapping if the system date isn’t the same as the documents create date. |
( &KOMK-WAERK& = 'USD' and &VBAK-ERDAT& = &SY-DATUM& ) OR &SY-TCODE& CP 'VA’ | Maps the field if the Document Currency is USD and the Document Create date is the system date OR if the transaction code starts with the letters “VA” |
'NL_RC_TR_ZE_ZC' CS &TAX_TYPE& | Only uses the mapping of the Tax Type contains any of these values: NL, RC, TR, ZE, or ZC. |
User-Exit Based Field Mapping
The Field Mapping allows dynamic mapping of SAP source fields to Determination and vice versa. In most cases the options of doing mappings by journey, routes, route groups, country groups, or company code are enough to meet most customer requirements; especially in combination with the Simple Expression feature that allows for some ABAP syntax to be added in the mapper directly. However, in some complex situations, or when the Thomson Reuters provided source bases aren’t covering a table required for a custom mapping, a customer might implement a user-exit based mapping. How to program a user-exit based field mapping see the Installation and Programmers Guide section “User-Exit in Field Mapper”.
Proxy Column for Tandem Use of On-Premise Determination and Cloud 2018.3 Determination
If you are only using an on-premise version of Determination, then you can skip this topic. It will not apply to your mappings.
With the release of Determination Cloud 2018.3, there were about 30 new fields that were created and new functions and content to support Oil and Gas customers. This addition is not going to be added to the on-premise version and thus creates some issues with two different XSD structures within the WSDL and proxy(s). Because the field mapping table uses dynamically generated code for each of the journeys, the WSDL version, if not selected correctly for the program, will cause a system ST22 error. We have added an additional column to the field mapper. It directs the mapping line to the correct proxy and XML structure, if the proxy field is populated with the proxy group code that is used exclusively for that mapping field.
If you are using the new Cloud Determination 2018.3 and above, AND you are using some of these new fields, then you will have to populate the proxy group code "
CL
” relating to Determination 2018.3, for the given line-item. If you are not using any of the new fields in 2018.3 and/or are NOT using the Cloud Determination, then you will NOT need to be concerned with this field. If the field is left blank on the mapping, then the line will apply to either WSDL. A code for the on-premise proxy “ OP
” in the field is used for fields that are only available in the on-premise proxy. See Proxy table configuration instructions for more information.
Example of new proxy column of field mapping table being used on a mapping for new fields in Determination 2018.3
Important Note on Field Mapping Errors
If you are doing a field mapping or address mapping and then encounter a program dump error screen this is because you have mapped an incorrect combination of journey, route, and source/target field in the mapping line. If you encounter this program dump you can simply check off the “Active” flag on the mapping line and repeat your process. If you do not get a program dump after the active flag is unchecked, then you know you have identified the culprit mapping line that is causing the problem. Once the line in question is identified you can investigate what the error situation is and how to fix it.
The error that will occur for an incorrect field mapping will now create an ST22 error that will be available for you to view. If the error occurs before the document is posted to the G/L then the dump error screen will pop-up and show you the error immediately. If the error happens in the call to the audit journey, then the error will not be a short dump that prevents the entry from posting to G/L and you will instead see a pop-up termination error. If that happens then double select on the pop-up error and it will tell you to go to transaction code ST22 to further review the error. Once you find the error on the ST22 transaction screen you will see within the error a message that tells you which journey and sort order line in the field mapping caused the issue. You will then need to correct this field mapping line to prevent the error. Example shown below:
