![npm (scoped)](https://img.shields.io/npm/v/@ventum-digital/iiq-plugin-project-generator?label=NPM) ![NPM](https://img.shields.io/npm/l/@ventum-digital/iiq-plugin-project-generator?label=License) ![npm](https://img.shields.io/npm/dt/@ventum-digital/iiq-plugin-project-generator?label=Downloads) # 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 -l -i -m -p [-d ] [-x ] ``` 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 -l -i -m -p [-d ] [-x ] ``` #### 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 -s -v [-d ] [-a ] ``` #### 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). ![Project SDK](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/setup-jdk.png) ### 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`. ![Link Gradle Project](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/link-gradle.png) ### 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. ![Gradle Repositories](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/repositories_gradle.png) ### *(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`. ![API Authentication](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/api-config.png) 3. Click on `Create` ![API Authentication Click](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/api-config-click.png) 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`. ![API Authentication Create](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/api-config-create.png) 5. You can now copy the `Client ID` and `Client Secret` from the created API client. ![API Authentication Save](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/api-config-save.png) --- ## 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. ![Gradle Build Task](https://git.ventum.com/sailpoint-plugins/archetype-2.0/-/raw/master/readme-img/gradle-tasks.png) ### 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))