Thursday, October 14, 2010

Detailing usage of the AIA Foundation Pack PIP Auditor

My colleague, Ahmed, attended an AIA presentation at the latest Oracle OpenWorld 2010. The session was presented by some of our Oracle acquaintances, and over 300 attended this particular presentation in which the following question was posed to the audience, "How many of you have used the PIP Auditor before?" Ahmed was the only one to raise his hand.

In light of this response, which indicates minimal usage (or understanding of the tool), I realized it may be beneficial to go back and provide an overview of the PIP Auditor, how to use it, and whether this is something you should consider.

What development tools are delivered with the AIA Foundation Pack?

The AIA Foundation Pack delivers several developer tools. The newest versions can always be downloaded from Metalink. These tools include:
  • PIP Auditor - Used to check if given BPEL and ESB projects follow the AIA methodology for coding conventions
  • PIP Diff - Used to determine the difference between one PIP audit report and another
  • PIP Shared Artifact Analyzer - Creates a list of artifacts that are shared between PIPs
  • Xman - XSL mapping analyzer
  • XSD Flattener - Used to flatten XML elements into a CSV format. Used primarily for documentation
What is the PIP Auditor?

The PIP Auditor is run against your BPEL and ESB code to check whether they follow the AIA methodology for coding conventions. The output is a static HTML report. Therefore, the results are a single snapshot of your code at the time it was run.

The PIP Auditor can be run against Oracle out-of-the-box PIPs, against PIPs that you have customized, or against your custom code that follows AIA design and development guidelines. Thus, in some cases, you may want to run the report weekly to continously monitor your progress (or lack thereof) of coding compliancy.

The PIP Auditor reports on compliancy to coding standards.

The PIP Auditor also provides suggestions for fixes for each of the identified violations.

Where can you get the PIP Auditor?

For AIA Foundation Pack 2.4 or higher, it is located under $AIA_HOME\DeveloperTools\PIPAuditor, or you can download the AIA Developer Tools from Metalink.

What kind of reports does the PIP Auditor generate?

The PIP Auditor generates what is called a "Technical Compliance Report", reporting code violations based on rules, priority, category, project, and test suite. This is a series of static HTML pages and a single XML file. The index.html page is the main page of the report, which all further pages can be accessed.

This main page provides a summary of the final report, as shown in the figure below.
The CodeBase_Audit.xml is a 5 to 10 MB XML file that contains the raw data that the HTML reports are based on. The output also includes numerous other HTML pages which exist under various subdirectories (e.g., Reports/Rules.html, Reports/TestResultCategory.html), all designed to provide different breakdowns of the data. These subpages are all accessible from the main index.html page.

By clicking on "Priority 1", you can see a further breakdown. Here, 4 specific test cases were failed across several of the projects.
By clicking on the test case, a detailed description of the test case is provided. For example, in the figure below, the EBFTargetNameSpacesCheck test checks that all target namespaces for EBF processes follow the standard pattern defined in the AIA naming standards guide. This is categorized as a Priority 1 violation.
The next figure is by project/process. As you can see here, the OrderCompletionNotificationOSMReqABCSImpl BPEL process has a total of 474 violations. If you click on the violation name, it will link you to the actual test case similar to the image immediately above.
How do you set up your environment to run the PIP Auditor?

Setting up the environment involves the following:
  • Download the AIA Developer Tools from Metalink
  • Install Java JDK/JRE 1.5.0_06 or higher
  • Extract DeveloperTools to some directory (e.g., /u01/aia/pipaudit)
  • Download XMLUnit 1.2 ( and extract xmlunit-1.2.jar to /u01/aia/pipaudit/DeveloperTools/lib
Our directory structure was as follows:
Here, the main directories include my source code (~/svn/code), the PIP Auditor files (~/pipaudit), and a local Apache server to host the final report (~/http-2.2.14).

How do you run the PIP Auditor?

Our code is maintained within multiple subdirectories under /u01/aia/svn/codebase. Per the command below, the PIP Auditor will parse all subdirectories and place the results under /u01/aia/http-2.2.14/htdocs. That way, the HTML reports are easily accessible remotely via a web browser.

export JAVA_HOME=
export PATH=$JAVA_HOME/bin:$PATH
export PIPAUDIT_HOME=/u01/aia/pipaudit/DeveloperTools
./ -inputDir /u01/aia/svn/codebase -outputDir /u01/aia/http-2.2.14/htdocs

The generates a pipaudit.log file with standard logging.

What other parameters can be used with

The syntax is as follows:
Syntax for invoking the PIPAuditor Tool is :
-inputDir {PIPS_DIR} -outputDir {OUTPUT_DIR} -testSuite {TEST_SUITE_NAME}

Parameters :
-inputDir        [REQUIRED] The directory which contains source of the PIP or ABCS, EBS,EBF, etc to be validated.
-outputDir       [REQUIRED] The directory where output files need to be generated.
-testSuite       [OPTIONAL] If not provided default testsuite name will taken from testsuite.xml.
-testName        [OPTIONAL] This will execute only the specified test.
-inputMetaFile   [OPTIONAL] The MetaFile which lists all the services used for the PIP.
Same as the GenerateScriptInput.xml used in BIG tool.
-inputMetaFile ALL would iterate through the inputDir and generate
reports for all PIPS where GenerateScriptInput.xml is found.
-version         [OPTIONAL] Displays the version of the tool.

./ -inputDir /home/demo -outputDir /home/pipaudit -testSuite ManualAudit
Please note that if you use the -testSuite ManualAudit parameter, Xman (another AIA Developer Tool) will be run.

Does the PIP Auditor provide any true value?
If you are extending or customizing PIPs, then you probably want to run the PIP Auditor and address all Priority 1 violations.

If you are developing custom code following the AIA development standards, then in my opinion, running the PIP Auditor is optional, as it is rare that you'll be following the coding standards 100%.

If you are not running the AIA Foundation Pack or not developing code that follows the AIA development methodology, then the PIP Auditor does not benefit you.

No comments: