Using the Compliance XQuery Policy
Learn about using the Compliance XQuery Policy to execute an XQuery statement on a service or message model to determine compliance.
For information about using policies in the context of the developer portal, see Business Policies.
Table of Contents
- About the Compliance XQuery policy
- Creating a Compliance XQuery policy
- Configuring a Compliance XQuery policy
- Compliance XQuery policy options
- Populating an XQuery policy with schema or WSDL data
- Populating an XQuery policy with service data
- Populating an XQuery policy with exchange (message) data
- Attaching the policy
About the Compliance XQuery policy
XQuery is a query language that queries and transforms collections of structured and unstructured data, usually XML. XPath is a subset of XQuery.
The Compliance XQuery policy executes an XQuery statement on the service or message model to determine compliance.
Creating a Compliance XQuery policy
The first step in creating a policy is to define the basic policy information.
To add a compliance policy
- Go to Workbench > Browse > Organization, and select Policies > Compliance Policies. The Policies Summary is displayed.
- Click Add Policy.
- Choose the policy type and click Next.
- Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.
For more information, see Add Policy.
Configuring a Compliance XQuery policy
Once you've created the policy, you can configure the policy options.
To configure a Compliance XQuery policy
- Go to Workbench > Browse > Organization and select the Policies > Compliance Policies folder. The Policies Summary is displayed.
- Find the policy on the list and click to go to the pane for the Compliance XQuery policy.
- In the second section, click Modify. The Modify Compliance XQuery Policy page opens, as shown below.
- Choose an asset type. For information on the individual options, see Compliance XQuery Policy Options below.
- Follow the steps for the specific asset type, to populate the Query Builder:
- When the Query Builder pane is populated, choose elements that you want to include in your Compliance XQuery policy. Use the arrow buttons to copy elements to the Namespace Declarations and/or XQuery fields.
- Click Evaluate to test the information, and debug as needed.
- When done, click Finish. The policy definition is saved.
That completes the policy configuration. You can now assign the policy to a service.
Compliance XQuery policy options
The Modify Compliance XQuery Policy wizard includes the options listed below.
- Asset Type
- Choose from the list of supported asset types that can be evaluated by the current rule definition including exchange:
For instructions, see Populating an XQuery policy with schema or WSDL data.
For instructions, see Populating an XQuery policy with service data.
- exchange (that is, message)
For instructions, see Populating an XQuery policy with exchange (message) data.
For instructions, see Populating an XQuery policy with schema or WSDL data.
- Tree Hierarchy
- The tree hierarchy stores the asset information that you specify for the current policy definition. You can populate it with any one of the four asset types (message, schema, service, or WSDL). When you choose the asset type, define the source, and click Load Context, the tree hierarchy is populated with the content.
- After the tree hierarchy is populated, you can select Namespace Declarations and XQuery expressions and transfer them to the target text boxes (Namespace Declarations and XQuery) by clicking the arrow buttons.
- Load Context
- Once you've specified the asset type, click the Load Context button to populate the tree hierarchy of the Query Builder with data to use in defining your Compliance XQuery policy. The applicable screen is displayed, depending on the asset type:
- Exchange—Displays the Select Usage Log screen which allows you to search for a usage log to upload into the tree hierarchy of the Query Builder. See Populating an XQuery policy with exchange (message) data.
- Schema—Displays the Upload File screen which allows you to upload a schema into the tree hierarchy of the Query Builder. See Populating an XQuery policy with schema or WSDL data.
- Service—Displays the Upload Service screen which allows you to navigate a tree hierarchy and select a service to be uploaded tree hierarchy of the Query Builder. See Populating an XQuery policy with service data.
- WSDL—Displays the Upload File screen which allows you to upload a WSDL into the tree hierarchy of the Query Builder. See Populating an XQuery policy with schema or WSDL data.
- Namespace Declaration
- You must specify the namespace declaration for the XQuery statement. All namespace declarations are separated by a semi colon (;) and are of the form:
declare namespace compCtx='http://www.soa.com/2007/Compliance-Context';
- This provides namespace prefix resolution for the XQuery statement, effectively decoupling the XQuery statement from literal namespace prefixes.
- The XQuery text box must contain the comp context (compCtx:) for the selected asset.
- Evaluates the XQuery statement against the current context, and displays the results in the associated text box. Note that the Query Builder implementation is for advanced users and requires a working knowledge of XPath/XQuery.
- The XQuery statement must evaluate as follows:
- A Boolean result of true for a passed rule
- A Boolean result of false for a failed rule
- An integer value of 0 for a passed condition
- 1 to denote a warning
- 2 to denote an error
- Warning Message
- Specify the warning message to be displayed if the XQuery statement evaluates to a warning (#4 above).
- Error Message
- Specify the error message to be displayed if the XQuery statement evaluates to an error (#5 above).
Populating an XQuery policy with schema or WSDL data
To populate a XQuery Policy with schema or WSDL data, you'll need to upload the applicable file. From the Asset Type list, select schema or wsdl, and then click Load Context. The Upload File page is displayed, as shown below.
Upload the asset file (schema or WSDL) to be used for testing the current compliance policy. Make sure you upload the correct file type, according to the asset type you specified.
The Query Builder tree is populated with the file you uploaded.
Populating an XQuery policy with service data
To populate a XQuery Policy with service data, choose an Asset Type of service and then click Load Context.
The Select Policy Asset page is displayed, as shown below.
Here, you can upload an asset file (Service) to be used for testing the compliance policy.
Navigate the tree hierarchy, choose a service, and click Next. You are returned to the Modify Policy page, and the service information is displayed in the Query Builder tree, as shown below.
You can now configure the policy further based on the service you selected, following the steps in To configure a Compliance XQuery policy (Step 6 onwards).
Populating an XQuery policy with exchange (message) data
To populate the policy with message data, choose Exchange from the Asset Type list, and then click Load Context. The Select Usage Log screen is displayed.
On this page, you can filter usage data, as shown below.
Choose a service/operation combination and specify a time range filter. Configure the Observer Filter and Time Range Filter and then click Refresh.
After completing the search, choose the usage logs you would like to use to populate the Query Builder, and then click Next to go to the Modify XQuery Policy page.
To view details for selected usage records, select a usage data report line item and click View Usage Record Details. The Usage Record Details screen displays with a list of usage data fields and associated SOAP messages.
Usage Record Details page
This page includes the following:
- Usage Detail
- The Usage Detail tab allows you to navigate the list of SOAP messages associated with the current usage record. To navigate to the next SOAP message, click Next or Previous.
- Recorded Messages
- The Recorded Message section displays SOAP messages associated with the usage record of the current service. To view the message details for the current SOAP message, just click the line item. To view message details in XML format, choose Raw Format. To save the selected SOAP message, click Save.
- Transaction Events
- The Transaction Events section displays a list of transactions associated with the selected service. Each line item includes the following:
- Elapsed Time
- Response Time
To view the usage detail for a transaction, just double-click the line item. An example is shown below. The example below combines the display of all three tabs.
To exit, click Close.
Attaching the policy
To use the policy, go to the Policies folder in the Root Organization and attach the policy to a web service, binding, or binding operation.