# 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
- Callable Policy Web Service interface definition

- Endpoints
- Detailed service description
- XML Schema data type definition

- AdditionalDataValue structure
- AdditionalDataValueType enumeration

- Interface: Policy

- Operation: evaluate

- Interface: PolicyManagement

- Operation: viewRuleFile
- Operation: deleteRuleFile
- Operation: loadRules
- Operation: listRuleFiles

- Rule files

## 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 `serviceProviderI`D: 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`.
- l`ong 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 `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.

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 (`p`r) 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 `PolicyReque`st 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:

- `getAdditionalDataIntValu`e(...), for int values
- `getAdditionalDataLongValu`e(...), for long value.
- `getAdditionalDataStringValue`(...), for String values
- `getAdditionalDataStringArrayValu`e(...), 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();

Wh`ere 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`