- Overview
- Prerequisites
- Repository cloned
- IIQDA installed, Eclipse installed
- SSB assumed
- Java version
- Examples
- Existing, established Eclipse project with IIQDA
- Existing, established Eclipse project without IIQDA
- No established Eclipse project
- Source control tips for Eclipse project files
- Extra credit - XML catalog element
Overview
This document guides the reader through creating a fresh IdentityIQ project with Eclipse, the Services Standard Build (SSB), and IdentityIQ Deployment Accelerator (IIQDA). This setup enables the IdentityIQ project to be built and deployed (via SSB or IIQDA or both), while also preparing the same for inclusion in a source code repository.
Prerequisites
Repository cloned
Each of the examples below assume you have cloned the repository to a location that makes sense for your developer tools. Keep track of this location, as you'll be headed back to work from it frequently enough for commits and other ad-hoc work outside of Eclipse.
IIQDA installed, Eclipse installed
Each walkthrough assumes you have Eclipse installed and the IIQDA plugin installed.
These examples use Eclipse Neon + IIQDA 3.0.1 (20170227-1747).
SSB assumed
It is assumed SSB is also at work here. You will see references to SSB build commands to make IIQDA work properly in this walkthrough.
Java version
The example files here assume the Oracle JVM 1.8 is used.
Examples
Below are a few examples, each with a different starting point to cover the most common use cases.
Existing, established Eclipse project with IIQDA
This walkthrough assumes you have a valid .project file in your repository and that IIQDA nature has already been added to it.
See examples below if you need to verify.
- In the workspace for Eclipse:
- File > Import
- Choose "projects from git"
- Choose "existing local repository"
- Click "add..." button to add your local repository (top level of cloned folder structure)
- Select your newly added repo and move on
- Choose "import existing eclipse projects" option and hit "finish"
- Your project should show in the workspace now
- Note it has NOT been moved on disk to the workspace and the files you work on "sit" in the cloned repo location - this is a good feature, as it promotes flexibility
- However, you should realize where your edited files exist at all times (as you'll need to know to check them into source control)
- You should see the IIQDA functionality is present, as is the little "IIQ" icon on the project folder
Existing, established Eclipse project without IIQDA
This walkthrough assumes you have a valid .project file in your repository and that IIQDA nature has NOT already been added to it.
See examples below if you need to verify.
- Go to the cloned repo location and edit the
.projectfile to include both the IIQDA nature andbuildCommand(see example of working.projectfile below), then save changes - Go to the cloned repo location and edit the
.classpathfile to look like the example in this article, then save changes - In the workspace for Eclipse:
- File > Import
- Choose "projects from git"
- Choose "existing local repository"
- Click "add..." button to add your local repository (top level of cloned folder structure)
- Select your newly added repo and move on
- Choose "import existing eclipse projects" option and hit "finish"
- Your project should show in the workspace now
- Note it has NOT been moved on disk to the workspace and the files you work on still remain in the cloned repo location - this is a good feature, as it promotes flexibility. However, you should realize where your edited files exist at all times (as you'll need to know to check them into source control).
- You should see the IIQDA functionality is present, as is the little "IIQ" icon on the project folder
- Note you should run a
build mainwith the SSB to create theidentityiq.jarandcommons-logging-1.1.3.jarrequired for full IIQDA functionality- The
.classpathexample shown below utilizes a relative project path (which is portable but requires at least 1 build first to make it available)
- The
No established Eclipse project
This example assumes you do NOT have a valid .project file in your repository. This might be because you have a brand new repo or the repo has been under source control without a .project file (i.e. someone didn't check that file in for some reason or others used another IDE or editor previously that did not use .project, as that is Eclipse-specific).
- In the workspace for Eclipse
- File > Import
- Choose "projects from git"
- Choose "existing local repository"
- Click "add..." button to add your local repository (top level of cloned folder structure)
- Select your newly added repo and move on
- Choose "import as general project" option and hit "finish"
- This does not give us Java or IIQDA functionality, but it creates a valid
.project&.classpathfile set for you to edit later
- This does not give us Java or IIQDA functionality, but it creates a valid
- Your project should show in the workspace now
- Note it has NOT been moved on disk to the workspace and the files you work on remain in the cloned repo location - this is a good feature, as it promotes flexibility. However, you should realize where your edited files exist at all times (as you'll need to know to check them into source control)
- While your new project will show in Eclipse, but is generic - right-click it and select "properties" from the context menu
- In left pane, select "project facets" item, then in right pane click link to "convert to faceted form"
- This will then show "project facets" like:
- Only "Java" will be checked
- The "Configuration" drop down will say "<custom>"
- The above two are what you want - hit "apply" and "ok" to close the dialog
- Close the eclipse project in the workspace
- Right-click > close project
- Go to the cloned repo location and edit the
.projectfile to include the IIQDA nature & buildCommand (see example of working.projectfile below) - save changes - Go to the cloned repo location and edit the
.classpathfile to look like the example in this article - save changes - In Eclipse, double-click your closed project to re-open it
- You should now see the IIQDA functionality is present, as is the little "IIQ" icon on the project folder
- Note you should run a
build mainwith the SSB to create theidentityiq.jarandcommons-logging-1.1.3.jarrequired for full IIQDA functionality- The
.classpathexample shown below utilizes a relative project path (which is portable but requires at least 1 build first to make it available)
- The
Source control tips for Eclipse project files
In the absence of any specific team guidelines, consider that putting .project and .classpath files for Eclipse in source control means saved time - as no one else has to learn and work with a "raw" file set w/o any Eclipse functionality. The first developer establishes the IIQDA and Eclipse project file set and all other developers can simply import an established Eclipse project into their workspace.
Thus, the general recommendation is to put .project and .classpath into source control (as everyone editing the project should be using the same configuration, Eclipse version, etc.).
Here are examples of each file for a working example of a faceted Eclipse project with Java + IIQDA (.project file + .classpath file).
Example .project file:
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>IdentityIQ</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>sailpoint.IIQ_Deployment_Accelerator.IdentityIQ.iiqArtifactBuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>sailpoint.IIQ_Deployment_Accelerator.IdentityIQ.iiqNature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
</natures>
</projectDescription>
Example .classpath file:
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="servicestools"/>
<classpathentry kind="src" path="src"/>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8">
<attributes>
<attribute name="owner.project.facets" value="java"/>
</attributes>
</classpathentry>
<classpathentry kind="output" path="bin"/>
<!--
added for supporting iiqda - note the "build/extract" location won't be present until a "build main" is run with SSB
-->
<classpathentry kind="lib" path="build/extract/WEB-INF/lib/identityiq.jar">
<attributes>
<attribute name="javadoc_location" value="build/extract/doc/javadoc/"/>
</attributes>
</classpathentry>
<classpathentry kind="lib" path="build/extract/WEB-INF/lib/commons-logging-1.1.3.jar"/>
</classpath>
Extra credit - XML catalog element
You can add XML DTD assistance when editing XML artifacts. This is similar to code completion we are used to with Java files in IDEs, but for XML documents.
The DTD validates and guides with respect to format of elements and attributes.
Note that it will not provide assistance with specific key names or values for entries in sailpoint.object.Attributes (as those are not in the DTD), but it will help in many other ways (like overall structure and permitted nesting of elements and attributes).
This DTD adjustment generally done is per-user for Eclipse. It can be project-specific, but such settings will likely not be in source control (nor should they be). Thus, the following steps highlight this change from an Eclipse-wide perspective. You need an established Eclipse project and you should run the SSB build main target at least once, as this creates the DTD in the build/extract area (which we refer to next).
Start in Eclipse -> Window menu -> Preferences and then:
- In left pane: XML > XML Catalog
- In right pane, click "add..." button - in new dialog that appears:
- "catalog entry" tab/button should be selected on the left
- Location - click "workspace" and browse to your project's build/extract location - you will see the
sailpoint.dtdDTD file there with a version number on it - select it - Key type =
public id - Key =
sailpoint.dtd - Click OK and OK again to save it
- In right pane, click "add..." button - in new dialog that appears:
Note the "key" we mentioned should look familiar - e.g. <!DOCTYPE Application PUBLIC "sailpoint.dtd" "sailpoint.dtd">.
Now open an XML artifact - a CTRL + Space (on PC) brings up code/markup assist features. A sample screenshot below shows this feature with a workflow XML document.
