IIQ Plugin Project Generator

The IIQ Plugin Project Generator is an NPM tool designed to streamline the setup of project structures for developing IdentityIQ (IIQ) plugins. It automates the creation of plugin projects and modules with customizable options and templates.

Features

• Generate Plugins: Quickly scaffold new plugin projects.
• Generate Plugin Modules: Create reusable npm packages tailored for IIQ plugins.
• Bundled-in Plugin Examples: Includes pre-defined templates, that can build and upload the plugin immediately project generation. The templates are:
  • DOM Customization: Demonstrates how to customize the IdentityIQ UI by adding a custom message to the 'Identity View' page.
  • Widget: A template that illustrates how to create a custom homepage widget in IdentityIQ.
  • Custom Page: Shows how to build custom pages in IdentityIQ, featuring a snake game powered by the p5.js library. (Why a game? Because plugins can be whatever you want!)
• NPM, TypeScript and SCSS Support: The generated projects include NPM, TypeScript and SCSS support for frontend development.
• Customizable Options: Easily specify details such as version, package name, and plugin description during project generation.
• Modularized Project Structure: The generated projects are divided into four IntelliJ modules for organized development:
  • Backend: Contains the Java code for the plugin.
  • Frontend: Contains the TypeScript, SCSS and HTML code for UI development.
  • Latex: Contains the LaTeX files for documentation.
  • Resources: Contains the plugins manifest and other IIQ XML resources (e.g. Capabilities).
• IntelliJ IDEA Support: The generated project is designed for IntelliJ IDEA with predefined UI scopes for each module, making it easy to navigate the project.
• Gradle Support: Includes Gradle build scripts for easy project management and building.
• Automatic Upload: Automatically upload the plugin to your IdentityIQ instance directly from the command line or with the IntelliJ "Run" function.
• Pre-defined Gitlab CI/CD Pipeline: The project includes a pre-defined Gitlab CI/CD pipeline for building and publishing.

Prerequisites

• Node.js: Ensure Node.js is installed.
  • Tested with node v23.7.0. It is confirmed, that the node v20.x will not work.
• NPM: Comes with Node.js.
• IntelliJ IDEA: Required to open the generated project automatically.

TL;DR

1. Install the package globally:

   npm install -g @ventum-digital/iiq-plugin-project-generator

2. Generate a plugin project:

    generate-plugin -n <pluginName> -l <pluginDisplayName> -i <iiqVersion> -m <minSystemVersion> -p <packageName> [-d <pluginDescription>] [-x <maxSystemVersion>]

3. Read the First time opening the plugin project section to set up the project in IntelliJ IDEA.

Installation

To install the package globally from npm, run the following command:

npm install -g @ventum-digital/iiq-plugin-project-generator

Commands

Generate a Plugin

To scaffold a new plugin project, run:

generate-plugin -n <pluginName> -l <pluginDisplayName> -i <iiqVersion> -m <minSystemVersion> -p <packageName> [-d <pluginDescription>] [-x <maxSystemVersion>]

Example:

generate-plugin --packageName custom-page-test --version 0.1.0 --iiqVersion 8.3 --pluginName CustomPageTest --pluginDisplayName "Custom Page Test" --minSystemVersion 8.0

Generate a Plugin Module

To create a new npm package to use with plugins, run:

generate-plugin-module -p <packageName> -s <npmScope> -v <version> [-d <packageDescription>] [-a <author>]

Example:

generate-plugin-module -p utility-functions -s ventum -v 1.0.0 -d "A sample module." -a "John Doe"

Command Line Options

Plugin Generation

| Option | Alias | Description | |-----------------------|-------|-------------------------------------------------| | --version | -v | Specify the plugin version. | | --iiqVersion | -i | Specify the target IIQ version. | | --pluginName | -n | Name of the plugin (lowercase, no spaces). | | --pluginDisplayName | -l | Display name for the plugin. | | --minSystemVersion | -m | Minimum system version required. | | --packageName | -p | Package name for the plugin (folder name). | | --pluginDescription | -d | Description of the plugin (optional). | | --maxSystemVersion | -x | Maximum supported system version (optional). | | --template | -t | Plugin template to use (optional). | | --author | -a | Author of the plugin (optional, used in Latex). | | --companyName | -c | Company name (optional, used in Latex). | | --supportMail | -m | Support email (optional, used in Latex). | | --javaVersion | -j | Java version (optional, defaults to 11). |

Plugin Module Generation

| Option | Alias | Description | |------------------------|-------|---------------------------------------| | --npmScope | -s | Scope for the NPM package. | | --packageName | -p | Package name for the module. | | --version | -v | Module version. | | --packageDescription | -d | Description of the module (optional). | | --author | -a | Author of the module (optional). |

First time opening the plugin project

JDK

When you first open the generated project in IntelliJ IDEA, you may need to configure the project SDK. Follow these steps:

1. Open the project in IntelliJ IDEA.
2. Go to File > Project Structure.
3. Select Project from the left sidebar.
4. Set the Project SDK to the appropriate version of Java (e.g., Java 11).

Gradle

When you first open the generated project in IntelliJ IDEA, you may need to sync the Gradle project. Follow these steps:

1. Open the project in IntelliJ IDEA.
2. Right click build.gradle file in the project explorer.
3. Select Link Gradle Project.
   

SailPoint IdentityIQ JARs (Important!)

To build the plugin, SailPoint IdentityIQ JARs need to be available to gradle.

Unfortunately, these JARs are not included in the project due to licensing restrictions and I cannot publish them to a public mvn repository myself. I have contacted SailPoint about the possibility of an official mvn repo and I will update this package to use it, if it happens.

For now, you will need to obtain them separately and:

1. You can place them in the libs directory of the project.
2. You can upload the JARs to a Maven repository and configure the build.gradle file to use that repository.

You can find the required commented out code in the sources/backend/build.gradle file, under the repositories section. Uncomment the relevant lines and adjust the paths to point to your local JARs or Maven repository.

(Optional) Automatic Plugin Upload

To allow for automatic upload of the plugin to the IdentityIQ instance, you need to set up the iiqUrl and iiq_base64Credentials properties in the gradle.properties file.

1. Open the gradle.properties file in the root of the project. If it doesn't exist, create it.

2. Add iiqUrl, iiqClientId and iiqClientSecret properties with the appropriate values:

   • iiqUrl: The URL of your IdentityIQ instance (e.g., http://localhost:8080/identityiq).
   • iiqClientId: Client ID for API authentication.
   • iiqClientSecret: Client Secret for API authentication

   Consult the step below on how to obtain these credentials.

3. Save the gradle.properties file. It should look something like this:

   iiqUrl=http://localhost:8080/identityiq
   iiqClientId=MYgjmYn1VZuFtvFfD55rqjmohWqve0MJ
   iiqClientSecret=pqy0BMMuChrddR9V

Getting the Client ID and Secret

1. Log in to your IdentityIQ instance.
2. Navigate to Global Settings > API Authentication.
3. Click on Create
4. Give it a name (e.g., IIQ Plugin Project Generator), select the proxy user (e.g., spadmin in your local environment) and click on Save.
5. You can now copy the Client ID and Client Secret from the created API client.

Build Targets

To build the plugin, do the following:

1. Open the project in IntelliJ IDEA.
2. Open the Gradle tool window (usually on the right side).
3. Navigate to Tasks > ventum plugin
4. Double-click on one of the build tasks to build the plugin.

Build tasks

| Task Name | Description | |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | packageClean | Builds the plugin ZIP file. This is the production config, that will also minify and obfuscate JS files. | | packageDevClean | Builds the plugin ZIP file in debug mode. The plugin version is saved under dev/dev.properties and incremented with each build. This is useful for development and testing. | | buildAndUploadPlugin | Builds the plugin (using packageDevClean) and uploads it to the IIQ instance. This task requires the iiqUrl, iiqClientId and iiqClientSecret properties to be set in the gradle.properties file. |

Output

The output of the build tasks will be located in the build directory of the project. The generated ZIP file can be uploaded to the IdentityIQ instance.

Author

Adam Mazurkiewicz-Madej ([email protected])