| Oracle® Retail Fiscal Management/RMS Brazil Localization Implementation Guide Release 14.1.3.1 E91382-02 |
|
 Previous |
 Next |
| Oracle® Retail Fiscal Management/RMS Brazil Localization Implementation Guide Release 14.1.3.1 E91382-02 |
|
Previous |
Next |
Brazil has complex tax and fiscal systems. In order to have a flexible format to fit any kind of tax scenario and also to make the tax rules setup part of a specialist solution, Oracle Retail has integrated its applications with third-party tax engines provided by Oracle partners. The ORFM system is integrated with the TaxWeb Tax Rules solution through the Oracle Retail Tax Integration Layer (RTIL).
|
Note: This chapter is only for customers who have TaxWeb as tax vendor. |
RTIL acts as a connector that exposes a Retail Tax Data Model API for calculating tax, which is envisioned to be an abstraction over the TaxWeb Tax Rules tax data model. RTIL hosts the TaxWeb Tax Rules Adapter that is responsible for converting the Retail tax data model into the native language of a tax service provider, and communicating with a third-party tax solution service. RTIL supports integration of RMS and ORFM with the TaxWeb Tax Rules. The ORFM system is integrated with the TaxWeb Tax Rules solution to obtain information about all Brazilian tax legislation, with a high level of exception treatments.For all flows in Oracle Retail that need to have tax calculation, the integration layer is used to have all taxes applied from the TaxWeb Tax Rules, considering the input parameters.The following processes in ORFM/RMS use the tax calculation integration:
Inbound NF validation
Outbound NF issuance
PO tax breakdown
Item creation
Refresh tax
Item fiscal reclassification
For each of these processes, the needed input information is sent to the TaxWeb Tax Rules through RTIL. RTIL is responsible for transforming the request information from the Retail tax data model format to the TaxWeb Tax Rules specific format, and vice versa for the response information.
This chapter covers the following topics:
RTIL is responsible for the TaxWeb Tax Rules API call with the necessary formatting. The TaxWeb Tax Rules API exposed has a native Nota Fiscal format, and formatting must be sent in that way for tax calculation in TaxWeb Tax Rules. In TaxWeb Tax Rules, an integration layer is used for data completion. Some of the attributes in the API must be determined by Tax Rules (such as CFOP). Only after this step is complete the tax classification is triggered internally in the TaxWeb Tax Rules. Once the taxes are classified, the API with the returned values is sent back to the integration layer in Oracle Retail.The layout of the TaxWeb Tax Rules solution is based on the NF layout and has the following structure:
Entities (foundation data and fiscal attributes of each entity of a NF, such as Issuer, Addressee, and Transporter)
NF header information
NF item information
Tax classification (enquadramento)
The Retail Tax Data model is an abstraction introduced over the TaxWeb Tax Rules Tax Data model with the aim of achieving semantic interoperability. The Retail Tax Data Model aims to decouple Oracle Retail Products (RMS, ORFM) from the vendor specific data model. This model enables RMS/ORFM to deal with a more generic format than being tightly locked with TaxWeb Tax Rules Vendor data model. This model allows applications to be more loosely coupled.
FiscDoc – This object represents a fiscal document and eventually maps to the Nota Fiscal of the TaxWeb Tax Rules in the integration with the TaxWeb Tax Rules. It has the information related to the NF header and it has included the other objects that detail each part of the fiscal document as the issuer, addressee, and items.
FiscEntity – This object has the fiscal and master information related to the entities in a fiscal document. This object will be used to detail the issuer/supplier, addressee/location and facilitator/transporter information.
LineItem – This object represents the detail of a line item in a fiscal document. It has included the taxes at item level.
TaxDet – This object represents the details of an individual tax. It can be attached at the Fiscal Document level or at a DocLineItem Level. Each tax applied to an item will have a different object of this type.
InformTax – This object represents the details of an individual tax informed by the calling application and supplied in the request. This indicates that the TaxWeb Tax Rules should not compute this specific tax, but can use this information to derive other taxes if they are dependent on the informed tax. This is an optional entity which is sent in scenarios where in the NF tax is assumed to be the correct one. It can be attached at the Fiscal Document level or at a LineItem level.
InconclRule – This object has the rules and laws applied to each tax. It has the regulation and the log of the tax classification. It notifies the rules that are not applied to the item and classified as inconclusive rules. This can be used as an information log to the user to show potential tax setup problems.
ProductItem/ServiceITem – Code and description of items which can be products or services. These objects will have the fiscal attribute details for the items depending on the item type (product or service).
FiscDocChnk – This is a placeholder object introduced to support a logical unit of work (contains one or more fiscal documents) that can be sent in a single request to the TaxWeb Tax Rules. It does not have a direct counterpart in the TaxWeb Tax Rules data model but aggregates to a collection of DocFiscal objects in the vendor data model. A collection of FiscDocChnk objects helps in enabling RTIL to support splitting a large request into multiple chunks and process them concurrently to enhance performance and throughput. Aggregation of the responses from the TaxWeb Tax Rules are handled internally in RTIL.
RTIL exposes a servlet controller to receive the HTTP request from ORFM/RMS application in a synchronous request/response pattern. Based on the http request from ORFM/RMS, RTIL will fetch the data from RMS/ORFM and form the request for external tax vendor. RTIL will invoke the associated external third party services with native POJO call to obtain the tax details which will be passed back to the calling application.
Retail Tax Integration Layer will be implemented as Java EE application with the associated tax service provider adapters. This layer will form the conduit between the Oracle Retail Applications and the Tax service provider. The Retail Tax Integration layer is responsible for assembling and disassembling of the vendor specific data model to Retail tax data model based on the configuration. The Retail Tax Integration layer is envisioned to host vendor specific connectors which can communicate to the external third party services. The subscribing application is not aware of the tax service provider, RTIL acts as a bridge between the subscribing application and third party tax service provider. In the current release, RTIL will host a TaxWeb Tax Rules adapter and interacts with the TaxWeb Tax Rules using a POJO interface.
The integration layer in Oracle Retail does the following.
Exposes a more abstracted tax data format (Retail Tax Data Model) for RMS/ORFM to pass their transaction details that require taxes to be computed
Performs the data transformation from canonical to the TaxWeb Tax Rules specific format
Invokes the taxation API of the TaxWeb Tax Rules
Transforms the response containing taxes from the TaxWeb Tax Rules specific format back to the canonical format to be consumed by RMS/ORFM
RTIL is used as the unique tax calculation entry point
The above diagram illustrates the high level components and its interactions along with the run time and the design time view of the system. The Retail Service Enabler Utility is used to generate the necessary PL/SQL producer and its associated artifacts to fetch/set tax staged data from the database.
The client uses an URL Invoker class signaling RTIL to fetch the tax request data from the client's staged tables and the TaxWeb Tax Rules API will be invoked as a POJO (Plain Old Java Object) call from RTIL.
The preceding diagram illustrates the deployment view of the components. The salient features of the architecture are:
Retail applications interact only with tax services in an abstracted tax data format using RTIL-supplied client components.
RTIL insulates the Oracle Retail applications from tax service providers. RTIL will be deployed as an enterprise application instance (EAR file) in Oracle WebLogic Application Server.
RTIL will host the vendor adapters.
The adapters interact with the tax service providers in native format.
The adapters are responsible for converting the Retail Tax Data Model to the application-specific data model and vice versa.
Tax service providers can be deployed on the same or a different application server, based on customer needs.
The flow typically involves RTIL being invoked by a HTTP request which contains the qualifying information to invoke the appropriate the TaxWeb Tax Rules API.
The primary group of operations supported are:
Fetch Tax Staged Data from RMS/ORFM and invoke the TaxWeb Tax Rules calculation API through a POJO call
Update the Tax Response on to the Staged Tables in RMS/ORFM
Support invocation of the TaxWeb Tax Rules tax fiscal foundation data and updation of foundation response back to RMS/ORFM
Invocation of a cancel Tax Transaction API on the TaxWeb Tax Rules (This is a compensation API to be invoked to eliminate stale data in the TaxWeb Tax Rules in case of failures of retail transactions in RMS/ORFM post the TaxWeb Tax Rules data updates).
URL Invoker – This is a java class loaded into the database JVM, which triggers RTIL to fetch the Tax request data from the RMS/ORFM staged tables. It's a synchronous call, which is blocked till RTIL updates the tax response from the TaxWeb Tax Rules back on to the RMS/ORFM staged tables.
It will be the responsibility of the URL Invoker to send a unique key to RTIL, which will be associated with the tax request and tax response that RTIL has to fetch and set. Also the differentiator parameters for the tax call or to fetch different foundation data or to invoke tax compensation API has to be sent by the invoker to trigger appropriate processing in RTIL.
Retail Tax API – This is a TaxAPI which is in a more abstracted format that is exposed by RTIL to RMS/RFM. Any data enrichment if required should be done prior to the invocation of this API Call. This API will be in the format of the Oracle Retail application implementation.
Since RMS/ORFM are Forms/PLSQL applications, the Oracle Object Types representing abstracted Tax Request and Response are generated from Functional Artifact Generator tool for the given RTIL Tax XSD's. This ensures the API is in the implementation format of the Oracle Retail application.
Based on the request parameters from the URL Invoker, appropriate tax API will be called from RTIL.
TaxData Stage component, PL/SQL packages –This is generated by RSE and provides the runtime support for fetching/setting tax data from/to the database staged tables.
RTIL broadly supports the following configuration features:
Logging/auditing
User-friendly exception messages
Logging is implemented in a declarative manner using Spring Aspect Oriented Programming (AOP). AOP is a paradigm that addresses separation of concerns, thereby ensuring that logging and business logic are kept separate in the code, avoiding code cluttering. Logging is introduced during run time in a noninvasive manner leveraging spring AOP features. The logging utilities are implemented using the industry-standard Apache commons logging API.The following are the classes that act as the logging aspect to the application and apply to different methods of the application as configured.
LoggerAspect
ObjectLoggerAspect
TimerLoggerAspect
This class logs entry and exit statements for the methods in core RTIL classes. This also logs if there is some exception during the execution of these methods.
This class logs the entire content of request and response objects used in the transactions. It also logs the request object content and response object contents both in the canonical and native TaxWeb Tax Rules format. This is useful for troubleshooting the request and responses.
This logs the time taken in milliseconds for execution of the methods present in assembler, Gateway, and adapter classes. This aspect can be used to obtain a timing profile of the method executions.These aspects are declared by annotations and registered in applicationContext.xml. The following is a snapshot of the applicationContext.xml configuration file which shows the configuration for registering Aspects.
<aop:aspectj-autoproxy /><bean id="timingLoggerAspect" class="com.oracle.retail.tax.aspects.TimingLoggerAspect" /><bean id="loggerAspect" class="com.oracle.retail.tax.aspects.LoggerAspect" /><bean id="objectLoggerAspect" class="com.oracle.retail.tax.aspects.ObjectLoggerAspect" />
|
Note: Removal of these entries in this configuration file is equivalent to removing the code which logs these details. Thus, the enablement/disablement of logging is controlled in a declarative manner using Spring AOP. |
A second level of control is available in the log4j.properties file. This file controls the following logging features whose configuration can be changed to suit customer needs:
Logging at different granularities (INFO, ERROR, DEBUG, FATAL)
File size limit for each log file (log4j.appender.LOGFILE.MaxFileSize)
Number of log files to be retained during logfile rollover (log4j.appender.LOGFILE.MaxBackupIndex)
The following is a snapshot of the log4j.properties configuration file supplied with default options during deployment time.
# Root Level Loggerlog4j.rootLogger=INFO,STDOUTlog4j.appender.STDOUT=org.apache.log4j.ConsoleAppenderlog4j.appender.STDOUT.layout=org.apache.log4j.PatternLayoutlog4j.appender.STDOUT.layout.ConversionPattern=%d %p [%c] - %m%nlog4j.appender.LOGFILE=org.apache.log4j.RollingFileAppenderlog4j.appender.LOGFILE.MaxFileSize=5MBlog4j.appender.LOGFILE.File=./log/rtil.log# Keep ten backup files.log4j.appender.LOGFILE.MaxBackupIndex=30# Pattern to output: date priority [category] - messagelog4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayoutlog4j.appender.LOGFILE.layout.ConversionPattern=%d %p [%c] - %m%n#Class Level loggerlog4j.category.org.dozer.MappingProcessor=INFO,STDOUT,appenderlog4j.category.com.oracle.retail.tax.aspects.TimingLoggerAspect=DEBUG,LOGFILElog4j.category.com.oracle.retail.tax.aspects.ObjectLoggerAspect=DEBUG,LOGFILElog4j.category.com.oracle.retail.tax.aspects.LoggerAspect=DEBUG,LOGFILElog4j.rootCategory= ALL,LOGFILE,STDOUT
RTIL provides some flexibility in configuring user-friendly error messages based on the exception conditions encountered. The ExceptionMessage.properties file contains the list of system-generated exception messages in RTIL, which can be further mapped to the user messages required by the customer. The file is a typical properties file containing key value pairs. This file is read by RTIL infrastructure to substitute the system generated message pattern (Key) with the supplied user message (value), and the user message is propagated to the calling infrastructure (ORFM/RMS).
|
Note: The configuration option provided is only for supplying/altering the user defined messages. This file does not support the addition/modification of system defined messages. |
ORFM calls the Tax Rules API for the expected scenario and considering the structure of the API, which is similar to a fiscal document. All the input parameters are formatted in that structure, and the returned values are also sent in the same format. The input parameters do not contain any tax information. Only the fiscal attributes and values are sent. In the output parameters, the tax calculation results are sent back based on the original values in the same fiscal document format.
RTIL being a J2EE application and deployed in WebLogic application server inherently supports parallel processing of requests, provided its clients (RMS/ORFM) can send the requests concurrently. However, within the context of a single request, the processing is will be from RMS/ORFM to RTIL and then to the TaxWeb Tax Rules**. In the event of a single request being very voluminous, this could result in slower throughput as it will be processed sequentially. Typical example of a large request could be a set of items ranged to large number of locations needing a taxation input.
To optimize the handling of large requests, threading is introduced in RTIL to enable concurrent processing. The approach of concurrent processing in RTIL is as follows:
A large request is partitioned into a set of logical units of work called chunks.
Each chunk is capable of being independently processed and the chunk is represented as a FisDocChnk object.
Client (RMS/ORFM) partitions the large request into chunks and invokes RTIL.
RTIL parses the requests and spawns the necessary threads to process the chunks individually.
Concurrent requests are sent to the TaxWeb Tax Rules with the individual chunks and responses are received**.
Responses are tagged accordingly to support aggregation and sent back to the calling client (RMS/ORFM).
RMS/ORFM can trigger the concurrent processing in RTIL by setting a boolean flag called "Thread_use" appropriately to Y/N which will be passed in the request. The behavior is controlled at the request level intentionally so that clients have the flexibility of optionally switching on concurrent processing in RTIL only for large request which merit concurrent processing for optimal throughput.
RTIL uses WebLogic WorkManager framework for thread management, which provides the following benefits:
Provides a concurrent programming API for EJBs/Servlets in a J2EE context.
Provides a container managed alternative to java Thread API thereby enabling the container full visibility and control over the executing threads.
Container based thread pooling and management.
Standards based implementation
The configuration required for the work manager is detailed in the RTIL configuration and operational considerations section.
RTIL Concurrent Flow Initiation
Figure 7-7 depicts how RTIL concurrent processing is triggered based on the Thread_Use flag value contained in the RMS request.
RTIL Concurrent Request Processing Flow
Figure 7-8 depicts handling of a large RMS request in RTIL in a threaded fashion. The steps for handling large RMS request in a threaded fashion is as follows:
The RMS request contains the logical chunks (FiscDocChunk[n]).
RTIL splits it into individual chunks.
Each chunk is fired in parallel as an independent tax calculation request to the TaxWeb Tax Rules.
The responses are collected from the TaxWeb Tax Rules and tagged accordingly to support consolidation of the responses into a single aggregated response in RMS.
For all the scenarios, the input parameters are based on the Retail Tax API objects. Only the tax objects are not used, and the detail data-mapping for the input parameters can change depending on each scenario.
Enter the Inbound PO NF through the ORFM user interface. Once the NF is entered, tax call is initiated. The taxes returned by the external tax engine is compared against the informed taxes for any discrepancy.
NFs from the supplier could be interfaced to RFM through EDI functionality. These NFs once generated also make a tax call through the batch provided. The taxes returned by the external tax engine is compared against the informed taxes for any discrepancy.
Tax calls are made from the RFM application during the receiving process based on the Resolution type on the Discrepancies identified during Validation of a NF.
For outbound transactions like Transfer, RTV and Inventory Adjustments initiated by the Retailer, ORFM generates the NFs automatically. These NFs generated makes the tax calls and the taxes are printed on the document before approval and inventory movement.
The PO tax breakdown is the calculation of all applicable taxes of a PO. The PO information is similar to a fiscal document, and it is similar to the NF issuing process. The PO information utilizes the API format to have the tax calculated.
During the item creation process, the sales taxes applicable to each location where the item is linked are calculated. The item creation process also makes a call to the tax API to obtain the sales tax rates. The same concept is applied to the default purchase taxes used for margin calculation.
Scenarios such as primary supplier change and fiscal reclassification call the same tax integration defined for original item creation process.
