Welcome to Cool Solutions

Fire Event On Button Click for IDM Designer / UserApp

Introduction

This article will show you how to trigger a custom event in a Provisioning Request Definition (PRD) from an HTML button that you place on a form. This custom would be defined for some other field on a form.
An example of where you would use this would be to run a query to fill a picklist, once the user has decided to run the query and clicked on the form button that will run the query.
Some of the script examples shown in this article are part of the gray APIs, which means they may change in future versions of the User Application workflow, and therefore use them at your own risk.
Prerequisites assumed in this article:

• Designer for Identity Manager 2.1.1
• User Application 3.5.1
• You understand the basics of creating PRDs, defining forms and fields.
• Adding fields to events and the basics of writing JavaScript and HTML.

Acknowledgements
Thanks to Rudy Duym, who helped me figure the scripts calls needed.

1.0 Define the Custom Event to be Fired

In my example I am going to use a field of data type "dn" and a PickList control. The purpose of the field is to display a list of groups that the user does not belong to by running a query that takes in the current user DN.

But remember the main objective of this exercise is to delay
the firing of the query until the user is ready to use it. Actually
this approach could be used in a variety of ways.

Do the following:

1. The picklist has the following properties:
- Entity key for DN expression: Group
- Display expression: Description

Click to view.

2. Linebreaks for the field are set to 0, because the HTML button (Section 2.0, Define the HTML Control) is to be placed after this field, and I want the button to be next to the field that it is going to fill in.

3. A custom event called doQuery with the following ECMAScript code:

IDVault.globalQuery("selectGroup","GroupsNotInList",{"userDN":form.getValue("recipient")})

Click to view.

Because this is a custom event, it will not be fired until it is called. Therefore, the query is not invoked, and the picklist is not initialized.

Define the HTML Control

To fire the event, we are going to place a button on the form next to the PickList field. This is done by using a string data type with an HTML control. In the HTML control, you place the HTML that you want on the page. For this example, this will be a button with some JavaScript to execute on the click of the button.
Do the following:
1. The only property on the HTML control is the following code. In Step 2, the code will be explained in detail. Note that everything after the return is all on one line.

(function(){return "<input type=\"button\" value=\"Do Query!\" onClick=\"JUICE.UICtrlUtil.showMsg('Calling query event.','1'); var ctrl = JUICE.UICtrlUtil.getControl('selectGroup'); var vals = ctrl.getValues(); var evt = new JUICE.WFASEvent('selectGroup', 'doQuery', vals, null, null);  dojo.event.topic.publish('WFAS_doQuery', evt);  \">";}) ();

Here's an explanation of JavaScript and HTML that are placed on the form. Note: The explanation lines are in bold.

(function(){
return "<input type=\"button\" value=\"Do Query!\" onClick=\"

Add an HTML input control of type button that has an OnClick JavaScript

JUICE.UICtrlUtil.showMsg('Calling query event.','1');

Display a message when the script is called for debugging so we know the script was called.

var ctrl = JUICE.UICtrlUtil.getControl('selectGroup');

Get the JUICE control for the picklist field, which is the field we want for firing the custom event.

var vals = ctrl.getValues();

Get the current values in the field. These are passed to the event, so we can potentially work on them in the event handler code.

var evt = new JUICE.WFASEvent('selectGroup', 'doQuery', vals, null, null);

Create an event object to fire the event. The first parameter is the field that has the event, the second is the name of the custom event to be fired.

dojo.event.topic.publish('WFAS_doQuery', evt);

Fire the event. WFAS_ is appended to the event name.

\">";

Close off the input HTML control.

}) ();

Hint:The implementation for all form script related methods can be found in WFASUtil.js under javascript/JUICE in the IDM.WAR.
The signature for the main function we used is:

JUICE.WFASEvent = function(/*string*/ afieldname, /*string*/ aeventname, /*string || array*/ avalues,
/*DOMEvent*/ domevt, /*string || array || object || integer || decimal*/ customdata)

3. The functions above are part of the "gray" APIs and should be used with caution. They also should be well documented where they are used, because they are subject to change.

Results of Running the Example

Do the following:
1. Request before the button is clicked.

Click to view.

2. Request after the button is clicked.

Click to view.