This chapter provides an overview and describes how to use the Code Compliance Inspector (CCI) with Oracle Enterprise Repository (OER).
This chapter includes the following sections:
Section 5.2, "Checking Compliance and Synchronizing Report Data in OER"
Section 5.3, "Configuring Reports for Access from the OER Reports Menu"
Adherence to open standards and the enforcement of good coding practices are key principles of SOA governance. The Code Compliance Inspector is a tool that checks for good coding practices in both SOA Suite projects.
The CCI is delivered with a set of pre-defined assertions that are based on the Web Services Interoperability Organization Basic Profile (WS-I BP) to check for design consistency and good coding and documentation practices. The CCI qualifies code as Compliant, Conformant, or Fully Conformant in alignment with those open standards and best practices.
The results are displayed in the Code Compliance Report that shows the level of compliance, pass and failure percentages, and provides a graphical bar chart that groups results by priority and policies. The results also include the Top 10 violating composites. The overall compliance score for a SOA Suite project is shown in the header section of the report.
The Code Compliance Inspector can also be used to check for good coding practices in Oracle Application Integration Architecture (AIA) integration projects. In addition to assertions based on WS-I BP, the Code Compliance Inspector provides assertions based on AIA Integration developer guidelines to check for design consistency and coding practices. CCI compliance results and reports are also supported for AIA composites.
For more information about using the JDeveloper CCI extension to develop composites and to check compliance, see "Using the Code Compliance Inspector" in the Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.
Figure 5-1 shows an example of the overall Code Compliance Report. This report is linked through the OER Reports page. You can click through the composites to get more detail about composites. You can also see each composite individually using the Asset Detail page in OER. Additionally, you can post the report files to a server and share the compliance results with colleagues.
This section provides an overview of the steps required to collect CCI reports that are ready to be associated in OER with harvested composites and published for view by OER users.
The CCI for OER consists of two command line utilities that are used by build administrators to generate reports that can be published in OER:
The checkCompliance command produces HTML compliance report files.
The cci-oerSynch command synchronizes the results to the repository, enabling users to access the reports from the OER console.
Configure an OER artifact store.
For more information, see Section 5.2.1, "Configuring an OER Artifact Store for CCI Reports".
Within in your build environment, configure the cci-oerSynch.properties file.
For more information, see Section 5.2.2, "Configuring the cci-oerSynch.properties File".
From your build environment, run the command line compliance script to generate CCI reports from the projects and prepare them for OER publication. You must run the command line tool to enable synchronization with OER.
For more information, see Section 5.2.3, "Running the Check Compliance Command".
Ensure that the SOA or AIA projects from which the reports are generated have been harvested into OER.
For more information about harvesting, see "Configuring and Using Automated Harvesting in Design-time and Runtime Environments" in the Oracle Fusion Middleware Configuration Guide for Oracle Enterprise Repository.
From your build environment that contains the CCI reports generated by the compliance check command, run the CCI-OER Synch command.
For more information, see Section 5.2.5, "Running the CCI-OER Synch Command".
Copy the newly generated CCI reports folder into the physical location associated with your OER artifact store. Note that if this location is hosted on the same system as the original reports folder, the CCI-OER Synch will automate this move. Otherwise, this is a manual step.
For more information, see Section 5.2.6, "Copying the Files".
Within your OER installation, configure the Compliance Report properties file to enable access to the CCI reports from the OER Reports menu.
For more information, see Section 5.3, "Configuring Reports for Access from the OER Reports Menu".
The CCI command line tools are distributed with OER within the <OER Oracle Home>/tools/solutions/<version>-ComplianceInspector.zip.
Ensure that the contents of the zip file are installed on the machine where your build environment exists.
Copy Compliance Inspector zip file to temporary folder.
Unzip the Compliance Inspector zip file.
Configure Compliance Inspector's cci-oerSynch.properties file located in: ComplianceInspector/config/cci-oerSynch.properties.
The properties file enables you to set static information about your environment.
Note:
Wherever you unzip this file to, the property file is relative to the ComplianceInspector directory under config. You can rename this directory; we refer to this location as the ComplianceInspector_Home.
Create and configure an artifact store(s) of the appropriate type (for example, HTTP) within OER.
For more information about using artifact stores, see Chapter 1, "Configuring an Artifact Store".
Name the artifact store(s) appropriate for its purpose (CCI-Reports-Production).
This command runs the Code Compliance Inspector on a specified SOA or AIA project folder and creates a new folder containing the CCI reports.
The checkCompliance command also uses the cci-oerSynch.properties file to retrieve the URL of the OER instance in order to look up both the composite Asset Type ID and the username with which you want to connect.
Use the rep://<ARTIFACTSTORE-NAME> as a part of the compliance.report.web.root property within the cci-oerSynch.properties file.
Example: compliance.report.web.root=rep://CCI-Reports-Production/reports
Reports will then have the following URL pattern:
rep://CCI-Reports-Production/reports/cci/AIADemo/reports/composites/AIADemoBatchJMSAdapter.html#hide_link
The second property: compliance.report.web.root, represents the base URI for the host that will contain the Compliance Report HTML files. The value supplied in this property is concatenated with the inputDir parameter when running the CCI-OER Synch tool. This concatenated value is what is embedded into the asset's metadata for the compliance report link.
In most cases, the value of the compliance.report.web.root property will point to the artifact store which was configured in Section 5.2.1.
For example:
<a target="_blank" href="rep://CCI-REPORTS">rep://CCI-REPORTS</a>
Invoke CCI with the checkCompliance.sh on Linux or checkCompliance.bat command on Windows using the following switches:
-inputDir {Absolute path to the folder that contains composite(s)}
This is a mandatory switch indicating where the input dir is located. If the -inputMetaFile switch is not specified, this input is not necessarily representative of a SOA Suite project. If the -inputMetaFile switch is provided, this specifies the project root directory (the source folder containing the project folder from ComplianceInspector_Home).
-outputDir {Output folder where the compliance report will be generated}
This is a mandatory switch to indicate where the output reports will be stored. For example:
If your composites live here: /tmp/cci/composites/AIADemo
And you pass the output directory as: /tmp
Then CCI will put the produced files here: /tmp/AIADemo
-policiesFile {Policies file name}
Use this optional switch to indicate which policies file CCI should run against, for example, Policies-WS-I_11.x.xml. The file is available under ComplianceInspector/lib or ComplianceInspector/config (Tool class path) or embedded in the compliance.policy.engine.jar.
-policy {Policy name}
This is an optional switch to specify the policy to execute. If not given, the default policy from Policies.xml will be executed.
-assertion {Assertion name}
Use this optional switch to indicate which assertion CCI should run against. This will run the tool for a specific assertion that you have defined, for example, ABCSTargetNameSpacesCheck.
-inputMetaFile {absolute path to a SOA Suite project metafile}
Use this optional switch if you want to run reports for a specific SOA Suite project. The input metafile contains paths pointing to the specific directories that Code Compliance Inspector needs to scan so that the output results are specific for the SOA Suite project. This file contains the names of all of the services that are used in a given SOA Suite project. When this option is specified, the -inputDir switch will point to the project root directory since the input metafile contains the directory path relative to this root. Here are some examples:
-inputMetaFile <dir path of the file>/GenerateScriptInput.xml
-inputMetaFile <dir path of the file>/MyPIPDP.xml
-inputMetaFile ALL
Use this optional switch if you want to run reports for all of your SOA Suite projects. When this option is specified, the -inputDir switch will point to the project root directory since the input metafile contains the directory path relative to this root.
-version
The -version flag tells you which version of CCI (CCI build date and time) you are using. This is an optional argument that displays the version information.
Here are some examples for invoking the Code Compliance Inspector from a command line:
Windows: checkCompliance.bat -inputDir D:\composites\demo -outputDir D:\ComplianceOut
Linux: checkCompliance.sh -inputDir /composites/demo -outputDir /ComplianceOut
For more information about harvesting, see "Configuring and Using Automated Harvesting in Design-time and Runtime Environments" in the Oracle Fusion Middleware Configuration Guide for Oracle Enterprise Repository.
The CCI-OER Synch updates composite assets in OER with links to the associated CCI reports. You must have already configured an OER artifact store, or otherwise have determined the location from which OER will publish the reports, before you run the CCI-OER Synch command.
If you are running the CCI-OER Synch command on the system from which OER will publish the reports, then you can specify the folder location in the cci-oerSynch.properties file using the oer.app.report.location property and the command will automatically move the reports from the input folder to the specified location.
If the destination OER report location is on a different system, then you must manually move the folder specified by the -reportLocation argument to the OER report location and ensure that the pathname to this location matches what is specified in the compliance.report.web.root property.
Examples:
For the artifact store:
compliance.report.web.root=rep\://INSTANCE/reports
For a direct HTTP resource:
compliance.report.web.root=http://www.example.com/CCI-REPORTS-Production
Update the cci-oerSynch.properties file, located in the ComplianceInspector/config directory, with the machine details where you have OER installed.
Run cci-oerSynch.bat or cci-oerSynch.sh, located in the ComplianceInspector/bin directory. Table 5-1 provides a list of the command line arguments you can pass:
Table 5-1 Command Line Arguments for OER Synch
Argument | Type | Description |
---|---|---|
-url <url to oer web service> |
Optional |
URL to OER web service. For example:
|
-user <oer user name> |
Optional |
Valid OER user login. This user must have privileges to update asset instances. |
-pwd <oer password for user name specified> |
Optional |
Password for the OER user login. |
-reportLocation <path to output directory generated by CCI> |
Required |
Location of the CCI HTML compliance reports, created by the compliance inspection tool, which you want to integrate into OER. |
Note:
If the optional command line arguments are not given, then the values will be taken from the cci-oerSynch.properties file. Command line arguments take precedence over the properties specified in the cci-oerSynch.properties file. Also, if the password is not given in the command line argument, then you will be prompted to enter it.
Copy the newly generated CCI reports folder into the physical location associated with your OER artifact store.
Note that if this location is hosted on the same system as the original reports folder, the CCI-OER Synch will automate this move. Otherwise, this is a manual step.
To verify that this worked, check that the link was created on the composite asset in OER.
After the CCI-OER Synch has linked CCI reports to composite assets in OER, a link to the report will appear on the composite detail page. CCI reports can be accessed from the OER Reports menu after the following configuration steps have been performed.
Note:
The name attribute in the report elements of the ComplianceReport.xml file are referenced within the $OER_APP_HOME/oer-app/WEB-INF/config/reports/custom.toc file. If these elements do not match, then the values of the displayName and description elements will not appear in the OER reports page.
The $OER_APP_HOME/oer-app/WEB-INF/config/reports/custom.toc file enables you to add URL patterns to a reporting system that you may have integrated with that is external from OER. The custom.toc file indicates which other XML files it will access to gather the 'custom' report grouping information from and display the corresponding information referred to in the custom.toc file.
To add and configure the compliance reports
Shut down the application server.
Edit the $OER_APP_HOME/oer-app/WEB-INF/config/reports/ComplianceReport.xml file.
Here is an out-of-the-box example of ComplianceReport.xml:
<?xml version="1.0" ?> <reports> <report name="complianceReportDoc"> <displayName>Compliance Report Documentation</displayName> <description>Documentation for setting up Compliance Reports. </description> <externalLink>http://www.example.com/pls/topic/lookup?ctx=as111170& id=OERIN851</externalLink> </report> <report name="complianceReport"> <displayName>Compliance Report</displayName> <description>This is the index page for all technical compliance reports.</description> <!-- update the host and port, according the your http enabled server where you have hosted the compliance reports. Use the OER download servlet to map the OER artifact store URL for browser consumption. Example: <externalLink>http://server.example.com:7101/oer/com.flashline.cmee. servlet.enterprisetab.Download?path=rep://INSTANCE/reports/cci/FPDemo/ index.html</externalLink> --> <externalLink>http://host.example.com/CCI/reports/index.html</externalLink> </report> </reports>
If there is only one SOA Suite project being summarized, then modify the existing report named complianceReport and go to step 9.
If you are using an OER artifact store to reference the location of your reports (which is recommended) then you should use the following URL pattern as a part of the externalLink element in the CustomReport.xml file:
http://host.example.com:port/oer/com.flashline.cmee.servlet.enterprisetab.Download?path=rep://<ARTIFACTSTORENAME>/relative_path/index.html
The Download servlet is required to decode and reformat the URL to give the user the correct URL that the artifact store represents. The use of the OER artifact store allows OER administrators to alter the hostname/port and path for the report server(s) without being forced to re-synch or modify multiple assets to update these details.
If more than one SOA Suite project will be summarized, then duplicate the report section a number of times equal to the number of projects to be reported by the Check Compliance tool.
Update the name attribute of each report element to a meaningful name (each must be unique).
Update the displayName, description and external link elements as appropriate to the SOA Suite project's report summary pages and save the edits.
Edit the $OER_APP_HOME/oer-app/WEB-INF/config/reports/custom.toc file
Example:
<?xml version="1.0" ?> <reportSections> <reportSection name="Custom"> <summary></summary> <description>Custom reports provide you with the flexibility to customize reports for your organization or build new reports that align your organizational metrics with your program goals.</description> </reportSection> <reportSection name="Compliance Reports"> <summary></summary> <description>Code Compliance Inspector report for design-time compliance information</description> <report name="complianceReportDoc"/> <report name="complianceReport"/> </reportSection> </reportSections>
Modify the report name elements to match those added or modified in the CustomReport.xml file.
Restart the OER application server for the changes to take effect, as shown in Figure 5-2.
Here is a sample of a ComplianceReport.xml file that is using the OER artifact store to lead to the compliance report summary page:
<?xml version="1.0" ?> <reports> <report name="complianceReport_project1"> <displayName>Compliance Report (Project 1)</displayName> <description>This is the compliance report summary page for Composite Project 1.</description> <!-- update the host and port, according the your http enabled server where you have hosted the compliance reports --> <externalLink>http://host.example.com/CCI/reports/project1/index.html </externalLink> </report> <report name="complianceReport_project2"> <displayName>Compliance Report (Project 2)</displayName> <description>This is the compliance report summary page for Composite Project 2.</description> <!-- update the host and port, according the your http enabled server where you have hosted the compliance reports --> <externalLink>http://usclqaap04.us.example.com:8080/tr130107/com.flashline.cmee .servlet.enterprisetab.Download?path=rep://INSTANCE/reports/cci/FPDemo/ index.html</externalLink> </report> </reports>
The 'real' URL path to this location is:
http://usclqaap04.example.com:8080/tr130107/reports/cci/FPDemo/index.html
The italicized portion of the URL above is the relative path to the report files which is also the relative path after the repository name.
In OER, click the Compliance Report link shown in Figure 5-3 to see the overall report for all composites, shown in Figure 5-4
Click a violating composite, shown in Figure 5-4 to see more detail about the violations and then fix the compliance problem.
You can also view compliance information on individual composites through OER, as in Figure 5-5.
Click the open link in the Compliance Report box to access detailed results, as shown in Figure 5-6.