Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.0 Part Number E16619-02 |
|
|
View PDF |
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:
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>
This section describes the Callable Policy Web Service interface.
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
This section describes the Policy Evaluation and Policy Management intrfaces.
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.
This section describes the XML scheme data type defnitions
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". |
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. |
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.
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.
Operations to manage policy rules.
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:
|
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.
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:
|
serviceName |
xsd:String |
N |
ServiceName associated with the rule file. |
Output message: deleteRuleFileResponse
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.
Loads a a policy rule file of a given type and service into the rules engine.
Part name | Part type | Optional | Description |
---|---|---|---|
type |
xsd:string |
N |
Type of rule file, either:
|
irlUrl |
xsd:string |
N |
URL to rule file to be loaded. |
serviceName |
xsd:string |
N |
ServiceName associated with the rule file. |
Output message: loadRulesResponse
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.
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:
|
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.