Workflow forms provide a great way to interact with the directory vault, but have some GUI limitations when you restrict yourself to creating the forms with IDM Designer.

There are various ways to enhance the functionality and GUI of workflow forms - one of those is the addition of jQuery scripting. A couple of integration samples have been published here on Cool Solutions.

This sample uses jQuery to implement dynamic interaction with server based Java classes with Ajax.

Ajax uses ECMAScript's capability to asynchronously send requests to some other device and react on the response, hereby allowing for a rather simple way to establish client-server communications from within your form and without submitting or reloading your form.

You can implement your own client-server interaction handler with some ECMAScript and Java code, but jQuery provides a simple way to handle all the harsh details for you and allows you to focus on your custom logic.

You will find plenty of information about jQuery and jQuery Ajax implementation, together with sample code here:

http://docs.jquery.com/

Possible scenarios for using Ajax in IDM workflow forms environments where you need to retrieve or write information in dynamic forms without submitting the form:

• accessing database information

• retrieving data from external websites

• accessing other ID vaults

• interact with other services

The jQuery implementation of Ajax uses JSON to transfer the request and response data over the wire. All you need to do is to ...

• [form] use ECMAScript to store your request data into an object and pass this object to jQuery

• [server] use custom logic to read the request and provide a JSON response

• [form] use ECMAScript to interpret the response object

This Cool Solution implements a pretty basic Ajax implementation called from an even simpler form:

The form has two text input fields; whenever some text is entered into one of the fields, an Ajax call is sent to the server, transmitting the contents of both fields.
To be more specific: the field:onchange handler calls the function registerChange() to check if the fields are initialized; then the function ajax_call_jquery() is called, which collects the user input and stores the data into an object named "inputData". Then it passes the object to the jQuery function $.ajax().

/** react on the changes in the text fields and call Ajax
 */
function registerChange( form, field )
{
	try
	{
		var fldValue	= field.getValue();
		if ( fldValue == "" ) return;
		ajax_call_jquery( form, '/ncsAJQ/ajax/test.jsp' );
	}
	catch( e )
	{
		form.showError( e );
	}
}

/** collect the data that we want to send to the service, then call Ajax
 */
function ajax_call_jquery( form, url )
{
	try
	{
		var inputData	= new Object();
		inputData[ "data1" ] = form.getValue( "fldText1" );
		inputData[ "data2" ] = form.getValue( "fldText2" );

		// call to jQuery Ajax
		$.ajax( {
			type:		'GET',
			url:		url,
			data:		inputData,
			success: function( data )
			{
				ajax_display( form, url, data );
			},
			error:	function( xhr, status )
			{
				ajax_display( form, url, xhr   " / "   status );
			},
			timeout: 9000
		} )
	}
	catch( e )
	{
		form.showError( e );
	}
}

The server logic is implemented as JSP for simplicity - in real life you'd probably rather implement the logic as servlet.
However, the equivalent logic could be implemented as PHP, Perl, ASP, you name it ... just as long as the result is some kind of JSON object.
In our case, the JSP decodes the request, adds some dummy data and wraps it all into a JSON object. It is your responsibility to replace the nonsense data with some more relevant logic.

<%@page import="java.io.StringWriter"%>
<%@ page language="java"
			contentType="application/json;"
			pageEncoding="ISO-8859-1"
			import="java.net.*, java.io.*, java.util.*, org.json.simple.*"
%><%
	try
	{
		// for JSON encoding/decoding see: http://code.google.com/p/json-simple/wiki/EncodingExamples

		// read data1 sent from the client
		String data1 = request.getParameter( "data1" );
		System.out.print( "NCS: data1="   data1 );

		// read data2 sent from the client
		String data2 = request.getParameter( "data2" );
		System.out.print( "NCS: data2="   data2 );

		// return some dummy data in various formats
		Map obj = new LinkedHashMap();
		obj.put( "jsp", "test2.jsp" );
		obj.put( "time", ( new Date()).toString() );
		obj.put( "data1", data1 );
		obj.put( "data2", data2 );
		obj.put( "test1", "foo" );
		obj.put( "test2", new Integer( 100 ) );
		obj.put( "test3", new Double( 1000.21 ) );
		obj.put( "test4", new Boolean( true ) );
		obj.put( "test5", null );

		// add a more complex result type (list)
		JSONArray list1 = new JSONArray();
		list1.add( "foo" );
		list1.add( new Integer( 100 ) );
		list1.add( new Double( 1000.21 ) );
		obj.put( "test6", list1 );

		// convert all data to JSON
		StringWriter stringWriter = new StringWriter();
		JSONValue.writeJSONString( obj, stringWriter );
		String jsonText = stringWriter.toString();

		// return the JSON string
		System.out.print( "NCS: result="   jsonText );
		out.write( jsonText );
	}
	catch ( Exception e )
	{
		System.out.print( "NCS: e="   e.toString() );
		out.write( "{[ "   e.toString()   " ]}" );
	}
%>

When the content is ready for the client, an event is triggered in the client Ajax script, where the function ajax_display() decodes and evaluates the response. Our sample script displays the received data on the form and extracts some data for demonstration purposes.

/** this event handler is called on return from the Ajax call
 *
 *		evaluate/display server response
 */
function ajax_display( form, url, data )
{
	if ( data )
	{
		form.setValues( "fldResult", dojo.toJson( data ) );
		if ( data.time ) alert( "Server date/time: "   data.time );
	}
}

The whole logic is contained in 3 files

• test.jsp represents the server logic

• ncsCustom.js hosts the client script

• jquery.min.js is the jQuery logic and was downloaded from jquery.com

These 3 files were stored in a custom WAR file to deploy on JBoss. Use your IDE (like Eclipse or Netbeans) or the JDK tools (like JAR.EXE) to create your own WAR file.
This custom WAR file is attached to this Cool Solution for convenience. You may copy the WAR file to your JBoss deployment directory (e.g., [jboss]/server/IDM/deploy or [jboss]/server/IDMProv/deploy) to make the demo logic available for testing on your JBoss server.

Also, the sample workflow and form is attached to this Cool Solution, so you can directly import the PRD into your environment. You will typically have to update the PRD trustees to reflect your own test environment.

Here are the instructions to manually build the sample workflow:

We start with a simple workflow - since we actually do not process anything, but only need a form for demonstration purposes, we just need a start and finish activity.



The request form gets two text input field named "fldText1" and "fldText2", as well as a text area field "fldResult" that we use to display the server response.



Both "fldText1" and "fldText2" get an onchange event handler.



The onchange event handler for both fields does nothing but call the registerChange() function.



You need to deploy the attached ncsAJQ.war file on JBoss by copying it into the IDM deploy subdirectory. This makes the ECMAScript available as "[jboss url]/ncsAJQ" or - with a relative path - "/ncsAJQ".

Enter the 2 paths for the external scripts, one for the custom logic, the other containing jQuery code.
Designer will show a warning message with such relative paths, since Designer cannot resolve the relative name. Ignore the message.



Now, deploy the new workflow and load the request form.



If everything went well, you can enter some text in the input fields and receive a response from the Ajax service.



If anything went wrong, you can try some diagnostics:
Check to see if the JSP is loaded: you should be able to enter "[jboss url]/ncsAJQ/ajax/test.jsp" (where "[jboss url]" is the part before - and not including - your IDM url, e.g., "http://172.17.2.91:8080/ncsAJQ/ajax/test.jsp") in your web browser and get some results.

If your web browser can't find the jsp, make sure you copied the WAR into the correct folder and check your [jboss]/log/server.log for errors.

If the test worked smoothly, replace the logic in the JSP by some more useful stuff, or replace the JSP by some other (servlet/PHP/.NET/[whatever]) service

 

Attachment:

Cool Solutions - Ajax with JQuery