Services Standard Build User Guide: SSB v6.1, May 2019
Services Standard Build User Guide: SSB v6.1, May 2019
Services Standard Build User Guide: SSB v6.1, May 2019
This document is intended to be a user-friendly guide explaining how to set-up the Services Standard
Build, as well as its applications.
Document Revision History
Revision Written/Edited By Comments
Date
February Blake Bowen Initial Creation (Current IdentityIQ version: 6.0)
2013
March 2013 Tina Timmerman 1st Revision
April 2013 Brendon Jones 2nd Revision
June 2013 Blake Bowen Final Revision for SSB 1.2, posted to Compass
August 2013 Blake Bowen Updated Compass links to new Compass
January 2015 Blake Bowen Updated with version 1.5 features, new Compass links,
and further clarification.
June 2016 Blake Bowen Updated Compass link to point to SSD get started page
September Paul Wheeler Updated with new features added in v2.
2016
October 2016 Paul Wheeler Minor corrections for revision 2.0.1.
December Paul Wheeler Example custom script file names modified so that they
2016 do not execute unless renamed.
January 2017 Paul Wheeler Support for environment-specific build.properties files
clarified.
February Paul Wheeler Minor restructure and updates for SSB v3 release
2017
June 2017 Justin Choponis, Paul Formatting and structure changes. Updates for SSB v4
Wheeler release
December Paul Wheeler Added plugin build information for SSB v5, added
2017 Deprecation Scanner in the Build Checks.
July 2018 Paul Wheeler Added functionality for subset builds, IdentityIQ
keystore file deployment and “secret” target.properties
files for SSB v6. Expansion of efixes in timestamp
order. Additional Build Check for Workflow trace
setting. Added information on the Dependency Check
utility.
May 2019 Paul Wheeler Added functionality for deploying the Accelerator Pack
with the SSB. Changes for support of Log4j2 in
IdentityIQ 8.0. Minor changes to Plugin Deployer and
Dependency Checker.
SSB Components
SSB scripts (build.xml, scripts/build.dev.xml, etc.) utilize Apache Ant 1.8.2, along with ant-
contrib 1.0b3 and catalina-ant (for Tomcat 7.x).
Apache Ant
This is the main build tool using XML documents as build instructions. You don’t have to do anything
special to start using Ant when using the SSB – it’s bundled right along with the other SSB artifacts (in
the lib/ant folder)!
See the project page at: https://ant.apache.org/. There is a user guide for 1.9.x and 1.10.x – these are
largely the same content that applies to the 1.8.x version used in SSB.
Ant Contrib
This has extensions for Ant and custom Ant tasks (like <if><then> blocks).
See the project page for more information: https://sourceforge.net/projects/ant-contrib/files/ant-contrib/.
Folder Structure
This is the high-level folder structure of the build. The top-level directories should not be modified,
though objects will be placed into these folders, either directly or in subfolders, to be used in the build
process.
• base - Contains binaries distributed by SailPoint. You can download these from Compass.
o ga - Contains the SailPoint GA release binary. You can have as many GA release binaries
as you want to build against, and the appropriate one will be selected using the values
you set in the build.properties file.
Example: /base/ga/identityiq-7.3.zip
o patch - Contains the SailPoint patch binaries. You can have as many patch binaries as
you want to build against, and the appropriate patch will be selected using the values you
set in the build.properties file.
Example: /base/patch/identityiq-7.3p2.jar
o efix - Contains any efix archives sorted by directory name where the directory name
follows the naming convention <version><patchlevel>. If there is no patch level it will
• config - Contains all your custom XML configuration objects sorted by folders where each sub
directory is named by the type of top level SailPoint object it holds. In the provided example
Application, Rule, TaskDefinition and TaskSchedule directories are shown. In general, as
you customize more object types, you should add a directory to contain that object. While
writing code, try to make the separation of object types as granular as possible such that it is easy
to view all objects of a particular type. For example, instead of inserting a rule directly into a
TaskDefinition, a reference to that rule should be created and the Rule itself would live in its
own file in the Rule directory. The idea is to separate and encapsulate.
o Note: While we recommend there just be objects in directories named for that object type
(Application, Bundle, etc), there is nothing special about the directory names under the
config directory. All files under config whose names end with a ‘.xml’ suffix will be
transformed through the build and tokenization and prepared for import into
IdentityIQ. Files with other kinds of name extensions (.txt, .old, etc.) under config are
ignored by the build process.
• db - Contains customized database scripts.
• lib - Contains libraries used by the build process. It contains Java code the Ant build scripts use,
but it does not get added to your installation of IdentityIQ. Do not put additional jars here. Put
them in the web/WEB-INF/lib directory.
• scripts - Except for the master build.xml file in the root directory, all other build files are
contained in this directory. Shipped and supported build files are read-only and follow the name
convention build.*.xml. If you customize the build process you must declare your
customizations in build files that follow the naming convention build.custom.*.xml.
o Three example scripts are provided illustrate how to extend the build process with site-
specific custom scripts.
▪ scripts/example.build.custom.Extend-idAttrs.xml (Configure extended
searchable Identity attributes using the ExtendedPropertyAccessor class)
▪ scripts/example.build.custom.Modify-WEB-XML.xml (Example of generic
replacement of text in the web.xml file)
▪ scripts/example.build.custom.modify-web_xml_timeout.xml (Modify the
timeout value in web.xml)
o Custom Ant scripts can inject their own site-specific logic in one of three places:
▪ The clean target, which allows the custom Ant script take whatever actions are
necessary when resetting the builds to a clean or blank state.
Copy the ExportScript.txt from the <SSB install directory> directory you unzipped earlier.
Paste this text file into the WEB-INF\bin folder of your IdentityIQ installation directory. Also, create a
folder called exports in the WEB-INF\bin folder.
Navigate back to the WEB-INF\bin folder within your IdentityIQ installation directory from a command
prompt. Launch the console by entering the command iiq console.
When you see the > prompt, enter the command source ExportScript.txt. This will run the export
script and export all your environment’s configuration objects into the exports folder you just created.
Place each xml object into its respective class folder. The recommended naming convention for each of
these object files is ObjectType-Name.xml. For example, CurrentApplicationExported.xml would
be split into Application-ActiveDirectory.xml and Application-PeopleSoft.xml, etc.
Copy the zip file for the IdentityIQ version you are using into the <SSB install directory>\base\ga
folder. Zip files can be downloaded from Compass if needed. NOTE: Multiple IdentityIQ zip files can
coexist in this directory; a variable in the build.properties file for each environment determines
which .zip file the build process will use.
If you are running a patched version of IdentityIQ, place the patch .jar file for your installation into the
<SSB install directory>\base\patch folder. Again, multiple patch jar files can coexist in this
directory and the build.properties file specifies which to use in the build (with the IIQPatchLevel
variable). All patch .jar files can be downloaded from Compass as well.
If you have any efixes for your current patch, be certain to copy those to an appropriate efix directory
and remember to check them into your revision control system if you are using one on your project.
Plugins
The SailPoint Plugin Framework is an extension framework model for IdentityIQ which enables third
parties to develop rich application and service-level enhancements to the core SailPoint platform. For
supported versions of IdentityIQ (7.1 and higher), plugins may be added to the build so that they will be
built and/or automatically installed or uninstalled.
Build/Compilation of Plugins
The SSB build process can build and compile plugins automatically from the plugin source code. This
requires that the plugins are placed under the pluginsrc folder at the root of the SSB, under a subfolder
named for each plugin. In addition, the components of the plugin must be located in specific subfolders
as shown in the table below.
Subfolder Description
pluginsrc/<PluginName>/db Contains the database scripts for the plugin (within
install, uninstall and upgrade subfolders)
pluginsrc/<PluginName>/import Contains the XML artifacts to be imported
For more information on each of these components, please refer to the Plugin Developer Guide for
IdentityIQ at https://community.sailpoint.com/docs/DOC-7562.
Plugins configured correctly under the pluginsrc folder will be built and compiled by the SSB. When
building plugins with the SSB there is no need for the separate build.xml or build.properties files
described in the Developer Guide.
Plugins will be built to the build/plugins folder when the main build is executed. The plugin zip file
will be located in the build/plugins/<PluginName>/dist folder. It will also be copied to the WEB-
INF/plugins/ssb/install folder in the IdentityIQ build for automatic deployment (see below).
config/ServiceDefinition/SSB_PluginImporterService.xml
web/WEB-INF/lib/ssb-plugin-importer.jar
In addition, the deployPluginImporter property in the build.properties file must be set to true.
If the plugin is not being compiled as part of the build process (see above) and you already have a plugin
packaged in a zip archive file, you can automatically deploy it by placing the zip file in the correct
location. If the plugin is being compiled by the build process, the zip file will automatically be created
and deployed.
The ServiceDefinition object defines the locations for automatic installation and uninstallation of
plugins in its Attributes map:
<Attributes>
<Map>
<entry key="installpath" value="WEB-INF/plugins/ssb/install"/>
<entry key="uninstallpath" value="WEB-INF/plugins/ssb/uninstall"/>
</Map>
</Attributes>
The installpath entry defines the location where the service will look for plugin archive files to install
when the server starts. The uninstallpath entry defines the location where it will look for plugins to
be removed. In the build, the WEB-INF folder is under the top level web folder. Although the locations
defined in these entries are configurable, they should normally be left as default. If you do change them,
plugins in the pluginsrc folder that are automatically built by the SSB will not be automatically
deployed. Furthermore, the plugins that are supplied with the SSD (such as the Log Level Manager and
Note that in SSD versions prior to 6.1 the install and uninstall locations were
web/plugins/system/SSB/install and web/plugins/system/SSB/uninstall respectively. When
migrating to SSD v6.1 or above you will need to move any plugins you have developed into the new
locations.
JDBC Drivers
A common practice with any IdentityIQ deployment is to update the JDBC driver used specific to your
database management system. This can help to avoid issues with performance and with vulnerabilities
associated with outdated versions of the driver. A guide on Compass outlines this procedure:
https://community.sailpoint.com/docs/DOC-4111.
Note when a JDBC driver is put in the SSB project folder area web/WEB-INF/lib, the developer should
check to remove the out-of-the-box JDBC driver by having the older jar deleted at build. This will
ensure that a deploy includes only the latest JDBC jar specific to your environment.
First, get your updated JDBC driver and place it in the web/WEB-INF/lib area of the SSB project. For
SQL Server, this might be sqljdbc42.jar. Run a build clean main target set and check the
build/extract/WEB-INF/lib folder for legacy jar files for your database system. In this example, that
may be sqljdbc4.jar (the default SQL Server driver that comes with IdentityIQ 7.0). Take note of the
jar file (generally is only one) and adjust the main target in build.xml.
Add a line to the main target (near top of target, there are a few of them already) like this:
<delete file="${build.web-inf.lib}/sqljdbc4.jar"/>
Note that there are also some other variables in the build.properties file that start with deploy, such
as deploySSF, deployGenericImporter and deployObjectExporter. These are only used in the full
SSD to define which of the SSD components and tools should be deployed in the build. In the stand-
alone SSB they are not used.
Supporting multiple platforms (Windows/Linux/Unix) for different environments
If your installation uses different operating systems for different stages of IdentityIQ development – for
example, Windows for sandboxes and Linux for Test and Production servers – you must configure
multiple build.properties files.
The generic build.properties file described above loads the defaults for the build with respect to the
path to Java binaries, IdentityIQ version and other details. These can be overridden on a per-server or
per-environment basis by specifying another properties file with properties that just apply to one server
or one environment. Each server or environment used in development and testing can override the
settings in build.properties by using its own <hostname>.build.properties or
<environment>.build.properties file. For example, if your host is named sailsandbox then the
properties file unique to that server would be called sailsandbox.build.properties. Or if your
environment (SPTARGET) is called dev you could have dev.build.properties. The server or
environment’s properties file has exactly the same format and fields as the build.properties file
described in the previous section and only has to specify the fields that it wants to override with values
that are different from the default build.properties file’s values. If you are running a build on a
server that has its own server-specific version of build.properties for an environment that has its
These can be used to inject credentials when targets using console iiqBeans are employed. This may
involve several targets like: import-custom, import-stock, import-lcm, import-ap, import-all,
importdynamic, deploy, importcycle, etc.
Use the console command iiq encrypt <password> to get the encrypted value of your password to
use here. Alternatively, the console_user and console_pass lines can be removed from
build.properties, which will force the user to enter them each time importdynamic (or a similar
target using import functionality) is run.
Example test.iiq.properties file (yours may differ due to IdentityIQ version changes):
##### iiq.properties #####
#
# (c) Copyright 2008 SailPoint Technologies, Inc., All Rights Reserved.
#
# This file contains configuration settings for IdentityIQ. For your unique
# environment, you will need to adjust the username and password properties on
# the dataSource below and uncomment the applicable database settings.
#
dataSource.username=root
dataSource.password=root
# Uncomment to send all SQL queries to std out. This provides a lot of output
# and slows down execution, so use it wisely.
#sessionFactory.hibernateProperties.hibernate.show_sql=true
Each file is just a list of key/value pairs. The build’s convention is that the keys follow a %%KEYNAME%%
pattern.
For example, you may have an Active Directory application configuration that looks like this:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sailpoint PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<sailpoint>
<Application authoritative="true" connector="sailpoint.connector.ADLDAPConnector"
featuresString="AUTHENTICATE, MANAGER_LOOKUP, SEARCH, UNSTRUCTURED_TARGETS" name="AD"
profileClass="" type="Active Directory">
<Attributes>
<Map>
<entry key="IQServiceHost" value="iqservicehost.example.com"/>
<entry key="IQServicePort" value="5051"/>
<entry key="password" value="2:omj3oouHSFb7dIPItTjNIgBCeZjxP+Vr9TewSXIIbxs="/>
<entry key="managerCorrelationFilter">
<value>
<Filter operation="EQ" property="DN" value="manager"/>
</value>
</entry>
<entry key="user" value="productionADuser"/>
<entry key="groupHierarchyAttribute" value="memberOf"/>
<entry key="authorizationType" value="simple"/>
...
Note that the password has been encrypted using the iiq encrypt utility; you should always do this,
especially if the password values are being stored in a properties or XML file that is part of a build
stored in a location where it may be accessible by users who do not need to know it.
To support deploying the same XML artifact to multiple environments, you would substitute passwords,
ports, etc. with keys that will go in your <environment>.target.properties file, so your application
configuration file instead looks like this:
%%AD_IQSERVICE_HOST%%=iqservicehost.example.com
%%AD_IQSERVICE_PORT%%=5051
Note that if you also have the “updateLog4jLoggers” property set to “true” in build.properties (see
“Configuring the build.properties file” above), the resulting properties file will include the entries in the
environment-specific log4j2.properties or log4j.properties file as well as commented-out
loggers discovered from BeanShell code in XML artifacts or from Java source code in the build.
Configuring deployment of encryption keys for each environment
IdentityIQ can be configured to use site-specific encryption keys for encrypting and decrypting
passwords, and this is considered best practice. This makes use of the IdentityIQ keystore, and with this
feature enabled a password used on one site cannot be decrypted on another site without having the site-
specific encryption keys. It is also recommended to use different encryption keys for each environment.
Information on the keystore and its configuration can be found in the IdentityIQ Administration Guide,
and additional details are available at https://community.sailpoint.com/docs/DOC-2031.
Once the keystore is configured for an IdentityIQ environment, the keystore files are stored in the
following default locations on each server:
WEB-INF/classes/iiq.cfg
WEB-INF/classes/iiq.dat
The SSB can manage deployment of keystore files only if they are stored in the default location. Some
customers place the files in a location external to the IdentityIQ application and reference their location
in the iiq.properties file. This can enhance security by limiting filesystem access to this location to
Note that when both methods are employed, the SPTARGET environment variable “wins”. This is by
design to provide on-the-fly flexibility.
export SPTARGET=dev
./build.sh war
mv identityiq.war identityiq-dev.war
export SPTARGET=test
./build.sh war
mv identityiq.war identityiq-test.war
export SPTARGET=prod
./build.sh war
mv identityiq.war identityiq-prod.war
Replace YOURMACHINENAME with your sandbox hostname, SAILPTAPP with your production hostname,
etc. The build will detect the hostname of the machine on which you are running the build script, and
apply sandbox.target.properties if you are running the build on your sandbox. There can be
multiple hosts pointing to the same target (e.g. if you have 2 prod application servers, you might have 2
hostnames (1 per line) pointing to prod).
Note: The hostnames used in servers.properties are case-sensitive. To get the proper value, you
need to check an environment variable for each host entry. For Windows, use the value exactly as
specified by the COMPUTERNAME environment variable (e.g. echo %COMPUTERNAME%). For
Linux/Unix/Mac, use the value exactly as specified by the HOSTNAME environment variable (e.g. echo
$HOSTNAME).
war:
[war] Building war:
/home/workspace/SSB/build/deploy/identityiq.war
[echo] A MD5 checksum was generated for this war file and
placed in the war file directory. Keep this checksum to diagnose
potential version issues
BUILD SUCCESSFUL
• Deploy this file to the target web application server. You may need to consult your application
server’s deployment guide for details. For Tomcat:
o Copy this custom identityiq.war to a folder under <Tomcat>/webapps
▪ (e.g. <Tomcat>/webapps/identityiq)
o Navigate to that directory and expand the war: jar xvf identityiq.war
o Delete the war file once you have expanded it
If this is a new deployment (and you don’t need to do a repeatable build – if so, see next heading) or if
the build is an upgrade of the IdentityIQ version running on that server, you will need to perform
additional actions to create the IdentityIQ database and tables or upgrade the system; consult the
IdentityIQ Installation Guide for details as needed. Otherwise you are ready to use your customized
IdentityIQ application.
If you wish to update any custom objects and redeploy them to IdentityIQ you can perform the
following steps. Open a terminal or command prompt window,
• Navigate to the <SSB install directory> folder and enter build importdynamic. This
command will import all the custom XML artifacts from your config folder into IdentityIQ. It
will utilize the DB connection from <environment>.iiq.properties and import those XML
objects into the IdentityIQ database. Target importdynamic will not cycle the application
server, a step required if changes are made to any class files included in your SSB directory. An
alternative to using build importdynamic is to manually import the sp.init-custom.xml file
that was generated during the build, using the command import sp.init-custom.xml inside
iiq console.
• Open IdentityIQ in a web browser and you will see the applications, rules, and other custom
objects from your original environment in this new one.
• Note that the SSB modifies the init.xml normally used for a “fresh” build of IdentityIQ. The
SSB modifies this file from the defaults to import all content (custom objects, LCM objects if
desired, and default objects).
You may want to put a flurry of such targets between a down and up target as well.
The main Ant file build.xml has a sample target initial-build that encapsulates these targets (no up
or down targets though). Advanced SSB users might tweak this target to provide flexibility in the “initial
build” process.
For instance, the above commands would be equivalent to: build initial-build
As a bonus, you could cycle the application server: build down initial-build up
Removal
Removing IdentityIQ via the SSB targets (reverse of “initial build”) will:
• Stop the application server
• Destroy the IdentityIQ DB (and plugin DB if 7.1+)
• Wipe the web application directory
• Start the application server
Example destroy target set might be: build main down dropdb cleanWeb clean up
Note the main target here ensures the latest files are placed for dropdb to use before the command is
executed.
No equivalent wrapper target has been provided for removing IdentityIQ, as the above functions are
destructive and should require more deliberate effort to instrument.
main
Default Ant target - runs this target when no target is specified.
This target has a hook to run custom Ant scripts - post.expansion.hook.
Example: build without a target is essentially build main.
This target also calls the scripts that perform checks as defined in the Build Checks section of this
document.
clean
Deletes everything in the <SSB install directory>\build directory.
It is recommended to run the clean target before most deployments, as this ensures a clean working
directory.
Examples: build clean main or build clean deploy or build clean dist
cleanWeb
Deletes everything in the directory as specified by build property IIQHome (generally the web directory).
You should stop the web application server before running this target (either with the down target or via
another method). It obeys the build property override.safety.prompts.
It is recommended to use caution when running this target as it essentially removes the web application.
This can be desirable to ensure a clean, fresh deployment directory.
By default, a build dist or similar deployment command pushes files to the directory specified by the
IIQHome build property – it may overwrite files, but does not remove any files. For example, if a file
myJavaLibrary.jar is in the SSB folder web/WEB-INF/lib and deployed to the web server, it will stay
on the web server until it is specifically removed. Even if the example jar file is removed from the SSB
project folder and a build clean deploy is run, myJavaLibrary.jar (our example) still remains on
the web server. The cleanWeb target is meant to address this issue (specifically in non-production
environments).
createdb
Depends on the build.properties file having a database account set up that has schema-creation
privileges. The properties db.url, db.password, and db.userid in the build.properties file must
be configured properly to use this build target. This will set up the IdentityIQ schema.
cycle
Helper target that depends on both application.server.start and application.server.stop
properties being properly set in build.properties. This will cycle your application server and reload
the web application. This is equivalent to calling targets down and up in sequence (with a pause in
between). The security context of the build process must have rights to perform the custom script
actions.
dropdb
Drops the IdentityIQ database – use with care. Depends on the build.properties file having a
database account setup that has drop privileges. The properties db.url, db.password, and db.userid
in the build.properties file must be configured properly to use this build target.
Note that IdentityIQ 7.1 introduces a new, separate database (identityiqPlugin by default). In this
release (v4), only the sqlserver and mysql database types for this target have been updated to work
with the new plugin DB. The other types (oracle and db2) will be addressed in a future release.
It obeys the build property override.safety.prompts.
When using this target, it is advisable to stop the web application server to close open database
connections (otherwise, your drop of the DB may fail). A properly-configured down target would suffice
here.
dist
Copies the entire expanded war content to your application server webapps directory (wherever the
IIQHome property points to).
dependency-check
Runs the OWASP Dependency Check utility. See the OWASP Dependency Check Vulnerability
Detection section of this document for details.
deploy
Runs entire build process and deploys the expanded war content to your application server webapps
directory (wherever the IIQHome property points to) and also import custom XML artifacts. The
equivalent of running the build with no target, plus running the dist and import-custom targets (i.e.
build main dist import-custom == build deploy).
When using this feature, you should ensure that application passwords and other sensitive data are not
being stored in clear text in the source files or in values substituted by tokens to avoid them being shown
in the resulting document.
Note that this documentation is intentionally generated outside of the build/extract folder, as it
should not be deployed to the web server during a build deploy (or similar target action).
down
Runs a custom script, as defined by application.server.stop in build.properties, to stop the
application server. The security context of the build process must have rights to execute your custom
script.
extenddb
This target allows for the deployment of named, extended attributes for objects that support such
extensions (Identity, Application, etc.). Prior to SSB v4, field-delivered customizations were needed to
deploy DB schema extensions, with the only default object extensions available as numbered columns.
This was especially true for initial builds of IdentityIQ using the SSB. SSB v4 delivers this target to
meet such needs and allows for low-touch deployments that use named fields.
This target is designed to be used immediately after createdb, but it can be run anytime the schema
extensions need to be added. It will not remove schema extensions, as it acts upon output from iiq
extendedSchema. This target relies on both the build.properties setting
usingDbSchemaExtensions and having customized Hibernate (hbm) and ObjectConfig XML files in
the SSB locations web/WEB-INF/classes/sailpoint/object and config/ObjectConfig
(respectively, and the ObjectConfig folder is optional). Because there are not special artifact
requirements here, this target can be used with or without fresh, initial builds of IdentityIQ.
This target will apply the output from iiq extendedSchema to your database, after applying DB
naming customizations. Exercise care, as this will actually run a SQL script for your database type
(similar to createdb and dropdb targets).
In SSB v4, only the sqlserver and mysql database types for this target have been established. The
other types (oracle and db2) will be addressed in a future release.
export
Exports objects specified within objectsToExport.properties (this will now be generated – edit
Rule-OutputCustomObjectFile.xml in scripts if you need to add more objects to ignore or export –
the variable name of ignored object classes is listOfIgnoredClasses) from your IIQHome repository
to build/export so that you don’t manually have to copy and paste XML from console-exported files
to your build environment. Edit the property file to include all types of objects you want to export, as
well as the names of the objects for each type.
import-all
Helper target that simply calls the following targets (in order): import-stock, import-lcm, import-
ap, import-custom.
Attempting to use an import target on a fresh DB (right after createdb finishes) will fail if you have
named, extended fields for objects (e.g. Identity, Application, etc.). See extenddb target for more
information.
import-custom
Does a console iiqBeans call to import <build extract location>/WEB-INF/config/sp.init-
custom.xml. This imports all custom XML artifacts into the database. This is usually not called
directly and is part of a higher-level call (e.g. deploy target). The exception here is a from-scratch
build.
Can utilize the console_user and console_pass build properties.
Attempting to use an import target on a fresh DB (right after createdb finishes) will fail if you have
named, extended fields for objects (e.g. Identity, Application, etc.). See extenddb target for more
information.
import-lcm
Does a console iiqBeans call to import <build extract location>/WEB-INF/config/init-
lcm.xml. This imports all default Lifecycle Manager (LCM) XML artifacts into the database. This
target is generally used for a from-scratch build.
Can utilize the console_user and console_pass build properties.
import-ap
Does a console iiqBeans call to import <build extract location>/WEB-INF/config/init-
acceleratorpack.xml. This imports all default (non-Beta) Accelerator Pack XML artifacts into the
database. This target is generally used for a from-scratch build.
Can utilize the console_user and console_pass build properties.
Attempting to use an import target on a fresh DB (right after createdb finishes) will fail if you have
named, extended fields for objects (e.g. Identity, Application, etc.), which is the case for the Accelerator
Pack. See extenddb target for more information.
import-stock
Does a console iiqBeans call to import <build extract location>/WEB-INF/config/init-
default_org.xml. This imports the stock (i.e. out-of-the-box) XML items that represent a base artifact
set for IdentityIQ. Note that the SSB renames the default init.xml to be init-default_org.xml.
This means importing init.xml from the build extract area includes customized elements (i.e. like
sp.init-custom.xml). Thus, the import-stock target merely imports default XML artifacts (it will
not import your customizations). This target is generally used for from-scratch builds. This target does
not import LCM-related elements.
Can utilize the console_user and console_pass build properties.
Attempting to use an import target on a fresh DB (right after createdb finishes) will fail if you have
named, extended fields for objects (e.g. Identity, Application, etc.). See extenddb target for more
information.
import (deprecated)
Deprecated target as of SSB v4. Maintained only for backwards compatibility at this time. Duplicates
the functionality of target import-custom. New work using the SSB should not use this target; use
import-custom instead.
importcycle
Helper target that runs the entire build process, imports custom XML artifacts, copies Java classes and
static web content, and cycles (restarts) the application server. Useful while developing custom Java.
(i.e. equivalent to build main dist import-custom cycle).
Can utilize the console_user and console_pass build properties (indirectly).
importdynamic
Helper target that runs the entire build process and imports some content that does not require an
application reload: custom XML, static web content etc. Useful for developing rules, workflow and
branding (i.e. equivalent to build main dist import-custom).
importjava
Helper target that runs the entire build process, copies Java classes and static web content, and cycles
(restarts) the application server. Useful while developing custom Java and you want to skip importing
custom XML artifacts. (i.e. equivalent to build main dist cycle).
initial-build
Helper target that runs several other targets. Requires careful planning but allows for rapid, repeatable
builds of an IdentityIQ environment.
Note: initial-build target is not recommended for production environments.
See section Executing a Repeatable, Initial Build of IdentityIQ with SSB for more details.
patchdb
Prior to SSB v4, a call to createdb would implicitly run the patch sql script
(upgrade_identityiq_tables... version and DB-specific). Now, that functionality has been broken out
into the target patchdb. This target is only effective if there is a patch level for IdentityIQ specified in
build.properties.
runSql
Can run arbitrary SQL scripts of your choosing against the IdentityIQ DB. This leverages the same
build.properties settings as other DB-related targets (i.e. createdb). Also like the other DB-related
targets, this uses the Ant sql task.
This target differs from most others in the SSB, as target properties can be passed in during the call. A -
D prefix is used with each property (e.g. -Dproperty1=value).
The table below shows the valid properties for command line use. Technically, these could also be
defined in build.properties. They are not defined there by default to increase the flexibility of the
target call.
Name Description Required
sql.input.file SQL script file you want to invoke against the Yes
IdentityIQ DB
sql.output.file File to receive query output. Can be useful if No.
query output should be saved or used for other If omitted, output is only
automation. printed to the screen (standard
out).
sql.error.action Specifies if a SQL error should stop script No.
processing. Sometimes, there are errors that can If omitted, action is “abort” on
be safely ignored. any SQL script error.
In addition to passing in properties for this command, know that Ant properties in the SQL script will be
expanded. Thus, instead of hard-coding your DB name for the script (as it will be the IdentityIQ DB)
like:
create table identityiq.myTable;
You could really define any arbitrary property for SQL script expansion that you’d like (either in the
relevant build.properties file (recommended) or ad-hoc via the command line.
Below are a few use case examples.
Example command (Windows pathing) that runs some SQL and saves output. Continues on error.
build runSql -Dsql.input.file=C:\input.sql -Dsql.output.file=C:\output.sql -Dsql.error.action=continue
Example command (Windows pathing) that runs some SQL and prints output to screen. Aborts on error.
build runSql -Dsql.input.file=C:\input.sql
If sql.input.file is defined in build.properties, you could run the command without passing in
command-line parameters. Note that this reduces flexibility of the command if multiple files need to be
processed.
build runSql
runUpgrade
Runs the patch command via sailpoint.launch.Launcher, which applies a patch to an IdentityIQ
installation. This is generally only needed when creating a new install via “initial build”.
Can utilize the console_user and console_pass build properties.
up
Runs a custom script, as defined by application.server.start in build.properties, to start the
application server. The security context of the build process must have rights to execute your custom
script.war.
war
Make a war file from the output generated by target main in the build/extract directory. A war file is
essentially a compressed archive file (known as Web Application Archive) that can be used for
deploying web applications to Tomcat or similar servers. The generated war file, identityiq.war, is
put into build/deploy.
This target includes a hook to run custom Ant scripts - post.war.hook.
For customers who are licensed to use the Accelerator Pack, the latest version can be downloaded at
https://community.sailpoint.com/community/identityiq/downloads.
These are the steps to deploy the Accelerator Pack with the SSB:
• Download the Accelerator Pack zip file from Compass, and copy to /base/ap folder in the SSB
• Edit build.properties and set:
o deployAcceleratorPack to “true”
o acceleratorPackVersion to the Accelerator Pack version, e.g. “2.2.0”
• Extract the Hibernate files and custom message file from the Accelerator Pack zip file. Run
build extractAPfiles to automate this. This will extract the following files to the ap-merge
folder at the root of the SSB file structure, creating the folder if it doesn’t exist:
o ApplicationExtended.hbm.xml
o BundleExtended.hbm.xml
o CertificationItemExtended.hbm.xml
o IdentityExtended.hbm.xml
o LinkExtended.hbm.xml
o ManagedAttributeExtended.hbm.xml
o iiqCustom.properties
• If you already have customized versions of any of the above files in your build, merge the
contents with the existing files. If you do not have customized version of these files, just copy
the extracted files into the correct location.
The Hibernate files (*.hbm.xml) should be placed in:
o <SSB Install Directory>/web/WEB-INF/classes/sailpoint/object/
The iiqCustom.properties file should be placed in:
o <SSB Install Directory>/web/WEB-INF/classes/sailpoint/web/messages
Go to QuickLink Administrative Tasks "Installed Accelerator Pack" and make sure all features are
displayed.
Build Checks
SSB v4 added a series of checks around the build process to alert the deployer to common
misconfigurations and deviations from best practices. The results of these checks are written to a log
file.
Please note these checks are only indicative in nature and can result in false positives.
This would match the file XYZ-Application-ActiveDirectory.xml if that file contains an IdentityIQ
Application object. The file could be anywhere in the directory structure under the config folder.
This will match the file XYZ-Rule-AD_Correlation.xml but only if that file is located directly under
the config/Rule folder.
It is possible to exclude specific folders from the naming convention check by editing the
ignoreFolderList property in the verifyNamingConvention entry in the file
scripts/build.check.xmlVerifyNamingConvention.xml. This contains a comma-separated list of
folders to ignore. By default it will exclude the SSF_Tools, SSF_Features, SSF_Frameworks and
SSP_Tools folders from the check:
ignoreFolderList="SSF_Tools,SSF_Features,SSF_Frameworks,SSP_Tools"
When the OBJECT keyword is specified and more than one object type is represented in an individual
file, the task will exclude that file from the naming convention check.
Any file or folder which is excluded from the check will be written to the log under the section “Skipped
for Name Convention checks”.
Checks after SSB Token Substitution Phase
The following checks are performed after tokens have been substituted from the target.properties
files.
1. Application password encryption check. All XML files that represent Application objects are
checked to verify whether they have passwords that are not encrypted.
2. iiq.properties password encryption check. All iiq.properties files are checked to verify
whether they have passwords that are not encrypted.
3. Workflow trace enabled check. All Workflow XML objects are checked to verify whether the
trace variable has been initialized to true. This should normally be set to false in production
environments to avoid unnecessary logging which could affect performance.
4. BeanShell code deprecation check. BeanShell code in the build is scanned to determine
whether there are any methods that are deprecated in the version of IdentityIQ that the build is
running for. This can be particularly useful when you are upgrading IdentityIQ, as manually
checking your BeanShell code for deprecations can be a time-consuming process. In the current
version of the deprecation scanner code there are a few limitations to be aware of:
• Classes declared within BeanShell are not handled, and invocations within can result in
false positives
• Any catch/finally blocks are not handled, and invocations within them are not scanned
• Chained invocations like method1().method2().method3() are not processed
• If a deprecated method is invoked multiple times it will be listed multiple times in the
log
• Variables representing objects where the object type is not declared can result in false
positives. When the scanner cannot determine the object type it checks only the
method portion against all deprecations known within the BeanShell namespace and
indicates any found as a “possible deprecated method” in the log.
• Missing import statements can also result in “possible deprecation” in the log.
The naming convention for build check scripts that are performed after the SSB token substitution phase
is:
build.postcheck.<name>.xml
Part of a generated Vulnerability Report for IdentityIQ is shown below. The vulnerabilities listed here
are related to the MySQL and SQL Server driver files. These are showing on the report because the
versions of these files that ship with the product are not the most recent (but provided to ensure
backwards compatibility) and are subject to some known vulnerabilities; this is one reason why it is
always recommended to update the JDBC drivers (see the JDBC Drivers section of this document under
Build Structure Set-up).
Running this target will first expand the product files and patches so that the library files are ready for
analysis. The first time the utility is executed it will download the latest vulnerability data. It will then
analyze the library files in the build/extract/WEB-INF/lib folder to determine whether there are any
matching vulnerabilities. Reports will then be generated in the build/dependency-check-reports folder.
This includes information about the library, the CVE and an explanation of why the detected
vulnerability does not affect IdentityIQ. In time, new vulnerabilities may be found, and if IdentityIQ is
not affected by these vulnerabilities the suppressions.xml file may need to be updated to suppress
reporting of them. SailPoint hopes to be able to provide and maintain a list of these detected
vulnerabilities on Compass in the near future so that questions resulting from any vulnerabilities
exposed by this utility can be quickly addressed.
The suppressions.xml file also contains a <suppress> entry for excluding any CVEs that have a score
below a given value. By default this value is 7, which represents the number above which a CVE is
given a severity of ‘High’.
<suppress>
<notes><![CDATA[
This suppresses all CVE entries that have a score below CVSS 7.
]]></notes>
<cvssBelow>7</cvssBelow>
</suppress>
This will be in the form of a zip file that can be expanded to replace the existing dependency-check-ant
folder at the root of the SSB. Ensure you copy across the existing suppressions.xml file to the root of
the dependency-check folder.
Exclusions
The Dependency Checker currently excludes files that contain the string “ojdbc”. This is designed to
omit Oracle JDBC drivers because the tool’s Central Analyzer requires access to files using a public
repository, and Oracle’s licensing restrictions prohibit this. Always ensure you are using the latest
version of the Oracle JDBC driver.