19 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

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 <scs> element must contain the value com.bea.wlcp.wlng.px21.plugin.PolicyPlugin.

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

Example 19-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

This section describes the Callable Policy Web Service interface.

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

This section describes the Policy Evaluation and Policy Management intrfaces.

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

This section describes the XML scheme data type defnitions

AdditionalDataValue structure

Defines the AdditionalDataValue structure.

Table 19-1 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.

Table 19-2 AdditionalDataValueType enumerators

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

Table 19-3 evaluateRequest parts

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

Table 19-4 evaluateResponse parts

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

Table 19-5 viewRuleFile parts

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

Table 19-6 viewRuleFileResponse parts

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

Table 19-7 deleteRuleFile parts

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

Table 19-8 deleteRuleFileResponse parts

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

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

Table 19-9 loadRules parts

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

Table 19-10 loadRulesResponse

Part name	Part type	Optional	Description
N/A	N/A	N/A	N/A

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

Table 19-11 listRuleFiles parts

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

Output message: listRuleFilesResponse

Table 19-12 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.