The following section describes how to use the callable policy interface exposed by Oracle Communications Services Gatekeeper.
The callable policy service in Oracle Communications Services Gatekeeper exposes two Web Services interfaces related to callable policy:
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
.
<serviceContract>
<scs>com.bea.wlcp.wlng.px21.plugin.PolicyPlugin
</scs>
</serviceContract>
<serviceContract>
<scs>com.bea.wlcp.wlng.px21.plugin.PolicyManagementPlugin
</scs>
</serviceContract>
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
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.
The policy management web service interface makes it possible to load and delete policy rules.
Defines the AdditionalDataValue structure.
Identifies the data type. See AdditionalDataValueType enumeration.
|
Operations to evaluate a request.
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.
Specifies any other data, specified as name-value pairs. See AdditionalDataValue structure.
|
If there is an internal error during evaluation process, a ServiceException is thrown.
If the policy evaluation request is rejected, a PolicyException is thrown.
Operations to manage policy rules.
Fetches a policy rule file of a given type and service from the rules engine.
If there is an internal error during evaluation process, a ServiceException is thrown.
If the policy evaluation request is rejected, a PolicyException is thrown.
Deletes a policy rule file of a given type and service from the rules engine.
If there is an internal error during evaluation process, a ServiceException is thrown.
If the policy evaluation request is rejected, a PolicyException is thrown.
Loads a a policy rule file of a given type and service into the rules engine.
If there is an internal error during evaluation process, a ServiceException is thrown.
If the policy evaluation request is rejected, a PolicyException is thrown.
Lists the rule files of a given type that are loaded into the rules engine.
If there is an internal error during evaluation process, a ServiceException is thrown.
If the policy evaluation request is rejected, a PolicyException is thrown.
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:
applicationID
: Application ID associated with the request.serviceProviderI
D: Service provider ID associated with the request.serviceName
: Service name from which the request originates or is destined for.methodName
: Method that triggered the request.serviceCode
. requesterID
.transactionID
.noOfActiveSessions
. ong timeStamp
: Time the request was sent to the rules engine for processing. Milliseconds from start of UNIX epoch.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:
Listing 16-2 shows the basic structure 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 PolicyReques
t member variable serviceName
to the rule variable sname
via the Policy Request object. The rule object pr
is assigned to the PolicyRequest
object.
?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 (p
r) must be retracted. Retracting the PolicyRequest object aborts further rule enforcement.
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.
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 PolicyReque
st object is pr
.
bind ?addDataValue = ?pr.getAdditionalDataStringValue("targetAddress");
The particular signature of the fetching method depends on the type of data:
getAdditionalDataIntValu
e(...), for int valuesgetAdditionalDataLongValu
e(...), for long value.getAdditionalDataStringValue
(...), for String valuesgetAdditionalDataStringArrayValu
e(...), for arrays of String valuesgetAdditionalDataBooleanValue
(...), for boolean valuesgetAdditionalDataShortValue
(...), for short valuesgetAdditionalDataFloatValue
(...), for float valuesgetAdditionalDataDoubleValue
(...), for double valuesgetAdditionalDataIntArrayValue
(...) for arrays of int values.
If the data type is unknown, it can be determined by invoking the discriminator method on the AdditionalDataValue
object.
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