Oracle SOA Suite 12c – Create, Deploy, Attach and Configure a Custom OWSM Policy – to report on service execution

This article describes how to develop a straightforward custom assertion that can be used as part of custom OWSM policy to be attached to Web Services in WebLogic, such as services exposed by SOA Composite applications and Service Bus projects as well as custom JAX-WS or ADF BC Web Services. The custom assertion that I demonstrate here reports the execution of web service operations to a JMS Destination and/or the system output. It shows how to access property values set on the policy binding (values specific for the service the policy is attached to) and how to inspect the headers and contents of the request and response messages. Most custom assertions will use a subset of the mechanisms shown in this example. As always, the source code is available for download. Note: this article was edited on April 6th to reflect better code structure.

Custom assertions can be used in policies that are applied to web services. Depending on the type and configuration of the policy and assertions, they can be triggered at different moments and perform different tasks. These assertions are similar to aspects (in AOP) that take care of cross cutting concerns and that do not interfere with the internals of a service. Policies are attached (and detached) at runtime by the administrators. The assertion discussed in this article is to be attached to the service binding at the inbound end of a SOA composite application (or at a Service Bus proxy service that serves the same purpose). The assertion will report every incoming request as well as each response returned from the service binding. This information can be leveraged outside the scope of this article to monitor the runtime service environment.

The steps describes in this article in the process of creating and putting into action the custom assertion are:

• Create Custom Policy:
  • Assertion Java Class
  • Policy XML File
  • Policy Configuration XML File
• Deploy Policy Artifacts to Runtime Fusion Middleware platform (and restart the WebLogic Servers)
• Import Policy Definition into Runtime Fusion Middleware platform
• Attach the Policy to a Service Binding in an existing SOA Composite application and configure the policy binding properties
• Invoke the service exposed by the [Service Binding in the existing] SOA Composite application
• Verify the results produced by the policy attachment

Create the Custom Policy

The main part of the custom assertion definition is a Java class. See for details the sources that can be downloaded from GitHub.The project contains a helper class – CustomAssertion – that takes care of some generic plumbing that are required for the AssertionExecutor superclass that needs to be extended. The class SOASuiteServiceExecutionReporter contains the custom logic that is to be executed whenever the policy assertion is triggered. In the current case, this logic consists of retrieving some key elements about the service request – service name, operation name, ECID, timestamp and selected payload details – and reporting them. Initially, this report consists of a few lines in the system output (i.e. the domain log file). Later on, we will send the report to a JMS destination.

The init() method is invoked by the OWSM framework when the policy is attached to a web service and whenever the configuration of the policy attachment is updated (i.e. its property values are changed). The init() method reads and processes the policy attachment configuration and initializes the SOASuiteServiceExecutionReporter, priming it for the correct actions whenever service executions trigger its execute method.

This code snippet relies heavily on the super class (CustomAssertion ) that returns the values for the properties from the iAssertion.

It also leverages the method initializeMessageTypesMapFromJson. This method performs the parsing of the operationMap property in the policy binding configuration. The properties are defined in the policy definition file – see below – and are set to binding specific values in the EM FMW control (or from WLST).

Properties can be simple string values. By using JSON snippets for the values of these properties, we can pass quite complex and extensive data structures into the policy attachment. In the current case, we use a JSON style property to specify for a policy binding which message types are processed ; each message type is a key in the JSON object and for each message type are defined: the name of the operation, an indication of the operation one-way is and an XPath expression to derive a value from the message payload to be reported.

This JSON structure looks like this- here message type getFlightDetailsRequest is mapped to operation getFlightDetails; from the request message, the value of element /soap:Envelope/soap:Body/flig:getFlightDetailsRequest/flig:FlightCode/com:CarrierCode should be reported:

The parsing of the JSON property is done using standard JSON-P support in this case, in the helper class ServiceReporterSettings:

In this code snippet, the JSON structure of the operationsMap property is parsed, interpreted and turned into a corresponding set of Java Objects. The data structures and class definitions are outlined in the next illustration:

 

 

The Execute method – processing every service execution

The execute method is invoked when the service receives a request or returns a response or a fault. The method gets passed in an IContext object. This object provides access to most relevant details about the request or response message – including the complete SOAP Envelope and the Transport Headers. Note that the GUID attribute contains the FMW ECID attribute value; the value is the same for the request message and the corresponding response (or fault) message.

 

One aspect of the custom assertion is the determination of the message type that is handled. The message type is read from the SOAP Body:

Here we use the getDataNode() helper method that is used to execute XPath queries against the mBody element, to derive the first child node within the SOAP Body.

When payload elements are to be extracted, this is done in a similar fashion:

The report on the service execution is created like this:

The policy can be attached to one service or  – more common – to may services. Each policy attachment (aka policy binding) can be configured with property values that are specific for the service and how the policy should act in the context of the service.

The file SOASuiteServiceExecutionReporterPolicyFile.xml contains the definition of the custom policy. This file is deployed to the runtime environment and also uploaded to the FMW Control, as we will see later on. This file defines the policy, its meta data including its properties etc.

The file policy-config.xml is another link in the chain. It joins the policy definition from the previous file with the Java Class.

 

 

Deploy Policy Artifacts to Fusion Middleware Infrastructure

Create a deployment profile (simple Java Archive) for the JDeveloper project. Deploy the project to a JAR file using this profile.

Copy JAR file to the WLS DOMAIN\lib directory (download the jar-file).

Using the target information in the EM FMW Control, I find out about the exact the file location for the WebLogic domain that hosts the SOA Suite:

the lib directory under this domain home is where the jar file should be moved.

Restart the WebLogic domain.

 

Import Policy Definition into Fusion Middleware Infrastructure

Start EM FMW Control.

navigate to Web Logic Domain – soa_domain | Web Services | WSM Policies.

Click on Import

Import zip file with appropriate structure (this means it should contain a folder structure of META-INF\policies\some-custom-folder-name\policyname.xml:

by clicking on Import

and selecting the right zip file:

The report back:

and the policy is listed:

Details:

note that the policy is enabled, local optimization is off and the policy applies to service bindings (not SCA components, although that could be an option too) and is in the category Service Endpoint

and on the assertion:

The policy is ready for attachment to service bindings.

 

Attach Policy to SOA Composite Service Bindings

Open the SOA Composite, such as the FlightService composite shown below. Click on the Service Binding to which the policy is to be attached:

Open the Policies tab:

Click on the button Attach/Detach to open the dialog where policies can be attached to the service binding.

Select the amis/monitoring policy. Click on Attach to bind this policy to the service binding.

Click on OK to confirm the policy attachment.

Click on Override Policy Configuration to set the property values that apply specifically to this policy attachment:

The properties that are defined in the policy configuration file – SOASuiteServiceExecutionReporterPolicyFile.xml – are listed and the current values are shown. These values can now be overridden for this attachment of the policy to the FlightService.

Click on Apply to confirm the property values.

At this point, the policy is primed for action for the FlightService.

Test the Custom Policy Activity

By invoking the various FlightService operations, we can now see the policy in action.

The effect of this call is reported by the custom policy in the log-file:

A call to another operation results in a similar report:

in the log file:

 

Note: even services to which the policy is attached without any additional configuration override will have their execution reported. However, these reports obviously cannot report the operation name (only the message type) nor any values from the payload. Here a report from the ConversionService that has the policy attached – without any configuration.

Resources

JSON parsing in Java – http://www.oracle.com/technetwork/articles/java/json-1973242.html and http://docs.oracle.com/javaee/7/api/javax/json/JsonReader.html.

Documentation for Fusion Middleware 12c (12.1.3)

Developing Extensible Applications for Oracle Web Services Manager –  http://docs.oracle.com/cd/E57014_01/owsm/extensibility/owsm-extensibility-create.htm#EXTGD153

Overriding Policy Configuration Properties – http://docs.oracle.com/cd/E57014_01/owsm/security/override-owsm-policy-config.htm#CACGHIFE

Managing Web Service Policies with Fusion Middleware Control – http://docs.oracle.com/cd/E57014_01/owsm/security/manage-owsm-policies.htm#OWSMS5573

XML Schema Reference for Predefined Assertions – http://docs.oracle.com/cd/E57014_01/owsm/security/owsm-assertion-schema.htm

Stepping Through Sample Custom Assertions – https://docs.oracle.com/middleware/1213/owsm/extensibility/owsm-extensibility-samples.htm#EXTGD162