cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

IdentityIQ 8.0: Plugin enhancements

IdentityIQ 8.0: Plugin enhancements

Back to the IdentityIQ 8.0 overview: What's new in IdentityIQ 8.0

 

 

Overview

Version 8.0 of IdentityIQ offers a number of enhancements to plugins:

  • Classes contained in a plugin can be leveraged from any area or feature of IdentityIQ where BeanShell can be used, such as rules, workflow steps, and scriptlets. Version 8.0 also provides mechanisms for limiting or blocking scripting access to plugin classes as needed, and some new iiq console commands to support troubleshooting of plugin classes.
  • Support for forms in the plugin configuration UI, giving you new ways to present complex or dynamic options in the plugin's configuration page
  • Stricter handling of executors for Tasks, Services, and Policies, with a global configuration option allowing you to "relax" the stricter declarations for legacy plugins, to help with forward compatibility.

 

Forms in plugin configuration

IdentityIQ 8.0 adds support for dynamic, form-based options in a plugin's configuration UI. For example, you could include a drop-down list of options for a plugin configuration setting, then show specific additional configuration settings based on the option the user chose from the drop-down. There are two ways to implement forms for your plugin's configuration: by defining the form directly in the plugin's manifest file, or by referencing a custom JavaScript form.

 

Defining a plugin form in manifest.xml

If you want to define a form directly in the plugin's manifest.xml file, use the settingsForm entry key. This example shows a simple form that includes help text for fields, and a default value for one field:

<entry key="settingsForm">
        <value>
          <Form name="ToDo Plugin Settings">
            <Attributes>
              <Map>
                <entry key="pageTitle" value="ToDo Plugin Configuration"/>
                <entry key="title" value="ToDo Plugin Configuration"/>
              </Map>
            </Attributes>
            <Description>Example form to display plugin settings</Description>
            <Section name="Configuration">
              <Field displayName="Delete Allowed" helpKey="Indicates whether or not todos can be deleted" name="canDelete" type="boolean"/>
              <Field displayName="Default Name" helpKey="The default name for a todo" name="defaultName" type="string" value="My Todo"/>
              <Field displayName="Default Time" helpKey="The default time in minutes for a todo" name="defaultTime" type="int">
                <DefaultValue>
                  <Integer>30</Integer>
                </DefaultValue>
              </Field>
              <Field displayName="Max Active Todos" helpKey="The maximum number of active todos a user is allowed to have before being flagged" name="maxUntilFlagged" required="true" type="int">
                <DefaultValue>
                  <Integer>10</Integer>
                </DefaultValue>
              </Field>
            </Section>
          </Form>
        </value>
      </entry>

 

For more information about using forms in IdentityIQ generally, see Forms 7.0+

 

Referencing custom javaScript forms in plugins

To reference a custom JavaScript form in your plugin:

  • In the plugin's manifest.xml file, use the settingsPage entry key to reference the name of the XHTML file that contains the HTML and any JavaScript for your plugin settings page - for example:
    <entry key="settingsPage" value="myPluginConfigForm.xhtml"/>
  • When packaging your plugin, place the settings XHTML page (that is, the page you reference in the settingsPage entry key) in the plugin's /ui folder.

 

Leveraging plugin classes

Enhancement to plugin functionality in IdentityIQ version 8.0 allow IdentityIQ scripts to access the classes defined in an installed IdentityIQ plugin. Classes contained in a plugin can be leveraged from any area or feature of IdentityIQ where BeanShell can be used, such as rules, workflow steps, and scriptlets.

 

Packaging plugin classes

BeanShell scripting invocations can use all Java classes (from all plugins) that are declared as exported for "scripting". These are declared in the plugin's manifest.xml file. The Java package name is specified under <String> in the <scriptPackages> element; for example:

 

<entry key="scriptPackages">
        <value>
          <List>
            <String>com.acme.todo.util</String>
          </List>
        </value>
      </entry>

 

 

The placement of classes in the plugin zip file is important. Classes are packaged in a jar that must be placed in the plugin's /lib directory. You can also put 3rd party jars in the /lib directory if you are using them.

 

Referencing plugin classes in BeanShell

Here is a simple example of BeanShell code that references a plugin class. The <Source> tag in this example is the element for the script embedded within the Rule XML object. If you use IdentityIQ's rule editor to create or edit your rule, you would omit the <Source> tag.

 

<Source>
     import com.acme.todo.util.TodoUtil;
     long now = TodoUtil.now();
     return "Hello World at " + now;
</Source>

 

New IIQ console commands for plugin class support

There are additions to the plugin command that is invoked from the iiq console. These new command help troubleshoot problems when accessing plugin classes from scripts.

 

  • The command plugin classes will show you the list of all the classes from all plugins which are available currently for scripting and executors.

> plugin classes  
Class                                                Usage          Plugin                      
==================================================   =============  =========================== 
com.acme.todo.util.TodoQuery                         Scripting      TodoPlugin 
com.acme.todo.util.TodoUtil                          Scripting      TodoPlugin 
com.acme.class.util.ClassUtil                        Scripting      ClassPlugin 
com.acme.todo.server.TodoFlaggingService             Service        TodoPlugin 
com.acme.todo.policy.TodoPolicyExecutor              Policy         TodoPlugin 

 

  • The command plugin classes <plugin_name> will show you the list of all the classes from the specified plugin which are available currently for scripting and executors

 

> plugin classes ClassPlugin  
Class                                                Usage          Plugin                      
==================================================   =============  =========================== 
com.acme.class.util.ClassUtil                        Scripting      ClassPlugin 

 

  • The command plugin list will list all of the installed plugins, including the plugin name, version, and if enabled/disabled.

 

> plugin list  
Name                                       Version   Status   
========================================   ========  ======== 
TodoPlugin                                      4.0  Enabled  
ClassPlugin                                     1.0  Enabled  

 

Plugin class script blocking

A new plugin mechanism can block IdentityIQ scripts from accessing classes from plugins. This "Prohibit Scripting" mechanism dynamically enables/disables the ability for scripts to load classes from plugins.

 

This mechanism can be set either via a configuration key, or via the UI.

 

To enable or prohibit scripting access via a configuration key, use the new SystemConfiguration key called pluginProhibitScripting. This is set in the Debug page:

  1. In the Debug Page, choose SystemConfiguration from the Configuration Objects drop-down.


  2. Find the pluginProhibitScripting key and set it to true to prohibit scripts from accessing plugin classes, or to false to allow scripts to access plugin scripts.

<entry key="pluginProhibitScripting" value="false"/>

 

To enable or prohibit scripting access to plugin classes via the UI:

  1. Navigate to the gear menu > Global Settings > IdentityIQ Configuration > Miscellaneous tab
  2. In the Plugin Settings area of the Miscellaneous tab, use the checkbox to enable or disable script access to plugin classes.

Declaring executors in plugins

IdentityIQ plugins support executors, which let you extend or add new policies, tasks, or services to IdentityIQ via a plugin. In earlier versions of IdentityIQ, plugins could optionally declare Service executors. In IdentityIQ version 8.0, there are some changes:

  • Two new declaration types, Task and Policy, have been added.
  • Declaring executors is now required for plugins developed against IdentityIQ 8.0
  • To ensure compatibility with older plugins, IdentityIQ 8.0 offers a configuration setting that lets you "relax" the declaration requirement, so that the declaration requirement won't cause your legacy plugins to fail. This is done in IdentityIQ's global settings, under the gear menu > Global Settings > IdentityIQ Configuration > Miscellaneous tab, in the Plugin Settings area:

 

Declarations are specified in the plugin's manifest.xml file - for example:

 

      <entry key="serviceExecutors">
        <value>
          <List>
            <String>com.acme.todo.server.TodoFlaggingService</String>
          </List>
        </value>
      </entry>
      <entry key="policyExecutors">
        <value>
          <List>
            <String>com.acme.todo.policy.TodoPolicyExecutor</String>
          </List>
        </value>
      </entry>
      <entry key="taskExecutors">
        <value>
          <List>
            <String>com.acme.todo.task.TodoTaskExecutor</String>
          </List>
        </value>
      </entry>

 

Plugin version number requirements

Refer to the IdentityIQ 8.0 Release Notes section on Upgrade Considerations for important information on new requirements for the plugin version number format.

 

For more information

Plugin Center

Labels (2)
Comments

where is the zip file described in the article?

 

@kristoffer_lock_tolbo I recommend visiting the IdentityIQ 8.0 overview: What's New in IdentityIQ 8.0 for more resources and files. I believe you will find the zip file that you are looking for there. Let us know if you have any more questions! 

Thank you for your great work. It really helpful.

In regards to leveraging plugin classes, there still seems to be a restriction if you try to reference a plugin class from a context which was initiated by the plugin the class resides in. For example:

  1. UI action makes rest call to IIQ which launches a workflow in context using workflower.launch
  2. Workflow launched in this context references a rule library which imports on the the scriptPackages classes defined in manifest
  3. Workflow step makes method call to rule library with the imported class referenced from above
  4. Class not found in namespace error is thrown

 

I do not see this when scheduling a workflow, which launches in a different context, nor do I see it when I reference the class from rules workflows outside of plugin context.

Im seeing the same issue when  using references a rule library as well from a workflow.  the class is not found.  any updates ? 

I have a plugin containing 1 package in the <scriptPackages> list, but no classes are visible when I issue the "plugin classes" command in the console.  This really shouldn't be that difficult, but I must be doing something wrong.

Can you provide an actual working example, complete with the manifest.xml file for a plugin containing a class that can be referenced by BeanShell code?  Thank you!

When we uninstall a plugin,  Is there any way to delete the xml that get imported during plugin installation. So I want to get all xml objects get deleted when plugin get uninstalled. Is it possible?

Apologies if I have asked, but is there documentation on how to create / use a custom JavaScript xhtml for a settings page for the plug-in?

Thanks in advance,

-Joseph 

@ccerghe1 I know this post is old but I ran into the same problem, where the plugin would install but the plugin classes result was empty.  In my case the problem was a mismatched version of javac being referenced in my build.xml file.  Once I corrected it to match the version on the server it worked.

Version history
Revision #:
6 of 6
Last update:
‎Mar 17, 2023 07:44 PM
Updated by: