For most installations of Oracle Communications Services Gatekeeper, the ability rapidly and accurately to evaluate the status of requests in terms of Policy, or rules governing a variety of service characteristics, is one of the most important features that the system offers.
|Note:||Some evaluations, such as enforcement of SLAs, are performed by the Interceptor Stack. See Service Interceptors for more details. The Policy system described in this chapter allows you to add additional types of evaluation to the request flow, including adding rules to be used for the Callable Policy Web Service.|
If you extend Oracle Communications Services Gatekeeper, particularly if you add a new Communication Service, you may also need to make changes in the Policy system to cover new functionality that you have added. This chapter provides a very high level description of the process by which policy requests are processed and though which new rules can be added. It covers:
When an application service request arrives at the service interceptor CreatePolicyRequestData, its parameters are put in a PolicyRequest object. The service interceptor EvaluateILOGPolicy evaluates these custom policy rules The rules themselves are written in the ILOG IRL language.
PolicyRequest object has a standard form. The values in the object must be mapped to the variables in the Policy Rule that will be used to evaluate them. The Policy Request object can contain subsets of this standard data:
applicationID: The Application ID of the requesting party
serviceProviderID: The Service Provider ID of the requesting party
nodeID: Used internally by Oracle Communications Services Gatekeeper - ignore
serviceName: The name of the software module in which the policy request originates. Used in the rules to match to service contracts in the SLAs and to look-up any rules specific to the service.
methodName: The name of the method which the request wishes to have executed. Access to this method is what is being evaluated.
serviceCode: The service code provided by the application, which is written to CDRs for tracking purposes
requesterID: An additional ID that may be provided by the application for tracking purposes. (dependent on the northbound interface being used)
All of the above are Strings.
transactionID: Used internally by Oracle Communications Services Gatekeeper - ignore
noOfActiveSessions: Used internally by Oracle Communications Services Gatekeeper - ignore
timeStamp: The time the request was fed to the Policy Engine.
reqCounter: The number of target addresses in the request. If only one target address is used in the request this value is set to 1. If using multiple target addresses in the request, it is the number of target addresses.
All of these are Longs.
In addition to these standard values, Policy Request objects contain all the parameters passed in from the application in its initial request, as
AdditionalParameters, an array of
AdditionalDataValue consist of a name-value pair. The following data types can be defined in an
intValue(int val):Integer values
longValue(long val):Long values
stringArrayValue(String val): Arrays of String values.
booleanValue(boolean val): Boolean values.
shortValue(short val): Short values.
charValue(char val): Char values.
floatValue(float val):Float values.
doubleValue(double val): Double values.
intArrayValue(int val): Arrays of int values.
The name of the name-value pair is defined in the dataName member variable in the
AdditionalData object. See Listing 16-1
AdditionalData adArray = new AdditionalData;
AdditionalDataValue targetAddressValue = new AdditionalDataValue();
AdditionalData adTargetAddressString = new AdditionalData();
adTargetAddressString.dataName = "targetAddress";
adTargetAddressString.dataValue = targetAddressValue;
adArray = adTargetAddressString;
policyRequest.additionalParameters = adArray;
If any of the incoming parameters from the application are complex types, the objects are automatically examined and broken down into simple Java types. So, for example, the Parlay X 2.1 complex type
ChargingInformation can contain a description, which is a string, a currency kind, which is also a string, an amount, which is a decimal number, and a code, which is a string. When the data is sent to the Policy Engine, it is broken down into a string value called
parameters.charging.currency, another string value called
parameters.charging.code, and so forth.
New rules can be added to the Policy Service. The rule must have a
name and a
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:
priority = high;
// fetch the policy request data and perform evaluations.
// Take action on
In order to perform an evaluation, the data in the
PolicyRequest object must be fetched by the rule in the Policy Engine and mapped to the equivalent variable name 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.
?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.
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
priority = minimum;
?pr: event PolicyRequest();
Data that is defined as
AdditionalValues must fetched as shown in Listing 16-6. The Additional Value named
targetAddress is stored in the variable
addDataValue. The PolicyRequest object is
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
bind ?type = ?pr.getAdditionalData.dataValue.discriminator().value();
Where type is one of the following:
The following shows an example of extending an existing rule file:
Use the operations in the PolicyService to manage the rule files, seein the System Administrator’s Guide.
It is possible to use generic data specified in service provider and application-level SLAs in a plug-in. This is useful when the choice of the action or behavior a plug-in should make is based on which service provider or application originates the request originates. For example, this can be used for information about parameters that corresponds to a certain group of applications. For instance a certain group might get the priority on their SMS set to LOW because they pay less. The priority might be a parameter that is sent down to the network which handles this.
In an SLA, a <contextAttribute> is defined as a name/value pair, where the name is defined in the tag <attributeName> and the value is specified in <attributeValue>.
A plug-in can retrieve the value specified in <attributeValue> using the name specified in <attributeName>. The value is retrieved using the RequestContext for the request:
String attributeValue = (String)RequestContextManager.getCurrent().get("<attributeName>");
For example, the value associated with the contextAttribute with the attributeName com.bea.wlcp.wlng.plugin.sms.testName1 is retrieved using:
String value1 = (String)RequestContextManager.getCurrent().get("com.bea.wlcp.wlng.plugin.sms.testName1");