User App ECMAScript Examples

From MicroFocusInternationalWiki
Jump to: navigation, search

Introduction

NetIQ's User Application is the front end for workflows and password self service.

Provisioning Request Definition (PRD) objects are used to define the Workflow process.

ECMAScript is the primary language for doing much of the work in these PRD's. There are a number of interesting things that can be done, and others that should be done, in almost any project.

The purpose of this page is to provide a set of useful functions that many Workflow implementations will likely need.

If you are just getting started with Workflows, this page will likely be of great help, but if you are truly just getting started, you might consider these two articles to help identify some of the moving parts in the process:

http://www.novell.com/communities/node/11580/introduction-workflows-and-prds-identity-manager-part-1

http://www.novell.com/communities/node/11582/introduction-workflows-and-prds-identity-manager-part-2


Your Contribution to this library

TODO

Backwards Compatibility

TODO

Function Library

Some of the following functions may work both, in workflows (running on the User Application server), i.e. mapping activities, and other operations , others may only work in form events (running in the client browser), like field and form events.

In practice, you may consider creating 3 files for your personal script library:

  • shared.js (functions available in forms and workflows)
  • form.js (functions available in forms)
  • wf.js (functions available in workflows)


Functions for Forms and Workflows

TODO

Client-Side Scripts and Server-Side Scripts

At first glance, many ECMAScript functions use an identical syntax when being called from form activities or from mapping activities. The implementation, however, is significantly different: While client scripts are executed by browser's script engine, server scripts internally are parsed, interpreted, and translated to Java by Rhino, an open-source implementation of JavaScript written entirely in Java (see https://developer.mozilla.org/en/docs/Rhino)


Constants

// ECMAscript variable types as returned by the typeof() function

var VARTYPE_OBJECT	=	"object";
var VARTYPE_ARRAY	=	"array";
var VARTYPE_STRING	=	"string";
var VARTYPE_DATE	=	"date";
var VARTYPE_BOOLEAN	=	"boolean";
var VARTYPE_NUMBER	=	"number";
var VARTYPE_FUNCTION	=	"function";
var VARTYPE_UNDEFINED	=	"undefined";


Essentials

Client-Side or Server-Side

Most of the User Application APIs look identically in both script flavors, however there are slight differences. If you're using the same script libraries for both, client and server scripts, you may sometime need to know where you are.

One key difference is the presence of the "Packages" object, which allows you to call java from a server side ECMAscript.

var isWorkflow = ( typeof( Packages ) === VARTYPE_OBJECT );



Error Handling, Logging, Debugging

Functions for Forms

TODO

Constants

Essentials

Form Field Operations

DAL Operations

jQuery Operations

Error Handling, Logging, Debugging

Functions for Workflows

TODO

Constants

Essentials

DAL Operations

globalQuery

The globalQuery() syntax is slightly different in workflows: while n form scripts the API has a fieldname parameter and returns an array in form scripts, is doesn't have this parameter in server-side activities and returns a list object. Also, both parameters are required. To add a word of caution: this function has been working in IDM versions from 3.x to the current 4.0.2; however, it is not officially documented and as such may or may not work in future releases of IDM.

globalQuery( key, param ) // returns list (not array!) of DNs

In pre-activity mappings simply enter the query.

IDVault.globalQuery( "myGlobalQuery", { "myParam1": "test; "myParam2": 123 } ); // query with 2 params
  or 
IDVault.globalQuery( "myGlobalQuery", {} );  // query without params

When you need to parse the returns of the query, use a loop like this:

var q = IDVault.globalQuery( "myGlobalQuery", { "myParam1": "test; "myParam2": 123 } );
for ( var i=0; i<q.size(); i++ )
{
	var dn = q.get( i );
	// .. your logic
}


If you prefer to use IDVault.globalQuery() in a shared script library for forms and activities, you may use a wrapper that handles both calling conventions:

/** wrapper around IDVault.globalQuery() that can be used in form scripts or workflows 
 * 
 * @param {object} IDVault
 * @param {string} fldName	// optional in form scripts, ignored in workflow scripts
 * @param {string} key	
 * @param {object} param	// 
 * @returns {object|array}
 */
function globalQuery( IDVault, fldName, key, param )
{
	var result = undefined;
	try
	{
		if ( isWorkflow )
		{
			if ( typeof( param ) === VARTYPE_UNDEFINED ) param = {};  // mandatory
			result = IDVault.globalQuery( key, param );  // list		
		}
		else
		{
			result = IDVault.globalQuery( fldName, key, param );  // dual array		
		}
	}
	catch( e )
	{
		if ( isWorkflow )
		{
			Packages.java.lang.System.out.println( "globalQuery( IDVault, " + key + ", param ): " + e );
		}
		else
		{
			alert( "globalQuery( IDVault, " + fldName + ", " + key + ", param ): " + e );
		}
	}
	return( result );
}

Error Handling, Logging, Debugging

Make WAR, don't laugh

TODO

Especially for form scripts it makes your work significantly easier if you move your script library to your own custom WAR file and simply reference this WAR from your PRDs

Wrap-up

Useful Reference articles

http://www.novell.com/communities/node/12740/howto-use-radio-buttons-user-application-turn-your-cb-radio

http://www.novell.com/communities/node/12722/howto-make-your-move-idm-workflows

http://www.novell.com/communities/node/12645/howto-validata-form-input-and-disable-submit-user-application-forms

http://www.novell.com/communities/node/11484/howto-change-frame-size-request-forms-user-application-idm-37x

http://www.novell.com/communities/node/9601/user-application-approval-forms-dynamically-generated-mv-checkboxpicklists-or-text-picklis

http://www.novell.com/communities/node/11530/howto-idm-workflow-loop-route-disable-inactive-users

http://www.novell.com/communities/node/11578/howto-programmatically-change-truefalsecheckbox-idm

http://www.novell.com/communities/node/11527/howto-change-or-remove-header-user-application-process-request

http://www.novell.com/communities/node/11492/howto-execute-workflow-activities-custom-delays-user-application

http://www.novell.com/communities/node/11489/howto-execute-workflow-activities-specified-date-user-application-idm-37

http://www.novell.com/communities/node/11225/howto-use-idm-designer-create-sorted-mvcheckboxes-idm-user-application

http://www.novell.com/communities/node/11224/howto-use-idm-designer-create-vertically-aligned-mvcheckboxes-idm-user-application

http://www.novell.com/communities/node/11218/howto-idm-replace-object-selector-simple-custom-search

http://www.novell.com/communities/node/12741/howto-use-radio-buttons-user-application-html-radio

http://www.novell.com/communities/node/12864/howto-add-your-two-cents-worth-log-log4j-and-userapp

https://www.novell.com/communities/node/13175/change-order-search-attributes-idm-dnlookup-controls

http://www.novell.com/communities/node/13752/howto-pimp-my-form-jquery-collapse-field-groups

https://www.netiq.com/communities/cool-solutions/howto-debug-your-user-application-form-scripts-quick-start/

http://www.novell.com/communities/node/9210/using-jquery-identity-manager-roles-based-provisioning-module-workflow-forms