5 Integration with Code Compliance Inspector

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:

5.1 Overview

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.

Figure 5-1 Overall Code Compliance Report

This image is described in surrounding text

5.1.1 Overview of Steps for Generating CCI Reports and Publishing them to OER

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:

  1. The checkCompliance command produces HTML compliance report files.

  2. The cci-oerSynch command synchronizes the results to the repository, enabling users to access the reports from the OER console.

Here are the overview steps

  1. Configure an OER artifact store.

    For more information, see Section 5.2.1, "Configuring an OER Artifact Store for CCI Reports".

  2. 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".

  3. 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".

  4. 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.

  5. 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".

  6. 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".

  7. 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".

5.2 Checking Compliance and Synchronizing Report Data in OER

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.

Here are the set up steps:

  1. Copy Compliance Inspector zip file to temporary folder.

  2. Unzip the Compliance Inspector zip file.

  3. 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.

5.2.1 Configuring an OER Artifact Store for CCI Reports

  1. 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".

  2. Name the artifact store(s) appropriate for its purpose (CCI-Reports-Production).

5.2.2 Configuring the cci-oerSynch.properties File

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>

5.2.3 Running the Check Compliance Command

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.

Examples

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

5.2.4 Harvesting the SOA or AIA Projects 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.

5.2.5 Running the CCI-OER Synch Command

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

Running CCI-OER Synch

  1. Update the cci-oerSynch.properties file, located in the ComplianceInspector/config directory, with the machine details where you have OER installed.

  2. 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:

http://example.com:port/oer/services

-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.

5.2.6 Copying the Files

  1. 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.

  2. To verify that this worked, check that the link was created on the composite asset in OER.

5.3 Configuring Reports for Access from the OER Reports Menu

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

  1. Shut down the application server.

  2. 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>

  3. 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.

  4. 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.

  5. Update the name attribute of each report element to a meaningful name (each must be unique).

  6. Update the displayName, description and external link elements as appropriate to the SOA Suite project's report summary pages and save the edits.

  7. 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>

  8. Modify the report name elements to match those added or modified in the CustomReport.xml file.

  9. Restart the OER application server for the changes to take effect, as shown in Figure 5-2.

Figure 5-2 OER Compliance Report Links

OER compliance reports

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.

5.3.1 Reviewing the Reports

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

Figure 5-3 Compliance Report Link

This image is described in surrounding text

Figure 5-4 Overall Code Compliance Report

This image is described in surrounding text

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.

Figure 5-5 Technical Compliance Report

Surrounding text describes Figure 5-5 .

Click the open link in the Compliance Report box to access detailed results, as shown in Figure 5-6.

Figure 5-6 Composite Compliance Report

This image is described in surrounding text