| 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 |
This chapter discusses the common issues that you have to consider as you progress towards a production environment involving the Oracle Retail Tax Integration Layer (RTIL). It is not a comprehensive list since they are very dependent on the retailer implementation.
The operational issues that are to be considered when using RTIL are detailed in the following sub sections:
Since RTIL is an integration subsystem that runs with no console, it is important to monitor the application log files that are created. The log files have to be monitored for the content (looking for exceptions), and also the size and growth of the exceptions. RTIL logs are created in the $WEBLOGIC_DOMAIN/log folder in the domain where RTIL is deployed.
The log files that are to be considered are:
rtil.log – This is the primary log file which captures the RTIL server interactions with external tax engine. All the exceptions/failures that occur in the tax engine and RTIL interactions are logged in this file.
taxdatastage_services.log – This log file captures RTIL interactions with RMS/ORFM application. All the exceptions/failures that happen during these interactions are logged in this file.
RTIL uses log4j for all of its logging control. It manages the logs size through its control file (log4j.properties), auto archive, and purge. This configuration file is embedded in the rtil-service.ear file in the lib\rtil-config.jar folder. This configuration file controls the behavior of logging in the rtil.log file. The file is configurable through the installer at install time. The file can also be manually modified for any changes that have to be made after the installation.
|
Note: Refer to the Apache Software Foundation http://logging.apache.org/log4j/1.2/manual.html for more details on log4j. |
Below is a snapshot of the RTIL log4j.properties
log4j.appender.LOGFILE=org.apache.log4j.RollingFileAppender log4j.appender.LOGFILE.MaxFileSize=5MB log4j.appender.LOGFILE.File=./log/rtil.log# Keep thirty 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
The property log4j.appender.LOGFILE.MaxFileSize determines the maximum size of the log file before being rolled over. It is recommended to have a optimal size of not more than 5 MB. If the size of this file increases, it may lead to performance issues.
The property log4j.appender.LOGFILE.MaxBackupIndex depicts the maximum number of files to be archived in the $WEBLOGIC_DOMAIN/log folder. This value has to be based on the retailers' needs, the archival strategies, and the backup strategies.
Retail tax transactions involves interactions between multiple applications like the Oracle Retail Integration Bus (RIB), RMS, ORFM, any Store Inventory Management system, any Warehouse Management system, RTIL and TaxWeb Tax Rules. Since there are multiple applications involved, they need to be handled very carefully in case of systemic failure in one or more applications.
The time-outs have to be configured diligently based on retailer's needs, volume of data, processing hardware etc. The time-outs have to ensure proper exits in case of slow responsive applications or systemic failures in applications.
A typical example of the retail tax transaction is as follows:
An inventory adjustment retail transaction comprises of the following interactions between RIB, RMS, ORFM, RTIL and TaxWeb Tax Rules:
Publication of Inventory Adjustment RIB message from any warehouse management system.
RMS consumes the RIB message through the subscription API and routes it to ORFM.
ORFM generates the Nota Fiscal (NF).
During NF validation, ORFM invokes a synchronous tax call to a TaxWeb Tax Rules through RTIL.
ORFM inventory is updated and the response is sent back to RIB.
To ensure that the retail transactions are not adversely impacted in case of systemic failures in one or more applications, the time-outs has to be configured appropriately to have a exit path.
The general rule of thumb is that the time out configurations progressively decrease in a call sequence flow as we move from the top layer to the lowest layer, and have to be configured in the following subsystems:
WebLogic Server
RMS
RIB
This time-out value is configured in the RMS table (RETAIL_SERVICE_REPORT_TABLE) for the record (RS_CODE=RTIL) and passed on to the RTIL client component (URLInvoker) when triggering a request to the RTIL server. Note the entry configured in the table is in the units of milliseconds. If the time-out value is not configured, then URLInvoker is set to a default value of 180 seconds.
This time-out caters to RTIL client component and ensures that the client component throws back an error response on expiry of the time-out in RTIL client or if the RTIL server fails to respond within the configured threshold.
The RIB transactions are also configured with a time-out threshold value to ensure that RIB transactions do not wait forever.
While setting up the test environment, the following time-out values are configured:
URLInvoker time-out – 1000 seconds
RIB time-out – 1200 seconds
If any of the subsystems are responding slowly outside the range of its configured thresholds, time-outs are triggered. Eventually, these are sent back to RIB with an error status, which causes RIB to rollback the transaction and deliver it to the error hospital or the adapter will shut down based on the nature of the error.
|
Note: The time-out configurations specified are for indicative purpose only. They have to be customized based on the retailers' platform, environment, transactional volume and hardware. |
RTIL has a workmanager called "RTILWorkMgr" to support concurrent processing in RTIL for voluminous requests. The concurrent processing behavior is triggered in RTIL based on flag contained in its client's (RMS/ORFM) request.
Since RTIL uses WebLogic WorkManager, the following configurations depicted below can be modified/tuned in the WebLogic administrator console by a WebLogic Administrator:
This parameter depicts the maximum number of concurrent threads that can be allocated to execute requests. The default is set to 16. Typically, it is recommended to set this value based on the number of processors available in the system in which RTIL is deployed.
This parameter depicts the maximum limit of the requests that can be queued or executed. The default is set to 20000. After this, the WebLogic Server rejects requests.
|
Note: The work manager configurations specified are for indicative purpose only. They have to be customized based on the retailers' platform, environment, transactional volume, and hardware. |
|
Note: In case the WebLogic Administrator wants to modify the workmanager configurations, the details are provided in Working with RTIL. |
This section discusses some of the errors (systemic or configuration related) that can occur in RTIL and its integration with the TaxWeb Tax Rules, and also RTIL integration with RMS/ORFM and consequently RIB. This section provides an overview of the errors, the cause and the corrective action that has to be taken. Some of the errors includes:
Error Message – In case the RTIL URL is incorrectly configured (format is wrong, hostname or port number is incorrect), any RMS/ORFM request to RTIL results in an error in the RTIL client component (URLInvoker hosted in RMS database schema), and the error message returned to the RMS is the incorrect URL format. The Example 9-1 provides the incorrect URL format, with the incorrect part highlighted in bold.
Example 9-1 Incorrect URL
http://mspdv310.us.oracle.com:17069/rtil-web/invokeApp123?invocationType=CALC_TAX&invocationKey=1234
Cause – The URL returned as depicted in the error message indicates that the RTIL URL is incorrectly configured in RMS.
Resolution – Update the URL column in the retail_service_report_url table with correct RTIL URL configuration as shown in Example 9-2. The correction is made to the portion that is highlighted in bold in Example 9-1.
Error Message – RTIL responds with the error message "Connection Refused" for any RMS/ORFM request to RTIL.
Cause – This error is typically thrown when the RTIL service is down.
Resolution – Restart the RTIL application instance from the WebLogic Administration Console. You must have WebLogic Admin privileges for this operation. In addition, an administrator has to investigate the WebLogic admin logs to ascertain the reason for the failure of the service before restarting it.
Error Message – In ORA-00942: table or view does not exist ORA-06512: at "SYS.DBMS_PICKLER", line 18ORA-06512: at "SYS.DBMS_PICKLER", line 58ORA-06512: at line 1
Resolution – Usually occurs because the user used in the connection point does not have sufficient privileges to the Package or Objects being referred to in the application. Either change the user that is being used or make sure proper permissions and synonyms are created in Oracle.
Error Message – Unknown Error occurred. Please check the log file for more details The error in the RTIL logfile is provided in Example 9-3
Example 9-3 RTIL Log File
java.lang.ClassNotFoundException: com.mcfox.tax.management.TaxRulesAPI
at weblogic.utils.classloaders.GenericClassLoader.findLocalClass(GenericClassLoader.java:280)
at
weblogic.utils.classloaders.GenericClassLoader.findClass(GenericClassLoader.java:253)at java.lang.ClassLoader.loadClass(ClassLoader.java:303)at java.lang.ClassLoader.loadClass(ClassLoader.java:248)at
weblogic.utils.classloaders.GenericClassLoader.loadClass(GenericClassLoader.java:177)at java.lang.Class.forName0(Native Method)at java.lang.Class.forName(Class.java:169)at
com.oracle.retail.tax.servicegateway.MastersafPojoServiceGateway.init(Unknown Source)at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)at java.lang.reflect.Method.invoke(Method.java:597)
Cause – This error typically occurs if the TaxWeb Tax Rules required libraries are not deployed in the $WEBLOGIC_DOMAN/lib folder of RTIL instance. The error message given is for reference only and will vary based on the missing library.
Correction – Refer to the TaxWeb Tax Rules Installation Guide and ensure that all the libraries (jar files) are made available in the $WEBLOGIC_DOMAIN/lib folder of the deployed RTIL instance. Before transferring the missing files, ensure that the RTIL application instance is shutdown from WebLogic admin console.
The following two steps are recommended for a quick sanity test to check if RTIL is deployed correctly and ready to serve requests:
Technical Ping
Application Ping
Technical Ping
This step is to ascertain if the RTIL service is running. Open a browser and enter the deployed RTIL URL in the address bar of the browser.
Expected Result – Enter the deployed RTIL URL in address bar of a browser http://<hostname>:<portnum>/rtil-web/invokeApp (For example http://mspdv310.us.oracle.com:17069/rtil-web/invokeApp). If the response in the browser window is "E|invocationKey not present", this implies RTIL service is running.
Application Ping
This step is to ascertain if RTIL is correctly deployed and the configuration to RMS/ORFM is valid.
To sanity test an RTIL deployment, run the stored procedure provided in Example 9-4 in an Oracle database schema in which RMS localized version has been deployed. Ensure that the arguments are replaced in the invokeURL call in the procedure to reflect the URL where RTIL is deployed.
Example 9-4 Procedure
Rem Rem This SQL Script executes the Java Stored ProcedureRemSET SERVEROUTPUT ONCALL dbms_java.set_output(2000);DECLARE o_status VARCHAR2(255); o_error VARCHAR2(255);BEGIN--EX : invokeUrl
invokeUrl('<url>',<invocationType>', '<keyId>', '<timeout>',o_status, o_error); DBMS_OUTPUT.PUT_LINE('status ' || o_status); DBMS_OUTPUT.PUT_LINE('status ' || o_error); END; /
url = url where RTIL is deployed
(For example, 'http://mspdv309.us.oracle.com:7003/rtil-web/invokeApp')
invocationType = CALC_TAX(for tax calls)
keyed = 1234 (a dummy key id)
time-out = 1800(a dummy time-out value)
Expected Result – 0L10N_ROUTE_INFO_NOT_FOUND@11234 – This would imply that RTIL is deployed correctly and also the configuration from RTIL to RMS/ORFM is valid.
Most of the retail tax transactions which have a taxation requirement are plain compute operations in TaxWeb Tax Rules without any data persistence. So failure in RTIL/RMS/ORFM post tax computations does not mandate a data rollback operation within TaxWeb Tax Rules. For certain exclusive ORFM scenarios like triangulation and recovery of ST, the TaxWeb Tax Rules performs persistence of data in its tables which mandate a rollback of data in case of failures in post processing.
For handling rolling back of persisted data in the TaxWeb Tax Rules tables in the event of a post processing failure in ORFM, it invokes a cancelTax (a compensation API) on to the TaxWeb Tax Rules which deals with explicit removal of persisted transaction data. In the rare event of failure of this compensation API, the failure will be logged in RTIL log file along with the data details. In such scenarios, a manual clean up of records is required. The following tables have to be cleaned:
TAX_DOCFISCALHIST
TAX_ENQHIST
TAX_ENQITHIST
TAX_PESSOAHIST
TAX_REC_ST_ENTRADA
TAX_REC_ST_SAIDA
|
Note: Refer to the TaxWeb Tax Rules documentation for further details on the tables. |
The TaxWeb Tax Rules libraries have to be frequently updated since the content of TaxWeb Tax Rules changes due to incorporation of Brazil tax legislation changes.
RTIL, RMS, ORFM and RIB also would have patch upgrade requirements. To ensure smooth flow of operations at the customer environment, these subsystems have to be stopped and started in a particular order.
The recommended order for stopping the systems during a patch maintenance window is RIB, RMS/ORFM and RTIL and the start up sequence is in the reverse order. RIB is an aggregation of distributed components and refer to RIB Operations Guide, for further details on start and stop of RIB internal components. TaxWeb Tax Rules being a library of RTIL does not have an independent operational start and stop sequence of its own.
The following table provides the failure scenarios in tax flows:
Table 9-1 Systemic Failure Scenarios in Tax Flows
| Event | Scenario | How is it handled |
|---|---|---|
|
RibForRMS goes down |
RTIL, TaxWeb Tax Rules computation is completed, and RMS/ORFM tables are updated |
Data will not be read/used as RIB transaction would have rolled back |
|
RTIL failure |
RIB transaction has updated RMS tables and RTIL stops responding |
URLInvoker in RMS will receive an error as it is a synchronous call, which will result in an "E" status back to RIB. RIB then initiates a rollback of the data updated in RMS |
|
RTIL fails to respond (very long running transaction) |
RIB transaction has updated RMS tables and RTIL does not respond |
URLInvoker will time-out resulting in an "E" status back to RIB which triggers a rollback of updated data in RMS |
|
TaxWeb Tax Rules business failure |
RIB transaction has updated RMS tables and RTIL fails to fetch the tax as the TaxWeb Tax Rules is unable to compute the tax due to a data issue in the request |
RTIL returns an error to RMS and RMS sends back "E" status to RIB which triggers a rollback of updated data in RMS |
|
RTIL failure in updating RMS tables with tax results |
RIB transaction has updated RMS tables with request data, RTIL successfully calls the TaxWeb Tax Rules and obtains the taxes and RTIL updates to RMS tables results in a failure |
RTIL returns an error to URLInvoker and this results in RMS sending an "E" to RIB which triggers a rollback of updated data in RMS |
Some of the business flows will have a RIB XA transaction spawn across RIB, RMS, ORFM, RTIL, and TaxWeb. In such scenarios, the performance of a RIB transaction is inclusive and dependent on the participating downstream applications like RMS/ORFM/RTIL/TaxWeb. You need to be aware that any adverse behavior of TaxWeb due to poor performance in case of high volume, inherent bugs (if any), or any other issues can potentially result in RIB timeouts/in doubt transactions/RIB failures impacting the RIB adapters.
TaxWeb's lazy load solution is recommended if RTIL is deployed on a memory constrained environment.
The TaxWeb solution has the following two flavors primarily in terms of the memory footprint it occupies:
Static Load Version
Lazy Load Version
The Static Load Version loads all the tax rules available in the content at initialization time and has a larger memory footprint. This version requires about 5 GB of Java Heap Size space for it to be functional.
The Lazy Load Version implements an on-demand load feature. This implies only the tax rules needed to satisfy a tax computation request is loaded on the fly into the TaxWeb engine when it receives a tax calculation request.
The Lazy Load version is provided as an alternative to address deployments where in there is a crunch for physical memory.
