Platform Development Studio - Developer’s Guide

Callable Policy Web Service

The following section describes how to use the callable policy interface exposed by Oracle Communications Services Gatekeeper.

Introduction

The callable policy service in Oracle Communications Services Gatekeeper exposes two Web Services interfaces related to callable policy:

Policy evaluation
Policy management

The callable policy service is intended to allow applications and network nodes that have no policy evaluation capabilities themselves to use the policy evaluation capabilities in Oracle Communications Services Gatekeeper. The service is not designed to expose the service to external service providers. Rather it is to be used internally as a way of exposing generic policy capabilities to network nodes within the telecom network where Oracle Communications Services Gatekeeper is deployed. Communication Services deployed in Oracle Communications Services Gatekeeper do not use the interfaces exposed by the callable policy Web Service.

For example, a node in the network might need to enforce a set of rules for requests flowing through it, to allow or deny requests based on time of day and originator of the request. In this case, the node might determine the originator of the request and use the callable policy evaluation Web Service to evaluate that request. The rule that is being evaluated uses the data provided in the web services call and makes its decision based on them. Modifications to the rules can be done using the policy management Web Service.

A user of the policy evaluation and policy management Web Services interfaces is registered using the same service provider and application model that is used for users of the Communication Services. If the system requires sessions, the user must be logged in using the same session manager interface exposed to these service provider applications.

Note:

If there is no specific rule file associated with a ServiceName loaded in the rule engine, it uses the default rule file in its evaluation. If you are using Callable Policy, you must make sure that an appropriate rule file is loaded into the rule engine. For more information. see the “Managing the PolicyService” chapter in the System Administration Guide.

It necessary to have service provider group and application group Service Level Agreements defined for the user of the callable policy service. To use the policy evaluation interface, the tag <scs> must contain the value com.bea.wlcp.wlng.px21.plugin.PolicyPlugin.

To use the policy management interface, the tag <scs> must contain the value com.bea.wlcp.wlng.px21.plugin.PolicyManagementPlugin.

Listing 17-1 Example of SLA that allows the use of both the policy evaluation and policy management interfaces

<serviceContract>

  <scs>com.bea.wlcp.wlng.px21.plugin.PolicyPlugin</scs>

</serviceContract>

<serviceContract>

   <scs>com.bea.wlcp.wlng.px21.plugin.PolicyManagementPlugin</scs>

</serviceContract>

Callable Policy Web Service interface definition

Endpoints

The endpoint for the Policy evaluation interface is:

http://<host:port>/callable_policy/Policy

The endpoint for the Policy management interface is:

http://<host:port>/callable_policy/PolicyManagement

Detailed service description

Policy Evaluation

The policy evaluation interface makes it possible for an external application to evaluate a request containing a set of parameters. The parameters in the request include authentication information, information on the type of service the request should be evaluated against, the method name of the method that should be evaluated, and arbitrary additional data provided as name-value pairs.

All request parameters are evaluated according to a policy rule.

When evaluated, a copy of the data provided in the evaluation process is returned together with information on the outcome of the requests, that is, if the request was allowed or denied. If the request was allowed, the application calling the Web Service must use the returned copy of the parameters for further processing, because the returned parameters in the request may have been changed by the policy rule processing.

Policy management

The policy management web service interface makes it possible to load and delete policy rules.

XML Schema data type definition

AdditionalDataValue structure

Defines the AdditionalDataValue structure.

Element Name	Element type	Optional	Description
name	xsd:string	N	Name part of the additional data name-value pair.
value	xsd:string	N	Value part of the additional data name-value pair.
type	callable_policy_local_xsd:AdditionalDataValueType	N	Identifies the data type. See AdditionalDataValueType enumeration.

AdditionalDataValueType enumeration

Describes a data type.

Enumeration value	Description
STRING_TYPE	Data type is String.
INTEGER_TYPE	Data type is Integer.
FLOAT_TYPE	Data type is float.
DOUBLE_TYPE	Data type is double.
CHAR_TYPE	Data type is Char.
BOOLEAN_TYPE	Data type is boolean.
INT_ARRAY_TYPE	Data type is int array.
STRINGARRAY_TYPE	Data type is String array.

Interface: Policy

Operations to evaluate a request.

Operation: evaluate

The policy evaluation interface makes it possible for an external application to evaluate a request containing a set of parameters. All of the request parameters are evaluated according to a Policy rule.

Input message: evaluateRequest

Part name	Part type	Optional	Description
type	xsd:string	N	Service type to be evaluated.
serviceName	xsd:string	N	ServiceName associated with the rule file.
methodName	xsd:string	N	Name of method to be evaluated.
requesterID	xsd:string	N	The application ID as given by the operator.
timeStamp	xsd:dateTime	N	Defines the date and time of the request.
additionalData	callable_policy_local_xsd:additionalDataValue	Y	Specifies any other data, specified as name-value pairs. See AdditionalDataValue structure.

Output message: evaluateResponse

Part name	Part type	Optional	Description
modifiedRequest	callable_policy_local_xsd:evaluateRequest	N	The response that Oracle Communications Services Gatekeeper returns after being evaluated by policy rules. Same data structure as evaluateRequest, but data may have been changed by the policy evaluation.
returnValue	xsd:string	N	Return value the policy rules passed back.
thrownException	xsd:string	N	Name of the exception thrown during evaluation.
thrownPolicyException	xsd:string	N	Name of the policy rejection exception thrown during evaluation.
denyReasonDescription	xsd:string	N	Description of the reason of denying the request.
denyCode	xsd:string	N	Code identifying the reason of denying the request.

Referenced faults

ServiceException:

If there is an internal error during evaluation process, a ServiceException is thrown.

PolicyException:

If the policy evaluation request is rejected, a PolicyException is thrown.

Interface: PolicyManagement

Operations to manage policy rules.

Operation: viewRuleFile

Fetches a policy rule file of a given type and service from the rules engine.

Input message: viewRuleFile

Part name	Part type	Optional	Description
type	xsd:string	N	Type of SLA, either: Application Serviceprovider
serviceName	xsd:String	N	ServiceName associated with the rule file.

Output message: viewRuleFileResponse

Part name	Part type	Optional	Description
return	xsd:String	N	The rule file.

Referenced faults

ServiceException:

If there is an internal error during evaluation process, a ServiceException is thrown.

PolicyException:

If the policy evaluation request is rejected, a PolicyException is thrown.

Operation: deleteRuleFile

Deletes a policy rule file of a given type and service from the rules engine.

Input message: deleteRuleFile

Part name	Part type	Optional	Description
type	xsd:string	N	Type of rule file, either: Application Serviceprovider
serviceName	xsd:String	N	ServiceName associated with the rule file.

Output message: deleteRuleFileResponse

Part name	Part type	Optional	Description
-	-	-	-

Referenced faults

ServiceException:

If there is an internal error during evaluation process, a ServiceException is thrown.

PolicyException:

If the policy evaluation request is rejected, a PolicyException is thrown.

Operation: loadRules

Loads a a policy rule file of a given type and service into the rules engine.

Input message: loadRules

Part name	Part type	Optional	Description
type	xsd:string	N	Type of rule file, either: Application Serviceprovider
irlUrl	xsd:string	N	URL to rule file to be loaded.
serviceName	xsd:string	N	ServiceName associated with the rule file.

Output message: loadRulesResponse

Part name	Part type	Optional	Description
-	-	-	-

Referenced faults

ServiceException:

If there is an internal error during evaluation process, a ServiceException is thrown.

PolicyException:

If the policy evaluation request is rejected, a PolicyException is thrown.

Operation: listRuleFiles

Lists the rule files of a given type that are loaded into the rules engine.

Input message: listRuleFiles

Part name	Part type	Optional	Description
type	xsd:string	N	Type of rule file, either: Application Serviceprovider

Output message: listRuleFilesResponse

Part name	Part type	Optional	Description
ruleFile	Array of xsd:string	Y	A list of rule files matching the given criteria.

Referenced faults

ServiceException:

If there is an internal error during evaluation process, a ServiceException is thrown.

PolicyException:

If the policy evaluation request is rejected, a PolicyException is thrown.

Rule files

The rule files are written in IRL, ILog Rule Language.

When writing rules in the context of Oracle Communications Services Gatekeeper policy rules, the following apply:

The rule is associated with a service name when loaded into Oracle Communications Services Gatekeeper policy service, Input message: loadRules.

Which rule to be triggered by Input message: evaluateRequest is correlated with the parameter serviceName given in the Web Service request.

When the evaluate request triggers the rule, a set of general parameters can be accessed by the policy rule:

String applicationID: Application ID associated with the request.
String serviceProviderID: Service provider ID associated with the request.
String serviceName: Service name from which the request originates or is destined for.
String methodName: Method that triggered the request.
String serviceCode.
String requesterID.
long transactionID.
int noOfActiveSessions.
long timeStamp: Time the request was sent to the rules engine for processing. Milliseconds from start of UNIX epoch.
long reqCounter: Defines the increase rate for related counters.

A rule must have a name and a priority. High priority rules are evaluated before low priority rules.There are a set of pre-defined priority levels, which are mapped to a numerical value:

minimum, where the value is -1*109
low, where the value is -1*106
high, where the value is 1*106
maximum, where the value is 1*109

Listing 16-2 shows the basic structure of a rule:

Listing 17-2 Skeleton of a rule

rule DenySubscriberNotExists

	priority = high;

	when

	// fetch the policy request data and perform evaluations.

	then

		// Take action on

};

In order to perform an evaluation, the data in the PolicyRequest object must be fetched by the rule and mapped to the equivalent variable names in the rule. The standard types of request data in the Policy Request are associated with variables of the same name in the rules. Below is an example of a rule assigning the PolicyRequest member variable serviceName to the rule variable sname via the Policy Request object. The rule object pr is assigned to the PolicyRequest object.

Listing 17-3 Policy Request data is fetched

?pr: event PolicyRequest(?sname: serviceName);

If the Policy Engine has evaluated the request and made the decision to deny it, the Policy Engine’s representation of the PolicyRequest object (pr) must be retracted. Retracting the PolicyRequest object aborts further rule enforcement.

Listing 17-4 Retract a request

retract (?pr);

If the Policy Engine has evaluated the request and made the decision to allow it, the Policy Engine’s representation of the request (pr) must still be retracted, but in the last rule of the execution flow. For example, this could be achieved by adding a general finalizing allow rule that retracts the request. This rule should have priority minimum.

Listing 17-5 General finalizing allow rule that retracts a request

rule AllowServiceRequest

	priority = minimum;

	when

		?pr: event PolicyRequest();

	then

		retract (?pr);

		?pr.allow();

Data that is defined as AdditionalValues must fetched as shown below. The Additional Value named targetAddress is stored in the variable addDataValue. The PolicyRequest object is pr.

Listing 17-6 Fetching AdditionalValue data

bind ?addDataValue = ?pr.getAdditionalDataStringValue("targetAddress");

The particular signature of the fetching method depends on the type of data:

getAdditionalDataIntValue(...), for int values
getAdditionalDataLongValue(...), for long value.
getAdditionalDataStringValue(...), for String values
getAdditionalDataStringArrayValue(...), for arrays of String values
getAdditionalDataBooleanValue(...), for boolean values
getAdditionalDataShortValue(...), for short values
getAdditionalDataCharValue(...), for char values
getAdditionalDataFloatValue(...), for float values
getAdditionalDataDoubleValue(...), for double values
getAdditionalDataIntArrayValue(...) for arrays of int values.

If the data type is unknown, it can be determined by invoking the discriminator method on the AdditionalDataValue object.

Listing 17-7 Determine the type of an AdditionalDatavalue

bind ?type = ?pr.getAdditionalData.dataValue.discriminator().value();

Where type is one of the following:

AdditionalDataType._P_ADDITIONAL_INT
AdditionalDataType._P_ADDITIONAL_LONG
AdditionalDataType._P_ADDITIONAL_STRING
AdditionalDataType._P_ADDITIONAL_STRING_ARRAY
AdditionalDataType._P_ADDITIONAL_BOOLEAN
AdditionalDataType._P_ADDITIONAL_SHORT
AdditionalDataType._P_ADDITIONAL_CHAR
AdditionalDataType._P_ADDITIONAL_FLOAT
AdditionalDataType._P_ADDITIONAL_DOUBLE
AdditionalDataType._P_ADDITIONAL_INT_ARRAY