Solution Testing and Debugging Guide
Version 1.0, July 2015
Solution Testing and Debuggin Guidelines
Copyright © 2015, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Contents 1. Introduction ...... 3 2. Environments ...... 4 3. Testing and Debugging Solutions ...... 5 3.1 Testing and Debugging in OSM ...... 5 3.1.1. Debugging OSM XQuery Expressions ...... 5 3.1.2. Testing OSM Cartridge Projects ...... 7 3.1.3. Testing OSM SOM Components ...... 7 3.1.4. Submitting Test Orders from Design Studio...... 8 3.2 Testing and Debugging in UIM ...... 9 3.2.1. Testing the Design and Assign Provider Function ...... 9 3.2.2. Testing the Calculate Technical Action Provider Function...... 10 3.3 Testing and Debugging in ASAP ...... 11 3.3.1. Testing ASAP Cartridge Projects Using OCA ...... 11 3.3.2. Testing ASAP Cartridge Projects Using the ASAP Test Suite ...... 13 3.3.3. Testing ASAP Cartridge Projects Using Design Studio Activation Tests ...... 13 3.3.4. Testing ASAP Cartridge Projects Using ASAP Unit Tests ...... 15 3.3.5. Testing ASAP Cartridge Projects Using Design Studio Custom Unit Tests ...... 16 3.3.6. Initializing the ASAP Environment ...... 19 3.3.7. Reviewing ASAP Work Order Statuses ...... 19 3.4 Using Emulators ...... 21 4. Troubleshooting ...... 22 4.1 Determining Version Numbers ...... 22 4.1.1. Determining the ASAP Application Version Number ...... 22 4.1.2. Determining the UIM Application Version Number ...... 22 4.1.3. Determining the OSM Application Version Number ...... 23 4.1.4. Determining the Design Studio Version Number ...... 23 4.1.5. Determining Design Studio Project Version Numbers ...... 24 4.2 Working with Log Files...... 25 4.2.1. Working with the OSM Log Files ...... 25 4.2.2. Working with the ASAP Log File ...... 25 4.2.3. Working with the UIM Log Files ...... 26 4.3 Working with Utilities ...... 26 4.3.1. Working with OSM Utilities ...... 26 4.3.2. Working with ASAP Utilities ...... 27 4.3.3. Working with UIM Utilities ...... 28 4.4 Understanding Common Errors ...... 29 4.4.1. Understanding UIM Errors ...... 29 4.4.2. Understanding OSM Errors ...... 30 4.4.3. Understanding ASAP Errors ...... 30
Solution Testing and Debugging Guide
1. Introduction
This paper describes techniques that you can use during solution development to accelerate solution testing and debugging processes.
Solution Testing and Debugging Guide
2. Environments
Solution development testing and debugging includes the following testing phases: • System Testing and System Integration Testing • Hand-off point to the SI, customer, or to the larger Oracle team • User Acceptance Testing • Performance Testing • Non-Functional Testing • System Readiness Testing • Failover Testing • Operational Readiness Testing This paper focuses on techniques that you can use during developer-level unit testing to prepare for integration testing.
Solution Testing and Debugging Guide
3. Testing and Debugging Solutions You can use multiple techniques to test and debug solutions. Some techniques are determined by the application in which you are working. This section describes common testing and debugging techniques for some Oracle Communications applications.
3.1 Testing and Debugging in OSM OSM is metadata-driven: when you add new OSM entities, such as new Project or Order entities, Design Studio builder identifies all errors. Fix these problems first.
3.1.1. Debugging OSM XQuery Expressions XQuery is used extensively in OSM. There are many tools available for debugging XQuery expressions. This section describes techniques for debugging XQuery expressions using the oXygen XML editor as a stand-alone editor or by installing the oXygen Eclipse plug-in. Note: To use the oXygen XML editor, you must first obtain an oXygen license.
Using the oXygen XML Editor as a Stand-Alone Editor The oXygen XML editor features syntax highlighting and checking of XQuery source files. To use the oXygen XML editor, you must first configure the editor to ensure that it can properly validate the OSM automator XQuery source code. Completing this setup ensures that the oXygen editor can locate imported XQuery libraries and external Java class references. Note: Before you perform the steps in the following procedure, you must:
Install the JDK, the Design Studio application, and the OSM SDK.
Install the OracleCommons_OSM_OSS_Common cartridge project into your Design Studio workspace.
See the Design Studio documentation for more information.
To set up the oXygen XML editor to use as a stand-alone editor for OSM:
1. Create an XML catalog file. This new XML catalog file is used to rewrite URL to libraries in OSM SDK or JDev directories.
Create an XML catalog file with the following content:
where
Solution Testing and Debugging Guide
pathname is the location of the directory that contains the OracleCommons_OSM_OSS_Common cartridge project.
For example:
file:///D:/DesignStudioKeplerslc01eqpworkspace/OracleComms_OSM_OSS_Common/r esources/OrderLifecycleManagement
2. From the oXygen preference dialog box, navigate to XML/XML Catalog. 3. Add the new XML catalog file to the list of catalogs. 4. Click OK. 5. From the oXygen preference dialog box, navigate to XML/XSLT-FO-XQuery/XQuery. 6. In the Validation Engine field, select Saxon-EE. 7. Click OK. 8. From the Document menu, select Transformation, and then Configure Transformation Scenario. 9. Name the scenario. 10. In the Transformer field, select Saxon-EE. 11. Click Extensions. 12. Add the following Java libraries as extensions by replacing $XXX with the pathname: a. $OSMSDK/Automation/automationdeploy_bin/automation_plugins.jar b. $Oracle/Middleware/modules/javax.ejb_3.0.1.jar c. $Oracle/Middleware/modules/javax.jms_1.1.1.jar 13. Click OK. 14. Click Save.
Using the oXygen Eclipse Plug-in with Design Studio
You can install the oXygen Eclipse plug-in into Design Studio. Installing the plug-in enables code syntax checking and color codes in the Eclipse XQuery text editor.
Note: To use the oXygen Eclipse plug-in, you must first obtain an oXygen license.
When you install the plug-in:
Design Studio can detect the floating license Design Studio automatically configures the XML catalog file You must reconfigure the transformation scenario
When installing the plug-in, consider the following:
You must manually associate the custom transformation scenario to every XQuery file. Switch to the oXygen XML perspective and use the Transformation tab to complete this configuration. XQuery files are not displayed in Design Studio project trees. You can view XQuery files in the Automated Task editor Properties tab, but you cannot open XQuery files from the Task editor. To view XQuery files in an editor, switch to the Package Explorer view, navigate to the resources directory of the project, then double-click the XQuery.
Solution Testing and Debugging Guide
3.1.2. Testing OSM Cartridge Projects To test OSM cartridge projects:
1. Validate the following in the Order Recognition Rule:
The XQuery that validates orders (the URI option is the recommended selection) The XQuery that sets the order priority and the order reference The XQuery that transforms the order data
You can submit a test directly from Design Studio using a sample order.
2. Validate the XQuery in the Order Item specification. The Order Item specification contains order data and all order parameters. XQuery is associated with each order item property. 3. Validate the XQuery associated with the fulfillment pattern and with the decomposition rules in the orchestration plan. 4. Ensure that during order processing orders properly arrive at the correct task. 5. Validate the XQuery associated with automated tasks. Automated tasks use XQuery to: Format and send order data Process response data and update OSM
When validating the XQuery associated with automated tasks, ensure that you have a valid sample doc example and use an emulator to send back responses.
3.1.3. Testing OSM SOM Components When testing the OSM Service Order Management component, you must have available an entire environment with servers or with emulators.
To test OSM SOM components:
1. Change the Oracle WebLogic rotation log server setting to 20M and change the log level to debug. 2. Change the OSM log4j log level to debug for the following components: ProcessBIReceiver ProcessBISender CaptureBIReceiver
The OSM log4j log level URL is: http://host:port/OrderManagement/admin/log4jAdmin
Changes that you make to the log4j log level are lost when the server is restarted.
3. In the WebLogic security realm, assign one user to deploy cartridge projects. This user should have OSM privileges and Design Studio deploy privileges. 4. If you’re using oXygen, validate the XQuery to ensure that no syntax errors exist.
Solution Testing and Debugging Guide
3.1.4. Submitting Test Orders from Design Studio The Design Studio Submit Test feature enables you to submit a sample XML order to a run-time environment for the purpose of testing cartridge projects. For example, when creating recognition rules for an orchestration cartridge project, you can submit sample orders to ensure that the OSM server is properly recognizing the input messages for each recognition rule and directing the order to the correct cartridge project. Additionally, you can target the sample order to a specific version of a cartridge project, test OSM behaviors, and so forth. When submitting sample orders to run-time environments, the root level of the sample order XML document must be the CreateOrder or the CreateOrderBySpec XML API request. For example:
You save all sample XML orders in a project samples directory, accessible from the Package Explorer view. To submit test orders to run-time environments: 1. In Design Studio, from the Package Explorer view, copy a sample XML order into the project samples directory. 2. Connect to an environment. When connecting to the environment, ensure that the account that you use to log in is set up properly in WebLogic. To submit tests from Design Studio, user accounts must be assigned to the OMS_client and to the OMS_ws_api groups in WebLogic. 3. If necessary, deploy the full cartridge project to the run-time environment. 4. From the Studio menu, select Show Design Perspective. 5. In the Studio Projects view, right-click a cartridge project and select Submit Test. If you have successfully connected to an environment and if your project contains a valid sample order in the project samples directory, Design Studio displays a list of environments and files available to submit. 6. Select an environment and order combination. The Console view is displayed, indicating the status of the submitted order. If the connection is successful, the Console view displays the OSM server response, which includes the order ID, version number, the cartridge project name, and so forth. Design Studio opens a browser window in the editor area that points to the log-in window for the environment.
Solution Testing and Debugging Guide
7. Log into the environment. The Web UI displays a list of orders submitted to the environment. 8. Locate the table row that contains your sample order. For example, you might locate the row using the order ID displayed in the Console view. 9. Double-click the sample order to open the order and review the order data in the Web UI tabs. For example, if you were submitting a sample order for an orchestration cartridge project, you could review the information in the Summary tab, Data tab, Orchestration Plan tab, and so forth. 10. (Optional) Update the cartridge project with additional changes, save the changes, and use the Optimize Deploy feature to deploy only the cartridge project metadata changes. 11. (Optional) Connect to another environment to test the cartridge project in multiple environments. 12. (Optional) Clear the environment connection information if you want to submit a sample order as a different user. From the Studio Projects view, right-click a cartridge project and select Submit Test, then select an environment, then select Clear Environment Credentials to clear the environment connection information.
3.2 Testing and Debugging in UIM The following sections describe how to test the Design and Assign provider function and the Calculate Technical Action provider function.
3.2.1. Testing the Design and Assign Provider Function During development, you write the Java code for the provider function, you build cartridge projects, and you deploy the cartridge projects to UIM using Design Studio. You use SOAP UI to test Web services associated with the provider function. You can test the Design and Assign provider function at the customer facing service level or at the resource facing service level.
To test the Design and Assign provider function:
1. In UIM, validate the results listed in the transaction log and visually inspect the outcome of the provider function. 2. Use Web services to call ProcessInteraction. 3. If ProcessInteraction fails, log in to the UIM server log and review errors. 4. In UIM, enable remote debugging server code. Edit the fileset UIM.sh (located in the UIM domain bin directory) and insert the italicized line in the example below:
JAVA_OPTIONS="${JAVA_OPTIONS} -DUSE_JAAS=false - Djps.policystore.hybrid.mode=false - Djps.combiner.optimize.lazyeval=true -Djps.combiner.optimize=true - Djps.authz=ACC"
JAVA_OPTIONS="${JAVA_OPTIONS} -Xdebug -Xnoagent - Xrunjdwp:transport=dt_socket,address=8999,server=y,suspend=n"
export JAVA_OPTIONS
Solution Testing and Debugging Guide
5. Restart the UIM managed server.
6. In Design Studio, use the Eclipse Java debugger with the following debug configuration: . Connection Type: Standard (Socket Attach) . Host: UIM host . Port: 8999 . Allow termination of remote VM: disabled
Using this configuration enables you to set breakpoints on Java code, such as the auto-design logic for service configurations.
7. Edit the UIM loggingconfig.xml file to display detailed Design and Assign run-time errors. This configuration is used only for testing and debugging. It should be disabled in a production system. Add the following configuration:
3.2.2. Testing the Calculate Technical Action Provider Function When testing the Calculate Technical Action provider function, you can enable debugging in the UIM logging configuration file. Enabling the debugging level generates a formatted document that contains before and after configuration. XPath expressions are evaluated against the elements in this document. You can test the Calculate Technical Action provider function in the context of a service order that includes a customer facing service action intended for the Design and Assign provider function.
To test the Calculate Technical Action Provider Function: 1. Open the domain/UIM/config/loggingconfig.xml file. 2. Add the following loggers:
Solution Testing and Debugging Guide
3.3 Testing and Debugging in ASAP There are multiple strategies available for testing ASAP cartridge projects. You can:
Test cartridge projects on the ASAP server using: o OCA o ASAP Test Suite o Design Studio Activation Test Test cartridge project components in Design Studio using: o Standard unit testing o Custom unit testing
The strategy that you use is determined by the type of work you are doing in ASAP. For example, you might need to: Review cartridge project content and functionality prior to a demonstration or a proof of concept. In this scenario, you might test using OCA. Develop cartridge projects in Design Studio and use iterative testing. In this scenario, you might test using standard unit testing.
3.3.1. Testing ASAP Cartridge Projects Using OCA The ASAP Order Control Application (OCA) is a Java-based GUI that communicates with the OCA Service Request Processor (SRP) server. OCA is commonly used to perform fallout management; however, you can also use it to perform Oracle Communications ASAP work order queries and submit new ASAP work orders. See Oracle Communications ASAP Order Control Application User's Guide for more information. The OCA is available as a stand-alone application or as an applet that you can run in a browser and embedded in an HTML Web page. You can use OCA for testing ASAP cartridge projects if you are unfamiliar with Design Studio and if you are preparing for a demonstration or proof of concept using productized cartridge projects. To test cartridge projects using OCA, you create an order in OCA and use OCA order management to monitor and examine the results. Testing using OCA requires that cartridge projects are fully designed, functional, and deployed to an ASAP server.
Solution Testing and Debugging Guide
The following screen shot shows the CSDL dialog box in OCA where you review the Common Service Description Layers (CSDLs) associated with a cartridge project:
The following screen shot shows the Work Order Details page in the OCA, where you can select work orders from the Work Order Query screen to view work order details:
Solution Testing and Debugging Guide
3.3.2. Testing ASAP Cartridge Projects Using the ASAP Test Suite An ASAP test suite is a set of text files that define work orders. Many ASAP cartridge projects (.sar files) contain a SampleWorkOrders directory with one or more test suites. You can create your own test suites in Design Studio by creating a test directory. The files that you add to this directory are bundled into the .sar file in the SampleWorkOrders directory. To test ASAP cartridge projects using a test suite, run the test suite script run_suite on the ASAP server. The test suite uses an SRP emulator to send work orders through ASAP. Use the asap_utils script or OCA to monitor the results.
3.3.3. Testing ASAP Cartridge Projects Using Design Studio Activation Tests
An Activation test case (test work order) enables you to test, in Oracle Communications Design Studio, the Activation order completion for a cartridge project to verify that a work order is sent to the Oracle Communications ASAP environment. Consider the following when creating and running test cases:
Solution Testing and Debugging Guide
Each test case can have multiple service actions. It is possible to run multiple tests that are identical except for the parameters. Design Studio runs all of the test cases in sequence. Test cases use OSSJ interface. Design Studio logs all OSS/J responses from the ASAP environment to the Console view in Design Studio.
To test ASAP cartridge projects in Design Studio, you create an activation test case and then you run the test case.
Use Activation test cases if you want to test cartridge projects without having to write Java code and if you are unfamiliar with OSS/J. Also, you can use Activation test cases to test ASAP cartridge projects if you are familiar with Design Studio and if you are preparing for a demonstration or proof of concept using productized cartridge projects. Testing using Activation test cases requires that cartridge projects are fully designed, functional, and deployed to an ASAP server. The following screen shot illustrates the steps to run a test case in Design Studio:
Solution Testing and Debugging Guide
3.3.4. Testing ASAP Cartridge Projects Using ASAP Unit Tests You can test cartridge projects using Design Studio unit tests. Unit tests contribute to building quality code and provide repeatable tests for regression. You can test the processor outside of the ASAP system because the interfaces and generative classes of the Java processor are all independent of the ASAP system and its classes (the generated InputBeans and output are not tied to ASAP). To run the processor, a test case is generated once (with a sample test based on information at the time of creation). You can extend the test case after it is generated. You can use ASAP unit tests for testing when you need to run a large set of unit tests quickly against your action processors. The unit test framework initiates all tests in a test subfolder. Unit testing is implemented as a JUnit test. JUnit tests can optionally be run with the JDT Debugger. See JUnit Web site for more information: http://www.junit.org
When testing ASAP cartridge projects using unit testing, consider the following: • When you create a network action, Design Studio auto-generates one JUnit test case in the src folder. A unit test class is created in same folder as the action processor class. • You use a .testdata Java property file and a .testinfo Java property file to set up a unit test. • You must create one or more .testdata files in Design Studio. The .testdata files contain test orders. • The .testinfo file is optional. Use this optional file to define the properties for which you are testing. You can also define what expected request the processor should create, the expected canned response returned to the processor, the expected exit type and whether it should be tested. • Save the .testdata files in a subfolder of the action processor implementation package named test. Optional .testinfo files can be used to enforce test conditions on results. • The parameters defined in the .testdata file are sent to the Action Processor code. • During the test, the ConnectionHandler doesn’t interface with the network element. The ConnectionHandler only logs the request generated by the network action and returns a null value. • Unit test only your action processor. • The quality of your test depends on the parameters defined in the .testinfo file. The following screen shots illustrate the .testdata file content and the .testinfo file content:
Solution Testing and Debugging Guide
To test ASAP cartridge projects using a unit test: 1. Select your TestCase Java class in your cartridge project. 2. Right-click the TestCase class and select Run As. 3. Select JUnit Test or Java Application. Design Studio displays the results in the JUnit view or in the Console view. The following screen shot illustrates the results as displayed in the JUnit view:
3.3.5. Testing ASAP Cartridge Projects Using Design Studio Custom Unit Tests You can use custom unit tests if you are using a connection handler with connections other than telnet. Custom connection handlers generate a skeleton to implement the IconnectionHandler and extend the base NE connection class. The NE Connection Handler editor indicates where additional code is required.
Solution Testing and Debugging Guide
Custom unit tests leverage the JUnit framework and attempt to run the .testdata file and the .testinfo files from the standard unit tests (you can override this behavior). Auto-generated TestCase provides a place holder to write your own custom unit tests.
When testing ASAP cartridge projects using custom unit testing, consider the following: • Custom unit testing requires Java development skills. • You can use a real connection handler to allow unit tests to be executed against a live device directly from Design Studio. • Custom unit testing is essential for iterative cartridge project development. For example, you can quickly test code changes against live devices. Also, custom unit testing does not require that you deploy the cartridges to the ASAP run-time environment. To test ASAP cartridge projects using custom unit tests: 1. Enhance the connection handler to run only in Design Studio. At run-time, ASAP provides the connection handler with communication parameters, such as user name, URLs, and so forth. Add the following properties to the connection handler to expose a new constructor that accepts a set of communication parameters to run only in Design Studio: // These properties will only be used when running from Design Studio private Properties testConfig = null; /** * Constructor for testing the connection handler inside of Design Studio. * This constructor is not used at runtime by ASAP * * @param config The offline configuration properties to use */ public MyConnectionHandler(Properties config) { super(); logger = new ConsoleLogger(); testConfig = config; } /** * Returns the value of a given parameter * * @param name The parameter name * * @return The value of the parameter or null if that parameter doesn't exist */ public String getParameter(String name) { // If we are running in an offline test mode (i.e. not in ASAP) we will use the test parameters provided // in the constructor. Otherwise we'll attempt to pull them from ASAP. if (testConfig != null) { return testConfig.getProperty(name); } // We are running live in ASAP! return super.getCommParam(name);
Solution Testing and Debugging Guide
} 2. Update the connect() and disconnect() methods so they are visible to your unit test. Update the methods from protected to public: public void connect() throws ConnectionException { . . . } public void disconnect() throws DisconnectionException { . . . } 3. Extend the generated unit test to add exit types. Use the user defined exit types that are defined in Design Studio: /* * This method is responsible for populating the Exit Types */ public void addUserExitTypes(TestCaseExitType exitType) { // Add All User Defined Exit Types exitType.addUserExitType(new TestCaseUserExitType(IExitType.FAIL, "Error response detected.", "FAILURE")); exitType.addUserExitType(new TestCaseUserExitType(IExitType.SUCCEED, "Error response detected.", "SUCCESS")); } 4. Write a unit test based on the following template: /** * Some test */ public void testCustom() throws Exception { // Create the Connection Handler (Offline Test version) Properties commConfig = new Properties(); commConfig.setProperty("LOOPBACK_ON", "0"); commConfig.setProperty("WEBEX_USERNAME", "username"); commConfig.setProperty("WEBEX_PASSWORD", "passw0rd"); commConfig.setProperty("WEBEX_EMAIL", "[email protected]"); commConfig.setProperty("WEBEX_PARTNER_ID", "12345"); commConfig.setProperty("WEBEX_SITEID", "243585"); commConfig.setProperty("WEBEX_URL", "https://apidemoeu.webex.com/WBXService/XMLService"); commConfig.setProperty("PROXY_SERVER", "aaa.oracle.com"); commConfig.setProperty("PROXY_SERVER_PORT", "80"); MyConnectionHandler connection = new MyConnectionHandler(commConfig);
// Create and populate the Input Parameters AddContactsInput input = new AddContactsInput(); input.setMCLI(“T_CISCO-WEBEX_5_5_PLATFORM”); input.setFirstName(“Test"); input.setLastName(“Test"); input.setEmail(“[email protected]"); // Create the Output Parameters AddContactsOutput output = new AddContactsOutput(); // Create the System Parameters SystemParameters systemParameters = new SystemParameters(new Properties(), null, null, new ConsoleLogger()); // Create the Exit Type Object IExitType exitType = getExitType(); AddContactsProcessor processor = new AddContactsProcessor(); connection.connect(); processor.execute(input, output, connection, exitType, systemParameters); connection.disconnect();
// Assert exitType and output parameters are set according to the expected test results. String exitTypeValue = exitType.getType();
Solution Testing and Debugging Guide
assertNotNull("Expected exit type to be set.", exitTypeValue); assertTrue("Expected Success exit type.", exitTypeValue.equals(IExitType.SUCCEED)); }
3.3.6. Initializing the ASAP Environment Before running ASAP diagnostic tools, you must first log into the ASAP server and source the ASAP Environment_Profile file: # cd
3.3.7. Reviewing ASAP Work Order Statuses
When debugging ASAP cartridge projects, first run the ASAP utility script asap_utils. Include the option 1 parameter to review the status of all work orders in the ASAP system, and sort the results numerically so that they appear in chronological order:
# asap_utils -d 1 | sort –n
Search the WO_ID column to find the row that corresponds to the work order that you are trying to debug, and then find the associated status from the WO_STAT value. The following example is the output for a work order called JSRP-1000 that is in state 253:
SRQ_ID WO_ID WO_STAT SRQ_STAT ... 2 JSRP-1000 253 13 ...
A work order can be in one of the following states:
102 WO_INIT: The work order is in the Initial state awaiting provisioning 103 WO_IN_PROGRESS: The work order is currently being provisioned 104 WO_COMPLETE: The work order has been completed 253 WO_FAILED: The work order provisioning has failed 255 WO_TRANSLATION_FAIL: The work order translation failed in the SRP
See the ASAP Developer’s Guide for a complete list of error codes.
State 102: WO_INIT
If the work order is stuck in the initialization state, it can mean that the work order has been scheduled for a future date. Check the scheduled date using the following SQL:
# echo "select SCHED_DTS from tbl_wrk_ord where WO_ID like 'WO_ID';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2`
where WO_ID is the work order ID that you are debugging. For example:
# echo "select SCHED_DTS from tbl_wrk_ord where WO_ID like 'JSRP-1000';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2`
SCHED_DTS 20111201 12:00:00
State 103: WO_IN_PROGRESS
Solution Testing and Debugging Guide
If the work order is stuck in the in-progress state, it can mean that ASAP cannot connect to the target network element. Run asap_utils with the option 7 parameter to review the current status of the network element:
# asap_utils -d 7
You can confirm that a problem exists if the State column displays Connecting for the associated network element. In most test systems, ASAP runs in a loopback mode. There should be no connection errors to a network element during a loopback mode. Confirm that ASAP is running in loopback mode by checking that LOOPBACK_ON field is set to 1:
# grep LOOPBACK_ON $ASAP_BASE/config/ASAP.cfg LOOPBACK_ON = 1 # System in loopback (1=Y / 0=N)
Next, ensure that the production mode setting (for example, PROD or TEST) selected during the ASAP installation matches the one used during network element configuration. To check, compare the value of the ASAP_SYS environment variable with the values in the TBL_ASAP_SYS.ASAP_SYS column in the SARM database:
# echo $ASAP_SYS TEST
# echo "select ASAP_SYS from TBL_RESOURCE_POOL;" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` ASAP_SYS TEST TEST ...
If the values in the database don’t match the $ASAP_SYS environment variable, update the database and restart the ASAP server. If the error persists, check for errors or exceptions in:
$ASAP_BASE/DATA/logs/ASAP.Console
Problems related to the environment classpath settings (for example, a ClassNotFoundException) appear in the console. An UnsatisfiedLinkError related to libCSF.so (for example, an error that states: wrong ELF class: ELFCLASS32) indicates that the environment has exceeded the default 32-bit Java Environment_Profile with a 64-bit version. JNEP requires 32-bit Java. Check the PATH environment variable and verify that it’s not pointing to a 64-bit version.
State 104: WO_COMPLETE If the work order was successful, no action is required. Use the diag_merge tool to review the work order processing details.
State 253: WO_FAILED If the work order failed, use the following query to review the reason for failure:
# echo "select FAILURE_REASON from tbl_wrk_ord where WO_ID like 'WO_ID';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2`
where WO_ID is the work order ID that you are debugging. For example:
# echo "select FAILURE_REASON from tbl_wrk_ord where WO_ID like 'JSRP- 1000';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2`
Solution Testing and Debugging Guide
FAILURE_REASON FAIL:The following validation errors have occurred: Parameter CALLER_ID must be 'Y' or 'N' (received: Yes);
If the FAILURE_REASON is empty or does not contain enough information to determine the cause, use the diag_merge tool to investigate
State 255: WO_TRANSLATION_FAIL
Translation failures usually occur when the ASAP service model hasn’t been refreshed completely. Ensure that all of the necessary cartridge projects have been deployed successfully and restart ASAP. If the problem persists, ensure that the work order contains the proper CSDL name.
3.4 Using Emulators The RSDOD reference implementation includes emulators that can be used as placeholders when integrating with external systems, such as supply chain management systems, partner gateway systems, and workforce management systems. You can use these emulators in RSDOD solutions to confirm that the technical order management layer is working properly. Also, you can develop additional emulators as a replacement for edge systems that are impractical to access during the solution development.
Solution Testing and Debugging Guide
4. Troubleshooting The following sections discuss strategies for determining version numbers and information about application log files.
4.1 Determining Version Numbers The following sections describe how to determine the release or version number of the applications and components included in your solution.
4.1.1. Determining the ASAP Application Version Number To determine the ASAP application version number: 1. Log into the ASAP server. 2. Navigate to the ASAP installation directory. 3. Run the following script: $ . ./Environment_Profile $ echo $RELEASE $VERSION \"R7_2_0_P3\" \"B8\" The echo command prints out the version and build number of your ASAP installation.
4.1.2. Determining the UIM Application Version Number To determine the UIM application version number: 1. Log into UIM. 2. From the Help menu, select About.
3. (Optional) Get additional information about the installation. a. Log into the UIM server.
Solution Testing and Debugging Guide
b. Navigate to the WebLogic domain on which UIM is installed. c. Navigate to the UIM/app directory. d. Run the following command: $ unzip -q -c inventory.ear META-INF/MANIFEST.MF Manifest-Version: 1.0 Ant-Version: Apache Ant 1.9.2 Created-By: 1.7.0_45-b18 (Oracle Corporation) Specification-Version: 140407.0039.B321 Implementation-Version: 7.2.4.0.0 Built-Date: 20140407.0039 The command prints out the version and build number of your UIM installation.
4.1.3. Determining the OSM Application Version Number To determine the OSM application version number: 1. Log into OSM. 2. Click About.
4.1.4. Determining the Design Studio Version Number To determine the Design Studio application version number: 1. From the Design Studio Help menu, select Install New Software. 2. Click What is already installed. 3. Click the Installed Software tab. 4. Scroll down to the Oracle Communications Design Studio feature. The version number appears in the Version column.
Solution Testing and Debugging Guide
4.1.5. Determining Design Studio Project Version Numbers The following sections describe how to determine cartridge project version numbers and model project version numbers.
Determining Application Cartridge Project Version Numbers You determine cartridge project version numbers using Design Studio. If a Design Studio system has access to a run-time installation, you can review the cartridge project version numbers in the Design Studio Cartridge Management view. To determine application cartridge version numbers: 1. In Design Studio, switch to the Studio Environment perspective. 2. In the Environment view, select an environment. The version of the application cartridge projects that are in the workspace appear in the Cartridges area. 3. In the Cartridge Management view, click the Query button. The Test Environment Connections dialog box appears. 4. Log into the environment. 5. Select a cartridge project in the Cartridge area. In the Deployed Versions area, the version displays for the cartridge project that is deployed to the run-time environment:
Determining Model Project Version Numbers Model projects are collections of data elements that can be referenced by other projects in a workspace. Model projects include business entities and schema entities that are not specific to an Oracle Communications application and enable you to leverage common definitions and share that data across a solution. You do not deploy model projects to run-time environments. To determine model project version numbers:
Solution Testing and Debugging Guide
1. In Design Studio, from the Studio Projects view, double-click a model project entity. The project opens in the Project editor. 2. Click the Properties tab. The version information is displayed among the fields on the Properties tab:
4.2 Working with Log Files The following section describes the log files that you can use when testing and debugging Oracle Communications applications.
4.2.1. Working with the OSM Log Files The OSM log files are available at the following location: oss_suite_domain_dir/servers/OSM_serverName/logs/OSM_serverName.log For example: private/aiacom_test_install/Middleware_wls/user_projects/domains/suite_domain/servers/OSM_ MS1/logs/OSM_MS1.log
4.2.2. Working with the ASAP Log File The ASAP log files are available at the following location: asap_dir/ DATA/logs For example: private/aiacom_test_install/asap/DATA/logs
There are two types of log files in ASAP:
1. Log files:
Solution Testing and Debugging Guide
Suffix: *.log Location: $ASAP_BASE/DATA/logs For example: $ASAP_BASE/DATA/logs/SARMENV1.log
2. Diagnostic files:
Suffix: *.diag Location: $ASAP_BASE/DATA/logs/
The .diag files contain more details about individual work orders. However, when reviewing .diag files it can be difficult to trace the flow of a given order because each of these files is specific to an ASAP component. Use the diag_merge tool to help consolidate the .diag file messages.
4.2.3. Working with the UIM Log Files oss_suite_domain_dir/UIM/logs/UIMserver_uim.log For example: aiacom_test_install/Middleware_wls/user_projects/domains/UIM/logs/UIM_MS1_uim.log
4.3 Working with Utilities The following sections describe application utilities that you can use to help troubleshoot issues.
4.3.1. Working with OSM Utilities
Log4J The Log4J OSM utility is located at the following location: http://host:port/OrderManagement/admin/log4jAdmin Changes will be lost on server restart.
Orchestration Plan When debug logging is enabled for the loggers starting with: oracle.communications.ordermanagement.orchestration.generation then the orchestration plan output is saved to the WebLogic domain directory. The following screen shot is an example of the output location:
Solution Testing and Debugging Guide
4.3.2. Working with ASAP Utilities
Log4J The Log4J ASAP utility is located at the following location: http://host:port/ENV_ID/log4jAdmin.jsp Use this utility to change the log-level of ASAP core server.
asap_utils Use the asap_utils –d 1 utility command to determine the status of a work order. The most common statuses are: 104 success 255 failure Note: Use the following command to sort orders with most recent at the bottom of the list: asap_utils –d 1 | sort –n Use the following command to view the installed network elements: asap_utils –d 7
diag_merge Use the following command to extract all of the logs for a given work order into a single file: diag_merge diagDirectory outputFile searchString For example: $ diag_merge DATA/logs/20130516 mylogfile.txt 20:603
The diag_merge utility simplifies debugging by consolidating all of the .diag file messages for a given work order into a single file, and the messages are sorted in chronological order. It can be run as follows:
# diag_merge diagDirectory outputFile searchPattern
For example, you can use the work order ID as the search pattern:
# diag_merge DATA/logs/20111101 diag.txt JSRP-1000
Solution Testing and Debugging Guide
The output file typically contains enough information to determine the reason a given work order succeeded or failed. If the output does not contain enough information, search the log or the .diag files for other messages that don't contain the work order ID.
4.3.3. Working with UIM Utilities
Debugging Server-side Java Code To debug the UIM server-side Java code: 1. Locate the following file: oss_suite_domain_dir/bin/setUIM.sh 2. Insert the italicized line: JAVA_OPTIONS="${JAVA_OPTIONS} -DUSE_JAAS=false - Djps.policystore.hybrid.mode=false -Djps.combiner.optimize.lazyeval=true -Djps.combiner.optimize=true -Djps.authz=ACC"
JAVA_OPTIONS="${JAVA_OPTIONS} -Xdebug -Xnoagent - Xrunjdwp:transport=dt_socket,address=8999,server=y,suspend=n"
export JAVA_OPTIONS 3. Restart the UIM managed server. In Design Studio, use the Eclipse Java debugger with the following debug configuration: Connection Type: Standard (Socket Attach) Host: UIMhost Port: 8999 Allow termination of remote VM: disabled Using this configuration enables you to set breakpoints on the Java code, such as the auto-design logic for service configurations.
Debugging Server-Side Database Queries To debug server-side database queries: 1. Extract the UIM application inventory.ear file. 2. Extract the library uim-entities.jar file. cd
Solution Testing and Debugging Guide
4.4 Understanding Common Errors The following sections describe errors common to Oracle Communications applications.
4.4.1. Understanding UIM Errors
Capture Business Interaction Error Problem: CaptureBI fails with the following error: While trying to look up comp/UserTransaction in /app/webapp/UIMServiceFulfillment/664356548 Resolution: This problem is caused by a UIM cartridge project deployment that requires a customlib EAR redeploy, because the cartridge project contributes Java classes. An EAR redeploy may leak PermGen space. When PermGen space is exhausted, the server can react in unpredictable ways. To correct this problem, restart the UIM managed server.
Process Business Interaction Error Problem: ProcessBI fails with the following error: InteractionAdapter.processInteraction Resolution: The captureBI request was empty of parameters. Check the contents of the service order and validate that the parameter set is in an entry near the bottom of the EBM in the element provord:Custom. If these were populated, pause the CaptureBI request queue and check the contents of the outgoing message from SOM.
Solution Testing and Debugging Guide
Clock Skew Error Problem: Calling Web services from a remote client (for example, using soapUI) with clock skew. Resolution: The remote client machine (the solution development environment) must not have a clock skew that is more than one minute offset from the server. Otherwise, Web services authentication fails due to wsu:Timestamp expiration, according to the WS-Security Addendum. There is no obvious error message from the server. The WebLogic server rejects the inbound request with an internal error. To correct this problem, manually adjust the remote client clock to synchronize with the server. Alternately, you can use NTP to automatically synchronize both machines.
4.4.2. Understanding OSM Errors
Complex Data Type Causing Deployment Error Problem: Deployment fails with an error similar to the following: Caused by: com.mslv.oms.metadatahandler.dataaccesslayer.ProxyException: ORA-02292: integrity constraint (ORDERMGMT_V2483.FK_OM_ORDER_INST_01) violated - child record found Resolution: With the introduction of the complex data type (CDT) in release 7.2.4, a development environment that changes the structure of a CDT causes deployment issues. When a CDT is deployed and an order exists in the system (even if it is completed) then the CDT structure cannot be edited and redeployed. The order must first be purged from the system. If you see this deployment error, purge your orders and redeploy.
Log Files Using Up Disk Space Error Problem: There are repeated errors logged in OSM, causing log files to accumulate and to use all available disk space, and preventing OSM from additional processing. Resolution: A JMS message has been delivered to an OSM queue that is not being processed correctly. It fails, and then gets redelivered in an attempt to re-process it. The re-delivery settings on the osm_events queue are set by default during OSM installation. When the MIK does a full stack installation, it edits the settings to ensure that so that JMS messages are not re-delivered continuously. If the MIK is used for a SOM-down installation, you must edit the JMS queue to change the redelivery limit to a number between 3 and 10. Also, define the Delay Override field with a value between 5000 and 30,000 milliseconds.
4.4.3. Understanding ASAP Errors
Unknown Exception Error Problem: An order fails with a generic error: Unknown exception, internal system processing error. Resolution: The credentials that OSM sent on the soap request are incorrect. By default, MIK creates a user in WebLogic server called asap_ws_user with a password of Oracle123. These credentials are created during the MIK installation. If the credentials were created in WebLogic manually, they may not match those created during the MIK installation. In the WebLogic security realm, change the password for user asap_ws_user to match those created during MIK installation.
Solution Testing and Debugging Guide
Activation Task Transitions to a Failure Task Error Problem: The Activation task fails and transitions to a Failure task. An error message similar to the following appears orderFailEvent.SARM_MSG:Routing Error for 'Americas West VoiceMailServer', ASDL 'A_VMS_CREATE_SUBSCRIBER' Resolution: Open a UNIX shell and navigate to your ASAP directory. For example, the ASAP directory may be similar to the following path: /private/aiacom_test_install/asap Run the following commands: . Environment_Profile asap_utils –d 7 A list of the configured network elements appears. Check the list in your error message to see if it is configured. For example:
Activation Task Hangs Error Problem: A process hangs at the Activation task. Resolution: If the process failed it would transition to a manual failure task. If the task remains at an Accepted state in OSM, then check that ASAP core is running. Run the following commands: . Environment_Profile status The following processes should be running:
Run the following command:
Solution Testing and Debugging Guide
stop_asap_sys –d And then run the following command: start_asap_sys –d
Error Code 103 Appears While Running asap_utils: Test Mode Problem: Error code 103 appears when you execute asap_utils. Resolution: ASAP was installed in the Test/Development mode but the network elements were configured in Production mode. Run the following commands: . Environment_Profile echo $ASAP_SYS Run the following SQL command: update tbl_resource_pool set ASAP_SYS='TEST';
Error Code 103 Appears While Running asap_utils: 64-bit JVM Problem: Error code 103 appears when you execute asap_utils. Resolution: When you run start_asap_sys, ensure that you are not using a 64-bit JVM. Run the following command to identify the Java version: java –version Update your PATH environment variable while running ASAP utilities so that any 64-bit JVM is removed from the PATH. Run the . Environment_Profile command to define the PATH to the 32-bit version that was used to install ASAP.
Error Code 255 Appears While Running asap_utils Problem: Error code 255 appears when you execute asap_utils. Resolution: Run the following diag_merge command to identify the problem. diag_merge DATA/logs/date myfile.txt WO_ID For example:
Solution Testing and Debugging Guide
ASAP CTRL Server Start Error Problem: ASAP CTRL server won’t start. You may see some of the following errors: 'Successful Connection to NEP_AS33 (127)' Oct 4 17:16:05 2013: SARMAS33: Msg 0 Severity 0 State 1 Server 'CTRLAS33' Proc '' @ 0 'Successful Connection to CTRLAS33 (36)' Oct 4 17:16:09 2013: ASAP System Event: SYS_TERM Error: Lost Connection to Control Server 'CTRLAS33', Terminating.... Oct 4 17:16:09 2013: ASAP System Event: SYS_TERM Error: Lost Connection to Control Server 'CTRLAS33', Terminating.... Oct 4 17:16:09 2013: SARMAS33: Msg 6 Layer 5 Origin 3 Severity 5 'ct_results(): network packet layer: internal net library error: Net-Library operation terminated due to disconnect' Resolution: Kernel settings are too low for ASAP. Follow these steps to increase them. 1. Using any text editor, create or edit the etc/sysctl.conf file. Edit the following fields with these values:
kernel.msgmax = 65536 kernel.msgmnb = 65536 kernel.msgmni = 2878
Specifying the values in the etc/sysctl.conf file ensures that the values persist when you restart the system.
2. Enter the following command to change the current values of the kernel parameters:
# /sbin/sysctl -p
3. Review the output from the command to verify that the values are correct. If the values are incorrect, edit the etc/sysctl.conf file, then enter the following command again:
# /sbin/sysctl –p
4. Enter the command /sbin/sysctl -a to confirm the values are set correctly. 5. Restart the computer or run the following command to make the changes in the etc/sysctl.conf file available in the active kernel memory:
sysctl -p
Installer fails without any obvious error message
Problem: The installer won't start in GUI mode, or exits without warning in console mode.
Resolution: There may be a missing system library called libXi. Use the following command to check to see if this library exists:
# ls /usr/lib/libXi.* /usr/lib/libXi.so /usr/lib/libXi.so.6 /usr/lib/libXi.so.6.0.0
If the library doesn't exist, use the following command to check to see if the associated libXi package is installed:
Solution Testing and Debugging Guide
# yum list libXi Installed Packages libXi.i386 1.0.1-4.el5_4 installed libXi.x86_64 1.0.1-4.el5_4 installed
If the 32-bit package libXi.i386 is missing, install the package and reinstall ASAP.
Solution Testing and Debugging Guide