By Robert Hunter, Senior Systems Engineer
An IBM Content Navigator (ICN) plug-in service is arguably one of the most flexible types of functionality you can add to ICN. An ICN plug-in service can be called from almost anywhere in ICN; the only stipulation is it must be called from a client-side asset like a plug-in action or a plug-in feature. ICN plug-in services can be configured to return almost anything and are primarily used to execute custom searches. They can also be used to work with third-party Java libraries and P8 specific APIs that cannot be accessed from client-side assets.
Overall, plug-in services are well documented between various Redbooks and the IBM Knowledge Center. However, we often receive questions that go beyond a basic plug-in service implementation.
Most commonly:
- Can you invoke a plug-in service as a POST request?
- Can you invoke a plug-in service without locking up the ICN Desktop?
The answer to both is yes. Below is further description along with some code samples.
Creating a New IBM Content Navigator Plug-in Service
To create a new ICN plug-in service within an existing ICN plug-in project, follow the steps below:
- Right-click the Java ICN plug-in project package.
- Hover over the “IBM Content Navigator” menu option.
- Hover over the “Server Extensions” menu option
- Select New Service… menu option.
This will add a new plug-in .java file to the Java package. The service needs to be able to handle all properties that are passed to it via the “HttpServletRequest request” function parameter. To end the service call, you need to call the “writeJSONResponse (JSONResponse jsonResponse, HttpServletResponse response)” function on the “PluginServiceCallbacks callbacks” function parameter. This will send the response to the client-side asset that initially invoked the plug-in service.
You will find the steps required to create a new plug-in described in a previous blog post. In that post, there is also information on common files within the plug-in project, as well as some other helpful information.
Accessing the Service
Below is sample code which executes a sample plug-in service:
define([ ‘dojo/_base/declare’, ‘ecm/model/Request’, ‘dojo/_base/lang’, ‘dojo/text!./templates/FooBarDijit.html’ ], function(declare, Request, lang, template) { return declare(‘package.name.FooBarDijit’, [], { templateString: template, fooBarFunction: function() { var requestParams = {}; requestParams.someParameter = ‘Foo Bar’; Request.invokePluginService(‘Plugin Name’, ‘Plugin Service Name’, { requestParams: requestParams, requestCompleteCallback: lang.hitch(this, function(response) { // Access the service response here }), requestFailedCallback: function(ex) { // An error occurred } }); } }); });Some important things to note:
- The “ecm.model.Request” dijit is necessary as it is responsible for calling the plug-in service
- Properties are passed to the plug-in service through a JavaScript object. The properties you want to expose need to be properties on said JavaScript object
- The “requestCompleteCallback (response)” property allows you to receive the response from the plug-in service
- The “requestFailedCallback (error)” property allows you to receive the error response if the plug-in service fails
Making a Background Service Call
The above sample code will execute an ICN plug-in service request in the foreground, which means that an IBM “Working” modal dialog will appear and prevent all other work for as long as the Content Navigator plug-in service request is executing. This isn’t desirable with most ICN plug-in service requests. Luckily, there is an additional property you can pass when invoking your ICN plug-in service which will enable the request to occur in the background, allowing additional work to be done while the plug-in service is executing:
Request.invokePluginService(‘Plugin Name’, ‘Plugin Service Name’, { requestParams: requestParams, requestCompleteCallback: lang.hitch(this, function(response) { // Access the service response here }), backgroundRequest: true, requestFailedCallback: function(ex) { // An error occurred } });Setting the “backgroundRequest” property to “true” allows the plug-in service to be executed in the background.
Making a POST Service Call
All above sample code will execute a plug-in service using a GET request. This becomes undesirable when it is necessary to pass more data to the ICN plug-in service than the browser will allow using a GET request. This is solved by using a POST request by calling “postPluginService()”, instead of the previously used function:
Request.postPluginService(‘Plugin Name’, ‘Plugin Service Name’, ‘application/x-www.form-urlencoded’, { requestParams: requestParams, requestCompleteCallback: lang.hitch(this, function(response) { // success // Access the service response here }), backgroundRequest: true, requestFailedCallback: function(ex) { // An error occurred } });As you can see from the above code block, you are able to make the POST request in the background as well. Not only will your IBM Content Navigator plug-in service work around a browser URL length restriction, your plug-in service will also run seamlessly in the background while you’re able to do other work!