Developing and deploying extensions for i2 Analyze

i2 Analyze Developer Essentials contains tools, libraries, and examples that enable development and deployment of custom extensions to i2 Analyze. The following information describes how you can use the config development environment to quickly deploy an extension for a config to test and develop.
For more information about the types of extension that are available, see i2 Analyze Developer Essentials.

If your extension is already built (.jar file), then create a folder with the same name as your jar file inside i2a-extensions directory. For example, if your .jar file is called opal-security.jar then place it inside i2a-extensions/opal-security directory. Afterwards, follow the instructions in Adding extensions to a config section.

Important: Do not modify the root pom.xml file within the i2a-extensions directory. When creating a project for your extension, a separate pom.xml is created to update with information about the extension.

Creating a project for your extension

You must create a Maven artifact to develop your extension in.

Copy the template templates/extension-development directory to the i2a-extensions directory and rename it to be the name of your extension. This name is also the artifact id. For example, name the directory opal-default-security-example. The directory structure is:
```
- i2a-extensions
    - <artifact_id>
        - src
            - main
                - java
            - test
                - java
        - pom.xml
```
Update the pom.xml file inside your new directory with information about your extension. The elements to modify are at the root of the file.
Update the values of the following elements:
- <groupId> is the name of the Java package
- <artifactId> matches the name of the directory for your extension
- <version> is the version number for your extension
  
  For example:
```
  <groupId>com.i2group</groupId>
  <artifactId>opal-default-security-example</artifactId>
  <version>1.0.0</version>
```
Run manage-environment -t extensions command to install the necessary dependencies. Note: If you can't see your new extension in the Java Projects explorer, press F1 (or Cmd+Shift+P in MacOS), type Java: Import Java Projects into Workspace and select it. It might take a minute before refreshing.

You can now start developing your extension. For examples on i2 Analyze extensions, check the examples in i2 Analyze Developer Essentials.

Copy the contents of src/main folder of the extension into the i2a-extensions/<artifact_id>/src/main directory.
Add any settings that are required by the extension to the analyze-settings.properties file.
Add any resources that are required by the extension to the /configs/<config_name>/configuration directory. For example, the group-based-default-security-dimension-values.xml file.

If your extension depends on external dependencies you need to add them to your project. To do this, open the JAVA PROJECTS tab view and expand your extension. Mouse-over the Maven Dependencies section and click '+'. Search for your dependency in the search bar at the top of the VS Code window. When you select your dependency, it is added to the pom.xml file for your extension. For information on how to add external dependencies from Maven Central, check Add a Maven dependency.

For example, the liberty-apis are published to Maven central. You can add these using the method mentioned previously, or by copying the following section into the pom.xml file.

  <dependency>
    <groupId>net.wasdev.maven.tools.targets</groupId>
    <artifactId>liberty-apis</artifactId>
    <version>LATEST</version>
    <type>pom</type>
  </dependency>

If your extension depends on other extensions (not in Maven Central), you must add them to your pom.xml file manually under the comment: .

For example, the auditing extensions in Developer Essentials depend on the opal-audit-example-common extension. To add it as a dependency, populate the values of the pom.xml file as follows:

  <!-- Extension specific dependencies -->
  <dependency>
      <groupId>com.i2group</groupId>
      <artifactId>opal-audit-example-common</artifactId>
      <version>1.0.0</version>
  </dependency>

You will also need to populate the i2a-extensions/extension-dependencies.json file with the extensions that you depend on, for example:

[
  {
    "name": "opal-audit-file-example",
    "dependencies": [
      "opal-audit-example-common"
    ]
  }
]

Adding extensions to a config

In the configuration you want to deploy your extension with, update the /configs/<config_name>/configuration/extension-references.json file and add the directory name for your extension in the extensions array.
For example, to add the extension in i2a-extensions/opal-default-security-example the extension-references.json file contains the following extensions array:
```
{
    "extensions": [
        {
            "name": "opal-default-security-example",
            "version": "1.0.0"
        }
    ]
}
```

Note: The extensions in the extension-references.json file are loaded in order. If an extension depends on another extension, define the dependent extension first.

Deploying your extension

Use the deploy command to build and deploy the extensions declared in extension-references.json for your configuration:

deploy

If you have multiple configs, specify the config name with -c <config-name>.

Debugging your extension

Deploying in debug mode

To deploy with the Liberty server running in debug mode, change the local variable LIBERTY_DEBUG to "true". To do this, create a docker.env file in the analyze-deployment-tooling directory. In the file, add the following line:

LIBERTY_DEBUG="true"

Then deploy from a clean environment by using deploy -c <config-name> -t clean followed by deploy-c <config-name>.

When the Liberty server starts, it waits for a debugger to be attached before continuing. This behavior is defined by the WLP_DEBUG_SUSPEND variable and can also be changed in the docker.env file. Note: The Liberty server will open and expose a unique debug port (7777) and wait for a debugger.

Attaching a debugger

The project is shipped with a default launch configuration which can be changed in .vscode/launch.json. Run the Java debugger by pressing F5 and choose Debug Extensions if asked.

Removing an extension

To remove an extension from a configuration, remove the extension from the extensions array within the extension-references.json file.

If you have additional .properties files that have been created for the extension in the configs/<config_name>/configuration directory, these will need to be removed as well.

Run the deploy command to remove the extension from the configuration.