Custom Service plugin overview

The Determinations Server Custom Service plugin allows you to leverage the Oracle Policy Automation technology to create a custom SOAP/HTTP based web service. It is a high level plugin that allows custom web services to be added to the Determinations Server. It provides access to the following Determinations Server APIs:

Interview
Assess
Determinations Engine.

At a high level, this plugin establishes which service a request corresponds to, then passes the processing to that request and writes out the response. Each component requiring a separate WSDL is considered a different service, and each service must have its own WSDL.

The most likely reasons for using a custom service are:

Where there is a need to provide a customized service definition (WSDL).
Because the new service needs to modify the default process flow of an existing service and/or actually orchestrate multiple processes to such a degree that it may be easier to implement a custom service.

Custom Service and the Determinations Server architecture

The following information details how the Custom Service plugin fits into the Determinations Server architecture, and how to use it in the Determinations Server environment.

Service plugin loading and registration.

Plugins are loaded using much the same mechanism as the one for Web Determinations (see Plugin loading, invocation and discovery)

Each plugin is tied to a particular rulebase and so will be polled once for each rulebase.

If hot-swapping mode is turned on:

When adding a new rulebase, the custom service plugin is given an opportunity to register a service against that rulebase.
When a rulebase is deleted, any service registered against it is automatically unloaded
Updating an existing rulebase is the equivalent of a delete and load.

Service plugin endpoints
As soon as an instance of a plugin is returned it will be asked for its endpoint. This endpoint is a URI and signifies that any request to that endpoint will be handled by this service.

It is the responsibility of the implementer to make sure the endpoint for their service is unique.
If multiple services use the same endpoint, the first service will be registered and all subsequent ones will be disregarded (remember you can't control the order in which plugins are loaded).
The following endpoints are reserved for the native services:
- "/server/soap/*" - Server Service(s)
- "/assess/soap/*" - The Assess Service(s)
- "/interview/soap/*" - The Interview Services(s)
Service endpoints are case sensitive so /My/Custom/Service is not the same as /my/custom/service.
Note For .NET Plugins:
Because ASP .NET is effectively integrated into IIS 6.0 by means of an ISAPI filter, each request must contain one of the recognized .NET extensions (for example, .aspx, .asmx) in order for it to be forwarded to the application properly. Note however that as this is automatically handled by the servlet layer, endpoints should be specified without any extension.

Thread safety
Since only one instance of a service plugin is registered per endpoint each service must be thread safe. Furthermore, any state that needs to be maintained by the service is entirely the responsibility of that service.

Getting the service WSDL

The service WSDL can be retrieved by appending '?wsdl' to the service endpoint. For example: if the service is registered at /my/custom/service then a call to http://<server>/my/custom/service?wsdl will return whatever wsdl is provided by the services' getWsdl() method.

Error handling

As the service is responsible for everything that happens at the SOAP/XML layer, it is the responsibility of the service to handle any exceptions it wishes to report in a meaningful way; for example, via a SOAP Fault.

Any unhandled exception that makes its way up to the servlet layer will be logged and cause the Determinations Server to return an HTTP 500 Internal Service Error.