@ventum-digital/iiq-plugin-project-generator
Version:
A npm tool to set-up the project structure for developing an IIQ Plugin.
241 lines (178 loc) • 11.7 kB
Markdown
  
# 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:
```bash
npm install -g @ventum-digital/iiq-plugin-project-generator
```
2. Generate a plugin project:
```bash
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](#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:
```bash
npm install -g @ventum-digital/iiq-plugin-project-generator
```
---
## Commands
### Generate a Plugin
To scaffold a new plugin project, run:
```bash
generate-plugin -n <pluginName> -l <pluginDisplayName> -i <iiqVersion> -m <minSystemVersion> -p <packageName> [-d <pluginDescription>] [-x <maxSystemVersion>]
```
#### Example:
```bash
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:
```bash
generate-plugin-module -p <packageName> -s <npmScope> -v <version> [-d <packageDescription>] [-a <author>]
```
#### Example:
```bash
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](#Getting-the-Client-ID-and-Secret) on how to obtain these credentials.
3. Save the `gradle.properties` file. It should look something like this:
```properties
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** ([adam.mazurkiewicz@ventum.com](mailto:adam.mazurkiewicz@ventum.com))