# Platform Development Studio - Developer’s Guide

# Policy

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:

- Overview
- Policy Request Data
- Adding a New Rule
- Using RequestContext Parameters Defined in Service Level Agreements

## Overview

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.

## Policy Request Data

A `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`. An `AdditionalDataValue` consist of a name-value pair. The following data types can be defined in an `AdditionalDataValue` object.

- `intValue(int val):` Integer values
- `longValue(long val):` Long values
- `stringValue(String val):` Strings.
- `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

Listing 16-1 Defining AdditionalData

    AdditionalData adArray[] = new AdditionalData[1];

    AdditionalDataValue targetAddressValue = new AdditionalDataValue();

    AdditionalData adTargetAddressString = new AdditionalData();

    targetAddressValue.stringValue(address);

    adTargetAddressString.dataName = "targetAddress";

    adTargetAddressString.dataValue = targetAddressValue;

    adArray[0] = 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.

## Adding a New Rule

New rules can be added to the Policy Service. The 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 16-2 Skeleton of a rule

    rule DenySubscriberNotExists

    {

    priority = high;

      when

      {

       // fetch the policy request data and perform evaluations.

      }

    then

      {

          // Take action on

      }

    };

### Mapping PolicyRequest Data

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.

Listing 16-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 16-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 16-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 in Listing 16-6. The Additional Value named `targetAddress` is stored in the variable `addDataValue`. The PolicyRequest object is `pr`.

Listing 16-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 16-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`

### Creating a New Rule File by Extending an Existing File: an Example

The following shows an example of extending an existing rule file:

1. List the Current Services’ Rule Files
2. Select the Service Whose Rule File You Wish to Extend
3. Add a New Extended Rule
4. Load the New Rule File.

Use the operations in the PolicyService to manage the rule files, see Managing the PolicyService in the System Administrator’s Guide.

## Using RequestContext Parameters Defined in Service Level Agreements

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");