ibm i2 enterprise insight analysis configuring a deployment … · 2020. 2. 14. · going live to...

Version 2 Release 2

IBM i2 Enterprise Insight AnalysisConfiguring a deployment before goinglive

IBM

Note

Before using this information and the product it supports, read the information in “Notices” on page165.

This edition applies to version 2, release 2, modification 1 of IBM® i2® Enterprise Insight Analysis (product number5725-G23) and to all subsequent releases and modifications until otherwise indicated in new editions. Ensure thatyou are reading the appropriate document for the version of the product that you are using. To find a specific versionof this document, access the Configuring section of the IBM Knowledge Center, and ensure that you select thecorrect version.© Copyright International Business Machines Corporation 2014, 2018.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.landing.doc/eia_configuring.html

Contents

Going live to Enterprise Insight Analysis users...................................................1Modifying the basic deployment...........................................................................................................1

Modifying the environment properties............................................................................................1Modifying the topology.................................................................................................................... 2Modifying the IBM HTTP Server properties.................................................................................. 13Modifying the database configuration...........................................................................................14Modifying the maximum number of notes in a record..................................................................20Specifying the connection URI...................................................................................................... 21

Modifying the credentials....................................................................................................................22Adding more data sources.................................................................................................................. 24

Adding i2 Connect to Opal deployments...................................................................................... 24Extending and adding Onyx deployments.................................................................................... 26

Replacing the i2 Analyze schema....................................................................................................... 58Creating an i2 Analyze schema and charting schemes................................................................ 59Specifying the i2 Analyze schema and the charting scheme....................................................... 60

Configuring the security schema and users....................................................................................... 61Security schemas...........................................................................................................................62Security schema definitions.......................................................................................................... 63Creating a security schema........................................................................................................... 66Specifying a security schema........................................................................................................ 67Setting default dimension values for Opal....................................................................................68Setting default dimension values for Onyx................................................................................... 69Setting up WebSphere Application Server Liberty profile security.............................................. 70Controlling access to features.......................................................................................................73

Configuring additional security........................................................................................................... 75Secure Sockets Layer connections with i2 Analyze......................................................................75Configuring SPNEGO single sign-on for i2 Analyze.......................................................................99Configuring X.509 client certificate authentication with i2 Analyze..........................................107Client authenticated Secure Sockets Layer with IBM i2 Connect..............................................116

Configuring search options............................................................................................................... 123Configuring the i2 Analyze Opal search...................................................................................... 123Configuring the i2 Analyze Analysis Repository search..............................................................144Configuring the i2 Analyze Onyx search......................................................................................148

Moving a deployment toolkit configuration......................................................................................156Redeploying and resetting i2 Analyze.............................................................................................. 157

Clearing data from the system.................................................................................................... 157Removing databases from the system........................................................................................157Deploying i2 Analyze................................................................................................................... 158

Backing up a deployment................................................................................................................. 159Backing up an offline i2 Analyze system.....................................................................................159Backing up an online i2 Analyze system.....................................................................................162

Setting up a localized deployment................................................................................................... 163Enabling bi-directional text support........................................................................................... 163

Notices......................................................................................................... 165Trademarks....................................................................................................................................... 166

iii

Going live to Enterprise Insight Analysis usersAfter you successfully create an example deployment of i2 Enterprise Insight Analysis, the next phaseis to prepare it for production by customizing it for your organization. Before your deployment goeslive, you must provide it with an i2 Analyze schema and a security schema, and you might decide toadd services or data stores to the base functionality.

Modifying the basic deploymentIn the deployment toolkit, you can identify and modify the core components of your deployment. Youcan use the toolkit to customize aspects of your deployment.

Modifying the environment propertiesThe script in the deployment toolkit that deploys i2 Analyze requires information about thedeployment environment. In the environment properties you can identify your Db2 location, specifythe installation directories that i2 Analyze uses, and specify the locations that i2 Analyze can storedata.

About this taskEach application that is defined in your topology file has an associated folder in the toolkit\configuration\environment directory that stores information about the environment that isspecific to that application. Two main files are stored for each of your applications:environment.properties

This file contains the file paths to use with the application. All the properties in this file must havevalues that match the environment.

environment-advanced.propertiesThis file contains more options about your environment. Although you can modify the values inthis file, you can deploy the application without making any changes.

The following properties are in the environment.properties file:db.installation.dir.db2

The installation path of Db2.db.database.location.dir.db2

The path to the directory at the root of Db2 database file storage.wlp.home.dir

The installation path for WebSphere Application Server Liberty profile.

Important: On Linux, when you run the deployment script, ensure that you have permission toread, write, and execute files in these directories.

java.home.dirThe installation path for the Java Development Kit (JDK).

solr.home.dirThe installation path for Apache Solr.

Note: This property is only required in a deployment that uses the Opal services.

zookeeper.home.dirThe installation path for Apache ZooKeeper.

© Copyright IBM Corp. 2014, 2018 1

Note: This property is only required in a deployment that uses the Opal services.

apollo.dataThe path to a directory where i2 Analyze temporary files are stored.

Procedure

For each application:1. Using a text editor, open the environment.properties file.2. Using the preceding descriptions, ensure that the property values match the deployment

environment.3. Save and close the file.

What to do nextAfter you update the environment properties, you can either modify other aspects of the deploymenttoolkit or redeploy the system to update the deployment with any changes. For more informationabout redeploying your system, see “Deploying i2 Analyze” on page 158.

Modifying the topologyThe topology.xml file contains the description of the physical architecture of the system that youwant to deploy. To change the physical architecture of the system, you must update thetopology.xml file and redeploy the system.

About this taskThe topology.xml file contains the information that the setup script requires to identify theprerequisites that are being used, where the system stores information, and the fragments tocombine to create the application.

You can make a number of changes to the topology.xml file. For more information about thechanges that you can make in the topology.xml file, see “The topology” on page 2.

Procedure

1. Using an XML editor, open toolkit\configuration\environment\topology.xml.2. Change the values of any attributes to match your environment.3. Check that the locations that i2 Analyze can store files match your environment.

Note: Ensure that any paths you set are to locations where the application server has permissionto store files.

4. Save your changes and close topology.xml.

What to do nextAfter you update the topology file, you can either modify other aspects of the deployment toolkit orredeploy the system to update the deployment with any changes. For more information aboutredeploying your system, see “Deploying i2 Analyze” on page 158.

The topologyIn the deployment toolkit, the topology file defines the physical architecture of the finisheddeployment, and the components that make up the pieces of that architecture. The topology filecontains domain-specific information that you must provide before deployment can take place.

The topology.xml file contains distinct sections for defining different aspects of a deployment.

2 IBM i2 Enterprise Insight Analysis Configuring a deployment before going live

i2-data-sourcesA definition of each data source that is available within the deployment.

databasesThe names, types, and locations of the databases that i2 Analyze uses to store data.

applicationsThe applications that comprise this deployment of i2 Analyze, and the locations of the applicationservers on which they are to be installed.

zookeepers and solr-clustersThe ZooKeeper hosts and Solr clusters that are used in this deployment.

connectorsThe connectors that are used with Connect in this deployment.

Data sourcesThe topology files that are supplied with each example in the deployment toolkit containpreconfigured <i2-data-source> elements. You can add additional <i2-data-source> elementsto define other data sources.

The <i2-data-sources> element must contain an <i2-data-source> element for each datasource that the deployment connects to. For example:

<i2-data-sources> <i2-data-source ar="false" default="false" id="infostore"> <DataSource Version="0" Id=""> <Shape>InfoStore</Shape> <Name>Information Store</Name> </DataSource> </i2-data-source></i2-data-sources>

Where:

Attribute Description

id A unique identifier that is used to distinguish this data sourcethroughout the system.

ar Indicates whether this data source is the Analysis Repository. Thisattribute must be set to true for the Analysis Repository, and tofalse for any other data source.

default An optional attribute that is used to specify that a different datasource from the Analysis Repository should be marked as thedefault searching option within the Intelligence Portal. To specifya different data source as the default, set this attribute to true forthat data source.

Each <i2-data-source> contains a single <DataSource> element that has two standardattributes and two child elements.

Going live to Enterprise Insight Analysis users 3


Id Reserved for future use. The value must be empty in this versionof i2 Analyze.

Version Reserved for future use. The value must be 0 in this version of i2Analyze.

Element Description

Shape Specifies the type of structure that the data source uses. You canspecify one of the following values:

• InfoStore• Repository• DAOD

Name The name of this data source, which is presented to users.

In addition, for data sources that you connect to using data access on-demand, you must also specifythe following attributes on the <DataSource> element:


EdrsPresent Indicates whether this data source has an external data retrievalservice.

EdrsGetContextSupported Indicates whether this data source has an external data retrievalservice that supports "get context" operations.

EdrsGetLatestItemsSupported

Indicates whether this data source has an external data retrievalservice that supports "get latest items" operations.

SesPresent Indicates whether this data source has a subset explorationservice.

ScsPresent Indicates whether this data source has a subset creation service.

ScsBrowseSupported Indicates whether this data source has a subset creation servicethat supports "browse" (that is, unbound search) operations.

ScsSearchSupported Indicates whether this data source has a subset creation servicethat supports "search" operations.

ScsNetworkSearchSupported

Indicates whether this data source has a subset creation servicethat supports "network search" operations.

ScsDumbbellSearchSupported

Indicates whether this data source has a subset creation servicethat supports "dumbbell search" operations.

ScsFilteredSearchSupported

Indicates whether this data source has a subset creation servicethat supports "filtered search" operations.


DatabasesThe <databases> element defines each database that i2 Analyze uses to store data. The<database> elements contain attributes that define information about the database, and themechanism that is used to connect to it.

For example:

<database database-type="InfoStore" dialect="db2" database-name="ISTORE" instance-name="DB"" xa="false" edition="" version="" host-name="host" id="infostore" port-number="50000" />

Where:


database-type Identifies the type of the database within i2 Analyze. This can be one ofthe following values:

• InfoStore• WriteStore• ccConfig

dialect Specifies the type of database engine. This attribute can be set to one ofthe following values:

• db2• sqlserver• oracle

database-name A name that identifies the database to the database engine.

instance-name The instance name that was specified during installation of your databaseengine.

xa Determines whether distributed transactions are enabled for thisdatabase.

edition Identifies the DB2 edition. This can be one of the following values:

• db2aese• db2awse• db2wse• db2ese• db2exp• db2expc• db2consv

version Identifies the DB2 version number.

host-name The host name of the server where the database is located.

id A unique identifier that is used to distinguish this database throughout thesystem.



port-number The port on the server to which to send requests for this database.

max-pool-size Sets the maximum number of connections that are allowed in theconnection pool.

ApplicationsThe <applications> element within the topology file describes the location and structure of the i2Analyze applications. The <applications> element can contain 1 or 2 child <application>elements that define the indexes, file stores, and WAR file for that application.

An <application> element has the following attributes:


name The name of the application. The following names are available:

• opal-server• onyx-server

You cannot have multiple <application> elements with the same name.

host-name The host name of the server where the application is located.

http-server-host

Determines whether the HTTP Server is configured by the deployment toolkit.

Set to true to configure the HTTP Server, or false not to configure the HTTPServer.

The following sections explain how to define the indexes, file stores, and WAR file for an application.

Indexes

An <application> element with the name onyx-server contains a child <lucene-indexes>element that defines the Lucene indexes to be used by the application.

At a minimum, the <lucene-indexes> element requires a <lucene-index> child element for theAnalysis Repository index. The <lucene-index> element can have the following attributes:


id A unique identifier that is used to distinguish this Lucene index.

main-index-location The location that is used to store the main index.

alternatives-location The location that is used to store the alternative term index.

File stores

An <application> element with the name opal-server contains a child <file-stores>element that defines the file stores that are used by the application. The location attribute specifiesthe file path to use for each file store. The other attributes must be left with their default values.


WAR files

An <application> element contains a child <wars> element. The <wars> element contains child<war> elements that define the contents of the i2 Analyze WAR files that are installed on theapplication server.

Each <war> element has the following attributes:


target The type of WAR file to create. The following types are available:

• opal-services-is• opal-services-daod• opal-services-is-daod• onyx-services-ar• onyx-services-daod• iBase• connectorCreator

name The name of the WAR file.

i2-data-source-id A name that identifies the <i2-data-source> element for this WAR file.

• For the opal-services-is and opal-services-is-daod WARs,this must reference a data source of shape InfoStore.

• For the onyx-services-ar WAR, this must reference a data source ofshape Repository.

context-root The URL that is used to access the WAR file.

• For the opal-services-is and opal-services-is-daod WARs,this is opal by default.

• For the opal-services-daod WAR, this is opaldaod by default.• For the onyx-services-ar WAR, this is apollo by default.

The following child elements of the <war> element can be defined:

data-sourcesIdentifies each database that is used by this WAR in a separate <data-source> element. Each<data-source> element has the following attributes:


database-id Identifies the database to use. This value must match the id value that isspecified in a <database> element.

• For the opal-services-is and opal-services-is-daod WARs,one <data-source> element must reference a database of typeInfoStore.

• For the onyx-services-ar WAR, one <data-source> element mustreference a database of type WriteStore.

create-database

Determines whether the database is to be created on the server that isspecified in the <database> element.



Set as true to create the database, or false not to create the database.

lucene-index-idsIdentifies the Lucene indexes that are used by this WAR in a child <lucene-index-id> element.Each Lucene index is identified by the value attribute, the value of which must match an id valuethat is specified in a <lucene-index> element.

solr-collection-idsIdentifies the Solr collections that are used by this WAR in child <solr-collection-id>elements. Each Solr collection is identified by the collection-id attribute, the value of whichmust match the id value that is specified in a <solr-collection> element.

For the opal-services-is WAR, the value for the collection-id attribute must bemain_index. For the opal-services-daod WAR, the value for the collection-id attributemust be daod_index. For the opal-services-is-daod WAR, one value for the collection-id attribute must be main_index and one must be daod_index.

A Solr collection belongs to a Solr cluster. Each Solr cluster is identified by the cluster-idattribute, the value of which must match an id value that is specified in a <solr-cluster>element.

The Solr collection with the collection-id value of main_index requires a directory to storedata before it is added to the Solr index. The value of the data-dir attribute specifies the filepath for the directory.

For more information about the ZooKeeper- and Solr-related elements in the topology.xml file,see “Solr and ZooKeeper” on page 10.

file-store-idsIdentifies the file stores that are used by this WAR. Each file store is identified by the valueattribute, the value of which must match an id value that is specified in a <file-store>element.

connector-idsIdentifies the connectors that are available in the opal-services-is-daod and opal-services-daod WARs in a child <connector-id> element. Each connector is identified by thevalue attribute, that value of which must match an id value that is specified in a <connector>element.

For more information about connector-related elements in the topology.xml file, see“Connectors” on page 12.

fragmentsSpecifies the fragments that are combined to create the WAR.

Note: All WARs must contain the common fragment.


In the example topology.xml file for the Information Store Opal example deployment, the opal-server application definition is:

<application name="opal-server" host-name="" http-server-host="true"> <wars> <war context-root="opal" name="opal-services-is" i2-data-source-id="infostore" target="opal-services-is"> <data-sources> <data-source database-id="infostore" create-database="true" /> </data-sources> <file-store-ids> <file-store-id value="chart-store" /> <file-store-id value="job-store" /> <file-store-id value="recordgroup-store" /> </file-store-ids> <fragments> <fragment name="opal-services-is" /> <fragment name="opal-services" /> <fragment name="common" /> <fragment name="default-user-profile-provider" /> </fragments> <solr-collection-ids> <solr-collection-id collection-id="main_index" data-dir="" cluster-id="is_cluster" /> </solr-collection-ids> </war> </wars> <file-stores> <file-store location="" id="chart-store" type="chart-store" /> <file-store location="" id="job-store" type="job-store" /> <file-store location="" id="recordgroup-store" type="recordgroup-store" /> </file-stores></application>


In the example topology.xml file for the Analysis Repository example deployment, the onyx-server application definition is:

<application name="onyx-server" host-name="" http-server-host="true" > <lucene-indexes> <lucene-index id="ar" main-index-location="" alternatives-location=""/> </lucene-indexes> <wars> <war context-root="apollo" i2-data-source-id="ar-id" name="onyx-server-ar" target="onyx-services-ar"> <data-sources> <data-source create-database="true" database-id="write1"/> </data-sources> <lucene-index-ids> <lucene-index-id value="ar"/> </lucene-index-ids> <fragments> <fragment name="common"/> <fragment name="onyx-services-ar"/> </fragments> </war> </wars></application>

Solr and ZooKeeperThe Opal services use Apache Solr for text indexing and search capabilities. The ZooKeeper servicemaintains configuration information and distributed synchronization across Solr.

The topology.xml file for a deployment that includes the opal-server application also includesthe <zookeepers> and <solr-clusters> elements. The <solr-clusters> and <zookeepers>elements define the Solr cluster that is used in a deployment and the ZooKeeper instance thatmanages it.


<solr-clusters>

In the supplied topology.xml file that includes the opal-server application with the opal-services-is WAR, the <solr-clusters> definition is:

<solr-clusters> <solr-cluster id="is_cluster" zookeeper-id="zoo"> <solr-collections> <solr-collection id="main_index" max-shards-per-node="4" num-shards="4" num-replicas="1" /> </solr-collections> <solr-nodes> <solr-node memory="2g" id="node1" host-name="" data-dir="" port-number="8983" /> </solr-nodes> </solr-cluster></solr-clusters>

The <solr-clusters> element includes a child <solr-cluster> element. The id attribute of the<solr-cluster> element is a unique identifier for the Solr cluster. To associate the Solr cluster withthe ZooKeeper instance, the value of the zookeeper-id attribute must match the value of the idattribute of the <zookeeper> element.

<solr-collections>The <solr-collections> element is a child of the <solr-cluster> element. The <solr-collections> element has child <solr-collection> elements. For an application thatincludes either the opal-services-is or the opal-services-daod WAR, there is a singlechild <solr-collection> element. For an application that includes the opal-services-is-daod WAR, there are two child <solr-collection> elements.

The <solr-collection> element has the following attributes:


id A unique identifier that is used to identify the Solr collection.

• For an application that includes the opal-services-is WAR, the valuemust be set to main_index.

• For an application that includes the opal-services-daod WAR, the valuemust be set to daod_index.

• For an application that includes the opal-services-is-daod WAR, thevalue must be set to main_index for one collection and daod_index for theother.

num-shards The number of logical shards that are created as part of the Solr collection.

num-replicas The number of physical replicas that are created for each logical shard in theSolr collection.

max-shards-per-node

The maximum number of shards that are allowed on each Solr node. Thisvalue is the result of num-shards multiplied by num-replicas.


<solr-nodes>The <solr-nodes> element is a child of the <solr-cluster> element. The <solr-nodes>element can have one or more child <solr-node> elements. Each <solr-node> element hasthe following attributes:


id A unique identifier that is used to identify the Solr node.

memory The amount of memory that can be used by the Solr node.

host-name The host name of the Solr node.

data-dir The location that Solr stores the index.

port-number The port number of the Solr node.

<zookeepers>

In the supplied topology.xml file that includes the opal-server application, the <zookeepers>definition is:

<zookeepers> <zookeeper id="zoo"> <zkhosts> <zkhost id="1" host-name="" data-dir="" port-number="9983" /> </zkhosts> </zookeeper></zookeepers>

The <zookeepers> element includes a child <zookeeper> element. The id attribute of the<zookeeper> element is a unique identifier for the ZooKeeper instance. To associate the ZooKeeperinstance with the Solr cluster, the value of the id attribute must match the value of the zookeeper-id attribute of the <solr-cluster> element.

The <zkhosts> element is a child of the <zookeeper> element. The <zkhosts> element can haveone or more child <zkhost> elements. Each <zkhost> element has the following attributes:


id A unique identifier that is used to identify the ZooKeeper host. This value must bean integer in the range 1 - 255.

host-name The host name of the ZooKeeper host.

data-dir The location that ZooKeeper uses to store data.

port-number The port number of the ZooKeeper host.

ConnectorsAn i2 Analyze Opal deployment that uses the i2 Connect services enables you to connect to externaldata sources. i2 Connect enables analysts to search for and retrieve data from external data sourcesand analyze the results on a chart.

The topology.xml file for a deployment that includes the opal-server application with the opal-services-is-daod or opal-services-daod WARs, also includes the <connectors> element.The <connectors> element defines the connectors that are used in a deployment.


<connectors>

The <connectors> element includes one or more child <connector> elements. The <connector>element can have the following attributes:


id A unique identifier that is used to identify the connector.

name The name of the connector, which is presented to users.

base-url The URL to the connector, made up of host name and port number. Forexample, https://host name:port number.

You can use the HTTP or HTTPS protocol.

configuration-url

The URL to any configuration that is required for the connector. The defaultvalue for the configuration-url attribute is /config.

The presence of the attribute in the topology.xml file is optional. If it isnot present, the default value is used.

In the example topology.xml file that is included in the daod-opal and information-store-daod-opal configurations, the <connectors> definition is:

<connectors> <connector id="example-connector" name="Example" base-url="http://localhost:3700/" /></connector>

Modifying the IBM HTTP Server propertiesIf the environment that you are deploying into has an HTTP server installation that is in a differentlocation from the example deployment, you can specify the different locations. The values thatdescribe your HTTP server installation are stored in the http-server.properties file, you canmodify the values to match the deployment environment.

About this taskThe property values in http-server.properties that specify the HTTP server directories are setto default values when the example is deployed. If you plan to use different locations for your HTTPserver directories, modify the values in toolkit\configuration\http-server.properties.The following properties are available:http.server.home.dir

The path to the installation directory of IBM HTTP Server. By default, C:/IBM/HTTPServer onWindows, or /opt/IBM/HTTPServer on Linux.

Important: On Linux, when you run the deployment script, ensure that you have permission toread, write, and execute files in the directories that IBM HTTP Server is installed.

http.was.module.dirThe path to the Web Server Plug-ins for WebSphere Application Server. By default, C:/IBM/WebSphere/Plugins/bin/32bits on Windows, or /opt/IBM/WebSphere/Plugins/bin/64bits on Linux.


Procedure

1. Using a text editor, open the http-server.properties file. You can find this file in the followinglocation: toolkit\configuration\environment.

2. Using the preceding descriptions, ensure that the property values match the deploymentenvironment.

3. Save and close the file.

What to do nextAfter you update the HTTP Server properties, you can either modify other aspects of the deploymenttoolkit or redeploy the system to update the deployment with any changes. For more informationabout redeploying your system, see “Deploying i2 Analyze” on page 158.

Modifying the database configurationThe example deployment configurations specify a local version of IBM DB2 as the databasemanagement system. When you set up your own system, you can deploy the Information Store andAnalysis Repository on different servers, or for your instance of the Analysis Repository you canchange the type of database management system.

Configuring remote IBM DB2 database storageYou can deploy i2 Analyze with DB2 database storage that is remote from the i2 Analyze server. Wheni2 Analyze is configured to deploy to a remote instance of DB2, the databases must be created andupdated remotely without the i2 Analyze deployment toolkit present on the server that hosts the DB2instance.

Before you begin

To deploy i2 Analyze using remote DB2 database storage, you must install DB2 on your databaseserver, and DB2 or IBM Data Server Client on the application server. Both instances of DB2 must beinstalled according to the specifications defined in the i2 Analyze software prerequisites. For moreinformation about installing the prerequisites, see Software prerequisites.

If you are using an existing installation of DB2 on the application server, you must remove any existingi2 Analyze databases. For more information about removing i2 Analyze databases, see “Removingdatabases from the system” on page 157.

About this taskTo deploy with remote storage, the deployment toolkit must contain certain information about yourDB2 instances. On the application server, update the deployment toolkit with the information aboutremote IBM DB2 instances. After you update the configuration, the specified databases are createdand updated on the remote servers when you redeploy the application.

Note: You can complete the steps performed by the catalogRemoteDB2Nodes task manually. Forexample, if you are deploying a system that uses Transport Layer Security (TLS).

To catalog the remote nodes manually, you can run the CATALOG TCPIP NODE instead of using thesetup -t catalogRemoteDB2Nodes command. For more information about the command, seeCATALOG TCPIP/TCPIP4/TCPIP6 NODE command.

The following table shows how the CATALOG command parameters map to the values in thetopology.xml file:


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/software_prerequisites.html

https://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.1.0/com.ibm.db2.luw.admin.cmd.doc/doc/r0001944.html

CATALOG TCPIP NODE command parameters <database> element attributes

TCPIP NODE nodename node-name

REMOTE hostname host-name

SERVER port number port-number

REMOTE_INSTANCE instance-name instance-name

Procedure

1. Edit the topology.xml file to specify your remote DB2 databases:a) Using an XML editor, open toolkit\configuration\environment\topology.xml.b) Update the host-name and port-number attribute values of the <database> element to

match the values of your remote DB2 instance.

Note: The value of the instance-name attribute must match the instance name of localinstance DB2.

c) Add the node-name attribute to the <database> element of the databases to be hostedremotely.For example:

<database dialect="db2" xa="false" instance-name="DB2" database-name="WriteSto" database-type="WriteStore" id="write1" host-name="hostname" port-number="50000" node-name="node1" />

Where the value for node-name is the name of the node to create in the DB2 node directory.The value of the node-name attribute must start with a letter, and have fewer than 8characters. For more information about naming in DB2, see Naming conventions.

Note: If the Analysis Repository and Information Store are using the same DB2 instance, theycan use the same node.

d) If you are deploying the Information Store database, add the os-type attribute to the<database> element for the Information Store database. The value of the os-type is used tosupport the search functionality for the Information Store.For example:

<database database-type="InfoStore" dialect="db2" instance-name="DB2" database-name="ISTORE" xa="false" edition="db2awse" id="infostore" host-name="hostname" port-number="50000" version="10.5" node-name="node1" os-type="WIN" />

Where the value for os-type is the operating system of the remote DB2 server.

Note: The value of the os-type attribute must be one of the following values: AIX, UNIX, orWIN.

Note: The values of the edition and version attributes must be correct for your remoteinstance of DB2. For more information about these attributes, see “Databases” on page 5.

2. Edit the environment.properties file, to specify the details of your remote and local instanceof DB2.a) Using a text editor, open toolkit\configuration\environment\server-name\environment.properties.



Where server-name is the name of your application server.b) Ensure that the value of the db.installation.dir.db2 property is set for the local instance

of DB2 on the application server.c) Set the value of the db.database.location.dir.db2 property for the remote instance of

DB2 on the database server.3. Ensure that the users that are specified for your databases in the toolkit\configuration\environment\credentials.properties file are valid for your remote instance of DB2.

4. Run the following command to add the nodes that are defined in the topology.xml file to theDB2 node directory:

setup -t catalogRemoteDB2Nodes

Note: The directory cache is refreshed as part of this process without any further action.5. If the Information Store or Analysis Repository databases that you are connecting to exist, you

must catalog the databases against the remote nodes that you created. To catalog your remoteDB2 databases, run the following command:

setup -t catalogDB2Databases

Note: The directory cache is refreshed as part of this process without any further action.

Results

A remote node is created with the name that is specified for the node-name attribute, and thedatabase is cataloged against that node.

To check that the remote nodes and databases are cataloged, you can use thelistDB2NodeDirectory and listDB2SystemDatabaseDirectory tasks:

• The listDB2NodeDirectory task lists the contents of the DB2 node directory.• The listDB2SystemDatabaseDirectory task lists the contents of the local DB2 system

database directory.

What to do nextRedeploy i2 Analyze so that the configuration changes are deployed to the application. For moreinformation about redeploying your system, see “Deploying i2 Analyze” on page 158.

Modifying the remote database configurationYou can change the configuration attributes of your remote DB2 databases in the i2 Analyzedeployment toolkit. To modify the remote database configuration, you must recatalog the remotenodes.

About this task

When you recatalog a remote node, the existing node is removed from the DB2 node directory and isthen cataloged again with the updated configuration values.

If you need to configure security settings on the connection, you can recatalog the remote nodesmanually, instead of using the tasks that are in the deployment toolkit. To recatalog the remote nodesmanually, you can use the DB2 UNCATALOG NODE and CATALOG TCPIP/TCPIP4/TCPIP6 NODEcommands.


You run the UNCATALOG NODE and CATALOG NODE commands manually instead of using therecatalogRemoteDB2Nodes task. For more information about the commands, see UNCATALOGNODE command and CATALOG TCPIP/TCPIP4/TCPIP6 NODE command.

Note: The catalogRemoteDB2Nodes and recatalogRemoteDB2Nodes tasks use the DB2CATALOG TCPIP NODE command. The following table shows how the CATALOG commandparameters map to the values in the topology.xml file:

CATALOG TCPIP NODE command parameters <database> element attributes

TCPIP NODE nodename node-name

REMOTE hostname host-name

SERVER port number port-number

REMOTE_INSTANCE instance-name instance-name

Procedure

1. Change the host name, port, and operating system type attributes of the remote database:a) Using an XML editor, open toolkit\configuration\environment\topology.xml.b) Update the host-name and port-number attribute values of the <database> element for

the database.c) Run the following command to recatalog the remote node:

setup -t recatalogRemoteDB2Nodes

2. Change the node name attribute of the remote database:a) Run the following command to uncatalog the remote node:

setup -t uncatalogRemoteDB2Nodes

b) Using an XML editor, open toolkit\configuration\environment\topology.xml.c) Update the node-name attribute values of the <database> element for the database.d) Run the following command to catalog the remote node:

setup -t catalogRemoteDB2Nodes

What to do nextRedeploy i2 Analyze so that the configuration changes are deployed to the application. For moreinformation about redeploying your system, see “Deploying i2 Analyze” on page 158.

Changing the database management systemIf you want to use a different database management system in your deployment, you need to updatethe details in the topology and, if appropriate, provide an alternative JDBC driver.

About this task

Important: The Information Store can be deployed on only DB2.

The database management system that is installed into your environment needs to be identifiedwithin the toolkit to ensure that the database interactions are correctly tailored. In addition, thetoolkit needs to contain the correct JDBC driver for the installed database management system. To





change the database management system, check that the details match the values that are specifiedin the toolkit.

Procedure

1. To change the database management system, copy the version of topology.xml that is specificto the database management system you are using from the examples directory into toolkit\configuration\environment.The topology files are in the following location: toolkit\configuration\examples\topology\database management system type\topology.xml.

Note: If you are using Oracle, you must populate the instance-name attribute.2. On the i2 Analyze server, open a command prompt and navigate to toolkit\scripts.3. To set the default values, run the following command:

setup -t generateDefaults

4. Check the default values in each file to ensure that they match your environment, and if requiredmodify the values.

What to do nextAfter you change the database management system, you must change the JDBC driver to match. Formore information about changing the driver, see “Changing the JDBC driver” on page 18.

Changing the JDBC driverThe application server requires a JDBC driver to enable communication with the database. The JDBCdriver that you provide to the deployment toolkit depends on the database management system touse with the deployment.

About this task

You must ensure that the correct JDBC driver is in use. Depending on the type of databasemanagement systems that are installed, the JDBC drivers that you provide differ. Choose the JDBCdrivers that relate to the database management systems that are installed.

Procedure

1. Locate the JDBC driver for your database management system.

• If you are using Db2, locate the IBM\SQLLIB\java\db2jcc4.jar file.• If you are using SQL Server, download the Microsoft JDBC Driver 6.0 for SQL Server from

https://www.microsoft.com/en-us/download/confirmation.aspx?id=11774. Extract thecontents of the download, and locate the sqljdbc_6.0\enu\jre8\sqljdbc42.jar file.

• If you are using Oracle 12c Release 1, locate the jdbc\lib\ojdbc7.jar file.• If you are using Oracle 12c Release 2, locate the jdbc\lib\ojdbc8.jar file.

2. Copy the relevant driver file for your database management system to the toolkit\configuration\environment\common\jdbc-drivers directory.

3. If you are using Oracle, or you want to use a JDBC driver .jar file that has a custom name, youmust add the jdbc-driver attribute to the <database> element in your topology.xml file.


https://www.microsoft.com/en-us/download/details.aspx?id=11774

For example:

<database dialect="oracle" xa="false" instance-name="" database-type="WriteStore" id="write1" host-name="" port-number="1521" jdbc-driver="jdbc_file_name.jar" />

jdbc_file_name is the name of the .jar file to locate in the toolkit\configuration\environment\common\jdbc-drivers directory to use for the deployment.

If you are using Oracle 12c Release 2, set the value as follows: jdbc-driver="ojdbc8.jar".

What to do nextAfter you update each property file, you can either modify other aspects of the deployment toolkit orredeploy the system to update the deployment with any changes. For more information aboutredeploying your system, see “Deploying i2 Analyze” on page 158.

Creating indexes in the Information Store databaseIn the Information Store, you can add indexes to the item type tables, and to the property typecolumns of those tables.

About this task

Indexes can improve the performance of Visual Query searches. Indexes can also improve theperformance of the merged property values definition views if you are using them.

To create an index, you must use the informationStoreModifications.sql file. This script isrun every time the Information Store database is created. You can also use themodifyInformationStoreDatabase toolkit task to run the script at any time.

For Opal deployments, the file must be in the configuration\environment\opal-server\databases\infostore directory. infostore is the value of the id attribute of the databaseelement for your Information Store database in the topology.xml file.

In the Information Store database, the IS_DATA schema contains the tables for each item type.Entity item type tables are prefixed with E_ and link item type tables with L_. In these tables,property columns are prefixed with P_.

For example, your i2 Analyze schema might contain a Person entity with a First Given Name property.If you know that this property is used a lot by analysts in Visual Query searches, you might want tocreate an index on that table and column. To create a simple index for the First Given Name property,add the following statement to the informationStoreModifications.sql file:

CREATE INDEX IS_DATA.E_PERSON_FN_IX ON IS_DATA.E_PERSON (P_FIRST_GIVEN_NAME);

IS_DATA.E_PERSON_FN_IX is the name of the index to create, IS_DATA.E_PERSON is the table forthe Person entity type, and P_FIRST_GIVEN_NAME is the column for the first given name propertytype.

To determine the syntax of the SQL statement that you must use to create the index, use thedocumentation for your database management system. For more information about creating indexesin a Db2 database, see CREATE INDEX statement.

Procedure

1. Identify the item types, and any of their property types, that you want to add indexes for.2. Create the directory for the informationStoreModifications.sql file.


https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.sql.ref.doc/doc/r0000919.html

a) In the configuration\environment\opal-server directory, create the databasesdirectory.

b) In the databases directory that you created, create the infostore directory.You can find the value to use for infostore in your topology.xml file. The value to use in yourdeployment is the value of the id attribute of the <database> element for your InformationStore database.For example, configuration\environment\opal-server\databases\infostore.

3. Using a text editor, create a file that is named informationStoreModifications.sql in theconfiguration\environment\opal-server\databases\infostore directory.

4. Develop a script to create the indexes on the tables and columns that you identified in step 1 in theinformationStoreModifications.sql file.

5. Save and close the file.6. If the Information Store database exists, run the modifyInformationStoreDatabase toolkit

task to run the script that you saved in step 4.a) Open a command prompt and navigate to the toolkit\scripts directory.b) Run the following command to run the informationStoreModifications.sql file:

setup -t modifyInformationStoreDatabase

What to do nextEnsure that the indexes you expect are in the Information Store database. You can use IBM DataStudio to see the indexes in the Information Store database.

Modifying the maximum number of notes in a recordIn a deployment that contains the Opal services, analysts can add notes that contain information thatis not categorized by the type of entity or link to Information Store records. The number of notes thata record contains can impact the performance of searching for and uploading that record.

About this task

You can configure the maximum number of notes that a record can contain to a number that bettermatches system requirements. By default, the maximum number of notes that a record can contain is50.

If a record already contains more notes than the maximum that you set, analysts can continue to editand delete the existing notes. However, analysts can only create notes in the record by deletingexisting notes until the number of notes is less than the new maximum.

Procedure

1. Using a text editor, open the DiscoServerSettingsCommon.properties file. You can find thisfile in the following location: toolkit\configuration\fragments\opal-services\WEB-INF\classes.

2. Change the value of the RecordMaxNotes property.For example, RecordMaxNotes=25.

3. Save your changes.


What to do nextAfter you modify the maximum number of notes a record can contain, you must redeploy i2 Analyzefor the changes to take effect. For more information about redeploying your system, see “Redeployingi2 Analyze” on page 105.

After you redeploy i2 Analyze, test that the system continues to meet your requirements.

Specifying the connection URIIf your deployment contains the Opal services and uses an extra proxy server between the clients andi2 Analyze, you must specify the URI that clients use to connect to i2 Analyze. Clients that do not usethe specified URI are unable to connect to i2 Analyze.

Before you beginYour proxy server must be configured so that any security configurations, for example Secure SocketsLayer or client certificate authentication, are passed through to the i2 Analyze server. You mustcomplete this according to the documentation for your proxy server.

About this task

The example deployments use a single HTTP server proxy on the i2 Analyze server that clientsconnect to. Your system might include an extra proxy server between the clients and the i2 Analyzeserver. Usually this extra proxy server has a different URI to i2 Analyze. If users try to connect to i2Analyze using the URI of the proxy server, they are unable to connect to i2 Analyze. To allow users toconnect by using the URI of the proxy server, you must specify that URI in the i2 Analyzeconfiguration. After you configure the connection URI for your deployment, users that connect to i2Analyze must use the URI that you specify.

Note: You can specify only one URI that clients can use to connect to your deployment of i2 Analyze.

When clients connect to your proxy server using the connection URI that you specify, you mustconfigure your proxy server to route requests from the client to the URI of the i2 Analyze server. TheURI of the i2 Analyze server is defined in the topology file. The URI is determined from the host-name attribute of the <application> element, and the context-root attribute of the <war>element. For example, the URI for a deployment with the following topology file is http://example.host/opal.

<application http-server-host="true" name="opal-server" host-name="example.host"> <wars> <war context-root="opal" name="opal-services-is" i2-data-source-id="infostore" target="opal-services-is"> ...</application>

Note: If your Opal application has the http-server-host attribute set to false, your proxy servermust route requests with the port number of the application. You can find the port number of theapplication in the toolkit\configuration\environment\opal-server\port-def.propsfile.

The following image shows the URIs that you might use in this example:


Client Proxy Server

i2 Analyze Server

IBM HTTP Server

WebSphere Application ServerLiberty profile

i2 Analyze application

http://proxy.server/i2

http://example.host:9082/opalhttp://example.host/opal

Procedure

1. Using a text editor, open the toolkit\configuration\fragments\opal-services\WEB-INF\classes\DiscoClientSettings.properties file.

2. Set the value of the FrontEndURI property to the URI that can be used to connect to yourdeployment of i2 Analyze through the proxy server.For example, FrontEndURI=http://proxy.server/i2.


What to do nextAfter you redeploy i2 Analyze and start the server, the URI that can be used to access the system isdisplayed in the console. Ensure that you can access i2 Analyze by using this URI from a clientworkstation that uses the proxy server.

Modifying the credentialsTo allow the deployment toolkit to update the database, Lightweight Third-Party Authentication(LTPA) keys, and Solr search platform components, you must provide user names and passwords. Theuser names and passwords that you provide allow the system to set up and administer components ofi2 Analyze, and are not used to access i2 Analyze.

About this task

Three types of credentials are stored in credentials.properties:

• Database• LTPA keys• Solr search platform


Note: Solr search platform credentials are only required for a deployment that uses the InformationStore.

You might need to change the values in the credentials.properties file from the values that areused in the example deployment. For example, IBM DB2 might require a different user name andpassword in a test or production system.

When you deploy i2 Analyze, the passwords in the credentials.properties file are encoded.

Database

For each database that is identified in topology.xml, you must specify a user name and apassword in the credentials.properties file. The setup script uses this information toauthenticate with the database.

Note: The user that you specify must have privileges to create and populate databases in thedatabase management system.

The database credentials are stored in the following format:

db.identifier.user-name=user namedb.identifier.password=password

The name of each database credential has three parts, two of which are variable:

Part Description

identifier The database identifier, for example infostore.

user-name or password Indicates whether the value is a user name or a password.

For example:

db.infostore.user-name=admindb.infostore.password=password

Note: The db.identifier.truststore.password credential is used only when you configurethe connection between the database and Liberty to use SSL. If you are not using SSL to securethis connection, you do not need to specify a value for thedb.identifier.truststore.password credential. For more information about configuringSSL, see Configure Secure Sockets Layer with i2 Analyze.

LTPA keys

You must provide a value for the ltpakeys.password property. This value is used by the systemto encrypt LTPA tokens.

• For a stand-alone deployment of i2 Analyze, you can specify any value as the password.• For a deployment of i2 Analyze that uses LTPA tokens to authenticate with other systems, you

must specify the same password that those systems use.

Solr search platform

The Solr search platform is used to search data in the Information Store. You must provide valuesfor the solr.user-name and solr.password properties. The Solr index is created when i2Analyze is deployed, and the values that you provide here become the Solr user name andpassword.


http://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.go.live.doc/c_kc_intro_ssl.html

Procedure

1. Using a text editor, open the toolkit\configuration\environment\credentials.properties file.

2. Modify any database or LTPA credentials that need to be updated:

• the database user names and passwords• the LTPA keys password

3. Leaving the current Solr properties unchanged, add any changes to the Solr credentials as newproperties.The new properties must be created in the following format:

solr.user-name.new=valuesolr.password.new=value

For example:

#Solr credentials#The user name and password for solr to use once deployedsolr.user-name=adminsolr.password={enc}E3FGHjYUI2A\=

solr.user-name.new=admin1solr.password.new=password

As a part of the deployment process:

• The new values will replace the original values in the file• The password value will be encrypted• Once changed, the credentials.properties file will be cleaned, removing the duplicate

values4. Save and close the credentials.properties file.5. Redeploy the system. In a command prompt, navigate to the toolkit\scripts directory and run

the following command:

setup -t deploy

Adding more data sourcesDepending on the original example that was deployed, you might want to extend your system to usedifferent sources of data. Extending your system in this manner not only allows you to gain access todifferent data, but also to different feature sets.

Adding i2 Connect to Opal deploymentsi2 Connect enables analysts to search for and retrieve data from external data sources by using theOpal quick search functions, and then analyze the results on a chart in Analyst's Notebook Premium.


You can add i2 Connect to a deployment of i2 Analyze that includes the Information Store with theOpal services.

Before you begin

You must have a deployment of i2 Analyze that includes the Information Store with the Opal services.

When you add i2 Connect to your deployment, the configuration for an example connector is included.To use the example connector, you must download and install Node.js to host the example connector.Download Node.js for your operating system from: https://nodejs.org/en/download/. You can installNode.js with the default settings.

About this task

The following procedure describes how to add i2 Connect to an existing deployment of i2 Analyze. Touse i2 Connect, you must obtain or create a custom connector to the external data source that youwant to search. The i2 Analyze toolkit contains an example configuration for the deployment, and anexample connector.

Procedure

1. Run the addI2Connect task to add i2 Connect to your deployment. In a command prompt,navigate to the toolkit\scripts directory and run the following command:

setup -t addI2Connect

2. If you want to use the example connector, complete the step to start the example connector inDeploying i2 Analyze with the Information Store and i2 Connect.

If you do not want to use the example connector, comment out or remove the following elementsfrom the configuration\environment\topology.xml file:

• The <connector> element with the ID example-connector• The connector-id element with the value example-connector

3. Run the setup script to redeploy i2 Analyze with i2 Connect.a) Open a command prompt and navigate to the toolkit\scripts directory.b) To deploy i2 Analyze with i2 Connect, run the following command:

setup -t deploy

4. Start i2 Analyze.a) Open a command prompt and navigate to the toolkit\scripts directory.b) To start i2 Analyze, run the following command:

setup -t start

5. Start, or restart, the HTTP server that hosts the reverse proxy.

What to do nextWhen you start i2 Analyze, the URI that users must specify in Analyst's Notebook Premium isdisplayed in the console. For example, This application is configured for access onhttp://host_name/opal.


https://nodejs.org/en/download/

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.deploy.example.doc/t_deploy_is_daod.html

Install Analyst's Notebook Premium and connect to your deployment. For more information, seeInstalling IBM i2 Analyst's Notebook Premium and Connecting IBM i2 Analyst's Notebook Premium toIBM i2 Analyze.

The example connector does not use client authenticated SSL communication between i2 Analyzeand any connectors, so a warning is displayed in Analyst's Notebook Premium. For more informationabout configuring client-authenticated SSL, see Client authenticated Secure Sockets Layer with IBMi2 Connect.

You can create your own connectors to use with deployments of i2 Analyze. For more informationabout creating your own connectors, see IBM i2 Analyze and i2 Connect.

Extending and adding Onyx deploymentsFor a deployment of i2 Analyze that uses the Analysis Repository, you can add connections to externaldata sources or an Information Store. For a deployment of i2 Analyze that uses the Information Store,you can add an Analysis Repository.

Note: If you have a system that includes multiple data sources, generally these have been set up touse different server profiles. There are multiple tasks that are able to function in an environment witha single profile that need to identify the correct profile in situations where there are multiple profiles.To specify the server profile, you must add the -s flag with the name.

For example, to start the server profile for the Information Store, run the following command:

setup -t start -s opal-server

To start the server with the Analysis Repository, run the following command:

setup -t start -s onyx-server

Adding an Information StoreYou can add an Information Store to a deployment of i2 Analyze that uses the Analysis Repository. Ina deployment with both data stores, data in both stores can be accessed by using Analyst's NotebookPremium, and data in the Analysis Repository can also be accessed by using the Intelligence Portal.

Before you beginBefore you add an Information Store to a deployment that uses the Analysis Repository, you mustensure that your security schema does not use READ_CLOAKED as a dimension level value.

About this task

Only one Information Store instance can be added per deployment, but this instance can be added toan existing deployment that is configured to use only the Analysis Repository. This task coverscreating an Information Store that is configured to use the Opal pattern of deployment.

Procedure

1. Run the addInformationStore task to add the Information Store configuration properties. In acommand prompt, navigate to the toolkit\scripts directory and run the following command:

setup -t addInformationStore

2. Add required credentials to the credentials.properties file.


a) Using a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Add the following database and Solr credentials to the file:

db.infostore.user-name=db.infostore.password=

solr.user-name=solr.password=

c) Specify a user name and password to use with the Information Store database.


d) Specify a user name and password to use with Solr.The Solr index is created when i2 Analyze is deployed, the values that you provide here becomethe Solr user name and password.

3. Deploy the example Information Store. In a command prompt, navigate to the toolkit\scriptsdirectory and run the following command:

setup -s opal-server -t deployExample

4. To populate your Information Store with the provided example data, run the following command:

setup -s opal-server -t ingestExampleData

Adding an Analysis RepositoryYou can add an Analysis Repository to a deployment of i2 Analyze that uses the Information Storedeployed using the Opal pattern. In a deployment with both data stores, data in both stores can beaccessed using Analyst's Notebook Premium, and data in the Analysis Repository can also beaccessed using the Intelligence Portal.

About this task

Only one Analysis Repository instance can be added per deployment, but this instance can be addedto an existing deployment that is currently configured to only use the Information Store. This taskcovers creating an Analysis Repository configured to use the Onyx pattern of deployment.

Procedure

1. Using an XML editor, open toolkit\configuration\environment\topology.xml.2. Add the following elements:

a) In the i2-data-sources section add the ar-id:

<i2-data-source id="ar-id" ar="true" default="true">  <DataSource Id="" Version="0"> <Shape>Repository</Shape> <Name>Analysis Repository</Name> </DataSource></i2-data-source>

b) In the databases section add the write1 database:

<database dialect="db2" xa="false" instance-name="" database-name="WriteSto" database-type="WriteStore" id="write1" host-name="" port-number="50000" />

c) In the applications section add the onyx-server application:

<application name="onyx-server" host-name="" http-server-host="true"> <lucene-indexes> <lucene-index id="ar" main-index-location="" alternatives-location="" /> </lucene-indexes> <wars> <war target="onyx-services-ar" name="onyx-services-ar" i2-data-source-id="ar-id" context-root="apollo"> <data-sources> <data-source database-id="write1" create-database="true" /> </data-sources> <lucene-index-ids> <lucene-index-id value="ar" /> </lucene-index-ids> <fragments> <fragment name="common" /> <fragment name="onyx-services-ar" /> </fragments> </war> </wars></application>

3. Add required credentials to the credentials.properties file.a) Using a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Add the following database credentials to the file:

db.write1.user-name=db.write1.password=

c) Specify a user name and password to use with the Analysis Repository database.


4. Deploy the example Analysis Repository. In a command prompt, navigate to the toolkit\scripts directory and run the following command:

setup -s onyx-server -t deployExample


Adding connectors to external sourcesIn addition to the Information Store, you can add data source connectors to a deployment of i2Analyze that uses the Analysis Repository. This allows you to search for data available in thesesources and to copy that information into the Analysis Repository as a record of your investigation.

There are three ways to deploy a data connector:

iBase ConnectorIf the external data source is iBase, then you can use the deployment toolkit and the i2 Analyzedocumentation to deploy and configure an iBase connector. In the Intelligence Portal, users canperform many of the same operations on the iBase database that they can perform on theAnalysis Repository. For more information about connecting to an iBase repository, see Deployingan iBase Connector.

Connector CreatorIf the external data source is a relational database, then you can deploy and configure ConnectorCreator instead of writing code in Developer Essentials. In this approach, Connector Creatorpresents its own user interface in the Intelligence Portal, and users can choose from apreconfigured set of parameterized searches to run. For more information about creating aconnection to relational database, see “Deploying Connector Creator” on page 40.

Other connectionsFor other external data sources, you can use i2 Analyze Developer Essentials to create and deploya custom data connector. The operations that users can perform then depend on theimplementation of the connector. For more information about connecting to other data sources,see IBM i2 Analyze Developer Essentials.

Deploying an iBase ConnectorAs part of an IBM i2 Analyze deployment, an iBase connector provides a mechanism for providingusers with access to an IBM i2 iBase database. The database becomes available in the IntelligencePortal as a data source that users can select and interact with.

There are two reasons for integrating iBase with a deployment of i2 Analyze. One reason is that youalready have an iBase deployment, and you want to retain your data and your data model as youupgrade or migrate to i2 Analyze. The other reason is that you already have a deployment of i2Analyze 4.1, and you want to use iBase as a way to ingest data from other data sources.

The deployment procedure that you follow for an iBase connector depends on your starting point.However, when the procedure is complete the combined deployment has the following features:

• Users can browse the entities, links, images, and documents that are stored in iBase.• When a user runs a free text search through the Intelligence Portal, the connector uses iBase

Search 360 to search for exact matches and variants.• When a user performs a property search for entities or links, the connector maps it to an equivalent

iBase query.• When a user creates a visual query in the Intelligence Portal, the connector translates it into an

iBase query.

Note: iBase connectors do not support the use of count conditions to search for entities that arelinked to a specific number of other entities.

• When a user clicks Show context to view the entities and links that are related to a search result,the connector performs the operation against the data in iBase.


http://ibm-i2.github.io/Analyze/

About this guide

The instructions describe how to deploy an iBase connector in i2 Analyze. For more information aboutprerequisites and supported environments, see the Release Material.

Note: This version of i2 Analyze supports one iBase connector per deployment.

The instructions assume that you have access to a distribution or a deployment of iBase 8.9.11 that isrunning on a compatible version of Microsoft SQL Server. The deployment process for the connectoralso requires a Java™ Database Connectivity (JDBC) driver that you can download from the Internetwhen you need it.

The instructions assume that you already have a working deployment of i2 Analyze with the Onyxservices. If you are deploying an iBase connector in a solution that uses both the Onyx and Opalservices, you must specify the Onyx server profile when you run any of the setup commands. Forexample, setup -t addIBaseConnector -s onyx-server.

The instructions for an iBase connector are detailed in the following sections. The essential steps aresummarized in the list.

1. Synchronize the iBase and i2 Analyze schemas.2. Configure the iBase connector.3. Deploy the iBase connector.

Synchronizing iBase and i2 Analyze schemasBefore you can configure and deploy an iBase connector, the deployments of i2 Analyze and iBasethat it connects must have compatible data structures. Depending on your starting point, you mustdeploy i2 Analyze with a schema that matches an iBase database, or iBase with a schema thatmatches a deployment of i2 Analyze.

About this task

i2 Analyze includes tools for creating an iBase schema from an i2 Analyze schema, and for performingthe opposite operation. To use an iBase connector, you need working deployments of iBase and i2Analyze whose schemas match.

If you want to set up a new i2 Analyze deployment that uses an existing iBase database, you mustcreate an i2 Analyze schema from that database. Then, you use this schema when you deploy i2Analyze. Follow the instructions in “Deploying i2 Analyze with a schema derived from iBase” on page30.

If you want to create an iBase database to use as a warehouse for an existing i2 Analyze deployment,you must generate the iBase schema from i2 Analyze. Then, you use this schema when you deployiBase. Follow the instructions in “Deploying iBase with a schema derived from i2 Analyze” on page33.

Deploying i2 Analyze with a schema derived from iBaseTo make an existing iBase database available through a new deployment of i2 Analyze, you must firstgenerate an i2 Analyze schema that is compatible with the iBase database. Then, deploy i2 Analyze.Finally, follow the instructions to configure and deploy the iBase connector.

Before you begin

Some iBase databases require modification or administration so that you can access them through aniBase connector. There are checks that you must perform before you do anything else:

• Ensure that your iBase deployment is at version 8.9.11, and that it is running on a compatibleversion of Microsoft SQL Server, and that Search 360 is enabled.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.landing.doc/eiarelnotes.html

• Use the Valid End Types tool in iBase Designer to ensure that the data in the database is properlyaligned with its schema.

• In the network configuration for SQL Server, ensure that the TCP/IP protocol is enabled.• Ensure that the SQL Server and SQL Server Browser services are both running on your server.• Ensure that you have access to an SQL Server account that is a member of both thedb_datareader and db_datawriter roles on the iBase database.

About this task

Mostly, the procedure for deploying i2 Analyze with a schema that is derived from iBase is the sameas the procedure for any other i2 Analyze deployment. The main differences come at the start, whenyou use the deployment toolkit and the Analysis Repository Tools to create and then refine theschema to use.

Procedure

1. Install, but do not deploy, i2 Analyze according to the instructions in the Installing IBM i2Analyze.

2. Create the configuration directory:a) Navigate to the \toolkit\examples\configurations\analysis-repository

directory.b) Copy the configuration directory to the root of the toolkit.

3. Download the jtds-1.2.4-dist.zip file from https://sourceforge.net/projects/jtds/files/jtds/1.2.4 and extract its contents.This file contains a JDBC driver for Microsoft SQL Server.

4. Copy the extracted jtds-1.2.4.jar file to the toolkit\configuration\environment\common\jdbc-drivers directory of your i2 Analyze installation.

5. Use a text editor to open the file at toolkit\configuration\environment\iBase\environment.properties.

6. Specify values for the following properties, and then save and close the file:

Name Value

i2analyze.schema The name of the generated i2 Analyze schema file, which issaved to the toolkit\configuration\fragments\common\WEB-INF\classes directory.

When you generate the schema, a properties file namediBaseToi2AnalyzeMappings.properties, which mapsiBase names to i2 Analyze type names, is saved to the samedirectory.

ibase.hostname The host name of the server where the iBase database isdeployed.

ibase.database The name in SQL Server of the iBase database from which tocreate the i2 Analyze schema.

ibase.username The user name of an SQL Server account that has permission toinsert and update iBase data.

ibase.password The password for the SQL Server account that has permissionto insert and update iBase data.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/installing_i2a.html

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/installing_i2a.html

https://sourceforge.net/projects/jtds/files/jtds/1.2.4


Name Value

ibase.instance The name of the SQL Server instance that hosts the iBasedatabase.

path.to.jtds.jar The full path to the directory that contains the jTDS driver file.

Tip: If your path contains spaces, you must enclose the valuewithin double quotation marks.

jtds.jar.name The name of the jTDS driver file, which is likely to bejtds-1.2.4.jar.

These property values are the only ones that you need to specify for this part of the deploymentprocess. You provide values for the other properties in environment.properties later on.

7. Provide your new deployment with some basic configuration settings:a) On the i2 Analyze server, open a command prompt and navigate to toolkit\scripts.b) To set the default values, run the following command:

setup -t generateDefaults

c) Check the default values in each file to ensure that they match your environment, and modifythem if required.

8. At the command prompt that you opened in the previous step, run the following command:

setup -t createI2AnalyzeSchemaFromIBase

The i2 Analyze schema file that you specified in the i2analyze.schema property, and itsassociated iBaseToi2AnalyzeMappings.properties file, are generated in the toolkit\configuration\fragments\common\WEB-INF\classes directory.

Important: For security reasons, running the createi2AnalyzeSchemaFromIBase taskdeletes the plain-text SQL Server password from the environment.properties file. When yourun more tasks that need access to the iBase database, you must reenter the password and savethe file again.

The generated i2 Analyze schema contains definitions for entity types and link types that match thedefinitions in iBase. The default definitions have the following characteristics:

• Entity types and link types all use the same icon.• Property types do not appear in a predictable order.• Item labels are set to the value of the DisplayName properties on those items.

Before you deploy i2 Analyze with the generated schema, you can use IBM i2 Analyze SchemaDesigner to improve it.

9. Install the Schema Designer from the tools\schema-designer directory of the i2 Analyzedistribution media.For more information, see the Schema Designer documentation.

10. Edit the schema to match your needs. There are several changes that you might consider:

• Specify different default icons for different entity and link types• Change how label generation works.• Create a charting scheme for the new schema.• Change the order of the property types within each item type.


http://www.ibm.com/support/knowledgecenter/SSFKBU/com.ibm.i2.iap.schemadesigner.doc/ar_tools_welcome.html

When you are content with the schema, you can deploy i2 Analyze.11. Use a text editor to open toolkit\configuration\fragments\common\WEB-INF

\classes\ApolloServerSettingsMandatory.properties.12. Set the value of the SchemaResource property to match the value that you set for

i2analyze.schema in the environment.properties file for the iBase connector.13. Specify the credentials:

a) Using a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the user name and password to use with the database.c) Enter the password to use to encrypt LTPA tokens.d) Save and close the credentials.properties file.

14. Run the setup script to create the example deployment:a) On the i2 Analyze server, open a command prompt and navigate to the toolkit\scripts

directory.b) To deploy the example, run the following command:

setup -t deployExample

c) To start the application server, run the following command:

setup -t start

d) Start, or restart, the HTTP server that hosts the reverse proxy.15. Open the Intelligence Portal, and test the deployment to ensure that it behaves correctly. If

necessary, adjust the settings, redeploy, and retest.

ResultsYou now have a deployment of i2 Analyze with a schema that is compatible with an existing iBasedatabase. Everything else about the deployment of i2 Analyze has its default or example behavior.

What to do next

To enable users to access iBase through the Intelligence Portal, configure and deploy an iBaseconnector on the i2 Analyze server.

Deploying iBase with a schema derived from i2 AnalyzeTo add a new iBase database to an existing i2 Analyze deployment, you must first generate adatabase schema from the i2 Analyze schema. Then, apply the schema to a new iBase database andpopulate the database. Finally, follow the instructions to configure and deploy the iBase connector.

Before you begin

Some deployments of i2 Analyze require modification or administration so that you can augmentthem with an iBase connector. You must perform these checks before you do anything else:

• Ensure that your i2 Analyze deployment is at a supported version (4.1.1. or later).• If your i2 Analyze deployment does not already use an SQL Server database, downloadjtds-1.2.4-dist.zip from https://sourceforge.net/projects/jtds/files/jtds/1.2.4 and extract itscontents.

• Copy the extracted jtds-1.2.4.jar file to the toolkit\configuration\environment\common\jdbc-drivers directory of your i2 Analyze installation.



About this task

The procedure for creating an iBase database with a schema that reflects the entity, link, and propertytypes in an i2 Analyze deployment starts with a new, empty iBase database. The next steps are toconfigure i2 Analyze with information about iBase, and then to generate, apply, and improve the newschema.

Procedure

1. Install iBase 8.9.11 and a compatible version of Microsoft SQL Server according to theinstructions in the iBase Release Notes.

2. Use iBase Designer to create an empty iBase database in your SQL Server instance.3. Create an SQL Server account that is a member of the db_datareader and db_datawriter

roles on the new iBase database.4. On the i2 Analyze server, use a text editor to open the file at toolkit\configuration\environment\iBase\environment.properties.

5. Specify values for the following properties:

Name Value

i2analyze.schema The file name of the i2 Analyze schema in the toolkit\configuration\fragments\common\WEB-INF\classesdirectory of the existing i2 Analyze deployment.

ibase.hostname The host name of the server where the iBase database isdeployed

ibase.database The name in SQL Server of the empty iBase database that youcreated

ibase.username The user name of an SQL Server account that has permission toinsert and update iBase data

ibase.password The password for the SQL Server account that has permissionto insert and update iBase data

ibase.instance The name of the SQL Server instance that hosts the iBasedatabase

path.to.jtds.jar The full path to the directory that contains the jTDS driver file

Tip: If your path contains spaces, you must enclose the valuewithin double quotation marks.

jtds.jar.name The name of the jTDS driver file, which is likely to bejtds-1.2.4.jar

These property values are the only ones that you need to specify for this part of the deploymentprocess. You provide values for the other properties in environment.properties later on.

6. On the i2 Analyze server, open a command prompt and navigate to the scripts directory of thei2 Analyze deployment toolkit.

7. Run the following command:

setup -t replaceIBaseSchemaFromI2Analyze


http://www.ibm.com/support/docview.wss?uid=swg27038010#relnotes__install_8911

The command populates the metadata tables in the iBase database, but does not create thedatabase tables and indexes.

Important: For security reasons, running the replaceIBaseSchemaFromI2Analyze taskdeletes the plain-text SQL Server password from the environment.properties file. When yourun more tasks that need access to the iBase database, you must reenter the password and savethe file again.

8. In iBase Designer, run the Schema Integrity Check tool twice consecutively on the iBase databaseto create all the necessary objects.For more information about the Schema Integrity Check tool, see the iBase Designer help.

9. Optional: Use iBase Designer to make improvements to the iBase schema that do not affect thestructure of the data.For example, change the representations of iBase item types, or assign semantic types to them.

10. Enable Search 360 on the iBase database.For more information, see the iBase Administration Center.

ResultsYou now have an iBase database with a schema that is compatible with an existing deployment of i2Analyze. Everything else about the iBase database has its default behavior.

What to do next

After you create the iBase database, you can populate it with your data. After you populate thedatabase, you can configure and deploy an iBase connector on the i2 Analyze server to enable usersto access iBase through the Intelligence Portal.

Configuring and deploying an iBase connectorWhen you have deployments of IBM i2 Analyze and iBase whose schemas are synchronized, you canconfigure and deploy an iBase connector on the i2 Analyze server. Users are then able to access iBasedata through the Intelligence Portal.

Before you beginTo deploy an iBase connector successfully, you must first have completed deployments of i2 Analyzeand iBase 8.9.11 whose schemas are synchronized in one of the following ways.

• Generate a new iBase database from an existing i2 Analyze schema by following the instructions in“Deploying iBase with a schema derived from i2 Analyze” on page 33, set the value to 1.

• Create an i2 Analyze schema from an existing iBase database by following the instructions in“Deploying i2 Analyze with a schema derived from iBase” on page 30, set the value to 2.

In addition, Search 360 must be enabled on the iBase database.

About this task

The process of configuring and deploying an iBase connector involves the following steps:

• Provide values for the remaining properties in the environment.properties file• Enable i2 Analyze to access binary documents in the iBase database• Use the deployment toolkit to add an iBase connector to your i2 Analyze configuration• Redeploy i2 Analyze with the iBase connector

If you use auditing in iBase, you can also configure the connector to log the iBase queries thatIntelligence Portal users submit to the audit database.


Configuring an iBase connectorWhen you have compatible deployments of i2 Analyze and iBase, you can configure an iBaseconnector to work between them. The procedure involves providing settings that affect how theconnector behaves, and changing some HTTP server settings. You can also enable iBase to audit thequeries that users make through the Intelligence Portal.

Procedure

1. Using a text editor, open the file at toolkit\configuration\environment\iBase\environment.properties.

2. Specify values for the following properties:

Name Value

ibase.origin.db.name A name for the connected iBase database that identifies it insome automatically generated configuration files. This propertycan have any value, but it must not be empty. It is conventionalto set it to the same value as ibase.database.

ibase.datasource.jndi The JNDI name for the data source, which is also used in theconfiguration files for an iBase connector. This property canhave any value, but it must not be empty. By convention, JNDInames start with "ds/"; for example, ds/iBase.

ibase.datasource.id The data source identifier for the iBase database, which is usedin some of the iBase connector configuration files. This propertycan have any value, but it must not be empty. It is common for itto match ibase.datasource.jndi, but without the "ds/"prefix.

ibase.security.context The security dimension values that items from iBase receive.You can opt to specify that items in iBase with different securityclassification codes (SCCs) receive different dimension values,but you must provide a default set with the following syntax:

ibase.security.context=Default,HI,OSI,CON

Here, Default is a fixed string, while HI, OSI, and CON aredimension value identifiers. You must ensure that you identify atleast one value from each dimension in your security schema.

Note: If you want items from iBase to receive the same securitysettings as items in the Analysis Repository receive by default,arrange for the setting here to be consistent with the<DefaultItemSecurityTags> setting in toolkit\configuration\fragments\core\ApolloClientSettings.xml.

If your iBase deployment uses SCCs, then you can specify adifferent set of dimension values for each SCC, like thisexample:

ibase.security.context=Default,HI,OSI,CON||SCC_1,HI,CON||SCC_2,OSI,UC


Name Value

Any item with an SCC that does not appear in theibase.security.context property value automaticallyreceives the Default settings.

ibase.operation.mode An indicator of whether you began your iBase connectordeployment with an existing deployment of i2 Analyze or iBase.You must give this property one of the following values:

• If you generated a new iBase database from an existing i2Analyze schema by following the instructions in “DeployingiBase with a schema derived from i2 Analyze” on page 33, setthe value to 1.

• If you created an i2 Analyze schema from an existing iBasedatabase by following the instructions in “Deploying i2Analyze with a schema derived from iBase” on page 30, setthe value to 2.

ibase.max.result.count The maximum number of results that the iBase connectorreturns in a single operation. This property can have any value,but it must not be empty. The purpose of the property is toprevent users from requesting large data sets from thedatabase. The count is based only on the number of matchesreturned in response to a query, it does not measure of theamount of data in each match instance.

The appropriate setting for your deployment depends on yourdeployment pattern, your data, and the type of results required.Start with an average value, for example 200, revise upwards ifyou need to see more results or downwards if you are lookingfor improved performance.

Note: Note: In the Onyx pattern, the maximum number ofresults that can be selected and added to the chart is 500.

ibase.library.id The identifier for the jTDS driver file, which is used in theconfiguration files for an iBase connector. This property canhave any value, but it must not be empty. For example,jTDSLib.

ibase.audit.required If you use auditing in iBase, you can configure the connector tolog all user queries to the iBase audit database. This propertymust be set to one of the following values:

• If you did not configure auditing in iBase, or you do not wantthe connector to log user queries, set the value to false.

• If you configured auditing and created an audit database iniBase, and you want to log all the queries that are submittedto iBase through the Intelligence Portal, set the value to true.

3. If you set ibase.audit.required to true, then you must specify values for three moreproperties:


Name Value

ibase.audit.database.name

The name in SQL Server of the iBase audit database.

ibase.audit.jndi The JNDI name for the data source that represents the iBaseaudit database. This property can have any value, but it mustnot be empty when ibase.audit.required is true. Byconvention, JNDI names start with "ds/"; for example, ds/audit.

ibase.datasource.audit.id

The data source identifier for the iBase audit database. Thisproperty can have any value, but it must not be empty whenibase.audit.required is true. It is common for thisproperty to match ibase.datasource.jndi without the"ds/" prefix.

You must also ensure that the SQL Server account that you specified in ibase.username is amember of the db_datareader and db_datawriter roles on the iBase audit database.

The final part of configuration is to enable i2 Analyze to access binary documents in the iBasedatabase by adding a rewrite condition and a rewrite rule to the HTTP server.4. Using a text editor, open the http-custom-rewrite-rules.txt file from the configuration\environment\proxy directory of the i2 Analyze deployment toolkit.

5. Add the following code to the file, between the lines that contain !Start_After_Rules! and !End_After_Rules!:

RewriteCond %{QUERY_STRING} ^documentId=DA-servlet/([^&]+)RewriteRule ^/${contextRoot:onyx-services-ar}/services/download /${contextRoot:iBase}/services/dadownload?documentId=%1 [PT]

Ensure that you enter the rewrite rule on a single line, omitting the line break in the example, butincluding a space after download.

6. Save and close the text file.You are now ready to install and deploy your iBase connector.

Installing and deploying an iBase connectorWhen you have a set of configuration files that meet your requirements, you can deploy the iBaseconnector. The following procedure describes how to add the connector and information about theiBase data source to your existing i2 Analyze deployment.

Procedure

1. On the i2 Analyze server, open a command prompt and navigate to the scripts directory of the i2Analyze deployment toolkit.

2. Run the following commands:

setup -t addIBaseConnectorsetup -t addIBaseDatasource

Important: For security reasons, running the addIBaseDatasource task deletes the plain-textSQL Server password from the environment.properties file. When you run more tasks thatneed access to the iBase database, you must reenter the password and save the file again.


3. Use the following command to stop the application nopserver:

setup -t stop

4. Redeploy i2 Analyze to add the iBase connector to the deployment, and to update IBM HTTPServer:

setup -t deploy

5. Use the following command to start the application server:

setup -t start

6. Restart IBM HTTP Server.

Updating an iBase connectorIf you need to modify the behavior of an iBase connector, the procedure for updating it is similar tothe procedure for the original deployment.

Procedure

1. On the i2 Analyze server, use a text editor to open the file at toolkit\configuration\environment\iBase\environment.properties.

2. Make your changes to the configuration.For example, you might enable auditing, or reduce the maximum number of results from an iBasesearch.

3. Reenter the SQL Server account password, and then save and close the file.4. Open a command prompt and navigate to the scripts directory of the i2 Analyze deployment

toolkit.5. Run the following sequence of commands:

setup -t addIBaseConnectorsetup -t addIBaseDatasourcesetup -t stopsetup -t deploysetup -t start

Note: You reuse the addIBaseConnector and addIBaseDatasource tasks, even though youare updating rather than adding these components.

6. Restart IBM HTTP Server.

ResultsAfter you complete this procedure, the i2 Analyze deployment is running again, with your changes tothe iBase connector in place.


Configuring custom logging for an iBase connectorBy default, an iBase connector inherits its logging settings from its parent i2 Analyze deployment. Youcan change this behavior so that iBase connector logging uses a different level, or is saved in adifferent location.

About this task

By default, the logging level for i2 Analyze is defined in a file named log4j.properties, in theconfiguration\fragments\common\WEB-INF\classes directory of the i2 Analyze deploymenttoolkit.

In an unmodified deployment, i2 Analyze sends the messages from a running iBase Connector to a filenamed IBM_i2_Analysis_Repository.log, in the usr\servers\onyx-server\logs\onyx-services-ar directory of WebSphere Application Server Liberty profile. The logging level is WARN,which logs potentially harmful situations, error events, and unrecoverable error events, but notinformational messages.

Procedure

To configure different logging specifically for an iBase connector, follow these instructions:1. Create a separate log4j.properties file in the configuration\fragments\iBase\WEB-INF\classes directory.

2. Populate the new log4j.properties file to reflect your requirements.

You can describe how to handle log messages from the following iBase connector libraries:

• com.i2group.connector.common• com.i2group.connector.common.adapter• com.i2group.connector.common.data• com.i2group.connector.common.data.basic• com.i2group.connector.common.editor• com.i2group.connector.daod.ibase

For more information about working with log4j, see the Apache Logging Services Project website athttp://logging.apache.org.

3. Update i2 Analyze by running setup -t deploy from a command prompt, as usual.

Deploying Connector CreatorAs part of an IBM i2 Analyze deployment, Connector Creator provides a way to access some types ofexternal data source without the need to write a custom data connector. Following a successfuldeployment, Connector Creator makes data from external sources available for users to query andview in the Intelligence Portal.

About this guide

The instructions in this deployment guide describe how to add Connector Creator to a deployment ofi2 Analyze that uses IBM DB2®. For more information about prerequisites and supportedenvironments for the rest of the system, see the Release Material.

The instructions assume that you already have a working deployment of i2 Analyze with the Onyxservices, and that you have access to the external databases that Connector Creator connects thisdeployment to.


http://logging.apache.org

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.landing.doc/eiarelnotes.html

If you are deploying Connector Creator in a deployment that uses both the Onyx and Opal services,you must specify the Onyx server profile when you run all the setup commands in this section. Forexample, setup -t addConnectorCreator -s onyx-server.

Important: For a successful deployment of Connector Creator, the Analysis Repository must be a DB2database. The configuration mechanism does not support any other database management system.

Installing Connector CreatorThe first stage of enabling access to an external data source through Connector Creator is to addConnector Creator itself to your deployment of i2 Analyze. The process creates storage for theconfiguration file, and adds new elements to the Intelligence Portal user interface.

Before you beginEnsure that i2 Analyze is deployed with IBM DB2.

Procedure


2. Run the following command to add Connector Creator to your i2 Analyze deploymentconfiguration:

setup -t addConnectorCreator

The command adds a fragment for Connector Creator to the toolkit\configuration\fragments directory, and information about the configuration database to the topology file.

3. Using a text editor, open the ApolloServerSettingsDaodMandatory.properties file fromthe new toolkit\configuration\fragments\Connected\WEB-INF\classes directory.

4. Delete the following line, and then save and close the file:

MainSearchIndex=C:/IBM/iap/daod5-data

5. Using an XML editor, open the topology.xml file from the toolkit\configuration\environment directory.

6. Complete the information about the configuration database by providing the host-name and theinstance-name. In most circumstances, these details are the same as for the i2 Analyze datastore:

<database database-type="ccConfig" dialect="db2" instance-name="InstanceName" database-name="CONFIG" xa="true" id="config" host-name="HostName" port-number="50000" />

7. Using a text editor, open the credentials.properties file from the toolkit\configuration\environment directory.

8. Provide db.config.user-name and db.config.password with the user name and passwordof a user with permission to add and modify the configuration database in DB2. Again, in mostcircumstances, these will match the credentials that you use for the i2 Analyze data store.


9. At the command prompt, run the following sequence of commands to deploy Connector Creatorand restart i2 Analyze:

setup -t stopsetup -t deploysetup -t start

10. Restart the HTTP server, and then open the Intelligence Portal in your web browser.The application toolbar contains a new Connected button that enables users to work with theexternal data sources that are connected through Connector Creator. However, no data sourcesare available until you also add those to the i2 Analyze deployment.

What to do next

After you install Connector Creator, the next part of the deployment process is to add informationabout the external data sources that users will run queries against.

Adding an external data source for Connector CreatorThe second stage of enabling access to an external data source through Connector Creator is toprovide the i2 Analyze deployment with information about that source. Depending on the databaseengine of the external source, you might also need to provide an additional JDBC driver.

About this task

Connector Creator uses the support in WebSphere Liberty Profile for connecting to relationaldatabases. For more information about connecting to different database engines, see the topic namedConfiguring database connectivity in Liberty, in the Liberty documentation.

Procedure

1. Obtain a Java Database Connectivity (JDBC) driver for the external database that you want toconnect to.

Note: If the external database is hosted on DB2, then you can use same JDBC driver that the i2Analyze data store and the Connector Creator configuration database use.

2. If necessary, save the driver file to the configuration\environment\common\jdbc-drivers directory of the i2 Analyze deployment toolkit.

3. Using an XML editor, open the server.datasources.xml file from the deploy\wlp\usr\servers\onyx-server directory of your i2 Analyze installation.

4. At the end of the file, immediately above the </server> closing tag, add a <library> elementand a <dataSource> element for the external database to which you want to connect.


http://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/twlp_dep_configuring_ds.html?lang=en

For example, the following pair of elements configures access to a locally hosted SQL Serverdatabase named Example, through the jTDS JDBC driver:

<library id="jTDSLib"> <fileset dir="C:/IBM/i2analyze/toolkit/ configuration/environment/common/jdbc-drivers" includes="jtds-1.2.4.jar"/></library><dataSource id="Example" type="javax.sql.XADataSource" jndiName="jdbc/Example"> <jdbcDriver libraryRef="jTDSLib" javax.sql.XADataSource="net.sourceforge.jtds.jdbcx.JtdsDataSource"/> <properties instance="SQLEXPRESS" databaseName="Example" serverName="localhost"/></dataSource>

WebSphere Liberty Profile supports connections to a range of different database engines. Theprecise requirements on the contents of the <library> and <dataSource> elements varyaccording to the database in question. For more information, see the Liberty documentation topicnamed Configuring database connectivity in Liberty.

5. Add user and password attributes to the <properties> element to specify the credentials of auser with appropriate access to the database.You can specify the user name in plain text, but for improved security you should encode thepassword:a) Open a command prompt and navigate to the deploy\wlp\bin directory of your i2 Analyze

installation.b) Run the following command to generate an encoded version of the password:

securityUtility encode --encoding=aes Password

c) Copy the output of the command to the value of the new password attribute.6. At the open command prompt, navigate to the scripts directory of the i2 Analyze deployment

toolkit.7. Run the following commands to add the external data source to your i2 Analyze deployment

configuration:

setup -t stopsetup -t start

What to do next

After you have added information about the external data source, you must create a configuration filethat identifies the data to query and maps that data to i2 Analyze entities, links, and properties.


http://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.wlp.doc/ae/twlp_dep_configuring_ds.html?lang=en

Creating the Connector Creator configuration fileTo exchange data with an external database, Connector Creator requires a configuration file thatcontains two kinds of information. You must define the queries that users can run, and map theresults of those queries to a form that i2 Analyze can accept.

About this task

A configuration file for Connector Creator is an XML file that contains similar information for each ofthe external databases that Connector Creator connects to. For each connected database, theconfiguration file must define:

• The queries that Intelligence Portal users can run against the database, written in SQL• Mappings from the query result structures to the property types of i2 Analyze entity and link types

The procedure here describes the process of building a Connector Creator configuration file. For moredetails about the contents of the file, see The Connector Creator configuration file.

Procedure

To be able to translate from query results to i2 Analyze data, you need an XML representation of the i2Analyze schema that you can examine and create mappings to.


2. Run the following command to generate a .jar file that contains the XML representation:

setup -t generateMappingJar -x i2analyze_schema -o definition_jar

Here, i2analyze_schema is the full name (including the path) of the schema file, and definition_jaris the full name (including the path) of the output .jar file.

Attention: If definition_jar specifies an existing file, the generateMappingJar task doesnot overwrite it. If you run the same command twice in succession, ensure that you moveor delete the output between calls.

Inside the .jar file, the name of the XML file that you need is schema4.xsd. You might find it helpfulto keep that file open in an editor as you follow the rest of this procedure to create the configurationfile itself.

3. Using an XML editor, create an empty XML file with a name of your choice.4. Create the root element of the configuration file, which must be named <configuration>.5. Inside the <configuration> element, create one <dataSource> child element for each

external database that you added to the server.datasources.xml file.6. To each <dataSource> element, add <name> and <description> child elements.

The text contents of these elements appear in the Intelligence Portal, where they identify eachsource to users, and provide summary information about their data.

7. To each <dataSource> element, add a <specification> child element with a text value thatidentifies the external database.For each data source, the contents of the <specification> element must match the value ofthe jndiName attribute of the corresponding <dataSource> element in theserver.datasources.xml file.

For more information about the three previous steps, see “The <dataSource> element” on page 49.


8. To each <dataSource> element, add a <securityDimensionValueIds> element thatspecifies the security dimension values to be assigned to all items that users retrieve from thisdata source.Add one <securityDimensionValueId> to its parent for each value that you want to assign.

Note: Items from external data sources are subject to the same rules as items from the AnalysisRepository. Every item must have at least one value from each dimension in the current i2Analyze security schema.

For more information about the previous step, see “The <securityDimensionValueIds> element” onpage 49.

9. To each <dataSource> element, add a <mappings> child element and a <resources> childelement.Populating these two elements for each data source is the most important, and the mostcomplicated, part of creating the configuration file.

For any data source, populating the <mappings> and <resources> elements is a recursive process:

• Each <resource> inside the <resources> element defines a broad SQL query to execute againstthe database, along with a set of additional clauses through which users can constrain the results.For example, the broad query might retrieve information about people from the database, while theadditional clauses might allow users to search for people with particular names, or ages, or heights.

• Each <mapping> inside the <mappings> element describes how Connector Creator should mapinformation from query results to item property values in i2 Analyze. When you have created themappings for one resource, it is likely that you can use some of the same mappings to deal with theresults from a different resource.

10. In each <resources> element, create and populate <resource> elements that define thesearches that users can run against the data source.a) To each <resource> element, add a <specification> child element that contains the SQL

query through which the data for the resource is retrieved.b) For each resource, identify the i2 Analyze item types that will represent the retrieved

information, and then populate a <supportedMappings> element with the names of theentity and link type mappings that Connector Creator will use.

You have not yet written them, but you can begin to determine how many mappings (that is,how many different types of information) each resource requires. Often, a resource thatretrieves entities will use one mapping, while a resource that retrieves entity-link-entitystructures will use three mappings.

Important: If a resource retrieves data in which one entity can be linked to another entity ofthe same type, then the ends require two separate mappings even though the mappingdefinitions can be identical.

For more information about this step, see “The <resources> element” on page 50.11. For each resource in the configuration file, create at least one <query> element to define a

search that users can run.Each query has a name and a description that appear in the Intelligence Portal, and aspecification that contains the broader query from the resource specification.

For more information about this step, see “Queries” on page 51.12. If a query enables or requires users to provide one or more parameters, then add <parameter>

elements to the query definition.

For more information about this step, see “Parameters” on page 52.When you have created all the resources and queries that you want to present to your users, you canwrite the mappings that enable them to see the results in the Intelligence Portal.


13. Determine whether the property types for the item types that you mapped are simple or complexaccording to your i2 Analyze XML schema definition. For the simple property types, createproperty mappings for each property type. For complex property types, use property groups togather together the mappings for the component simple properties that make up the complexproperty type.

For more information about this step, see “The <mappings> element” on page 54.

ResultsYou now have a Connector Creator configuration file that contains all of the necessary information toallow users to run a single query against an external data source. After you have successfully testedthe configuration in your i2 Analyze deployment, you can return to this procedure to add furtherqueries to Connector Creator.

What to do next

When you have a self-consistent Connector Creator configuration file, you can upload it to theconfiguration database on the i2 Analyze server.

Uploading and downloading the configuration fileInstalling Connector Creator adds the Connected button to the Intelligence Portal toolbar, but it doesnot enable users to query your external data source. To make Connector Creator useful, you mustupload the configuration file that defines the queries that users can run.

About this taskThe configuration database for Connector Creator stores a single set of configuration settings at anygiven time. Any upload operation that you perform overwrites any previous settings. As a result, it iseasy to create your configuration incrementally, and to test modifications regularly.

To aid debugging, the commands for uploading and downloading the configuration file both supportan "-lp" option that enables Java logging. The value that you specify is the path to a configuration filethat looks like this example:

.level=INFOjava.util.logging.FileHandler.limit=50000java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatterhandlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandlerjava.util.logging.FileHandler.count=1java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatterjava.util.logging.ConsoleHandler.level=ALLjava.util.logging.FileHandler.pattern=LogFile

Note: This is standard Java logging, and there are many online resources that describe how to createand edit configuration files.

Procedure

1. On the i2 Analyze server, open a command prompt and navigate to the scripts directory of the i2Analyze deployment toolkit.

2. If you have previously uploaded a configuration file, run the following command to download it:

setup -t downloadCcConfig -c ExistingConfig.xml


By performing this step, you ensure that you can revert to a known configuration in the event thatyour new file does not work correctly.

Note: In some circumstances, the downloaded file can contain empty elements that were notpresent in the original configuration. To prevent this behavior from affecting you, search the file forempty <queries/> and <select/> elements, and delete any that you find.

3. Run the following command to upload your new Connector Creator configuration file to theconfiguration database:

setup -t uploadCcConfig -c NewConfig.xml

4. Restart the HTTP server, and then open the Intelligence Portal in your web browser.When you click Connected, the user interface contains information about the data source to whichyou provided access, and the queries that users can run.

What to do next

Verify that everything in the user interface that relates to Connector Creator behaves as you expect,and that you can run the queries and interact with their results. If you experience problems, you canexamine the console.log file in the deploy\wlp\usr\servers\onyx-server directory of youri2 Analyze installation, or the additional log files in the Connected, onyx-services-ar, andmessages sub-directories of that location.

When you are satisfied with the functionality that you have enabled, you can return to theconfiguration file and add more queries, more resources, or more data sources to Connector Creator.


The Connector Creator configuration fileTo make an external database available through Connector Creator, you must provide a description ofthe data that you want to access. The Connector Creator configuration file describes and maps thedata to the XML schema definition that you generate from your i2 Analyze schema.

In outline, the XML file that maps the data from the external database and specifies the queries thatusers can run has the following structure:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><configuration> <dataSource> ... <securityDimensionValueIds/> <mappings> <mapping> <properties/> <propertyGroups/> ... </mapping> ... <linkMapping> <properties/> <propertyGroups/> ... </linkMapping> ... </mappings> <resources> <resource> <securityDimensionValueIds/> <supportedMappings/> <queries> <query> <parameters/> </query> ... </queries> </resource> ... </resources> </dataSource> ...</configuration>

Each <dataSource> element represents an external database that is connected through ConnectorCreator. You can configure the connections to multiple data sources in a single file.

Every <dataSource> element contains a <mappings> element and a <resources> element. Themappings specify how Connector Creator transforms data from an external database into items thatusers can view and manipulate in i2 Analyze. The resources specify the data that you want to enableusers to search, such as database tables or selected columns from one or more tables. The resourcesalso define the queries that users can run against the specified data through the Intelligence Portal.


The <dataSource> elementIn the configuration file for Connector Creator, the single <configuration> root element containsone or more <dataSource> elements, each of which specifies an external database. No matter howmany data sources Connector Creator is connected to, there is always one configuration file.

The <dataSource> element requires a <name> child element that identifies the database in theIntelligence Portal. Optionally, you can include a <description> element that also provides adescription of the external data.

<configuration> <dataSource> <name></name> <description></description> <specification></specification>

<securityDimensionValueIds> <securityDimensionValueId></securityDimensionValueId> ... </securityDimensionValueIds> <mappings/> <resources/> </dataSource> ...</configuration>

Connector Creator uses the contents of the mandatory <specification> child element to associatethis configuration information with an external data source that you added to the i2 Analyzedeployment. The contents of the element must match the value of the jndiName attribute of thecorresponding <dataSource> element in the server.datasources.xml file.

The <securityDimensionValueIds> elementIn i2 Analyze, security dimension values set the access and grant permissions on items, which controlthe level of access that users receive. In the configuration file, the<securityDimensionValueIds> element contains <securityDimensionValueId> childelements that specify how Connector Creator assigns security dimension values to items that arederived from external data.

In the configuration file, the <securityDimensionValueIds> element can be a child of<dataSource> elements and <resource> elements. In the first case, its contents affect all itemsthat Connector Creator retrieves from that data source. In the second case, the contents of<securityDimensionValueIds> affect items from that resource only.

Note: The effects of these elements are additive. The items from a particular resource receivesecurity dimension values from <securityDimensionValueIds> elements at the local scope, andat the data source scope.

You can specify security dimension values in two ways:

• To give the same security dimension value to all items, you can set the text content of a<securityDimensionValueId> element to the identifier of a security dimension value. Forexample, <securityDimensionValueId>CON</securityDimensionValueId>.

Note: You can use this technique at the <dataSource> scope to arrange for all items from the datasource to get the same security dimension values as items in the Analysis Repository receive bydefault. To do so, create a <securityDimensionValueId> element for each value in the


<DefaultItemSecurityTags> setting in toolkit\configuration\fragments\onyx-services-ar\ApolloClientSettings.xml.

• To give different security dimension values to different items, you can use the source attribute toidentify a column in the retrieved data that contains security dimension value identifiers. Forexample, <securityDimensionValueId source="Security_Dimension_1"/>.

Note: This option is only appropriate for <securityDimensionValueIds> elements that arechildren of <resource> elements.

If you specify a security dimension value identifier and a source database column, for example<securityDimensionValueId source="Security_Dimension_1">CON</securityDimensionValueId>, then the fixed value applies when source column does not containa value.

If you specify only a source database column, but the column does not contain a value for a particularitem, then another <securityDimensionValueId> element in the configuration file must apply tothat item.

The <resources> elementIn the Connector Creator configuration file, the <resources> element has child <resource>elements. Each <resource> element specifies a subset of the database to search, and defines thequeries that users can run against that data. You create a separate <resource> element for eachdata subset that you want users to be able to query.

Every <resource> element has a mandatory <specification> child element whose content is anSQL statement. The specification defines the data that each query runs against, and you must enclosethe statement in parentheses so that Connector Creator can append query specifications forexecution.

For example, the resource might be a database table with the name PERSON, and you might want toallow users to retrieve data from all the columns in the table. In this case, the resource specificationmight be (Schema.PERSON), where Schema is the table schema. Alternatively, if you want to retrieveonly given names, surnames, and ages from the table, you might set the value to (SELECTFIRST_NAMES, SURNAME, AGE FROM Schema.PERSON).

Note: You must use a SQL Alias for each select statement.

To continue the example, a specification for a resource that returns data for creating linked entitiesmight include SQL JOIN statements that combine data from several tables. To retrieve data on peopleand their vehicles from separate PERSON, OWNS, and VEHICLE tables, the SQL statement might looklike this:

(SELECT PERSON.PERSON_ID, PERSON.SURNAME, OWNS.BOUGHT, VEHICLE.VEHICLE_ID, VEHICLE.MAKEFROM Schema.PERSONJOIN Schema.OWNS USING (PERSON_ID)JOIN Schema.VEHICLE USING (VEHICLE_ID)) AS T

If a resource specification returns data for linked entities that have the same type, then the data forboth entities must appear in the same set of results. The column names and the aliased column


names that the property mappings specify must match. Here is an example specification for aresource that returns the ages of people that are associated with other people:

(SELECT P1.PERSON_ID AS PERSON_ID, P1.AGE as AGE, P2.PERSON_ID AS PERSON_ID2, P2.AGE AS AGE2, Schema.PERSON_PERSON.*FROM Schema.PERSON_PERSONJOIN Schema.PERSON P1 ON Schema.PERSON_PERSON.FROM_ID = P1.PERSON_IDJOIN Schema.PERSON P2 ON Schema.PERSON_PERSON.TO_ID = P2.PERSON_ID) AS T

Supported mappings

Every <resource> element has a mandatory <supportedMappings> child element containsfurther <mappingRef> child elements. Each <mappingRef> identifies a mapping that transformsdata from the resource into i2 Analyze item data. The contents of a <mappingRef> element mustmatch exactly the value of the mappingID attribute of the required mapping.

<dataSource> <resources> <resource> <specification>...</specification> <securityDimensionValueIds> <securityDimensionValueId>...</securityDimensionValueId> ... </securityDimensionValueIds> <supportedMappings> <mappingRef>...</mappingRef> ... </supportedMappings>

<queries/> </resource> ... </resources> </dataSource>

A resource that retrieves data for entities of a single type requires one <mappingRef> element.However, a resource that retrieves data for linked entities requires three <mappingRef> elements:one for the link type, and two for the entity types that the link connects. When a link type connectsentities of the same type, you must reference both of the entity mappings.

Queries

When a <resource> element has a <queries> child element, the latter contains <query> childrenthat define the search operations that users can run against the data that the resource defines.


Note: If a <resource> does not have a <queries> element, then users cannot run direct queriesagainst it. However, data that the resource retrieves can still appear in the results of "show context"operations.

<resource> ... <queries> <query> <specification>...</specification> <names> <name locale="default">...</name> </names> <descriptions> <description locale="default">...</description> </descriptions> <parameters/> </query> ... </queries> </resource>

Within each <query> element, the value of the mandatory <specification> child element is anSQL statement that refines the specification in the parent resource. When a user runs the query,Connector Creator appends the query specification to the resource specification through a WHEREclause.

For example, you might set the specification to T.AGE=?AGE and create a parameter to enable usersto search by age. Alternatively, to create a query with no user-defined parameters that returns thenames of 32-year-old people, you might set the specification to T.AGE='32'.

The <query> element has a mandatory <names> child element and an optional <descriptions>child element that identify the query and describe its functionality to users. The text contents of the<name> and <description> elements specify the text that appears in the Intelligence Portal userinterface. Both elements have a reserved, mandatory locale attribute that you must set to defaultin all cases:

Parameters

When you configure a query that enables users to provide search parameters, you must includeelements that describe them. The <parameters> element contains <parameter> child elements


that define the search parameters that users can enter, and the fields in the Intelligence Portal wherethat happens.

<query> <parameters> <parameter parameterName="..."> <edit>...</edit> <labels> <label locale="default">...</label> </labels> <hints> <hint locale="default">...</hint> </hints> <select> <options> <option value="...">...</option> ... </options> </select> </parameter> ... </parameters> </query>

Each <parameter> element has a mandatory parameterName attribute that identifies theparameter in the specification of its parent query. The value of the attribute must match the value inthe <specification> element. For example, if the specification in the query contains a parameternamed ?AGE, then the parameterName attribute of the <parameter> element must have the valueAGE.

Note: All the parameters within a query must have different names, but you can use the sameparameter name in multiple queries.

If you add no more attributes to the <parameter> element, then Intelligence Portal users can enterunconstrained alphanumeric values. However, the element supports optional attributes that allowmore control:

Name Value

parameterType The type of permitted values for the parameter. Legal values forthis attribute are string for alphanumeric values, integer forpositive whole numbers, date for dates, or choice to provide alist of options.

Note: If you set the type of a parameter to choice, you must alsoprovide that parameter with a <select> child element.

inclusiveMin For a parameter of type integer or date, a lower bound on thevalue that users can enter. For a date, the value must be in theformat yyyy-mm-dd.

inclusiveMax For a parameter of type integer or date, an upper bound on thevalue that users can enter. For a date, the value must be in theformat yyyy-mm-dd.


Name Value

required true to specify that a user must enter a value for this parameter;false otherwise.

To constrain the values of a string parameter, you can use the optional <edit> child element. Thetext content of the element must be a character data (CDATA) declaration, and the supported syntaxis the same as for the first parameter to the JavaScript RegExp constructor, except that the doublequotation marks are not required.

Note: The <edit> element does not support the JavaScript global search modifier, but you canemulate it by using a wildcard in the form of an asterisk (*) at the end of an expression. For example,to match any number of digits, set the contents of the <edit> element to <![CDATA[\d*]]>. Toconfigure case-insensitivity, you must specify both uppercase and lowercase character ranges in theexpression. For example, <![CDATA[\b[Ii][Bb][Mm]]]> matches the string "IBM" in anycombination of uppercase and lowercase letters.

If you set parameterType="choice" on the <parameter> element, then a <select> childelement is mandatory. The <select> element in turn has a mandatory <options> child. Inside<options>, each <option> element has a value attribute that determines the value of theparameter when a user selects the option. The text content of the <option> element appears in theIntelligence Portal.

Finally, the <parameter> element has optional <labels> and <hints> children that enable you tospecify a label and provide a tooltip for the parameter in the Intelligence Portal. These elementsbehave like the <names> and <descriptions> children of the <query> element. In particular,locale="default" is mandatory on <label> and <hint> elements.

The <mappings> elementThe <mappings> element in the Connector Creator configuration file determines how the data inquery results turns into property values in i2 Analyze. To make the most of external data, it isimportant to get the mappings right.

To work out what the mapping to an item type in the i2 Analyze must look like, you start with theschema4.xsd file that you created in “Creating the Connector Creator configuration file” on page 44.For each item type, the important element is the one whose name attribute isTypeName_CardContent. This element describes the properties that items of type TypeName canhave. For example, here is the start of a definition for an item type named Person:

<xs:complexType name="Person_CardContent"> <xs:sequence> <xs:element ... /> ... </xs:sequence></xs:complexType>

In schema4.xsd, the <xs:element> children of the complex type have name attributes whoseformat is TypeName_PropertyName. These are the names that you use in the mapping. If the typeattribute of the same element indicates a simple data type, then the element represents a property in


https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/RegExp

the schema. If the type attribute references a further complex type, then the element represents aproperty group.

<xs:complexType name="Person_CardContent"> <xs:sequence> <xs:element name="Person_FullName" type="Person_FullName" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Person_DateofBirth" type="xs:dateTime" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence></xs:complexType>

<xs:complexType name="Person_FullName"> <xs:sequence> <xs:element name="Person_First_Given_Name" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="Person_FamilyName" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence></xs:complexType>

In the Connection Creator configuration file, the <mappings> element contains <mapping> and<linkMapping> child elements that map the data in the external data source to entities, links, andproperties. Both children have a mandatory mappingID attribute that specifies a unique identifier forthe mapping within the configuration file. This is the identifier that you provide to a <mappingref>element in a <resource> definition.

<mappings> <mapping mappingID="personsMapping"> ... </mapping> ... </mappings>

Each <mapping> element has two mandatory child elements. The contents of the <targetName>element match the name of the schema type that the mapping is for (that is, the TypeName part ofTypeName_CardContent). The contents of the <itemIdentifier> element specify the name ofthe column in the external data that contains unique identifiers for the items in the search results.


Note: <targetContainerName> is an optional element that can specify the name of the containerelement for search results of the same type. Usually, the container name is the same as the item typename, but with an "s" appended. In these circumstances, you do not need to include the element.

<mappings> <mapping mappingID="personsMapping"> <itemIdentifier>PER_ID</itemIdentifier> <targetName>Person</targetName> <targetContainerName>Persons</targetContainerName> <propertyGroups> ... </propertyGroups> <properties> ... </properties> </mapping> ... </mappings>

Each <linkMapping> element has the same child elements as <mapping>, plus four extra,mandatory ones for information that is specific to links:

<linkMapping mappingID="employment"> <itemIdentifier>PER_ORG_ID</itemIdentifier> <fromEndItemIdentifier>PER_ID</fromEndItemIdentifier> <toEndItemIdentifier>ORGID</toEndItemIdentifier> <strength>Confirmed</strength> <direction>NONE</direction> <targetName>Employment</targetName> <targetContainerName>Employments</targetContainerName> <propertyGroups> ... </propertyGroups> <properties> ... </properties> </linkMapping>

<fromEndItemIdentifier> and <toEndItemIdentifier> have contents that specify the namesof the external data columns that contain unique identifiers for the entities at each end of the link.<strength> and <direction> have contents that specify how certain the link is, and the directionof the relationship that it represents. Confirmed and NONE are common values to use here.

Property groups and properties

If you identify data in your query results that maps to the values of simple properties in the i2 Analyzeschema, then you can populate the <properties> element of your <mapping> with <property>children.

Every <property> element has two child elements: <name> and <source>. The contents of<name> must match the name attribute of an <xs:element> in the schema that has a simple data


type, as described at the start of the topic. The contents of <source> must the name of the column inthe query results that contains values for this property.

<mapping mappingID="personsMapping"> ... <propertyGroups> <propertyGroup> <name>Person_FullName</name> <properties> <property> <name>Person_First_Given_Name</name> <source>GIVEN</source> </property> <property> <name>Person_FamilyName</name> <source>FAMILY</source> </property> </properties> </propertyGroup> </propertyGroups> <properties> <property> <name>Person_DateofBirth</name> <source>DOB</source> </property> </properties> </mapping>

If you identify data in your query results that maps to properties in the i2 Analyze schema that appearin property groups, then you can populate the <propertyGroups> element of the <mapping>. Each<propertyGroup> element has a mandatory <name> child whose contents must match the nameattribute of an <xs:element> in the schema that references a complex data type.<propertyGroup> elements also have a <properties> child that obeys the same rules as theelement with the same name that is a direct child of <mapping> or <linkMapping>.

Connector Creator example filesThe documentation for Connector Creator includes a pair of example files that you can use toexperiment with the technology. The files enable you to populate and query a sample databaseaccording to the procedures that the previous topics describe.

example.txt contains an SQL script that creates a small group of database tables and populatesthem with some sample data.

configuration.xml is a Connector Creator configuration file that presents searches over thesample data to Intelligence Portal users. The file also maps search results to be compatible with thedefault i2 Analyze law enforcement schema, and the default security schema.

In their supplied form, the example files require an empty database named "Example" that theypopulate and search. Some of the SQL statements in the configuration file assume that the RDBMS isDB2, but it is not difficult to convert them to other dialects if you want to.

To use the example files, assuming that you already installed Connector Creator:

1. Run the script in example.txt to create and populate tables in the example database.


2. Add the example database as a data source in i2 Analyze.3. Upload the Connector Creator configuration file.4. Open the Intelligence Portal, and click Connected in the menu bar.

Replacing the i2 Analyze schemaAn important part of converting an example deployment to a live deployment, is the modification orreplacement of the i2 Analyze schema. You replace the schema so that it models the data that youwant to analyze.

The i2 Analyze deployment toolkit contains four pairs of example i2 Analyze schemas and chartingschemes:

Law EnforcementThe law enforcement schema deals with criminal activity. It contains entity and link types that aredesigned to track connections within criminal networks.

Commercial InsuranceThe commercial insurance schema deals with fraud in a commercial setting. It contains entity andlink types that are designed to track financial transactions such as credit card payments andinsurance claims.

MilitaryThe military schema helps with military intelligence tracking. It contains entity and link types thattarget military operations.

Signals IntelligenceThe signals intelligence schema focuses particularly on the cellphones and cell towers that areinvolved in mobile telecommunications, and on the calls that take place between them.

Note: Some of the example schemas and charting schemes are provided in multiple languages. Theseversions are located in a directory that is named with the language code inside the configuration\examples\schemas directory.


Depending on the deployment pattern you chose, your example deployment has either the lawenforcement or the signals intelligence schema. Unless your data is very close to those examples, theright approach is to start again from scratch.

Note: If your data is close to the example schema, then you can modify the schema instead ofreplacing it, and there is slightly less for you to do. You can follow the procedure in Modifying the i2Analyze schema.

One of the consequences of replacing or significantly modifying the schema is that it becomesincompatible with any data in your deployment, see “Clearing data from the system” on page 157. Asa result, these activities require you to clear the data from i2 data stores. The other requirementsdepend on your deployment pattern.

For the different example configurations that IBM provides, the procedures for replacing the i2Analyze schema are as follows:

• If your deployment contains only the Analysis Repository, then redeploying with your new schema(and an accompanying charting scheme) is enough. See “Deploying i2 Analyze” on page 158.

• If you deployed the Information Store with the Opal services, then you also need to replace theconfiguration file that governs what filters users see during Quick Search and Visual Queryoperations. See “Setting up search results filtering” on page 126.

• If your deployment uses the Information Store with the Opal services and you are defining theproperty values of merged i2 Analyze records, you must update your merged property valuesdefinition views. See Define how property values of merged records are calculated.

• If you deployed the Information Store with the Onyx services, then you also need to replace theCognos reports and mapping files that control how users interact with search results. See“Configuring the i2 Analyze Onyx search” on page 148.

Important: Replacing the schema is about the most significant change you can make to a deploymentof Enterprise Insight Analysis. Aim to do it soon after a successful example deployment, and longbefore a production deployment. Large changes to an i2 Analyze schema when users and data dependon it are hard to manage.

You can learn more about deploying a custom schema at the IBM Security Learning Academy.

Creating an i2 Analyze schema and charting schemesThe supplied i2 Analyze schemas are suitable for production deployments of Enterprise InsightAnalysis only when the target environment is close to one of the example deployments. Usually, youmust prepare for production deployment by creating your own i2 Analyze schema and your ownversions of the other configuration files that depend upon it.

The deployment toolkit includes example schemas that target particular domains: commercialinsurance, law enforcement, military intelligence, and signals intelligence.

• If one of the supplied schemas matches your requirements, you can use it without modification.Even so, depending on the deployment pattern, you might need to create or edit some of the otherEnterprise Insight Analysis configuration files.

• Alternatively, one of the supplied schemas might contain some of the entity and link types that youneed. If you can meet your requirements by expanding or modifying the existing types, then you canedit the schema to make it fit for purpose.

• If none of the supplied schemas is appropriate, then you can create your own schema that preciselymodels the data in your organization.

When you create a schema, you must also create one or more charting schemes to accompany it.These separate files specify how entities and links and their properties appear when they are


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.maintain.doc/modifying_i2analyze_schema.html

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.maintain.doc/modifying_i2analyze_schema.html

https://www.securitylearningacademy.com/course/view.php?id=2629

visualized on charts. To provide users with more flexibility in their investigations, you can visualizedata in different ways by creating multiple charting schemes.

The deployment toolkit includes charting schemes that match the example schemas. You can updatethese schemes to match any modifications you make to the example schemas; or else you can createcharting schemes that match a custom schema.

After you create a schema and its corresponding charting schemes, you can deploy it into a testenvironment for evaluation. Creating an effective schema involves several cycles of reviewing andtesting before you use it in a production environment.

After a schema enters production, the changes that you can make to it are strictly limited. Therefore,it is important to ensure that the schema meets the requirements of the organization before it goeslive.

You can view, edit, create, and upload schemas with Schema Designer. For instructions on creatingand editing an schema, see the Schema Designer documentation.

Specifying the i2 Analyze schema and the charting schemeDeveloping an i2 Analyze schema and a charting scheme for an Enterprise Insight Analysisdeployment is an iterative process. You can expect to modify the schema several times as you buildtowards the production version. As you do so, you must change other parts of the system too.

Before you beginEach time you come to this task, you have an i2 Analyze schema that is different from the one thatcurrently applies to the deployment. Either you created a schema, or you edited an existing schema.Now you want to apply the schema to the deployment and test it.

About this task

This procedure contains an outline of the steps to follow as you develop a schema for yourdeployment of i2 Analyze. In reality, you are likely to follow some of the steps on each iteration of yourdesign. At the beginning of the process, when you create or copy the schema and charting schemefiles, you must specify the new files in the deployment toolkit. As you develop the schema, you mightneed to clear data from the system, or modify your sample data, or edit another part of theconfiguration that depends on the schema.

Procedure

Much of the work in developing the i2 Analyze schema and the other files that depend on it lies inmaking them consistent with each other. One approach is to start with a schema that contains only afew of the types that you plan to create. Then, get an i2 Analyze deployment working that uses thosetypes. After that, you can add more types to a system that you know to be sound.1. If you created an i2 Analyze schema and charting scheme, copy the files to the configuration\fragments\common\WEB-INF\classes directory of the deployment toolkit.

2. If you changed the file names of the i2 Analyze schema and charting scheme, set the i2 Analyzeschema and charting scheme that the deployment uses.a) Using a text editor, open the ApolloServerSettingsMandatory.properties file in the

same directory as the schema files.b) Set the values of the SchemaResource and ChartingSchemesResource properties to the

names of your schema and charting scheme.c) Save and close the settings file.


3. If you made anything other than additive changes to the schema, then clear the data, the searchindex, and the database from the system.See “Redeploying and resetting i2 Analyze” on page 157.

4. If your deployment includes the Opal services, create and configure facets to match the item andproperty types that you added or changed in the i2 Analyze schema.See “Setting up search results filtering” on page 126.

5. If your deployment uses the Information Store with the Opal services and you are defining theproperty values of merged i2 Analyze records, you must update your merged property valuesdefinition views.See Define how property values of merged records are calculated.

6. If your deployment includes the Onyx services and the Information Store, edit the Cognosmappings to match the schema.See “Configuring the i2 Analyze Onyx search” on page 148.

7. If you have sample data that does not exercise or is no longer compatible with the new version ofthe schema, update it.

8. Redeploy i2 Analyze.

What to do nextRepeat the procedure until your i2 Analyze schema fulfills the needs of your organization. When theschema reaches that point, you can go on to finalize the charting scheme and develop the securityschema.

Configuring the security schema and usersExample deployments of i2 Analyze have security schemas that allow the software to work, but arenot suitable for production purposes. Before you go live, you must develop a security schema thatmeets the needs of your organization.

An i2 Analyze security schema defines the security dimension values that you can assign to items andrecords in i2 data stores, and the security permissions that you assign to groups of users.

The fact that the data stores contain dimension values means that significant changes to the securityschema can require you to clear and reingest or repopulate data. This behavior is reasonable whileyou develop your deployment, but not after you go live with it. As a result, it is important to refine thesecurity schema before you put it into production. After you go live, the changes that you can makeare much more limited.

The following diagram shows the workflow for configuring security during development of your i2Analyze deployment:

In addition to the security schema, a separate file can be created that allows you to control access tospecific features and commands.


Security schemasAn i2 Analyze security schema defines the security dimensions that exist in a deployment, and thedimension values that can be assigned to items and records. A security schema also defines thepermissions that i2 Analyze users can receive.

Every deployment of i2 Analyze has a security schema whose contents reflect local requirements. It isthe responsibility of the deployer to ensure that the security schema is appropriate for theenvironment where it is used. Often, the security dimensions map to security classifications that existin the organization.

Before you create a security schema, it is important to understand the relationship between thesecurity model and the security schema. For more information, see IBM i2 Analyze security model .

Security dimensions

A security schema defines access security dimensions and grant security dimensions separately.Although they have the same structure, access and grant security dimensions are distinct from eachother. In a security schema, dimensions and dimension values must have identifiers that are uniqueacross the whole schema.

Security permissions

A security schema defines security permissions by user group, and then by dimension. For a particularuser group, the schema identifies one or more dimensions for which membership of that group affectsaccess rights. For each identified dimension, the schema contains a list of security permissions.

It is not necessary for the security schema to define permissions for every user group in theorganization. Similarly, it is not necessary for the permissions within any particular dimension orgroup to set a security level for every possible dimension value. The completeness of the schema isjudged at run time when the security level of a particular user for a particular item or record iscalculated.


Security schema definitionsAn i2 Analyze security schema is an XML file with a relatively simple structure. Security dimensionsand security permissions are defined in separate sections of the file.

In outline, the <SecuritySchema> root element of a security schema contains child elements forthe dimension and permission definitions:

<SecuritySchema> <SecurityDimensions Id="" Version=""> <AccessSecurityDimensions> <Dimension ...> <DimensionValue ... /> ... </Dimension> ... </AccessSecurityDimensions>

<GrantSecurityDimensions> <Dimension ...> <DimensionValue ... /> ... </Dimension> ... </GrantSecurityDimensions> </SecurityDimensions>

<SecurityPermissions> <GroupPermissions ...> <Permissions ...> <Permission ... /> ... </Permissions> ... </GroupPermissions> ... </SecurityPermissions></SecuritySchema>

The <SecurityDimensions> element has attributes for the Id and Version of the schema. If youmodify any part of the security schema, retain the identifier but increment the version number. In thisway, you ensure that all i2 data stores and services are informed of the changes.

In a valid security schema, the <AccessSecurityDimensions> and<GrantSecurityDimensions> elements must be present, and there must be at least one<GroupPermissions> element inside <SecurityPermissions>.


Security dimension definitionsSecurity dimensions are defined in an i2 Analyze security schema file as children of the mandatory<AccessSecurityDimensions> and <GrantSecurityDimensions> elements. A valid securityschema defines at least one access and one grant security dimension.

The syntax for defining a security dimension does not depend on whether it is an access or a grantdimension. The structure of the XML is always the same. The following example shows a simple,complete <Dimension> element:

<Dimension Id="SD-SC" DisplayName="Security Classification" Description="The security classification of this information" Ordered="true"> <DimensionValue Id="TOP" DisplayName="Top Secret" Description="Top Secret" /> <DimensionValue Id="RES" DisplayName="Restricted" Description="Restricted" /></Dimension>

The attributes of the <Dimension> element affect how the values in the security dimension areinterpreted.


Id A unique identifier that is used to distinguish this security dimensionthroughout the system.

DisplayName A name that identifies this dimension to the user in the Intelligence Portal,for example.

Description A more detailed description of this security dimension that provides moreinformation to the user. In the Intelligence Portal, the description is usedas a tooltip.

Ordered Indicates whether the values in this dimension form a descendingsequence in which each value supersedes the values below it.

Marking this dimension as Ordered="true" means that a user who hasaccess rights to "Top Secret" data implicitly has the same access rights to"Restricted" data as well. For a dimension in which Ordered="false",there is no such implication, and access rights must be assigned explicitlyfor each dimension value.

The Id, DisplayName, and Description attributes of <DimensionValue> elements have thesame purpose and meaning as the <Dimension> attributes with the same names. The identifiers ofdimension values must be unique within the dimension that defines them.

Important: After you deploy i2 Analyze, the changes that you can make to security dimensions arelimited. You cannot add or remove dimensions, or remove dimension values. You can only add valuesto existing dimensions. For this reason, you must understand the requirements of your organizationbefore you deploy i2 Analyze in a production environment.

Security group permission definitionsIn an i2 Analyze security schema, the mandatory <SecurityPermissions> element contains oneor more <GroupPermissions> elements. Each <GroupPermissions> element defines the


security levels that users in a particular group receive for items and records with particular dimensionvalues in an i2 Analyze deployment.

The syntax for defining the security permissions for user groups enables membership of one group toconvey permissions across several dimensions, and allows different groups to convey differentpermissions for the same dimensions. The following example shows how to structure<GroupPermissions> elements inside the <SecurityPermissions> element:

<SecurityPermissions> <GroupPermissions UserGroup="Clerk"> <Permissions Dimension="SD-SC"> <Permission ... /> </Permissions> ... </GroupPermissions> <GroupPermissions UserGroup="Manager"> <Permissions Dimension="SD-SC"> <Permission ... /> ... </Permissions> <Permissions Dimension="SD-IT"> <Permission ... /> ... </Permissions> ... </GroupPermissions> <GroupPermissions UserGroup="Security Controller"> <Permissions Dimension="SD-GA"> <Permission ... /> </Permissions> </GroupPermissions></SecurityPermissions>

The value of the UserGroup attribute of each <GroupPermissions> element must match the nameof a group of i2 Analyze users.

The value of the Dimension attribute of each <Permissions> element must match the identifier ofone of the dimensions that is defined in the first part of the schema.

It is normal for <Permissions> elements for the same dimension to appear in more than one<GroupPermissions> element:

• Users who are members of one group but not the other can receive different access levels on itemsand records that have the same dimension values.

• When users are members of more than one group, <Permissions> elements for the samedimension are combined before any access level calculation takes place.

In many deployments of i2 Analyze, there is one grant security dimension that contains onedimension value. By referring to the grant security dimension from a single <GroupPermissions>element, you can arrange for grant access to be in the hands of users who are members of adedicated group.

Important: You can add and remove <GroupPermissions> elements from a deployed securityschema, if the resulting system continues to obey the rules of i2 Analyze. In particular, it must remain


possible for all users to get an access level that is not "none" for at least one value in every accessdimension.

Security permission definitionsThe security permission definitions in an i2 Analyze security schema each associate a singledimension value with a single security level. The definitions can be simple because of the additionalcontext that their location in the security schema file provides.

The <Permission> elements that define security permissions always appear inside<Permissions> elements, which in turn always appear inside <GroupPermissions> elements.

<GroupPermissions UserGroup="Manager"> <Permissions Dimension="SD-SC"> <Permission DimensionValue="TOP" Level="READ_CLOAKED" /> <Permission DimensionValue="RES" Level="UPDATE" /> </Permissions> <Permissions Dimension="SD-IT"> <Permission DimensionValue="HUMINT" Level="READ_ONLY" /> </Permissions></GroupPermissions>

It is possible, and often desirable, for identical <Permission> elements to appear in differentlocations in an i2 Analyze security schema. The effect of a security permission definition dependsentirely on its position in the file.

Important: Like the <GroupPermissions> elements that contain them, you can add and remove<Permissions> and <Permission> elements from a deployed security schema, if the resultingsystem does not break the rules of i2 Analyze.

Creating a security schemaEvery deployment of i2 Analyze requires a security schema that encapsulates the security model forthat deployment. The easiest way to create a security schema is to start from the example that IBMprovides with the platform.

Before you begin

Before you create the XML security schema file, you must design the security model for yourdeployment of i2 Analyze. In particular, you must identify or create the user groups to which securitypermissions are assigned.

When you deploy i2 Analyze, the group names in your security schema must match the names of usergroups in the user repository.

About this task

An i2 Analyze security schema contains definitions of security dimensions and security permissions.When you create a security schema, you define the dimensions and dimension values first, and thendefine the security permissions that refer to them.

Procedure

1. Navigate to the directory in the deployment toolkit that contains the example security schema:toolkit\configuration\examples\security-schema\example-dynamic-security-schema.xml.


2. Make a copy of the example-dynamic-security-schema.xml file, give it an appropriatename, and then open it in an XML editor.

3. Edit the contents of the <AccessSecurityDimensions> element so that it contains a<Dimension> element for each category that your deployment uses to determine access rights toitems and records in i2 data stores.

4. Edit the contents of the <GrantSecurityDimensions> element so that it contains a<Dimension> element whose value you can use to convey grant access rights.

5. Edit the contents of the <SecurityPermissions> element:a) Add or modify <GroupPermissions> elements so that they reflect all the user groups to

which you assign security permissions. The group names in your security schema must matchthe names of user groups in the user repository.

b) Within each <GroupPermissions> element, add or modify <Permissions> elements toindicate which dimensions are affected by membership of each user group.

c) Within each <Permissions> element, add or modify <Permission> elements to assignsecurity levels to items and records that have particular dimension values.

If your deployment of i2 Analyze includes an Analysis Repository but no Information Store,there are four permitted values for the Level attribute of the <Permission> element:

• NONE• READ_CLOAKED• READ_ONLY• UPDATE

If your deployment includes an Information Store, then READ_CLOAKED is not a permittedvalue, and a security schema that contains it is invalid.

6. Increment the value of the Version attribute of the <SecurityDimensions> element.7. Save the completed security schema to the configuration\fragments\common\WEB-INF\classes directory in the deployment toolkit.

What to do nextModify the deployment toolkit to specify that i2 Analyze uses the new security schema, and thenredeploy the platform and conduct your tests. If necessary, iterate over these steps again until youhave the security schema that you need.

Specifying a security schemaThe security schema is a key component of an i2 Analyze deployment, and configuring it correctly isan important part of the development process. Replacing or making significant changes to thesecurity schema requires you to clear and repopulate the data stores in your deployment.

About this task

One of the features of i2 Analyze security is that items in the Analysis Repository and records in theInformation Store must have dimension values from every dimension in the security schema. As aresult, it is not possible to add security dimensions or remove dimension values without invalidatingthe data in the data stores. IBM recommends that you build and refine the security schema beforeyour deployment goes into production use. See Understanding IBM i2 Analyze: Security model formore information about the security model and the security schema.


Procedure

After you perform an example deployment of i2 Analyze, use the following procedure to replace thesecurity schema with one that you created or modified.

Note: For a description of how to make small modifications to the security schema in a productiondeployment of i2 Analyze, see Modifying the security schema.1. In Windows Explorer, navigate to the configuration\fragments\common\WEB-INF\classes directory in the deployment toolkit.

2. Open the ApolloServerSettingsMandatory.properties file in a text editor.3. Set the value of the DynamicSecuritySchemaResource property to the name of your new or

modified security schema.4. Save and close the properties file.5. Follow the instructions in “Clearing data from the system” on page 157 to remove all the data from

the data stores in the i2 Analyze deployment.6. Follow the instructions in “Deploying i2 Analyze” on page 158 to deploy your new or modified

security schema and restart the system.

What to do nextAfter you change the security schema, you might need to change the dimension values that recordsand items receive when they enter the system. After those changes, add some data to the system,and verify that users see the behavior that you intended. Iterate over the process of modifying andreplacing the schema as many times as you need.

Setting default dimension values for OpalIn a deployment with the Opal services, when users create Information Store records in Analyst'sNotebook Premium, i2 Analyze applies a default set of dimension values to the record. Similarly, whenthe Information Store ingests data, the created records receive dimension values during the process.

About this task

You might change the default security dimension values that are applied to records for differentreasons:

• If you change the dimensions or dimension values in your security schema.• If the security requirements of your deployment change.

Regardless of your reason for changing the default security dimension values, or when the values areapplied, each record must have at least one dimension value from each security dimension.

Procedure

1. When analysts create Information Store records in Analyst's Notebook Premium, the recordsreceive default security dimension values. To change the set of security dimension values thatrecords receive by default:a) In a text editor, open the configuration\fragments\common\WEB-INF\classes\ApolloServerSettingsMandatory.properties file from the deployment toolkit.

b) Update the DefaultSecurityDimensionValues property with the identifiers of securitydimension values that you want to be applied by default.For example, DefaultSecurityDimensionValues=CON,OSI,HI.

In a standard deployment of i2 Analyze, a supplied implementation of theDefaultSecurityDimensionValuesProvider that applies dimension values from the


http://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.maintain.doc/modifying_security_schema.html

DefaultSecurityDimensionValues property is used. You can create your ownimplementation by using i2 Analyze Developer Essentials.

2. When data is ingested into the Information Store, the records that it contains receive their securitydimension values during the ingestion process.To change the behavior of the ingestion process, update the contents of the<securityDimensionValues> element in the mapping file with the identifiers of securitydimension values that you want to be applied by default.

For more information about updating the default security dimension values that are applied duringingestion, see Information Store data ingestion.

3. Redeploy and restart your deployment of i2 Analyze.

Setting default dimension values for OnyxIn a deployment with the Onyx services, when a user creates an item in the Analysis Repository, i2Analyze applies a default set of dimension values. Similarly, when the Information Store ingests data,the created records receive dimension values during the process.

About this task

You might change the default security dimension values that are applied to items and records fordifferent reasons:

• If you change the dimensions or dimension values in your security schema.• If the security requirements of your deployment change.

Regardless of your reason for changing the default security dimension values, or when the values areapplied, each item and record must have at least one dimension value from each security dimension.

Procedure

1. If you have an Analysis Repository, i2 Analyze assigns dimension values to items in severaldifferent circumstances. Items receive dimension values when Intelligence Portal users createthem. Items also receive dimension values when users search for them through an iBaseconnector, Connector Creator, or a custom data access on-demand solution.a) To change the set of security dimension values that items in the Analysis Repository receive by

default:

1) In an XML editor, open the configuration\fragments\onyx-services-ar\ApolloClientSettings.xml file from the deployment toolkit.

2) Update the <DefaultItemSecurityTags> element with the identifiers of securitydimension values that you want to be applied by default.

3) Save and close the file.b) If your deployment of i2 Analyze includes an iBase connector, edit the configuration\environment\iBase\environment.properties file in the deployment toolkit. Updatethe ibase.security.context setting with the identifiers of security dimension values thatyou want to be applied by default.

c) If your deployment of i2 Analyze includes Connector Creator, update the contents of the<securityDimensionValueIds> element in the configuration file with the identifiers ofsecurity dimension values that you want to be applied by default.

d) If your deployment of i2 Analyze includes a custom data access on-demand solution, update itsbehavior to provide the items that it retrieves with the security dimension values that you wantto be applied by default.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.iap.admin.ingestion.doc/data_ingestion.html

2. If you have an Information Store, the records that it contains receive their security dimensionvalues during the ingestion process.To change the behavior of the ingestion process, update the contents of the<securityDimensionValues> element in the mapping file with the identifiers of securitydimension values that you want to be applied by default.

For more information about updating the default security dimension values that are applied duringingestion, see Information Store data ingestion.

3. Redeploy and restart your deployment of i2 Analyze.

Setting up WebSphere Application Server Liberty profile securityThe access levels that each user receives within i2 Analyze are determined by their membership ofgroups. The names of these groups must match the group permissions elements values that aredefined in your security schema.

Before you beginEnsure that the application server is stopped. To stop the application server, run the followingcommand:

setup -t stop

About this task

Important: WebSphere Application Server Liberty profile can handle multiple security approaches.Always use an approach that is appropriate to the environment that you are deploying into. Forinformation on WebSphere Application Server Liberty profile security approaches, see Securing theLiberty profile and its applications.

The following rules apply:

1. You must create groups in the WebSphere Application Server Liberty profile user registry whosenames exactly match the UserGroup attribute of the group permissions elements in the securityschema.

2. You must ensure that every user is a member of enough groups such that they are assigned adimension value and level from each access security dimension. A user does not require amapping to a grant security dimension.

To illustrate these rules, consider that the example security schema defines the following dimensionsand groups:

Group PermissionsUserGroup value

Group Permissions forDimension

Dimension values and level

Analyst Security Compartment Human Informants - update, Open SourceIntelligence - read_only

Clerk Security Compartment Open Source Intelligence - update

Controlled Security Level Controlled - update

Unclassified Security Level Controlled - update, Unclassified - update

Security Controller Grant Access Security Controller - update

To map to this security schema, the user group values in the table must match with the user groups inthe user repository.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.iap.admin.ingestion.doc/data_ingestion.html

http://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/twlp_sec.html?lang=en

http://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/twlp_sec.html?lang=en

Each user in this deployment must be in either of the "Analyst" or "Clerk" groups, and either of the"Controlled" or "Unclassified" groups.

Every deployment must contain an account that is associated with the administrator role. You cancreate a group in the user repository named "Administrator", or you can change the value of thesecurity.administrator.group property to the name of an existing group in the repository. Thesecurity.administrator.group property is in the environment-advanced.properties filefor each application, in the toolkit\configuration\environment\application directory.When an i2 Analyze user is a member of this group, they can access administrative features.

The following process is an approach to security in WebSphere Application Server Liberty profile thatuses a basic user registry.

Procedure

1. Create the users and groups in WebSphere Application Server Liberty profile for each of the grouppermissions elements in the security schema.a) In an XML editor, open the user.registry.xml file. You can find this file in the C:\IBM\i2analyze\deploy\wlp\usr\shared\config directory of your WebSphere ApplicationServer Liberty profile installation.

b) Use the following template to add your users and groups to the user.registry.xml file asthe first child of the <server> element:

<basicRegistry id="basic" realm="WebRealm"> <user name="" password="" /> <group name=""> <member name="" /> </group></basicRegistry>

Use the following information to populate the template:

• There is a <user> element for each user of the system. The <user> element's name andpassword attributes must be populated for that user.

• There is a <group> element with a name attribute that matches the name of each securitydimension in the security schema.

• The <group> elements are populated by <member> elements. For a user to be a member ofa group, a <member> element's name attribute must match that user's name attribute.

If you are using the example deployment, the user Jenny is a member of each group.


In the following example user.registry.xml, the users Analyst1, Clerk1, and Demo havebeen added into a subset of the groups. If you use the following example, log in as these usersto see the different permission levels of each group:

<basicRegistry id="basic" realm="WebRealm"> <user name="Jenny" password="{xor}FToxMSY="/> <user name="Analyst1" password="{xor}Lz4sLCgwLTs=" /> <user name="Clerk1" password="{xor}Lz4sLCgwLTs=" /> <group name="Analyst"> <member name="Jenny"/> <member name="Analyst1"/> </group> <group name="Clerk"> <member name="Jenny"/> <member name="Clerk1"/> </group> <group name="Controlled"> <member name="Jenny"/> <member name="Analyst1"/> </group> <group name="Unclassified"> <member name="Jenny"/> <member name="Clerk1"/> </group> <group name="Security Controller"> <member name="Jenny"/> </group> <group name="Administrator"> <member name="Jenny"/> </group> </basicRegistry>

The passwords are encoded by the WebSphere Application Server Liberty profile security utility.2. Use the WebSphere® Application Server Liberty profile securityUtility command to encode

the password for each user.a) Navigate to the bin directory of your WebSphere Application Server Liberty profile deployment

that is configured by the deployment toolkit. By default WebSphere Application Server Libertyprofile is deployed in the C:\IBM\i2analyze\deploy\wlp directory.

b) In a command prompt, run the following command:

securityUtility encode password

The encoded password is displayed in the command line. Record the encoded password,including the {xor} prefix, and use the encoded password as the password in theuser.registry.xml file.

For more information about using the security utility, see securityUtility command.3. Save and close the file.


https://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/rwlp_command_securityutil.html

4. To start the application server, open a command prompt and navigate to toolkit\scripts.Then, run the following command:

setup -t start


What to do nextTo test that your changes have worked, log in to i2 Analyze as one of the users that you added to theuser registry.

Controlling access to featuresIn addition to access to records, you can also control access to features or types of command. Torestrict access to features, you need to specify a command access control file.

You can use a command access control file to specify the permissions to assign to each user groupthat you specified in the security schema. The command access control file can be used to setpermissions that apply to i2 Analyze and, if applicable, to other custom client services.

Note: By default access control is not enabled, allowing all authenticated users access to all featuresexcept exporting search results to a CSV file. After you set command access control, you can revert tothis default state by ensuring that the CommandAccessControlResource property in the toolkit\configuration\fragments\opal-services\WEB-INF\classes\DiscoServerSettingsCommon.properties has no value.

The following permissions apply to the features and commands present in i2 Analyze:i2:Notes

Members of groups that have this permission can create and access notes on records. Withoutthis permission, records do not display the Notes tab, and the contents of any notes are notsearchable.

i2:RecordsUploadMembers of groups that have this permission can create and modify records and upload them tothe Information Store. Without this permission, records can be searched, and added to charts, butchanges to records cannot be shared.

i2:RecordsDeleteMembers of groups that have this permission can delete records that were originally uploaded byusing Analyst's Notebook Premium. Without this permission, records can be searched, added tocharts, and uploaded, but records cannot be removed from the Information Store.

i2:RecordsExportMembers of groups that have this permission can export records that are returned in searchresults to a CSV file. Without this permission, records that are returned in search results cannot beexported to a CSV file.

i2:ConnectorsIf you are using i2 Connect, members of groups that have this permission can view all i2 Connectconnectors. Without this permission, i2 Connect connectors are not visible unless individualconnectors are specified by using the i2:Connectors:connector-id permission.

i2:Connectors:connector-idIf you are using i2 Connect, members of groups that have this permission can view the i2 Connectconnector with the matching connector-id. Without this permission, the specified i2 Connectconnector is not visible. For example, i2:Connectors:example-connector.


Note: When you upgrade a system that has access to specific features enabled, ensure that you checkfor new features that require new permissions. Without updating your file to add permissions, accessto the features is denied to all users.

Setting up example command access controlThe example-command-access-control.xml file provides a demonstration of command accesscontrol that matches the example security schema. If you have an example deployment, you can usethis file to test command access control.

Procedure

To enable the command access control example:1. Copy the example-command-access-control.xml file from toolkit\configuration\examples\security-schema to toolkit\configuration\fragments\opal-services\WEB-INF\classes.

2. To specify the example file to be used in DiscoServerSettingsCommon.properties:a) Using a text editor, open the toolkit\configuration\fragments\opal-services\WEB-INF\classes\DiscoServerSettingsCommon.properties file.

b) Specify the example file as the value for the CommandAccessControlResource property:

CommandAccessControlResource=example-command-access-control.xml

c) Save the file.3. Follow the instructions in “Deploying i2 Analyze” on page 158 to enable command access control

and restart the system.

Setting up command access control to match your environmentYou can use command access control to determine the access to commands and features in yourdeployment. You can create a command access control file to match the specific needs of yourdeployment.

Before you beginBefore you create the command access control file, you must identify the user groups for use by yourdeployment. When you deploy i2 Analyze, the group names in your command access control file mustmatch the names of user groups in the security schema.

Procedure

1. Create a custom command access control file.a) Navigate to the directory in the deployment toolkit that contains the example security schema:toolkit\configuration\examples\security-schema\example-command-access-control.xml.

b) Make a copy of the example-command-access-control.xml file, give it an appropriatename, and then open it in an XML editor.

c) For each user group in your deployment, create a CommandAccessPermissions element thatspecifies the permissions you would like to grant.


For example:

<CommandAccessPermissions UserGroup="Analyst"> <Permission Value="i2:RecordsUpload" /> <Permission Value="i2:RecordsDelete" /></CommandAccessPermissions>

Note: For permissions that apply to all user groups, to prevent the need to give the permissionto each group individually, you can use a wildcard character:

<CommandAccessPermissions UserGroup="*"> <Permission Value="i2:Notes" /></CommandAccessPermissions>

d) Save the completed file to the configuration\fragments\opal-services\WEB-INF\classes directory in the deployment toolkit.

2. To set the command access control file to be used in the deployment:a) Using a text editor, open the toolkit\configuration\fragments\opal-services\WEB-INF\classes\DiscoServerSettingsCommon.properties file.

b) Specify your command access control file as the value for theCommandAccessControlResource property.For example:

CommandAccessControlResource=my-command-access-control.xml

c) Save the file.3. Follow the instructions in “Deploying i2 Analyze” on page 158 to enable command access control

and restart the system.

Configuring additional securityDepending on the requirements of the deployment, you can configure your deployment to useadditional security mechanisms.

Secure Sockets Layer connections with i2 AnalyzeSecure Sockets Layer (SSL) technology can be used to establish an encrypted connection between aclient and server. You can use SSL to ensure that communication between i2 Analyze components isencrypted.

Depending on your topology and requirements, you can configure SSL for the following connections:

• The client and the HTTP Server• The HTTP Server and WebSphere Application Server Liberty• WebSphere Application Server Liberty and the search indexing mechanism• WebSphere Application Server Liberty and the database management system

The versions of the TLS protocol that are supported by i2 Analyze are TLS V1.1, and TLS V1.2.

The instructions are intended for readers who are familiar with configuring i2 Analyze, securingnetwork connections, and managing SSL key authentication certificates. Refer also to thedocumentation for the individual components: IBM HTTP Server, IBM WebSphere Application ServerLiberty profile, Apache Solr, DB2, or Microsoft SQL Server.


The instructions are based on a sample scenario for a single-server deployment. The instructions useself-signed certificates to demonstrate working SSL configurations. In a production deployment, youmust use certificates that are signed by a trusted certificate authority.

The instructions use self-signed certificates to demonstrate working SSL configurations. In aproduction deployment, you must use certificates that are signed by a trusted certificate authority.

Attention: IBM takes reasonable steps to verify the suitability of i2 Analyze for Internetdeployment. However, it does not address lower-level issues such as guarding networksagainst penetration, securing accounts, protecting against brute force attacks, configuringfirewalls to avoid DoS or DDoS attacks, and the like. For your deployment of i2 Analyze, followindustry-standard practices and recommendations for protection of your systems. IBMaccepts no liability for the consequences of such attacks on your systems. This information isnot intended to provide instructions for managing key databases or certificates.

Connections between components of i2 AnalyzeDepending on your deployment pattern, i2 Analyze connections can involve the client, the HTTPserver, WebSphere Application Server Liberty, the database management system, and the searchindexing mechanism. You can choose to secure connections by using SSL.

The physical architecture and the network topology of an i2 Analyze deployment determine howappropriate it is to use SSL to secure its connections. For example, if two parts of the deployment areon a single machine that you physically control, then the need for SSL to secure the connectionbetween them might be reduced. If your deployment contains a firewall, then you might need toweigh the benefits of inspecting traffic against the benefits of encrypting it.

The following diagram shows the connections in a deployment that you can use SSL to secure:

IBM HTTP Server

Liberty

Clients

Server


Intelligence Portal

Analyst’s Notebook Premium

Database management system

Analysis Repository

Information Store

1.

3.

2.

Zookeeper4.

Solr

The numbered connections in the diagram are as follows:


1. The connections between the clients and the HTTP server.2. The connection between the HTTP server and Liberty.3. The connection between Liberty and the search indexing mechanism.4. The connection between Liberty and the database management system.

To secure connection 2, you must first secure connection 1. To secure connection 3, you must secureconnections 1 and 2.

Important:

• You can secure the connection to the search indexing mechanism by using SSL only if yourdeployment uses an Information Store with Opal services. In Opal services Apache Lucene, Solr,and ZooKeeper enable a high standard of search and indexing performance.

• ZooKeeper does not support SSL encrypted communication with clients. To secure the connectionto ZooKeeper, you can set up a secure connection by using an alternative method to SSL, such as anSSH tunnel.

• You can secure the connection to the database management system by using SSL only if yourdeployment uses one of the following options.

– The Analysis Repository on DB2– A Microsoft SQL Server– An Information Store on DB2 with the Opal services

SSL certificates for i2 AnalyzeSSL communication relies on encryption, keys, and certificates to initiate a secure connection. Thecertificates are stored in keystore files on the client and the server.

Certificates are exchanged to establish trust during the handshake process that initiates a secureconnection. When a certificate is granted through a certificate authority, that certificate can be trustedby the clients or applications that trust certificates that are signed by that authority. A public keycertificate that authenticates a server is stored in a keystore file on the server. Trusted certificateauthority certificates are stored in the client's truststore file.

As part of the SSL handshake process, certificates are exchanged that are signed by a trustedcertificate authority to verify that a certificate is authentic. The environment where you are deployingi2 Analyze might already have a well-defined certificate process that you can use to obtain certificatesand populate the required key and trust stores.

The examples in the following procedures use self-signed certificates to demonstrate working SSLconfigurations. In a production deployment, you must use certificates that are signed by a trustedcertificate authority.

If all of the public key certificates are signed by the same certificate authority, then you can add thecertificate authority's certificate to each of your truststores. If you have a number of certificates toauthenticate trust, you might have to add multiple certificates to your truststores.

In the examples, the self-signed certificate is created in a keystore, exported, and imported to therelevant truststore. When you configure SSL communication between components of i2 Analyze, youmust have the required certificates in the correct keystores. In the following procedures, examplescommands are provided for creating, exporting, and importing self-signed certificates.

SSL keystores for i2 AnalyzeTo use SSL to secure a connection between components, i2 Analyze requires Java KeyStore (JKS) orCertificate Management System (CMS) key database files depending on the components. The


keystore contains the certificate that acts as the identity of the server and the truststore contains alist of certificates that are trusted by a server.

A JKS file is a repository of security certificates that is used in SSL encryption. In WebSphereApplication Server and Apache Solr, a file with extension .jks serves as a keystore.

IBM Global Security Kit (GSKit) is a common component that is used by IBM HTTP Server and DB2 forits cryptographic and SSL capabilities. CMS is the native GSKit key database (keystore) that containscertificates. GSKit stores public and private keys and certificates in a key database. A key databaseconsists of a file with a .kdb extension and up to three other files with .sth, .rdb, and .crlextensions.

You must save the key database password to a stash file on your computer. Save this password sothat product components can use SSL without requiring any intervention from you.

The following diagram shows where these files are used in the components of i2 Analyze and theconnections between them.

IBM HTTP Server

Liberty

Clients

Server


Intelligence Portal



Analysis Repository

Information Store

Solr

Keystore Truststore

Keystore

Keystore

Truststore

Truststore Keystore

Truststore

The environment in which you are deploying i2 Analyze might already contain files that are candidatesfor use as keystores or truststores. If not, you must create the required files. The files that arerequired in the sample scenario that is described in the instructions are summarized by component inthe following list.

IBM HTTP ServerTo enable SSL connection, the HTTP server requires a CMS key database (*.kdb). The passwordfor this key database must be saved to a stash file. A certificate in the key database identifies theHTTP server and is used when clients connect to i2 Analyze so that they can authenticate theHTTP server. This key database is also used as a truststore to authenticate the certificate that itreceives from Liberty.

The i2 Analyze client's truststore, usually located in the operating system or web browser, is usedto authenticate the certificate that it receives from the HTTP server.


WebSphere Application Server LibertyThe Liberty server requires a keystore file (*.jks) and a truststore file (*.jks).

A certificate in the keystore identifies the Liberty server and is used to connect to the HTTP Server.The HTTP Server key database authenticates this certificate that it receives from Liberty.

The certificate in the Liberty truststore is used to authenticate certificates that are received fromthe database management system keystore and the Solr keystore.

SolrThe Solr server requires a keystore file (*.jks) and a truststore file (*.jks). Solr also requiresthat all Solr certificates are available in the Solr truststores and the Liberty truststore, so thatindividual nodes can trust one another, and Liberty can trust the Solr nodes.

The certificate in the Solr keystore identifies the Solr Server and is used to connect to Liberty.

The certificate in the Solr keystore also identifies each Solr node and is used to authenticatesecure connection within Solr itself, using the Solr truststore. The certificate in the Solr truststoreis used to authenticate the certificate that it received from the Solr keystore.


To enable SSL connection, the database management system requires a keystore to connect toLiberty. The type of keystore depends on the type of database management system. For moreinformation about SSL in your database management system, see “Configuring SSL for a DB2instance” on page 90 or “Configure SSL for a Microsoft SQL Server” on page 92.

The certificate in the database management system keystore identifies the databasemanagement system server and is used to connect to Liberty.

In the following procedures, example commands are provided for creating the keystores, certificates,and truststores to use with each component of i2 Analyze. The instructions contain details that arebased on a single-server deployment example.

Securing the connection between clients and the HTTP serveri2 Analyze supports the use of SSL to secure the connections between the clients and the HTTPServer. After you configure the connections between the clients and the HTTP server, you can opt toconfigure the connection between the HTTP server and WebSphere Application Server Liberty.

About this task

To connect to i2® Analyze by using SSL, the client workstation must first trust the HTTP serverbecause the client connects to i2 Analyze through the HTTP server. Trust is established through acertificate that is associated with the HTTP server and trusted by the client workstation.

The diagram shows the connection that you secure by completing the steps in the followingprocedures. It also shows the key database that is required.


Liberty

Clients

Server


SSL connection

IBM HTTP Server

Intelligence Portal


Truststore

Key database

You must modify the configuration of both the i2 Analyze application and the HTTP server to use SSLto secure the connection.

Creating the HTTP Server key database and certificateThe HTTP Server stores its associated certificates in a key database. You must create and populate akey database for the HTTP Server to use. In a test environment, you can create a self-signedcertificate to demonstrate SSL communication.

About this task

In i2 Analyze, SSL connections that involve the HTTP server require a key database that contains asigned certificate. In a production deployment, after you create the key database, you must populateit with a certificate that is signed by a trusted certificate authority. To demonstrate a workingconfiguration, you can create and use a self-signed certificate.

The IBM Key Management utility uses a GUI or Window Manager. If you do not have a GUI or WindowManager on your system, you can use the command line interface.

• For more information about the command line interface, see Managing keys from the command line.• For more information about the GUI, see Managing keys with the IKEYMAN graphical interface.

Procedure

1. Create a key database.For example, run the following command:

gskcapicmd -keydb -create -db "C:\IBM\i2analyze\i2-http-keystore.kdb" -pw "password" -stash

• Save a password for the key database to a stash file by using the -stash attribute.• Set -db location to the directory that contains the toolkit directory in your deployment. For

example, the file path in your deployment might be C:\IBM\i2analyze\i2EIA.


https://www.ibm.com/support/knowledgecenter/SSEQTJ_9.0.0/com.ibm.websphere.ihs.doc/ihs/cihs_ikeycmdline.html

https://www.ibm.com/support/knowledgecenter/SSEQTJ_9.0.0/com.ibm.websphere.ihs.doc/ihs/welc_ikeymangui.html

2. Create a self-signed certificate.For example, run the following command:

gskcapicmd -cert -create -db "C:\IBM\i2analyze\i2-http-keystore.kdb" -label "httpKey" -dn "CN=hostname" -pw "password"

Important: Set the value of CN to the fully qualified domain name for host name of the server thathosts the HTTP server. The URL that you use to connect to i2 Analyze must use the same value forthe host name as the value of the CN. The password is the one that you saved to the stash file instep 1.

3. Extract the certificate from the key database.For example, run the following command:

gskcapicmd -cert -extract -db "C:\IBM\i2analyze\i2-http-keystore.kdb" -label "httpKey" -target "C:\IBM\i2analyze\i2-http-certificate.cer" -pw "password"

Set the location of the certificate to the same directory as the key database.

What to do next

To enable SSL connections to i2 Analyze, the certificate that you added to, or created in, the keydatabase must be installed to be trusted on each client workstation.

Installing the certificate on client workstationsTo enable SSL connections to i2 Analyze, the certificate in the key database must be trusted on eachclient workstation.

About this task

The following steps describe how to install and trust the self-signed certificate on a Windows client.To install the certificate on Linux workstations, see the documentation for your operating system.

Procedure

1. Copy the certificate to any folder on the client workstation.2. To install the certificate, complete the following steps:

a) Double-click the certificate file.b) Click Install Certificate, and then click Next.c) Click Place all certificates in the following store.d) Click Browse, select Trusted Root Certification Authorities and click OK.e) Click Next, and then click Finish.

Note: If the certificate is self-signed, Windows displays a security warning because it cannotverify the self-signed certificate. Click Yes to accept the certificate.


Configuring the HTTP server for SSLIn a default deployment of i2 Analyze, SSL is disabled. To enable clients to connect through SSL, youmust modify the configuration of both the i2 Analyze application and the HTTP server.

Before you begin

Ensure that the following attributes of the <application> element in the topology.xml are setcorrectly:

• The http-server-host attribute is set to true• Ensure that the host-name attribute is set to the name of the machine that you are running Liberty

on.

For more information about modifying the topology file, see Modifying the topology.

Procedure

1. Stop the HTTP server.

Run the command to stop the HTTP server, C:\IBM\HTTPserver\bin\httpd -k stop.2. Edit the http-server.properties file.

a) Navigate to the toolkit\configuration\environment directory, and open the http-server.properties file in a text editor.

b) Set the http.server.ssl.enabled property to true.c) Set the http.server.keystore.file property to the location of the key database file of

your HTTP server.For example, C:/IBM/i2analyze/i2-http-keystore.kdb.

d) Set the http.server.keystore.certificate.label property to the label of the HTTPserver certificate that is in the key database file. For example, httpKey.

3. Open a command prompt and navigate to the toolkit\scripts directory.4. To deploy i2 Analyze with the edited http-server.properties file, and to install the SSL

configuration on the HTTP server, redeploy i2 Analyze.For more information, see Deploying i2 Analyze.The httpd.conf and plugin-cfg.xml files are updated to use the SSL configuration.

5. Restart the HTTP server.

Run the command to start the HTTP server, C:\IBM\HTTPserver\bin\httpd -k start.

What to do next

If you modified the FrontEndURI property in your deployment, you must update it to use the HTTPSprotocol. For more information about changing the FrontEndURI property, see “Specifying theconnection URI” on page 21.

To connect to the deployment from your client, see:

• “Connecting to the Intelligence Portal from a web browser” on page 83• “Connecting from Analyst's Notebook Premium” on page 83


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.go.live.doc/t_specifying_the_deployment_structure.html

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.go.live.doc/t_deploy.html

Testing SSL in an i2 Analyze deploymentTo ensure that a deployment allows only connections that use SSL, you can access it from a clientworkstation. The procedure is different depending on whether you connect through a web browser orAnalyst's Notebook Premium.

Before you begin

• The certificate that the client receives from the HTTP server must be trusted on the clientworkstation. For more information, see “Installing the certificate on client workstations” on page81.

• The Liberty application server must be running.

Connecting to the Intelligence Portal from a web browserIf the connection from a web browser to the HTTP server in an i2 Analyze deployment is correctlyconfigured to use SSL, you can use the HTTPS protocol to connect to the Intelligence Portal. If theapplication works as you expect, then the connection is secured by SSL.

Procedure

1. Open a web browser and connect to the Onyx services at http://host_name/apollo.host_name is the fully qualified domain name or IP address of the HTTP server, and matches theCommon Name value of the certificate.

If SSL is configured correctly, you are automatically redirected to https://host_name/apollo.2. Open a web browser and connect to the Opal services at http://host_name/opal

host_name is the fully qualified domain name or IP address of the HTTP server, and matches theCommon Name value of the certificate.

If SSL is configured correctly, you are automatically redirected to https://host_name/opal.

ResultsWhen you connect to the Intelligence Portal, the connection is secure.

Connecting from Analyst's Notebook PremiumIf the connection from Analyst's Notebook Premium to the HTTP server in an i2 Analyze deploymentis correctly configured to use SSL, you can use the HTTPS protocol to connect to the Onyx or the Opalservices. If the application works as you expect, then the connection is secured by SSL.

Before you begin

To connect to the Onyx or the Opal services, you must install the appropriate Analyst's NotebookPremium connector for your deployment. For more information about installing the Analyst'sNotebook Premium connectors, see Installing IBM i2 Analyst's Notebook Premium.

Procedure

1. Open Analyst's Notebook Premium and connect to the Onyx services at the URL https://host_name/apollo.host_name is the fully qualified domain name or IP address of the HTTP server, and matches theCommon Name value of the certificate.

Note: You cannot connect by using the HTTP protocol http://host_name/apollo.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/installing_anbp.html

2. Open Analyst's Notebook Premium and connect to the Opal services at the URL https://host_name/opal. host_name is the fully qualified domain name or IP address of the HTTPserver, and matches the Common Name value of the certificate.

Note: You cannot connect by using the HTTP protocol http://host_name/opal.

ResultsWhen you connect to i2 Analyze, the connection is secure.

Securing connections with LibertyYou can use SSL to secure the connection between WebSphere Application Server Liberty and theHTTP server, the database management system, and Solr. To secure connections in i2 Analyze, theHTTP Server must trust the certificate that it receives from Liberty and Liberty must trust thecertificates that it receives from the database management system and Solr.

About this task

i2 Analyze uses a Java keystore to contain the certificate that is required to identify the i2 Analyzeserver when it connects with the HTTP Server.

i2 Analyze uses a Java truststore to verify the certificates that are received from the databasemanagement system, and Solr.

For more information, see “SSL keystores for i2 Analyze” on page 77.

Creating the Liberty keystore and certificateWebSphere Application Server Liberty stores certificates in Java keystore files (.jks). Follow theprocedure to create a Java keystore, and export with the appropriate certificates.

About this task

The following steps use a self-signed certificate. In a production environment, use or request a signedcertificate for Liberty from a certificate authority. Place this certificate in the Liberty keystore.

Procedure

Create a keystore and self-signed certificate for Liberty by using the Java keytool utility.For more information, see keytool - Key and Certificate Management Tool.a) Open a command prompt and navigate to the i2analyze\deploy\java\bin directory.b) Create a keystore and certificate.

For example, run the following command:

keytool -genkeypair -alias "libertyKey" -keystore "C:\IBM\i2analyze\i2-liberty-keystore.jks" -dname "CN=hostname" -keyalg RSA -storepass "password"

Important: Ensure that you enter values as follows:

• Enter a unique alias.• Set the location of the keystore to the directory that contains the toolkit. In some deployments,

this path might be C:\IBM\i2EIA.• Set the value of CN to the host name of the server that hosts Liberty.• Assign a secure password.

c) Export the certificate from the Liberty keystore.


https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html


keytool -exportcert -alias "libertyKey" -keystore "C:\IBM\i2analyze\i2-liberty-keystore.jks" -file "C:\IBM\i2analyze\i2-liberty-certificate.cer" -storepass "password"

What to do next

If you are using self-signed certificates, add the certificate that you exported from your Libertykeystore to the HTTP server key database. For more information, see “Adding the Liberty certificate tothe HTTP key database” on page 87.

Configuring Liberty for SSLTo secure the connection between WebSphere Application Server Liberty and other components in i2Analyze, you must configure Liberty for SSL. Update the configuration with the location of a keystoreand truststore to use, and the passwords that are used to access the certificates that are containedwithin them.

Before you beginCreate a keystore and truststore for Liberty that contain the required certificates. For moreinformation, see “Creating the Liberty keystore and certificate” on page 84.

About this taskModify the i2 Analyze topology.xml file to specify that a secure connection must be used with theapplication server. Then, update the credentials.properties file to specify the password for theLiberty keystore and truststore files.

When the procedure is completed, it is only possible to connect to Liberty by the HTTPS protocol thatuses the secure port that is defined in the port definition properties file. The non-secure port cannotbe used.

Procedure

1. In an XML editor, open the toolkit\configuration\environment\topology.xml file.a) In the <application> element for the application server to secure, add the secure-connection attribute with the value of true.For example, add the attribute as highlighted in the following code:

<application http-server-host="true" name="opal-server" host-name="hostname" secure-connection="true">

Note: The host-name attribute value must match the common name that is associated withthe certificate for the application server.

b) Add the <key-stores> element as a child of the <application> element. Then, add a child<key-store> element.For your keystore, specify the type as key-store and file as the full path to your keystore.


For example, add the attribute as highlighted in the following code:

<application http-server-host="true" name="opal-server" host-name="hostname" secure-connection="true">... <key-stores> <key-store type="key-store" file="C:/IBM/i2analyze/i2-liberty-keystore.jks"/> </key-stores>...</application>

2. Specify the keystore passwords in the credentials file.a) In a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the password for the keystore that you specified in the topology.xml file.

ssl.keystore.password=password

3. Redeploy i2 Analyze so that the configuration changes are deployed to the application. For moreinformation, see Deploying i2 Analyze.

What to do next

You must secure the connection between the HTTP Server and Liberty. For more information, see“Securing the connection between the HTTP server and Liberty” on page 86.

Securing the connection between the HTTP server and LibertyUse SSL to secure the connection between the HTTP server and WebSphere Application ServerLiberty. The HTTP server key database and the Liberty truststore must contain the requiredcertificates.

Before you begin

• Secure the connection between clients and the HTTP server. For more information, see “Securingthe connection between clients and the HTTP server” on page 79.

• Configure Liberty for SSL. For more information, see “Configuring Liberty for SSL” on page 85.

About this taskThe diagram shows the connection that you secure by completing the following instructions. It alsoshows key database and keystore that are required.



Liberty

Clients

Server


Existing SSL connection

IBM HTTP Server

Intelligence Portal


Truststore

Key database

SSL connection

Keystore

Truststore

Adding the Liberty certificate to the HTTP key databaseTo secure the connection between the HTTP server and Liberty, you must add to the key database thecertificate that is required to enable trust with Liberty.

About this task

If you are using self-signed certificates, add to the HTTP server key database the certificate that youexported from your Liberty keystore.

In a production environment, import certificates into the HTTP key database to ensure that thecertificates that are received from Liberty are trusted.

Procedure

Add the certificate that you exported from the Liberty keystore into the HTTP Server key database.

For more information about exporting the certificate from the Liberty keystore, see “Creating theLiberty keystore and certificate” on page 84.


gskcapicmd -cert -add -db "C:\IBM\i2analyze\i2-http-keystore.kdb" -label "libertyKey" -file "C:\IBM\i2analyze\i2-liberty-certificate.cer" -pw "password"

Configuring the IBM HTTP ServerTo secure the connection between the i2 Analyze application server and the HTTP server, you mustarrange for the plugin-cfg.xml file to contain some necessary information.

Procedure

1. Stop the HTTP Server.


2. Navigate to the toolkit\configuration\environment directory, and open the http-server.properties file in a text editor.

3. Set the value of the http.server.ssl.require.secure.backend property to true, and thensave and close the file.

4. Open a command prompt, and navigate to the toolkit\scripts directory.5. To deploy i2 Analyze with the edited http-server.properties file, run the following

command:

setup -t configureHttpServer

The plugin-cfg.xml file is updated to enforce that a secure connection is available between theHTTP server and Liberty.

6. Navigate to the IBM\HTTPServer\plugins\iap\config directory, and open the plugin-cfg.xml file in an XML editor.

7. In each <ServerCluster> element, there is a child <Server> element. Ensure that each ofthese <Server> elements has a child <Transport> element that uses the https protocol.Depending on your deployment, update the <ServerCluster> element with the value "opal-server_cluster", or the <ServerCluster> element with the value "onyx-server_cluster" or both.a) Add the following code element to any of the child <Server> elements that do not have a child<Transport> element that uses the HTTPS protocol.

<Transport Hostname="hostname" Port="portnumber" Protocol="https"></Transport>

hostname is the same as the <Transport> element that uses the HTTP protocol andportnumber matches the value in the port definition properties for the application that you aresecuring. You can find this value in C:\IBM\i2analyze\toolkit\configuration\environment\opal-server or C:\IBM\i2analyze\toolkit\configuration\environment\onyx-server.

b) Add the following <Property> elements as children of each <Transport> element that usesthe HTTPS protocol:

<Property Name="Keyring" Value="C:/IBM/i2analyze/i2-http-keystore.kdb"/><Property Name="Stashfile" Value="C:/IBM/i2analyze/i2-http-keystore.sth"/>

Where the Value attributes contain the absolute paths to the keystore for the HTTP server andthe associated password stash file.

c) Save and close the plugin-cfg.xml file.

8. Restart the HTTP server.

What to do next

To ensure that the configuration is correct, look in the IBM\HTTPServer\plugins\iap\logs\plugin-cfg.log file.


If the <Property> elements for the keyring and stashfile are not present on each<Transport> element in your plugin-cfg.xml, the following error message is displayed:

ERROR: ws_transport:transportInitializeSecurity: Keyring was not set.ERROR: ws_transport:transportInitializeSecurity: No stashfile or keyring password given.

To resolve this issue, ensure that the <Property> elements for the keyring and stashfile arepresent on each <Transport> element in your plugin-cfg.xml.

Securing the connection between Liberty and the databaseIn an i2 Analyze deployment, Liberty connects to the database management system. You can securethe connection between Liberty and the database management system by using SSL.

Before you begin

Configure Liberty for SSL. For more information, see “Configuring Liberty for SSL” on page 85.

About this task

• You can secure the connection to the database if your deployment uses the Analysis Repository onDB2 or Microsoft SQL Server, or an Information Store with the Opal services.

• You cannot use SSL to secure the connection if you are using the Analysis Repository on Oracle, oran Information Store with the Onyx services.

Setting up an SSL connection to the database is a two-part process. First, you must configure yourdatabase instance to use SSL. Then, regardless of which database management system you use, youmust update the i2 Analyze configuration with the location of the truststore and the truststorepassword.

This diagram shows the connection that you secure by completing the steps in the followingprocedures. It also shows the keystore and truststore that are required.


IBM HTTP Server

Clients

Server

Intelligence Portal



Analysis Repository

Information Store

SSL connection

Liberty

i2 Analyze application Keystore

Truststore

Keystore

Configuring SSL for a DB2 instanceTo secure the connection between the i2 Analyze application server and the database instance, youmust change the configuration of both. The DB2 Server stores its associated certificates in a keydatabase, you must create and populate a key database for the DB2 Server to use.

About this task

In i2 Analyze, SSL connections that involve the DB2 server require a key database that contains asigned certificate. In a production deployment, after you create the key database, you must populateit with a certificate that is signed by a trusted certificate authority. To demonstrate a workingconfiguration, you can create and use a self-signed certificate. If you are using a certificate that issigned by a certificate authority, then you can add it to the key database, you do not need to completestep 2 to create the self-signed certificate.

Ensure that you understand the details that are provided in the DB2 documentation to configure SSLfor your DB2 instance. For more information, see Configuring Secure Sockets Layer (SSL) support in aDB2 instance.

For example, to run the commands in the procedure, set your Windows environment variable asfollows: set PATH=<path_to_gsk8_directory>\bin;<path_to_gsk8_directory>\lib;%PATH%

Procedure

1. Create a key database by using the GSKCapiCmd tool.a) Start the GSKCapiCmd tool.

Note: Start the GSKCapiCmd tool by using the gskcapicmd command. Follow the details thatare provided in the DB2 documentation link for the path to the command, the required libraries,and the command syntax.


https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.sec.doc/doc/t0025241.html

https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.db2.luw.admin.sec.doc/doc/t0025241.html

b) Create a key database.For example, to create the key file, run the following command:

gsk8capicmd_64 -keydb -create -db "C:\IBM\i2analyze\i2-db2-keystore.kdb" -pw "password" -stash


• Set the location of the key database to the directory that contains the toolkit. In somedeployments, this path might be C:\IBM\i2EIA.

• Assign a secure password.2. Create a self-signed certificate.

For example, to create the self-signed certificate, run the following command:

gsk8capicmd_64 -cert -create -db "C:\IBM\i2analyze\i2-db2-keystore.kdb" -label "dbKey" -dn "CN=hostname" -pw "password"

Note: The command is a simplified version of the command in the DB2 documentation without theO, OU, L, and C values that are not required for this example. Use a label of dbKey to align withhttpKey and libertyKey used in the HTTP Server and Liberty keystores. Ensure that thecommon name in the certificate matches the fully qualified domain name of the database instanceserver.

3. Extract the certificate from the key database.For example, to extract the certificate, run the following command:

gsk8capicmd_64 -cert -extract -db "C:\IBM\i2analyze\i2-db2-keystore.kdb" -label "dbKey" -target "C:\IBM\i2analyze\i2-db2-certificate.cer" -pw "password"

4. Configure DB2 for SSL.For example, to configure DB2 for SSL only, run the following commands:

db2 "UPDATE DBM CFG USING SSL_SVR_KEYDB C:\IBM\i2analyze\i2-db2-keystore.kdb"db2 "UPDATE DBM CFG USING SSL_SVR_STASH C:\IBM\i2analyze\i2-db2-keystore.sth"db2 "UPDATE DBM CFG USING SSL_SVR_LABEL dbKey"db2 "UPDATE DBM CFG USING SSL_SVCENAME 50001"db2set DB2COMM=SSL

5. Navigate to the toolkit/scripts directory to run setup commands.

setup -t stopdb2stopdb2startsetup -t start

What to do next

After you configure DB2, you can check the db2diag.log file to ensure that there are no errors withyour SSL configuration.


Configure SSL for a Microsoft SQL ServerTo secure the connection between the i2 Analyze application server and the database instance, youmust change the configuration of both. The Microsoft SQL Server stores its associated certificates andyou must create or obtain certificates for the Microsoft SQL Server to use.

Before you configure SSL for your SQL Server instance, obtain a certificate to use with it. In ademonstration system, you can create a self-signed certificate by following the instructions inCreating and Installing SSL certificate, in Enabling client side SSL encryption to SQL Server.

Note: Ensure that the common name in the certificate matches the fully qualified domain name of theSQL Server instance.

To configure SSL for your SQL Server instance, see Enable Encrypted Connections to the DatabaseEngine (SQL Server Configuration Manager). Then, extract your certificate in the DER-encoded binaryformat as a .cer file. For more information, see Export a certificate.

To verify that you configured your SQL Server instance correctly, see Test the connectivity withencryption in Enabling client side SSL encryption to SQL Server.

Configuring i2 Analyze to connect to a database instance using SSLTo connect to a database instance by using SSL, i2 Analyze must be able to trust and verify thecertificate that it receives from the database server. Those requirements mean that the certificatemust also be stored in a truststore that i2 Analyze can access.

Before you begin

• Ensure that you configured Liberty for SSL. For more information, see “Configuring Liberty for SSL”on page 85.

• Your database management system must be configured for SSL. For more information, see:

– “Configuring SSL for a DB2 instance” on page 90– “Configure SSL for a Microsoft SQL Server” on page 92

About this task

i2 Analyze uses a Java truststore to verify the certificate from the database server, and so you mustcreate a truststore on your i2 Analyze server that contains the trusted certificates for your database.You can use the same truststore that you created for Liberty. For more information, see “Creating theLiberty keystore and certificate” on page 84.

For Liberty to communicate with the secured database, in the topology database element you mustspecify the secure connection attribute to be true and the name of the truststore that contains thedatabase certificate. Also, specify the correct port number, which corresponds to the SSL port for thedatabase. In the credentials.properties file, the correct password for the specified truststoremust be added.

Procedure

1. Create the Liberty truststore and import into the truststore the certificate that you exported fromthe database management system.For example, run the following command:

keytool -importcert -alias "dbKey" -file C:\IBM\i2analyze\i2-db2-certificate.cer -keystore "C:\IBM\i2analyze\i2-liberty-truststore.jks" -storepass "password"


https://blogs.msdn.microsoft.com/docast/2016/04/28/enabling-client-side-ssl-encryption-to-sql-server-2/

https://msdn.microsoft.com/en-us/library/ms191192%28v=sql.110%29.aspx#configureserverconnections

https://msdn.microsoft.com/en-us/library/ms191192%28v=sql.110%29.aspx#configureserverconnections

https://technet.microsoft.com/en-us/library/cc730988%28v=ws.11%29.aspx

https://blogs.msdn.microsoft.com/docast/2016/04/28/enabling-client-side-ssl-encryption-to-sql-server-2/

Enter yes in response to the query, Trust this certificate?



this path might be C:\IBM\i2EIA.• Assign a secure password.

2. Modify the i2 Analyze topology to use SSL for its database connection.a) In an XML editor, open the toolkit\configuration\environment\topology.xml file.b) In the <database> element for the database that you want to connect to with SSL, add thesecure-connection="true" attribute.

c) In the same <database> element, add the trust-store attribute with the location of thetruststore.The sample scenario uses a common truststore for Liberty that you created in step1 and definein the <key-stores> element as shown in the example. Alternatively, you can use a specifictruststore that is defined for DB2.

<database database-type="InfoStore" dialect="db2" instance-name="DB2" database-name="ISTORE" edition="db2aese" xa="false" id="infostore" host-name="hostname" port-number="50001" version="10.5" secure-connection="true" trust-store="C:/IBM/i2analyze/i2-liberty-truststore.jks"/>

d) In same element, ensure that the following attribute values are correct:

• The host-name attribute value must match the common name that is associated with thecertificate for the database.

• The port attribute value must match value of the port number when you configured DB2 forSSL.

3. Specify the truststore password in the credentials file:a) In a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the password for the truststore:

• For the Analysis Repository, enter a password for the db.write1.truststore.passwordcredential.

• For the Information Store, enter a password for thedb.infostore.truststore.password credential.

What to do next

Redeploy i2 Analyze so that the configuration changes are deployed to the application. For moreinformation, see Deploying i2 Analyze.



Testing the deploymentTo test the SSL connection between i2 Analyze and the database management system, connect to i2Analyze. After you connect, ensure that you can create, browse, and search for data.

Procedure

1. Connect to your data store by using one of the supported clients. For more information, seeConnecting clients.

2. Create, browse, and search for data to ensure that the database connection is working.

Securing the connection between Liberty and SolrAn i2 Analyze deployment with Opal services uses Apache Solr for the text indexing and searchcapabilities. You can secure the connection between Liberty and Solr by using SSL.

Before you begin

Configure Liberty for SSL. For more information, see “Configuring Liberty for SSL” on page 85.

Create the Liberty truststore. For more information, see “Configuring i2 Analyze to connect to adatabase instance using SSL” on page 92.

About this task

Setting up an SSL connection to the Solr is a two-part process. First, you must configure Solr to useSSL. Then, you must update the i2 Analyze configuration with the location of the Solr keystores andpasswords.

The certificate in the Solr keystore is used to identify the Solr server. The certificate in the Libertytruststore is used to authenticate certificates that are received from the Solr keystore.

The certificate in the Solr keystore is also used for authentication within Solr itself, using the Solrtruststore. The certificate in the Solr truststore is used to authenticate the certificate that it receivedfrom the Solr keystore.

The diagram shows the connection that you can secure by completing following the followinginstructions. It also includes the keystores and truststores that are required for a single server.


https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.deploy.example.doc/connecting_to_clients.html

IBM HTTP Server

Clients

Server

Intelligence Portal


SSL connection

Liberty


Solr

Keystore

Truststore Keystore

Truststore



ZooKeeper

Note: These instructions do not cover securing the ZooKeeper connection. ZooKeeper does notsupport SSL encrypted communication with clients. To secure the connection to ZooKeeper, you canset up a secure connection by using an alternative method to SSL, such as an SSH tunnel.

Creating Solr keystores and certificatesSolr stores its associated certificates in keystore and truststore files (.jks). The certificate in the Solrkeystore identifies the server that Solr is deployed on. This certificate is checked against thecertificate in the Liberty truststore when Liberty attempts to connect to Solr.

About this task

To ensure that communication between the i2 Analyze application server and the Solr index issecured, create a keystore and truststore for Solr.

The following steps use a self-signed certificate. In a production environment, use or request a signedcertificate for Liberty from a certificate authority. Place this certificate in the Liberty keystore.

For Solr to work correctly, there must be a keystore for each server on which Solr is deployed. Eachkeystore contains a certificate that identifies the server. Solr also requires that all Solr certificates areavailable in the Solr truststore and the Liberty truststore, so that individual nodes can trust oneanother, and Liberty can trust the Solr nodes.

Depending on the topology of your deployment, you might need to create a separate keystore andtruststore for each Solr node.

Procedure

1. Create a keystore and export a certificate for Solr by using the Java keytool utility.For more information, see keytool - Key and Certificate Management Tool.a) Create a keystore and a certificate.




keytool -genkeypair -alias "solrKey" -keystore "C:\IBM\i2analyze\i2-solr-keystore.jks" -dname "CN=hostname" -keyalg RSA -storepass "password"


• Set the value of CN to the host name of the server that hosts Solr.• Set the location of the key database to the directory that contains the toolkit. In some

deployments, this path might be C:\IBM\i2EIA.• Set the storepass attribute to be a secure password for the keystore.

Enter the key password for the Solar key or press the Return key to confirm that the keypassword is the same as keystore password.

b) Export the certificate from the Solr keystore.For example, run the following command.

keytool -exportcert -alias "solrKey" -keystore "C:\IBM\i2analyze\i2-solr-keystore.jks" -file "C:\IBM\i2analyze\i2-solr-certificate.cer" -storepass "password"

Enter the password that you set for the keystore in the previous step.2. Create the Solr truststore and import the required certificates.

If you are using a self-signed certificate, import the certificate that you exported from the Solrkeystore in step 1b.


keytool -importcert -alias "solrKey" -keystore "C:\IBM\i2analyze\i2-solr-truststore.jks" -file "C:\IBM\i2analyze\i2-solr-certificate.cer" -storepass "password"

In response to the prompt, enter yes to trust the certificate.

Configuring an SSL connection to SolrTo secure the connection between the i2 Analyze application server and Solr, you must change theconfiguration of both. i2 Analyze manages the configuration of Solr, the i2 Analyze configuration mustdefine the keystore and truststore for Solr.

Before you begin

• Ensure that you configured Liberty for SSL. For more information, see “Configuring Liberty for SSL”on page 85.

• You must have the appropriate keystore set up for your Solr deployment. For more information, see“Creating Solr keystores and certificates” on page 95.

About this task

i2 Analyze uses a Java truststore to verify the certificate from the Solr server, and so you must createor reuse a truststore on your i2 Analyze server to contain the trusted certificates for your Solr system.You can use the same truststore that you created for Liberty to hold the certificate from the databasemanagement system. For more information, see “Configuring i2 Analyze to connect to a databaseinstance using SSL” on page 92.


Procedure

1. Ensure that the Liberty instance is stopped before you implement the configuration changes, byrunning the command: setup -t stop

Ensure that the Liberty instance is stopped, otherwise you encounter an error if you try to run thecommand when you complete the configuration changes.

2. Create the truststore and import the certificate that you exported from the Solr keystore into thetruststore.

This truststore can be the truststore that you created for the certificate that you exported from thedatabase management system. Alternatively, you create a new truststore if the file does not exist.


keytool -importcert -alias "solrKey" -keystore "C:\IBM\i2analyze\i2-liberty-truststore.jks" -file "C:\IBM\i2analyze\i2-solr-certificate.cer" -storepass "password"




this path might be C:\IBM\i2EIA.• Assign a secure password.

3. Modify the topology.xml file to specify SSL for its Solr connection.a) In an XML editor, open the toolkit\configuration\environment\topology.xml file.b) In the <solr-cluster> element for the Solr cluster that you want to connect to with SSL, add

the secure-connection attribute with the value of true.For example, add the attribute as highlighted in the following code:

<solr-cluster id="is_cluster" zookeeper-id="zoo" secure-connection="true">

c) Add the key-store and trust-store attributes to either the <solr-cluster> or to the<solr-node> element.Add the attribute values as defined:key-store

The path to the Solr keystore. For more information, see “Creating Solr keystores andcertificates” on page 95. Reference step 1a.

trust-storeThe path to the Solr truststore. For more information, see “Creating Solr keystores andcertificates” on page 95. Reference step 2a.

• For example, add the attribute as highlighted in the <solr-clusters> element:

<solr-cluster id="is_cluster" zookeeper-id="zoo" secure-connection="true" key-store="C:\IBM\i2analyze\i2-solr-keystore.jks" trust-store="C:\IBM\i2analyze\i2-solr-truststore.jks">


• For example, add the attribute as highlighted in the <solr-node> element:

<solr-node memory="2g" data-dir="C:\IBM\i2analyze\data\solr" host-name="hostname" id="node1" port-number="8983" key-store="C:\IBM\i2analyze\i2-solr-keystore.jks" trust-store="C:IBM\i2analyze\i2-solr-truststore.jks">

Note: The host-name attribute value must match the common name that is associated withthe certificate for Solr. For more information, see “Creating Solr keystores and certificates” onpage 95. Reference step 1a.

4. Modify the topology.xml file to add the Liberty truststore.Add a child <key-store> element. For your keystore, specify the type as trust-store andfile as the full path to your truststore.For example, add the element as highlighted in the following code:

<application http-server-host="true" name="opal-server" host-name="hostname" secure-connection="true">... <key-stores> <key-store type="key-store" file="C:\IBM\i2analyze\i2-liberty-keystore.jks"/> <key-store type="trust-store" file="C:\IBM\i2analyze\i2-liberty-truststore.jks"/> </key-stores>...</application>

5. Specify the truststore and keystore passwords in the credentials file.a) In a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the passwords for the Solr keystore and truststore that you specified in the topology file.

solr.truststore.password=passwordsolr.keystore.password=password

c) Enter the password for the Liberty truststore that you specified in the topology file.

ssl.truststore.password=password

What to do next

Redeploy i2 Analyze so that the configuration changes are implemented in i2 Analyze and Solrconfiguration. For more information, see Deploying i2 Analyze.

Connect to your Information Store. For more information, see Connecting IBM i2 Analyst's NotebookPremium to IBM i2 Analyze.

Search for data to ensure that the Solr connection is working.

Resources for system protectionIn order to protect your system from external forces, you must implement system controls thatprevent or mitigate the effect of attacks. Although IBM does not manage login configuration, and the



https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.anb.admin.doc/connecting_to_anbpremium.html

https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.anb.admin.doc/connecting_to_anbpremium.html

responsibility for protection of your network from external attack remains yours, the followingcommunities provide a starting point for your investigation into preventative methods.The Open Web Application Security Project

The Open Web Application Security Project Foundation is a not-for-profit organization that isdedicated to enabling organizations to conceive, develop, operate and maintain applications thatcan be trusted. In particular, see https://www.owasp.org/index.php/Blocking_Brute_Force_Attacks and https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Password_Complexity.

SANS InstituteThe System-Admin, Audit, Network and Security Institute is the largest source for informationsecurity training and security certification in the world. It also develops, maintains, and makesavailable at no cost, the largest collection of research documents about various aspects ofinformation security, and it operates the Internet's early warning system - the Internet StormCenter. In particular, see https://www.sans.org/security-resources/policies/general/pdf/password-construction-guidelines

Common Weakness Enumeration

CWE™ is a community-developed list of common software security weaknesses. It serves as acommon language, a measuring stick for software security tools, and as a baseline for weaknessidentification, mitigation, and prevention efforts.

In particular, see http://cwe.mitre.org/top25/index.html#CWE-307.

Configuring SPNEGO single sign-on for i2 AnalyzeThe following section describes how to configure IBM i2 Analyze with Simple and Protected GSS-APINegotiation Mechanism (SPNEGO) single sign-on. The instructions detail how to configure SPNEGOsingle sign-on with an existing deployment of i2 Analyze.

There are many different single sign-on technologies. This section defines a SPNEGO single sign-onsetup with workstations that are members of the same Microsoft Active Directory domain. i2 Analyzeuses the users and groups in Active Directory to determine the authorization of users.

The instructions assume that the following prerequisites are installed and accessible:

• A Microsoft Windows® Server running an Active Directory Domain Controller and associatedKerberos Key Distribution Center (KDC).

• A Microsoft Windows® domain member (client) with a web browser that supports the SPNEGOauthentication mechanism.

• A working deployment of i2 Analyze that can be accessed by users in Active Directory.

For information on the prerequisites that are required, see the Before you begin section of ConfiguringSPNEGO authentication in Liberty in IBM Knowledge Center.



https://www.owasp.org/index.php/Blocking_Brute_Force_Attacks


https://www.owasp.org/index.php/Authentication_Cheat_Sheet#Password_Complexity


https://www.sans.org/find-training/


https://www.giac.org/

https://isc.sans.edu/


https://www.sans.org/security-resources/policies/general/pdf/password-construction-guidelines


http://cwe.mitre.org/top25/index.html#CWE-307

https://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/twlp_spnego_config.html


Intended audience

This section is intended for readers who are familiar with configuring and managing domaincontrollers, Microsoft Active Directory, and have an understanding of SPNEGO single sign-on.

i2 Analyze with SPNEGO single sign-onBy following the IBM i2 Analyze Deployment Guide, i2 Analyze is configured to use user names andpasswords that are stored in a file-based registry. By configuring the deployment to use SPNEGOsingle sign-on, a user is logged in through the domain client workstation that they are logged in to.

After a user logs in to a single sign-on environment, they are authenticated with any systems that theyhave access to. i2 Analyze can be configured to allow authentication through SPNEGO single sign-on,with authorization through Active Directory.

SPNEGO single sign-on enables users to log in to a Microsoft domain controller, and be authenticatedwithin the single sign-on environment. In SPNEGO single sign-on, to change the user that is logged into i2 Analyze, the user must log out of the workstation, and a new user must log in to the workstation.

SPNEGO single sign-on planningPlanning an implementation of SPNEGO single sign-on with i2 Analyze ensures that the system youcreate matches the needs of your organization. It is important to understand the organizationalrequirements and your environment before you begin to plan.

Before you start implementing the solution, ensure that you understand the following aspects of theproposed system:

• What SPNEGO single sign-on is, and the implications of implementing it in your environment. Formore information, see Single sign-on for HTTP requests using SPNEGO web authentication in IBMKnowledge Center.

• The physical architecture that is required to use SPNEGO single sign-on.• The value of the UserGroup attribute of each <GroupPermissions> element to use with your i2

Analyze deployment. For more information, see the i2 Analyze Security White Paper.

i2 Analyze with SPNEGO single sign-on modelConfiguring i2 Analyze to use SPNEGO single sign-on changes the way that users authenticate withthe platform. A deployment that uses SPNEGO single sign-on requires the user to access i2 Analyzeon a workstation that is a member of the same domain as i2 Analyze.

Authentication

When i2 Analyze is configured to use SPNEGO single sign-on, the authentication sequence betweenthe client and the platform matches the following steps and the associated diagram:

1. The client attempts to connect to WebSphere Application Server Liberty profile with an HTTP/Post/Get request.

2. WebSphere Application Server Liberty profile returns HTTP 401 with a Negotiate header.3. The client requests a SPNEGO token from the domain controller.4. The domain controller returns a SPNEGO token to the client.5. The client attempts to connect to WebSphere Application Server Liberty profile with an HTTP/Post/Get request and the SPNEGO token.

6. On successful authentication, the client receives a Lightweight Third-Party Authentication (LTPA)token in a cookie. During normal operation, the client passes the cookie back to i2 Analyze.


http://www.ibm.com/support/knowledgecenter/SSEQTP_8.5.5/com.ibm.websphere.nd.doc/ae/csec_SPNEGO_explain.html

http://www.ibm.com/support/docview.wss?uid=swg27042326

Authorization

After the user is authenticated, they are logged in to i2 Analyze. To define the data that the user hasaccess to, the user must be authorized by i2 Analyze.

For authorization, the i2 Analyze application communicates with Active Directory, through theWebSphere Application Server Liberty profile user registry APIs to retrieve information about thecurrent user. The principal provider then maps the retrieved information to security dimension valuesin the i2 Analyze security schema.

The following diagram shows how authorization works in i2 Analyze:


Implementing SPNEGO single sign-onSPNEGO single sign-on enables users to log in to a domain client workstation, and be authenticatedwith i2 Analyze. Complete any configuration changes to i2 Analyze, and test the system.

Before you begin

• For information on the prerequisites that are required, see the Before you begin section ofConfiguring SPNEGO authentication in Liberty.

• If you previously deployed i2 Analyze with basic authentication, you must remove or comment outthe complete <basicRegistry> element from your user registry.

About this task

Populate Active Directory with the correct users and groups for your environment. Then, complete theconfiguration steps for WebSphere Application Server Liberty profile and the i2 Analyze application.Redeploy i2 Analyze, and connect to i2 Analyze from a client workstation.

Configuring Microsoft Active DirectoryThe users that are in Microsoft Active Directory are used to authenticate with i2 Analyze. The groupsthat are in Active Directory are used for authorization in i2 Analyze.

About this task

Create Microsoft Active Directory groups that match the value of the UserGroup attribute of each<GroupPermissions> element in the i2 Analyze security schema file.

The groups that you create in Microsoft Active Directory are used for authorization in i2 Analyze. Toidentify the groups correctly, you must ensure that the names of groups in Active Directory exactly



match the value of the UserGroup attribute of each <GroupPermissions> element in the securityschema.

Note: The security schema that the deployment uses is defined in theApolloServerSettingsMandatory.properties file. The security schema, and properties filesare in the toolkit\configuration\fragments\common\WEB-INF\classes directory.

In a single sign-on setup, the following users must be present in Active Directory:

• A user for the server that hosts the i2 Analyze application, that is mapped to a Kerberos ServicePrincipal Name (SPN).

• The users that are used to log in to i2 Analyze.

To authorize users, the following groups must be present in Active Directory:

• A group for each of the group permission elements in the i2 Analyze security schema.• A group for administrators.

Procedure

1. Create the Microsoft Active Directory groups.

For more information, see How to Create a Group in Active Directory.

a) Open the Microsoft Active Directory groups controller.b) Create groups whose names exactly match the value of the UserGroup attribute of each<GroupPermissions> element in the i2 Analyze security schema file.

2. Create any Microsoft Active Directory users.Create user accounts that can be used to log in to i2 Analyze.

For more information, see How to Create a Domain Account in Active Directory.3. Make each user a member of the correct groups for your environment.

The groups that the user is a member of in Active Directory are used for authorization in i2 Analyze.

For more information, see Adding Users to an Active Directory Group.

ResultsThe users that can access i2 Analyze are created, and are members of the groups that define theiraccess levels.

Configuring WebSphere Application Server Liberty profileCreate the Kerberos service principal name (SPN) and keytab file for the server that hosts WebSphereApplication Server Liberty profile that runs the i2 Analyze application. Edit the WebSphere ApplicationServer Liberty profile configuration to use SPNEGO single sign-on and the Active Directory registry.

Before you beginTo use SPNEGO single sign-on with the Liberty server that is deployed by i2 Analyze and otherWebSphere Application Server servers, each server must use the same LTPA keys file. For moreinformation about LTPA, see Authentication - LTPA.

The value that is set for the ltpakeys.password property in the credentials.properties filemust match the password that is required to import the keys from the LTPA keys file. If you changethe password in the credentials.properties file, you must redeploy i2 Analyze for the passwordchange to take effect.


https://msdn.microsoft.com/en-us/library/aa545347%28v=cs.70%29.aspx

https://msdn.microsoft.com/en-gb/library/aa545262%28v=cs.70%29.aspx

https://msdn.microsoft.com/en-us/library/ee796906%28v=cs.20%29.aspx

http://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/cwlp_authentication.html%23cwlp_authentication__ltpa?lang=en

Procedure

1. Configure WebSphere Application Server Liberty profile to use SPNEGO single sign-on by using thefirst two steps in Configuring SPNEGO authentication in Liberty as a reference.a) Create the Kerberos SPN and keytab files on the domain controller.

Note: Ensure that the host file on the Active Directory server uses the full host name, includingthe domain name, for the i2 Analyze server. Remove any entries that use only the short namefor the i2 Analyze server. The value in the host file must match the value that is used for theSPN.

b) Configure the server that hosts WebSphere Application Server Liberty profile, and WebSphereApplication Server Liberty profile.

2. Configure WebSphere Application Server Liberty profile to use the Microsoft Active Directoryregistry by using the instructions in Configuring LDAP user registries with Liberty as a reference.a) Complete step 1 to add the features to the server.xml file.b) Complete step 4 by using the Microsoft Active Directory Server example to populate the<ldapRegistry> element.

Note: This information does not cover the configuration of Secure Sockets Layer (SSL) betweenWebSphere Application Server Liberty profile and Active Directory. Do not include the <ssl>and <keyStore> elements from the example, in your server.xml.

c) Ensure that the mapping between Active Directory and the i2 Analyze security schema iscorrect. Add the following code after the <ldapRegistry> element in the server.xml file:

<federatedRepository> <primaryRealm name=""> <participatingBaseEntry name=""/> <groupSecurityNameMapping inputProperty="cn" outputProperty="cn"/> </primaryRealm></federatedRepository>

Populate the empty name attribute values by using the following information:

• The <primaryRealm> element's name attribute has the same value as the realm attributeof the <ldapRegistry> element.

• The <participatingBaseEntry> element's name attribute has the same value as thebaseDN attribute as the <ldapRegistry> element.

By default, all requests to access protected resources use SPNEGO authentication. If you previouslydeployed i2 Analyze with basic authentication, you must ensure that the basic registry is not presentin the user.registry.xml file.3. Using an XML editor, either remove or comment out the complete <basicRegistry> element in

the i2analyze\deploy\wlp\usr\shared\config\user.registry.xml file.

Configuring the i2 Analyze applicationUpdate the web.xml file that is used in the onyx-services-ar application to enable SPNEGOauthentication. Then, set the security administrator group to the value used in Microsoft ActiveDirectory.

About this taskUse the following steps to update the web.xml that applies to the onyx-services-ar applicationserver.



http://www.ibm.com/support/knowledgecenter/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/ae/twlp_sec_ldap.html

Procedure

1. Edit the web.xml file.a) Using a text editor, open the toolkit\configuration\fragments\onyx-services-ar\WEB-INF\web.xml file.

b) Comment out the following lines from the web.xml file:

<filter> <filter-name>SSOAuthenticationFilter</filter-name> <description> Only for use in SSO. Must be removed if using SPNEGO Kerberos authentication. </description> <filter-class> com.i2group.apollo.servlet.SSOAuthenticationFilter </filter-class></filter>

<filter-mapping> <filter-name>SSOAuthenticationFilter</filter-name> <url-pattern>/services/InfoService</url-pattern></filter-mapping>

2. Using a text editor, open toolkit\configuration\environment\server\environment-advanced.properties. Edit the value of the security.administrator.group property tothe name of the group in Active Directory to use for administrators. For example, i2Admins.

The mapping to the administrator group must be in terms of the Common Name that is defined inthe <participatingBaseEntry> element of the <federatedRepository> element in theserver.xml file. For more information about the <federatedRepository> element, see“Configuring WebSphere Application Server Liberty profile” on page 103.

Redeploying i2 AnalyzeAny time that you change the configuration of i2 Analyze, you must redeploy the system.

Procedure

1. Open a command prompt and navigate to toolkit\scripts.2. Ensure that the application servers are stopped. To stop the application server, run the following

command:

setup -t stop

3. To deploy i2 Analyze components, run the following command:

setup -t deploy

Use the information in Troubleshooting the deployment process to ensure that i2 Analyze isdeployed successfully.



setup -t start


Testing i2 Analyze with SPNEGO single sign-on on the client workstationTo test the SPNEGO single sign-on setup, connect to i2 Analyze from a domain client workstation. Theuser that is logged in to the domain client is logged in to i2 Analyze.

Before you begin

• Your web browser must be configured according to step 3 in Configuring SPNEGO authentication inLiberty.

• You must be logged in to the client workstation as one of the users in the domain controller, who isin at least one group per security dimension in the i2 Analyze security schema.

About this taskLog in to the client workstation as users with different access levels. For each user, complete thefollowing steps to demonstrate that authorization is working correctly when you are using SPNEGOsingle sign-on.

Procedure

1. Open your web browser, and navigate to http://host_name/apollo (where host_name is thefully qualified domain name or IP address of the server that hosts the i2 Analyze application).

2. Create, browse, and search for data, to ensure that your are authenticated and authorized with theplatform correctly.

Note: When you create items, ensure that the permissions are set up so that you have access toview them.

Resources for system protectionIn order to protect your system from external forces, you must implement system controls thatprevent or mitigate the effect of attacks. Although IBM does not manage login configuration, and theresponsibility for protection of your network from external attack remains yours, the followingcommunities provide a starting point for your investigation into preventative methods.The Open Web Application Security Project




















Configuring X.509 client certificate authentication with i2 AnalyzeYou can enable your deployment to use X.509 client certificate authentication. After successfulconfiguration, users can log in to i2 Analyze with client certificates instead of user names andpasswords.

After you configure client certificate authentication, a user does not need to enter a user name andpassword separately. Each certificate is associated with a single user in the user registry to enableauthentication. Anyone that has access to a client certificate can log in to i2 Analyze as the userassociated with that certificate without entering a password.

To enable a user to log in using a client certificate, the client certificate must be installed in the user'spersonal certificate store on the workstation they are using to access i2 Analyze. After the clientcertificate is installed in the personal certificate store, the user can use the certificate to log in to i2Analyze through the Intelligence Portal or Analyst's Notebook Premium.

When a user connects to the Intelligence Portal, the web browser prompts the user to choose thecertificate to use to log in to i2 Analyze. If the user is using Analyst's Notebook Premium, the userchooses the certificate to use to log in when they open a connection to the Analysis Repository orInformation Store.

Intended audience

This information is intended for readers who are familiar with managing key databases andcertificates, user authentication mechanisms, and the i2 Analyze toolkit.

Prerequisites

The starting point for configuring client certificate authentication is a deployment of i2 Analyze that isconfigured to use Secure Sockets Layer on connections to the HTTP Server, and between the HTTPServer and Liberty. For more information about configuring Secure Sockets Layer on connections tothe HTTP Server, see Configuring Secure Sockets Layer with i2 Analyze.


Client certificatesThe client certificates that are used to authenticate users must be signed by a certificate authoritythat is trusted by the i2 Analyze server.

The common name in a client certificate must match a user name in the i2 Analyze user registry. Auser that selects such a certificate logs in to i2 Analyze as the corresponding i2 Analyze user.



https://www.ibm.com/support/knowledgecenter/en/SSXVXZ/com.ibm.i2.eia.go.live.doc/c_kc_intro_ssl.html

You can have as many client certificates as you require. Each certificate is associated with a singleuser in the user registry. Each certificate can be installed on any number of workstations. Eachworkstation can have any number of certificates installed.

To demonstrate a working configuration, you can use a self-signed client certificate. For moreinformation, see “Creating a self-signed client certificate” on page 108. However, in a productiondeployment you must use certificates that are signed by a certificate authority that is trusted by the i2Analyze server.

There are many methods for obtaining an X.509 certificate that is signed by a certificate authority.When you receive a signed certificate, you also receive signer certificates so that you can trust theclient certificates that are signed by that certificate authority. If the certificate authority that signedyour certificates is not already trusted within the key database, you must add any signer certificates tothe key database so that the certificate authority is trusted.

For information about managing key databases, certificates, and trusted certificate authorities usingthe IBM Key Management utility, see Managing keys with the IKEYMAN graphical interface.

Creating a self-signed client certificateThe client certificate is used to log in and authenticate a user with i2 Analyze. Use the IBM KeyManagement utility to create a self-signed certificate.

About this task

Create a self-signed certificate to use as a client certificate to demonstrate a working configuration. Ifyou are using client certificates that are signed by a certificate authority, you do not need to completethe following instructions.

Procedure

1. Start the IBM Key Management utility.For more information, see Starting the Key Management utility user interface.

Note: The IBM Key Management utility uses a GUI or Window Manager. If you do not have a GUI orWindow Manager on your system, you can use the command line interface to complete the sameactions. For more information about the command line interface, see Key Management utilitycommand-line interface (gskcmd) syntax.

2. Open the key database that is used for Secure Sockets Layer (SSL) connections. If you followed theinstructions to set up the SSL example, the key database file is IBM\i2analyze\i2-http-keystore.kdb.For more information about opening a key database, see Working with key databases.

3. Create a self-signed certificate.For more information, see Creating a self-signed certificate.a) Set the Key Label to a value that enables you to identify the user.

For example, Jenny.b) Ensure that the value of Common Name matches the name of a user in the user registry for i2

Analyze.

If you are using the example user registry, set the value of Common Name to Jenny.

Note: The user name cannot contain a comma (,).

For this example, you can use the default values for the remaining properties.4. Export the certificate and private key from the key database.

a) Click Export/Import.


https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/welc_ikeymangui.html

https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_keymangui.html

http://www.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.ihs.doc/ihs/rihs_ikeycmdsyn.html?cp=SS7K4U_8.5.5


https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_createkeydb.html

https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_certselfsigned.html

b) Ensure that Export Key is selected.c) From the Key file type list, select PKCS12.d) Set the File name to a value that enables you to identify the user.

For example, Jenny.p12.e) Ensure that Location is set to the same directory as the key database.f) Click OK.g) When you are prompted, provide a password that is used to access the keys.

5. Extract the certificate from the key database.a) Click Extract Certificate.b) From the Data type list, select Binary DER data.c) Set the Certificate file name to a value that enables you to identify the user.

For example, Jenny.der.d) Ensure that Location is set to the same directory as the key database.e) Click OK.

Configuring the key databasesTo enable the i2 Analyze server to trust the client certificates, you must ensure that the signer of yourclient certificates is trusted within the i2 Analyze key database. You must also create a copy of thekeystore as a truststore that WebSphere Application Server Liberty uses.

About this taskIf you are using client certificates that are signed by a certificate authority, ensure that the certificateauthority that signed the certificates is trusted within the i2 Analyze key database.

You can list the certificate authorities that are trusted within a key database in the IBM KeyManagement utility. For more information, see Listing certificate authorities.

After you add the certificate to the key database, create a truststore that WebSphere ApplicationServer Liberty uses. The truststore is a copy of the i2 Analyze key database.

Procedure

1. Start the IBM Key Management utility.For more information, see Starting the Key Management utility user interface.

Note: The IBM Key Management utility uses a GUI or Window Manager. If you do not have a GUI orWindow Manager on your system, you can use the command line interface to complete the sameactions. For more information about the command line interface, see Key Management utilitycommand-line interface (gskcmd) syntax.

2. Open the key database that is used for Secure Sockets Layer (SSL) connections. If you followed theinstructions to set up the SSL example, the key database file is IBM\i2analyze\i2-http-keystore.kdb.For more information about opening a key database, see Working with key databases.

3. Add the certificates to the key database, to ensure that the certificates received from the client aretrusted.a) In the IBM Key Management utility, with the i2 Analyze key database open, select Signer

Certificates from the list in the Key database content pane.b) Click Add.c) Click Browse, and locate your certificate.


https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_ikeylistca.html

https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_keymangui.html



https://www.ibm.com/support/knowledgecenter/SSEQTJ_8.5.5/com.ibm.websphere.ihs.doc/ihs/tihs_createkeydb.html

Note: When you are using a self-signed client certificate, add the self-signed client certificate as asigner certificate. For example, Jenny.der.

4. The Liberty truststore must contain the certificates to ensure that the certificates received fromthe client are trusted.a) Run the following command to import the required certificate into the truststore. If the

truststore does not exist, it is created.:

keytool -importcert -alias "signerKey" -keystore "C:\IBM\i2analyze\i2-liberty-truststore.jks" -file "C:\IBM\i2analyze\signer-certificate.cer" -storepass "password"

Note: When you are using a self-signed client certificate, add the self-signed client certificateas a signer certificate. For example, Jenny.der.

ResultsThe key database contains the signer certificates so that the client certificates can be trusted. Thetruststore is populated so that Liberty can use it to trust the client certificates.

Configuring i2 AnalyzeTo enable a user to log in using a client certificate, you must modify some of the configuration files fori2 Analyze.

About this taskAdd a rewrite rule that enables client authentication on the IBM HTTP Server to the i2 Analyzeconfiguration. Then, update the web.xml file for the application to enable client certificateauthentication.

Procedure

1. Using a text editor, open the configuration\environment\proxy\http-custom-rewrite-rules.txt file. Add the following line between the !Start_After_Rules! and !End_After_Rules! lines to enable client certificate authentication:

SSLClientAuth Optional

2. In an XML editor, open the toolkit\configuration\environment\topology.xml file.a) Add a child <key-store> element to the <key-stores> element.

For your truststore, specify the type as trust-store and file as the full path to yourtruststore.



<application http-server-host="true" name="opal-server" host-name="hostname" secure-connection="true">... <key-stores> <key-store type="key-store" file="C:\IBM\i2analyze\i2-liberty-keystore.jks"/> <key-store type="trust-store" file="C:\IBM\i2analyze\i2-liberty-truststore.jks"/> </key-stores>...</application>

b) Specify the truststore password in the credentials file. In a text editor, open the toolkit\configuration\environment\credentials.properties file and enter a password forthe truststore that you specified in the topology.xml file.

ssl.truststore.password=password

3. Using an XML editor, open the wlp\usr\servers\server\server.xml file. Modify the <ssl>element with the id defaultSSLConfig to includeclientAuthenticationSupported="true". For example:

<ssl clientAuthenticationSupported="true" id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore"/>

4. Edit the web.xml files that are associated with your deployment.a) If you are configuring the Opal services, use an XML editor to modify the toolkit\configuration\fragments\opal-services-is\WEB-INF\web.xml file.

Comment out the following lines so that form based authentication is not used:

<login-config> <auth-method>FORM</auth-method> <realm-name>Form-Based Authentication Area</realm-name> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/login.html?failed</form-error-page> </form-login-config></login-config>

In the login configuration section, add the following lines to define the client certificateauthentication method:

<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>WebRealm</realm-name></login-config>


b) If you are configuring the Onyx services, use an XML editor to modify the toolkit\configuration\fragments\onyx-services-ar\WEB-INF\web.xml file.

Comment out the following lines so that the authentication header is not filtered:

<filter> <filter-name>SSOAuthenticationFilter</filter-name> <description> Only for use in SSO. Must be removed if using SPNEGO Kerberos authentication. </description> <filter-class> com.i2group.apollo.servlet.SSOAuthenticationFilter </filter-class></filter>

<filter-mapping> <filter-name>SSOAuthenticationFilter</filter-name> <url-pattern>/services/InfoService</url-pattern></filter-mapping>

In the login configuration section, add the following lines to define the client certificateauthentication method:

<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>WebRealm</realm-name></login-config>

ResultsThe i2 Analyze application is configured to allow client certificate authentication.

Redeploying i2 AnalyzeAny time that you change the configuration of i2 Analyze, you must redeploy the system.

Procedure


command:

setup -t stop


setup -t deploy




setup -t start


Installing client certificatesAfter you create the client certificates, install the client certificates on the client workstations. Afterthe client certificates are installed, they are available to be selected by users to use to log in to i2Analyze.

About this task

On each client workstation that you want a user to be able to log in from, install the client certificateand exported keys as a Personal certificate. You can install multiple certificates and their associatedkeys on a workstation to allow multiple users to log in.

If you are not using a self-signed certificate, install the signer certificate that is associated with yourclient certificate so that your operating system can verify the client certificates.

Procedure

1. Copy your client certificate and the exported keys to a permanent directory on the clientworkstation.

2. Install the client certificate and exported keys to the Personal store:a) Double-click the keys file.

For example, Jenny.p12.The Certificate Import Wizard is displayed.

b) Click Next.c) Click Browse, and locate the keys file to import.

For example, Jenny.p12. Then, click Next.d) Enter the password that you specified when the keys were exported from the key database, and

click Next.e) Click Place all certificates in the following store.f) Click Browse, and select Personal.g) Click Next, and then click Finish.

3. If you are using a self-signed certificate, install the client certificate to the Trusted RootCertification Authorities store:a) Double-click the client certificate file.

For example, Jenny.der.b) Click Install Certificate, and then click Next.c) Click Place all certificates in the following store.d) Click Browse, and select Trusted Root Certification Authorities.e) Click Next, and then click Finish.f) If the operating system cannot verify the certificate, a security warning is displayed.

Click Yes to accept the certificate.


ResultsThe client certificate and exported keys are installed. Users can select a certificate to use to log in toi2 Analyze.

Testing the deploymentTo ensure that the deployment is using client certificate authentication, access i2 Analyze from aclient workstation. Connect to the system by using a web browser or Analyst's Notebook Premium.

Before you begin

• A client certificate must be installed on the client workstation. For more information about installingthe client certificates, see “Installing client certificates” on page 113.

• The application server must be running.

Connecting to the Intelligence PortalYou can use X.509 certificates to authenticate users in the Intelligence Portal. The connection to thei2 Analyze server is secured, and the user is authenticated with the server by the client certificate thatis provided by the client.

Before you begin

If you are using the Mozilla Firefox browser, you must add your certificates to the Mozilla Firefox,because Mozilla Firefox does not use the operating system's certificate store. Import your clientcertificates into Your Certificates in Mozilla Firefox.

Procedure

1. Open a web browser, and navigate to https://host_name/apollo (where host_name is thefully qualified domain name or IP address of the HTTP server).

You are prompted to provide a certificate.2. Select the client certificate to use to authenticate with the server from the list that is displayed.

ResultsWhen client certificate authentication is configured correctly, you are logged in to the IntelligencePortal as the user associated with the selected certificate.

Connecting to the Analysis Repository from Analyst's Notebook PremiumYou can use X.509 certificates to authenticate users in i2 Analyze from Analyst's Notebook Premium.The connection to the i2 Analyze server is secured, and the user is authenticated with the server bythe client certificate that is provided by Analyst's Notebook Premium.

About this task

When you first start Analyst's Notebook Premium, or if you change the connection to a repository, theapplication displays a window that contain connection details for the Analysis Repository.

Procedure

1. Enter the name of the repository, and the URL of the server to connect to.Use the HTTPS protocol to connect to the server. For example, https://host_name/apollo(where host_name is the fully qualified domain name or IP address of the HTTP server).

2. Select Use client certificate and click Browse. Then, choose the client certificate to use toauthenticate with the server.


3. Click OK.

ResultsWhen client certificate authentication is configured correctly, you are logged in to i2 Analyze as theuser associated with the selected certificate.

Connecting to the Information Store from Analyst's Notebook PremiumYou can use X.509 certificates to authenticate users in i2 Analyze from Analyst's Notebook Premium.The connection to the i2 Analyze server is secured, and the user is authenticated with the server bythe client certificate that is provided by Analyst's Notebook Premium.

About this task

Connect to the Information Store, and select a client certificate to use to authenticate with the i2Analyze server.

Procedure

1. Enter the name of the repository, and the URL of the server to connect to.Use the HTTPS protocol to connect to the server. For example, https://host_name/opal(where host_name is the fully qualified domain name or IP address of the HTTP server).

You are prompted to provide a certificate.2. Select the client certificate to use to authenticate with the server from the list that is displayed.

ResultsWhen client certificate authentication is configured correctly, you are logged in to i2 Analyze as theuser associated with the selected certificate.

Resources for system protectionIn order to protect your system from external forces, you must implement system controls thatprevent or mitigate the effect of attacks. Although IBM does not manage login configuration, and theresponsibility for protection of your network from external attack remains yours, the followingcommunities provide a starting point for your investigation into preventative methods.The Open Web Application Security Project


















Client authenticated Secure Sockets Layer with IBM i2 ConnectTo secure the connection between Liberty and any IBM i2 Connect connectors, you must configureLiberty and your connectors to use SSL. If you are using SSL, i2 Analyze enforces client authenticatedcommunication with a connector.

Before you begin

In a production deployment you should configure i2 Analyze to connect to your connector using clientauthenticated SSL communication. To do so, your connector and i2 Analyze must trust the certificatesthat they receive during the SSL handshake process. In a production environment, the certificatesmust be signed by a trusted certificate authority. For more information about client authenticated SSL,see Client-authenticated TLS handshake.

The following diagram shows the keystores and truststores that are required for Liberty and theconnector.

IBM HTTP Server

Liberty

Clients

Server



Connector

Keystore Truststore

KeystoreTruststore

The Liberty server requires a keystore file and a truststore file, both (*.jks). Your connector can useany implementation for its keystore and truststore. The certificates in each truststore must trust thecertificates received from the corresponding keystore.

The certificates that are required are as follows, where certificate authority (CA) X issues thecertificates to the connector (the server) and Liberty (the client):

The connector requires:

• In its keystore:

– The personal certificate issued to the connector by CA X



https://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake

– The connector's private key• In the truststore:

– The CA certificate for CA X

Liberty requires:

• In its keystore:

– The personal certificate issued to Liberty by CA X

– Liberty's private key• In its truststore:

– The CA certificate for CA X

About this taskAfter you have created and populated the keystores and truststores for the connector and Liberty, youmust configure Liberty to use SSL to communicate with any connectors.

The following steps explain the process of updating the i2 Analyze configuration with the location of akeystore and truststore to use, and the passwords that are used to access the certificates that arecontained within them.

To configure the example-connector to use client authenticated SSL, and for examples of how tocreate keystores, truststore, and certificates for Liberty, follow the instructions in “Securing theexample connector” on page 118.

Procedure

1. In an XML editor, open the toolkit\configuration\environment\topology.xml file.a) Add the <key-stores> element as a child of the <application> element. Then, add child<key-store> elements.For your keystore, specify the type as key-store, and file as the full path to your keystore.For your truststore, specify the type as trust-store, and file as the full path to yourtruststore.For example, add the attribute as highlighted in the following code:

<application http-server-host="true" name="opal-server" host-name="hostname">... <key-stores> <key-store type="key-store" file="C:/IBM/i2analyze/i2-liberty-keystore.jks"/> <key-store type="trust-store" file="C:/IBM/i2analyze/i2-liberty-truststore.jks"/> </key-stores>...</application>

b) Update the base-url attribute of any connectors using SSL to use the HTTPS protocol.


For example:

<connectors> <connector id="example-connector" name="Example" base-url="https://localhost:3700/" /></connector>

Note: Ensure that the host name that is used in the base URL matches the common name on thecertificate of the connector.

2. Specify the keystore and truststore passwords in the credentials file.a) In a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the password for the keystore and truststore that you specified in the topology.xmlfile.

ssl.keystore.password=passwordssl.truststore.password=password


What to do next

You can create your own connectors to use with the deployment of i2 Analyze, when you create yourown connector you can implement security that conforms to the security required by IBM i2 Connect.For more information about creating your own connectors, see IBM i2 Analyze and i2 Connect.

When you use a connector configured for SSL communication, you should not see any warningsdisplayed in Analyst's Notebook Premium.

Securing the example connectorIn a production deployment, you must configure your connectors with client authenticated SSLcommunication. You can configure the example connector to communicate with i2 Analyze usingclient authenticated SSL communication.

Before you beginYou must configure your connectors to use client authenticated SSL communication with i2 Analyze.For more information about configuring security between connectors and i2 Analyze, see “Clientauthenticated Secure Sockets Layer with IBM i2 Connect” on page 116.

About this taskConfigure secure communication between Liberty and the example connector that is provided with i2Analyze. The following steps demonstrate how to create the keystores, truststores, and certificates,then configure i2 Analyze and the example connector to use them.

When you create your own connector, you can implement the security implementation in the sameway as used in the example connector, or a different method depending on your requirements.

In a production deployment, you must use a certificate that has been signed by a trusted certificateauthority, which the connector can verify. The following steps use a self-signed certificate todemonstrate the functionality.



https://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.connect.developer.doc/i2_analyze_i2_connect.html

Procedure

Create a keystore for Liberty that contains a signed certificate that is used to authenticate with theconnector.

1. Create a keystore and self-signed certificate for Liberty by using the Java keytool utility.For more information about the Java keytool utility, see keytool - Key and Certificate ManagementTool.a) Open a command prompt and navigate to the i2analyze\deploy\java\bin directory.b) Create the keystore and certificate by running the following command:

keytool -genkeypair -alias "libertyKey"-keystore "C:\IBM\i2analyze\i2-liberty-keystore.jks"-dname "CN=hostname" -keyalg RSA -storepass "libertyKeyStorePassword"


• Set the location of the keystore to the directory that contains the toolkit. In somedeployments, this path might be C:\IBM\i2EIA.

• Set the value of CN to the host name of the server that hosts Liberty as defined in thetopology.xml file.

The password that is specified is used to access the keystore.c) The example connector implementation requires the Liberty certificate in a base64 encoded

format. Export the certificate in base64 encoding by running the following command:

keytool -exportcert -alias "libertyKey"-keystore "C:\IBM\i2analyze\i2-liberty-keystore.jks"-file "C:\IBM\i2analyze\i2-liberty-certificate.cer"-rfc -storepass "libertyKeyStorePassword"

Create a keystore for the connector that contains a signed certificate that is used to authenticate withLiberty.

2. Create a keystore and certificate for the connector using the IBM Key Management Utilitycommand-line interface.For more information about the IBM Key Management Utility, see Key Management Utilitycommand-line interface (gskcmd) syntax.a) In a command prompt, navigate to the IBM\HTTPServer\bin directory.b) Create a keystore in PKCS12 format. To create the keystore, run the following command:

gskcmd -keydb -create -type pkcs12-db "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"-pw "connectorKeyStorePassword"

The password that is specified is used to access the keystore.c) Create a self-signed certificate by running the following command:

gskcmd -cert -create-db "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"-label "connectorKey" -dn "CN=localhost" -pw "connectorKeyStorePassword"




https://www.ibm.com/support/knowledgecenter/en/SSEQTJ/com.ibm.websphere.ihs.doc/ihs/rihs_ikeycmdsyn.html

https://www.ibm.com/support/knowledgecenter/en/SSEQTJ/com.ibm.websphere.ihs.doc/ihs/rihs_ikeycmdsyn.html

Important: Set the value of CN to the host name of the server that hosts the connector asdefined in the topology.xml file. By default in the daod-opal example configuration, thevalue is localhost.

3. The example connector implementation requires the private key in the PEM format, and thecertificate for the connector.a) Export the personal certificate and private key into a PKCS12 file by running the following

command:

gskcmd -cert -export-db "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"-pw "connectorKeyStorePassword" -label "connectorKey" -type pkcs12-target "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.p12"-target_pw "connectorKeyPassword" -target_type pkcs12

b) Convert the private key from the PKCS12 format to the PEM format. You can use OpenSSL todo this, for more information about OpenSSL see https://www.openssl.org/source/. If you areusing OpenSSL, you can run the following command:

openssl pkcs12 -in C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.p12-out C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-key.pem-nocerts -nodes

c) Extract the certificate for the connector by running the following command:

gskcmd -cert -extract-db "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"-label "connectorKey"-target "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.cer"-pw "connectorKeyStorePassword"

Create a truststore for Liberty that contains the certificate that is used to trust the certificate that itreceives from the connector.

4. Create the Liberty truststore and populate it with the connector's certificate using the Javakeytool by running the following command:

keytool -importcert -alias "exampleconnector"-keystore "C:\IBM\i2analyze\i2-liberty-truststore.jks"-file "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-certificate.cer"-storepass "libertyTrustStorePassword"



https://www.openssl.org/source/

5. Populate the connector keystore with Liberty's certificate using the IBM Key Management Utilityby running the following command:

gskcmd -cert -add -type pkcs12-db "C:\IBM\i2analyze\toolkit\examples\connectors\example-connector\example-connector-keystore.p12"-pw "connectorKeyStorePassword" -label "libertyKey" -trust enable-file "C:\IBM\i2analyze\i2-liberty-certificate.cer"

6. The example connector implementation requires the certificate that is used to trust Liberty toalso be present in the example-connector directory. Copy the C:\IBM\i2analyze\i2-liberty-certificate.cer file to the C:\IBM\i2analyze\toolkit\examples\connectors\example-connector directory.

7. Start, or restart, the HTTP server that hosts the reverse proxy.The certificates are now in place to enable client authentication SSL between Liberty and theconnector.

8. Configure the example connector to reference the certificates that you created, and the hostname of the gateway. Using a text editor, modify the security-config.json file with thefollowing values.https

Set to true to use the HTTPS protocol when connecting to the connector.keyFileName

The file name for the private key of the connector in PEM format. For this example, example-connector-key.pem.

keyPassphraseThe password that is required to access the key file specified in keyFileName. For thisexample, password.

certificateFileNameThe file name for the certificate of the connector. For this example, example-connector-certificate.cer.

certificateAuthorityFileNameThe file name of the certificate that enables trust of the certificate received from Liberty. Forthis example, i2-liberty-certificate.cer.

gatewayCNThe common name of the gateway. This must be the value of the common name in thecertificate the connector receives from Liberty. You specified the value of the CN in thecertificate in step 1.

Configure Liberty to use the keystore and truststore that you created.9. In an XML editor, open the toolkit\configuration\environment\topology.xml file.

a) Add the <key-stores> element as a child of the <application> element. Then, add child<key-store> elements.For your keystore, specify the type as key-store, and file as the full path to your keystore.For your truststore, specify the type as trust-store, and file as the full path to yourtruststore.



<application http-server-host="true" name="opal-server" host-name="hostname">... <key-stores> <key-store type="key-store" file="C:/IBM/i2analyze/i2-liberty-keystore.jks"/> <key-store type="trust-store" file="C:/IBM/i2analyze/i2-liberty-truststore.jks"/> </key-stores>...</application>

b) Update the base-url attribute of any connectors using SSL to use the HTTPS protocol.For example:

<connectors> <connector id="example-connector" name="Example" base-url="https://localhost:3700/" /></connector>

Note: Ensure that the host name that is used in the base URL matches the common name on thecertificate of the connector.

10. Specify the keystore and truststore passwords in the credentials file.a) In a text editor, open the toolkit\configuration\environment\credentials.properties file.

b) Enter the password for the keystore and truststore that you specified in the topology.xmlfile.

ssl.keystore.password=libertyKeyStorePasswordssl.truststore.password=libertyTrustStorePassword


12. Start the example connector.a) In a command prompt, navigate to the toolkit\examples\connectors\example-connector directory.

b) To start the Node.js server, run the following command:

npm start

Note: The example connector uses port number 3700. Ensure that no other processes areusing this port number before you start the connector.

13. Start i2 Analyze.a) On the i2 Analyze server, open a command prompt and navigate to the toolkit\scripts

directory.b) To start i2 Analyze, run the following command:

setup -t start




What to do next

Use Analyst's Notebook Premium to connect to your deployment. For more information, seeConnecting IBM i2 Analyst's Notebook Premium to IBM i2 Analyze.

Now that the example connector is configured for SSL, no warnings are displayed in Analyst'sNotebook Premium.

Configuring search optionsDepending on the requirements of the environment that you are deploying into, a number ofconfigurable options are available for searching and indexing. For example, for performance reasons,you can modify the minimum number of characters to be used within a wildcard search or customizealternative terms that are used.

Configuring the i2 Analyze Opal searchData can be searched using a number of configurable options. With the Opal services, you canconfigure indexing, Quick Search, and Visual Query features to match your needs.

Configuring the Opal search indexi2 Analyze enables searching of information that is stored in the Information Store and other datasources. The quality of the search results is affected by the index that the Solr component creates,and the lists of synonyms that it maintains for common search terms.

By default, the Solr search index is created in US English, and uses synonym lists that contain USEnglish terms. When you change the language of the search index, a default synonyms list in thespecified language is used to create the associated term index. Solr provides the facility to configurethe synonyms that are used for querying textual data. In i2 Analyze, you can use this option to apply acustomized list of synonyms at query time.

A synonym is a word or phrase that means exactly or nearly the same thing as another word orphrase. Synonyms, if not accounted for, can cause a reduction in the relevance of a search result whenyou search for keywords that are present in alternative forms in your index.

The synonyms file is the part of the Solr configuration that accounts for the presence of synonyms inyour data. For example, your data might contain the words, “bag, handbag, pocketbook, purse” for theconcept “bag”. When someone searches they are likely to search for one, but expect results for allfour. To meet that expectation, you might want to create a customized synonyms file to accommodatesimilar variations that are specific to your data. The exact words in a synonyms list that are mostuseful in your deployment depend on the content of your data. You can also use a mix of languages,which might be useful in some contexts, for example names: 'George, Γεώργιος, Jorge'.

The topology file is used to specify the language of the search index and to specify a customizedsynonyms file. Both the language country-code and the customized synonyms file specification areoptional.

• If the language country-code and the synonyms file are not specified, then the default US Englishsearch index and associated default synonyms file are used.

• If only the language country-code is supplied, then the specified language country-code index andassociated default synonyms file are used.

• If only the synonyms file is specified, then a US English index with the specified synonyms file isused.


http://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.anb.admin.doc/connecting_to_anbpremium.html

• If both the language country-code and the synonyms file are specified, then the specified languageand the specified synonyms file are used.

Specifying the Solr index languageBy default, the Solr search index is created in US English. If you need to, you can change the languageof the generated indexes.

About this task

Specification of the language country-code is optional. The default language value is en_US for USEnglish. All indexes use the language country-code that is specified. The supported language optionsare en_US (US English), ar_EG (Arabic), and he_IL(Hebrew).

When you change the language, a default synonyms file is associated with the language selection. Youcan change the default synonyms file to use a customized synonyms file. For more information, see“Creating a Solr synonyms file” on page 125.

Procedure

1. In an XML editor, open the toolkit\configuration\environment\topology.xml file.2. In the <solr-cluster> or <solr-collection> element, add the language-country-code

attribute with the value for your chosen language.For example:

<solr-clusters> <solr-cluster language-country-code="ar_EG" ...> <solr-collections> <solr-collection="type_index" language-country-code="ar_EG" ... /> </solr-collections> <solr-nodes/> </solr-cluster> </solr-clusters>

Where type is the type of index to be used: main or daod.

Note: You can set the language for the main_index or the daod_index, but you cannot haveboth in the same deployment.

3. Save the topology.xml file.4. On the i2 Analyze server, open a command prompt and go to the directory toolkit\scripts.5. To stop Websphere Application Server Liberty, run the following command.

setup -t stopLiberty

6. To create and upload the Solr configuration to the ZooKeeper hosts, run the following command.

setup -t createAndUploadSolrConfig

7. To clear the search index, run the following command.

setup -t clearSearchIndex


8. To start Websphere Application Server Liberty, run the following command.

setup -t startLiberty

Results

• When a language country-code is specified only in the <solr-cluster> element, all indexes usethe language country-code specified.

• When a language country-code is specified in the <solr-collection> element, only the index inthat collection uses the language that is specified, this value overrides the language country-codespecified in <solr-cluster>.

Creating a Solr synonyms fileThe deployment toolkit specifies the synonyms file that contains the list of alternative terms for eachsupported language. You can modify or replace the supplied default files to introduce extra terms thatmatch the needs of your deployment.

About this task

The default synonyms file and synonyms list are in US English. The synonyms files that are associatedby default with each supported language are supplied in the directory, toolkit/examples/solr-resources/solr-synonyms.

To customize the alternative terms that are used in search operations for your data, you can createfiles that contain different terms from those terms that are contained in the supplied synonyms files.

The topology file can be used to specify a customized synonyms file as an alternative to the defaultsynonyms file that is associated with the language country code. The customized file must adhere tothe following guidelines.

• The file must be UTF-8 encoded.• The terms in the file must match the terms that are produced by the analyzer chain that is used in

Solr prior to the synonym filter being applied.• If multiple forms of a word exist, all the forms must be specified in order for synonym matching to

work on each form.• Words from Latin script languages, for example French or Italian, must be specified without

diacritics. For example, use the following substitution:

– a instead of á– c instead of ç

• Arabic and Hebrew words must be specified exactly as they are written.

Procedure

1. Create a text file that defines synonyms in the required Solr format.

For more information, see https://lucene.apache.org/core/6_6_2/analyzers-common/org/apache/lucene/analysis/synonym/SolrSynonymParser.html.

Note:

a. You cannot search for multi-word terms. However, if you have data that contains terms "USA"and "United States of America", you can search for "USA" and use a synonym to ensure a matchwith "United States of America".


https://lucene.apache.org/core/6_6_2/analyzers-common/org/apache/lucene/analysis/synonym/SolrSynonymParser.html

https://lucene.apache.org/core/6_6_2/analyzers-common/org/apache/lucene/analysis/synonym/SolrSynonymParser.html

b. You can provide synonyms for terms that include punctuation. However, a search on such aterm might not work correctly. The unexpected result is because a filter is applied beforesynonyms, which means, for example, "Mary-Ann" becomes "Mary,Ann" and then synonyms areexpanded from "Mary and "Ann"; not "Mary-Ann" or "Maryann".

2. Save the file with a .txt extension, for example custom-synonym.txt.3. In an XML editor, open the toolkit\configuration\environment\topology.xml file.4. In the <solr-cluster> or <solr-collection> element, add the location of your synonyms

file.For example:

<solr-clusters> <solr-cluster synonyms-file="C:/custom-synonyms.txt" ...> <solr-collections> <solr-collection id="type_index" synonyms-file="C:/custom-synonyms.txt" ... /> </solr-collections> <solr-nodes/> </solr-cluster> </solr-clusters>

Where type is the type of index to be used: main or daod.

Note: You can set the synonyms file for the main_index or the daod_index, but you cannot haveboth in the same deployment.

5. Save the topology.xml file.6. On the i2 Analyze server, open a command prompt and go to the directory toolkit\scripts.7. To create and upload the Solr configuration to the ZooKeeper hosts, run the following command.

setup -t createAndUploadSolrConfig

Results

• When a synonym file is specified only in the <solr-cluster> element, all indexes use thesynonym file that is specified.

• When a synonym file is specified in the <solr-collection> element, only the index in thatcollection uses the synonym file that is specified, this value overrides the synonym file that isspecified in the <solr-cluster>.

Setting up search results filteringIn i2 Analyze, users can filter search results. You can configure the types of items and properties, aswell as metadata criteria, that appear in the filter list by creating and configuring facets.

About this task

In a deployment of i2 Analyze, the results configuration file defines which property types andmetadata criteria for each item type to display with facets in both the Quick Search and Visual Queryresults views. Both the Quick Search and Visual Query results views display the same filters.

When you deploy the information-store-opal example, the law-enforcement-schema-results-configuration.xml results configuration file that configures the facets specific to the


law-enforcement-schema.xml is used. In addition, an example configuration file for each of theexample schemas is included in the examples\schemas directory. If your system uses a modifiedversion of one of the example schemas, you can modify the appropriate results configuration file. Theexample results configuration files are located the configuration\examples\schemas\en_USdirectory. The results configuration file that you want to use in the deployment is located in thetoolkit\configuration\fragments\common\WEB-INF\classes directory.

In your results configuration file, the item types that are defined must correspond to entity and linktypes in your schema otherwise you are unable to start i2 Analyze. Examine your schema and the datain your system, and decide which property types for each item type to display with facets in theresults view. Metadata criteria are not defined in the schema, however for each item type you candecide which metadata criteria to display with facets.

If you do not specify a results configuration file, all of the property types and metadata criteria thatcan be displayed with facets, for all of the item types, are displayed in the results view in schemaorder.

Selecting the property types that can be used to filter search results can improve the facetingperformance, and improve the facets that are displayed to a user. For example, if a property typecontains only unique values, the user sees a facet for each value that is returned in search results. Ifyou configure that property type to not display with facets, it means that fewer facets must becalculated and that more useful facets from different property types are displayed instead. Examplesof property types that you might configure to not display with facets are license plates and socialsecurity numbers.

For more information about the results configuration file and the changes that you can make, see“Understanding the results configuration file” on page 128.

Procedure

1. Using an XML editor, open the results configuration file that you would like to modify.2. Add, modify, or remove any <ItemTypeFacet> elements and appropriate child<PropertyTypeFacet> and <MetadataFacet> elements for your deployment.

Note: Property types that have the following logical types cannot be used to filter search results:

• GEOSPATIAL• MULTIPLE_LINE_STRING


Note: Ensure that your modified file is stored in the toolkit\configuration\fragments\common\WEB-INF\classes directory.

4. If you have changed the name of the file that is used in the original deployment, you must reset thename of the file that the deployment uses.a) Using a text editor, open the DiscoServerSettingsCommon.properties file in thetoolkit\configuration\fragments\opal-services\WEB-INF\classes directory.

b) Ensure that the value of the ResultsConfigurationResource property is set to the name ofyour results configuration file, then save and close the file.

Tip: If you do not want to configure your results, clear the value of theResultsConfigurationResource property.

What to do nextRedeploy i2 Analyze, and run a selection of queries on an Information Store. Continue to change theconfiguration until you are satisfied with the types of filter that are available.


Understanding the results configuration fileIn your results configuration file, you define the item types and associated property types andmetadata criteria that can be used to filter results for each of the entity and link types in your i2Analyze schema. By defining the filtering behavior for different item types, you can refine the filteringto provide the most valuable filters for your environment.

The results configuration file has the following basic shape:

<tns:ResultsConfiguration ...> <Facets InlineLimit="5" ViewAllLimit="100">  <ItemTypeFacet TypeId="ET1" Subfacets="ExcludeSpecific">  <PropertyTypeFacet TypeId="ADD1" /> ... <MetadataFacet Criterion="NotesCreatedBy" /> ... </ItemTypeFacet> ... </Facets></tns:ResultsConfiguration>

Where the <ItemTypeFacet> element is used to define which item type you are defining propertytypes and metadata criteria for. The value of the TypeID attribute specifies the item type. This valuecorresponds to the Id value of an <EntityType> or <LinkType> in the schema.

Property types are specified in child <PropertyTypeFacet> elements. The value of the TypeIdattribute specifies the property type. This value corresponds to the Id value of a <PropertyType> inthe i2 Analyze schema.

Metadata criteria are specified in child <MetadataFacet> elements. The value of the Criterionattribute specifies the metadata criteria and can have the following values:NotesCreatedBy

The display name of the user who has added a note to the record.FirstUploadedBy

The display name of the user who first uploaded the record.FirstUploaded

The date that the record was first uploaded.LastUploadedBy

The display name of the user who last uploaded the record.LastUploaded

The date that the record was last uploaded.IngestionDataSourceName

The data source name that the record was ingested from.

If the record was uploaded from Analyst's Notebook Premium, the IngestionDataSourceNameis automatically set to ANALYST.

Note: Any child <MetadataFacet> elements must be specified after all of the child<PropertyTypeFacet> elements within an <ItemTypeFacet> element.

In the <ItemTypeFacet> element, the value of the Subfacets attribute defines the method forspecifying the property types and metadata criteria.

The Subfacets attribute can have the following values:All

All property types of this item type and metadata criteria are available as filterable options for theresults. This behavior is the default if an item type is not added to the results configuration file.For example:

<ItemTypeFacet TypeId="ET5" Subfacets="All" />

Declaring this fragment while working with the law enforcement schema will allow you to filter by'Person' and by all the available properties and metadata.

Note: You must not specify any child elements when the value of the Subfacets attribute is All.

IncludeSpecificSpecific property types of this item type and metadata criteria are displayed in the filtering lists.For example:

<ItemTypeFacet TypeId="ET5" Subfacets="IncludeSpecific"> <PropertyTypeFacet TypeId="PER4" /> <PropertyTypeFacet TypeId="PER6" /> <MetadataFacet Criterion="NotesCreatedBy" /></ItemTypeFacet>

Declaring this fragment while working with the law enforcement schema will allow you to filter by'Person' and by 'First (Given) Name', 'Family Name', and 'NotesCreatedBy'.

Note: You must specify at least one child <PropertyTypeFacet> or <MetadataFacet>element when the value of the Subfacets attribute is IncludeSpecific.

ExcludeSpecificSpecific property types of this item type and metadata criteria are excluded from the filtering lists.For example:

<ItemTypeFacet TypeId="ET3" Subfacets="ExcludeSpecific"> <PropertyTypeFacet TypeId="VEH2" /> <MetadataFacet Criterion="FirstUploaded" /></ItemTypeFacet>

Declaring this fragment while working with the law enforcement schema will allow you to filter by'Vehicle', but not by 'License Plate Number' or 'FirstUploaded'.

Note: You must specify at least one child <PropertyTypeFacet> or <MetadataFacet>element when the value of the Subfacets attribute is ExcludeSpecific.

NoneNo property types of this item type and metadata criteria are available for filtering. For example:

<ItemTypeFacet TypeId="ET5" Subfacets="None" />


Declaring this fragment while working with the law enforcement schema will allow you to filter by'Person' but not by any of the properties of the Person type, such as eye color nor any of themetadata criteria.

Note: You must not specify any child elements when the value of the Subfacets attribute isNone.

Additionally, you can disable all property type and metadata criteria for faceting by using thePropertyTypeFacetsEnabled and MetadataFacetsEnabled attributes of the <Facets>element. By default, both property type and metadata criteria are enabled for faceting. To disable, setthe attribute values to false.

Modifying the wildcard minimum character limitsWildcard characters are used to match zero or more alphanumeric characters in a search term. Youcan configure how users complete Quick Search and Visual Queries by modifying the minimumnumber of characters that must be included in a search term that includes wildcards.

About this taskThe following wildcard characters are available in i2 Analyze:*

Matches zero or more alphanumeric characters in this position.

For example, the search term Tim* matches Tim, Time, and Timely.

?Matches one alphanumeric character in this position.

For example, the search term Tim? matches Time.

Wildcard characters can be used at any position in a search term.

Search terms with wildcard queries might result in a large number of matches, which might causeperformance problems. To reduce the possible matches from a wildcard search, you can ensure thatusers provide a minimum number of characters with a wildcard. For example, the term "*" matcheseverything. If users must provide a minimum of 3 characters with an asterisk, for example the term"abc*", the number of matches is reduced to values that begin with "abc".

If the minimum number of characters is set too high, users might not be able to search for the termsthat they need. For example, in a deployment where the wildcard minimum characters are configuredas follows:

• A minimum of 3 characters other than asterisks (*) must be provided in a term.• A minimum of 2 characters other than question marks (?) and asterisks (*) must be provided in a

term.

If the user knows only 2 characters of a license plate, they might not be able to use a wildcard search:

• If the user knows the position of the 2 characters, they can use the question mark wildcardcharacter in the search. If the 2 characters are in positions 2 and 3, then the query "?AB*" is valid inthe configuration that is described.

• If the position of the characters is not known, the user might want to search for "*AB*", which isinvalid in the configuration that is described.

In addition to wildcard characters that are specifically entered as part of Visual Query, severalconditions provide implicit wildcard logic:

• 'Starts with' - Applies an asterisk to the end of the condition. For example, 'Starts with: Fred' isequivalent to 'Fred*', which could match; Fred, Frederick, or Freddie.


• 'Ends with' - Applies an asterisk to the start of the condition. For example, 'Ends with: Fred' isequivalent to '*Fred', which could match; Fred, Wilfred, or Alfred.

• 'Contains' - Applies an asterisk to both the start and the end of the condition. For example,'Contains: Fred' is equivalent to '*Fred*', which could match any of the above terms, but also includeAlfredo.

The use of these conditions follow the same limits as wildcard characters that have been enteredexplicitly.

To change the minimum number of characters that must be included in a search query with a wildcardcharacter, edit properties in DiscoServerSettingsCommon.properties.

The properties that specify the minimum number of characters for Quick Search are:WildcardMinCharsWithAsterisk

The minimum number of characters other than asterisks (*) that must be included in a wildcardquery that contains an asterisk.

WildcardMinCharsWithQuestionMarkThe minimum number of characters other than question marks (?) and asterisks (*) that must beincluded in a wildcard query that contains a question mark. This value should be less than, orequal to the value of the WildcardMinCharsWithAsterisk property.

The properties that specify the minimum number of characters for Visual Query are:VisualQueryWildcardMinCharsWithAsterisk

The minimum number of characters other than asterisks (*) that must be included in a VisualQuery condition that contains or implies asterisks.

VisualQueryWildcardMinCharsWithQuestionMarkThe minimum number of characters other than question marks (?) and asterisks (*) that must beincluded in a wildcard query that contains a question mark. This value should be less than, orequal to the value of the VisualQueryWildcardMinCharsWithAsterisk property.

Procedure


2. For Quick Search, edit the values of the WildcardMinCharsWithAsterisk andWildcardMinCharsWithQuestionMark properties.

3. For Visual Query, edit the values of the VisualQueryWildcardMinCharsWithAsterisk andVisualQueryWildcardMinCharsWithQuestionMark properties.


What to do next

After you complete the instruction in “Redeploying and resetting i2 Analyze” on page 157 to redeployi2 Analyze, run a selection of Quick Search and Visual Queries that use conditions including wildcardcharacters.

Visual Query condition restrictionsIn order to create a configuration file that helps you to manage your Visual Query performanceeffectively, it is important to understand the available restrictions. Having a proper understanding of


the implications of the rules that can be created, allows you to reduce the number of iterationsrequired.

The visual-query-configuration.xml file in configuration/fragments/opal-services-is/WEB-INF/Classes includes commented out examples of rules applicable to the lawenforcement schema. Using these examples as guidance, you can create rules that apply to yoursystem.

Important: The rules that are added in visual-query-configuration.xml are applied to the i2Analyze server and not the Analyst's Notebook Premium client. As such, users are still able toconstruct queries that include restricted conditions, but the server will prevent the query from beingrun.

Depending on your circumstances, there are two main approaches that can be used to create yourrules:Invalidating a particular type of query

If you are aware of query types that are an issue, you can deny the specific conditions that lead tothe issue, allowing all other Visual Query behavior to remain unchanged.

Enabling specific queriesIf you are uncertain about the type of queries that might produce an issue, or want to restrict thetypes of searches that can be carried out, you can deny all conditions, and selectively allow thetypes of query that you require.

As you build up your Visual Query configuration file, it is worth bearing in mind the following keyconcepts:

Rule componentsEach rule consists of the following components:

• Rule Type - Whether the rule should allow or deny a specific type of operation• Item Type - Which Item Type the rule should apply to• Property Type - Which Property Types for the specified Item Type that the rule should cover• Operator - Which Operator Types to apply the rule to• Date and Time Aspects - Which types of temporal aspect to apply the rule to. For example, day

of the week, or time of the day.

Implicit 'all valid'If one or more of the above rule components are not specified, the rule will be applied to all theVisual Query conditions that would be valid.

Rule orderingVisual Query rules are applied sequentially, meaning that if conflicting rules are added, they arehandled in order, allowing rules that are later in the file to overwrite earlier rules. This allows youto refine your conditions, for example:

<Deny/><Allow ItemTypeId="ET5" PropertyTypeIds="PER9, PER15" Operators="EQUAL_TO, BETWEEN"/>

Using these rules, searches for people with specified dates of birth or genders are permitted, butall other Visual Query conditions are prevented from running.

Rule TypeThere are two types of Visual Query condition rule. The type of restriction determines whether theoperators specified in the rule are allowed or denied.

The type of rule can be either:

• Deny - Specify a rule that prevents an operation• Allow - Specify a rule that enables an operation

Note: For each rule that you add to the visual-query-configuration.xml, you must specify thetype of rule.

Item Type IdentifierA restriction that only includes the restriction type will apply to all the types of item that are specifiedin the schema. If required, to apply the restriction to a specific type of item, you can add an Item TypeIdentifier.

The ItemTypeId attribute allows you to specify an item type to restrict. It assumes that the specifiedvalue is found in the current i2 schema that is being used in your deployment. To help ensure that youvalues are valid, you might want to have the schema open for reference when you are creating yourrestrictions. In addition, to help troubleshoot issues, it may also help to add the display name ordescription of the item type into a comment about the restriction.

For example the following item type in the schema:

<EntityType Id="ET5" SemanticTypeId="guid8A586959-9837-47DE-8DBF-BC7031F01545" Description="Person details" DisplayName="Person" Icon="Person (Shaded Shirt)">

could be used to create the following rule in your configuration file:

<Allow ItemTypeId="ET5" Operators="EQUAL_TO, BETWEEN"/>

Note: You can only specify one type of item per rule.

Property Type IdentifiersIf you have added an Item Type Identifier to a Visual Query rule, by default, the rule will apply to allthe applicable property types. If required, to apply the rule to specific property types, you can add theproperty types identifiers.

The PropertyTypeIds argument allows you to specify the property types to restrict. It assumesthat the specified values are found in the current i2 schema that is being used in your deployment. Tohelp ensure that your values are valid, you might want to have the schema open for reference whenyou are creating your restrictions. In addition, to help troubleshoot issues, it may also help to add thedisplay name or description of the property type into a comment about the rule.

Note: Property Type Identifiers can only be applied to rules that specify an Item Type, and theProperty Types must correspond to the specified Item Type

For example the following property types in the law enforcement schema:

<EntityType Id="ET5" SemanticTypeId="guid8A586959-9837-47DE-8DBF-BC7031F01545" Description="Person details" DisplayName="Person" Icon="Person (Shaded Shirt)">... <PropertyType Position="2" Mandatory="false" SemanticTypeId="guidFE45F1C4-B198-4111-8123-F42D2CD6419D" DisplayName="Date of Birth" Description="" LogicalType="DATE" Id="PER9"> <PossibleValues /> </PropertyType> <PropertyType Position="3" Mandatory="false" SemanticTypeId="guid7548369B-BA9A-4C4B-AEAD-0CB442EAFA27" DisplayName="Gender" Description="" LogicalType="SUGGESTED_FROM" Id="PER15"> <PossibleValues> <PossibleValue Description="" Value="<Unknown>"/> <PossibleValue Description="Male" Value="Male"/> <PossibleValue Description="Female" Value="Female"/> </PossibleValues>...</EntityType>

could be used to create the following rule:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9, PER15" Operators="EQUAL_TO, BETWEEN"/>

Note: This example restriction allows conditions to be run that search for 'equal to' exact values. Inaddition it includes allowing conditions that search between specified values. As a range of valuescannot be determined for a 'suggested from' property type, conditions that are between a specifiedrange will only be enabled for dates of birth.

Date and Time AspectsWhen a rule specifies property types with the DATE or DATE_TIME data type, there are a number ofoptions for querying that data. Rules can be applied to specific aspects of temporal information.DATE_AND_TIME

Apply the rule to conditions that include both a date and time. For example: Searches for peoplespotted in a specific location at specific time.

DATEApply the rule to conditions that focus on a date. For example: Searches for people born on aparticular day.

TIMEApply the rule to conditions that focus on a time. For example: Searches for financial transactionsthat regularly occur at a set time.

DAY_OF_MONTHApply the rule to conditions that focus on the day of the month. For example: Searches for peoplepaid on a specific day of the month.

MONTHApply the rule to conditions that focus on the month. For example: Searches for people bornwithin a specific month.

QUARTERApply the rule to conditions that focus on the quarter of the year. For example: Searches forfinancial results.

YEARApply the rule to conditions that focus on a specific year. For example: Searches for people bornwithin a specific year.

DAY_OF_WEEKApply the rule to conditions that focus on a specific day of the week. For example: Searches forevents that always occur on a Tuesday.

WEEK_OF_YEARApply the rule to conditions that focus on the week of the year as calculated using the ISO weekdate system. For example weekly sales results.

OperatorsYou can use operators to specify the types of visual query condition to restrict. If you do not specifyan operator, the restriction applies to all valid operations.

STARTS_WITHApplies an implicit asterisk to the end of the condition. For example, Starts with: Fred isequivalent to 'Fred*', which might match; Fred, Frederick, or Freddie.Supported logical types:

• SINGLE_LINE_STRING• SUGGESTED_FROM• SELECTED_FROM

Note: The server places a limit on the length of the strings that this operator considers. By default,the limit is 256 characters.


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER4" Operators="STARTS_WITH"/>

ENDS_WITHApplies an implicit asterisk to the start of the condition. For example, Ends with: Fred isequivalent to '*Fred', which might match; Fred, Wilfred, or Alfred.Supported logical types:


Note: The server places a limit on the length of the strings that this operator considers. By default,the limit is 256 characters.

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER4" Operators="ENDS_WITH"/>

CONTAINSApplies an implicit asterisk to both the start and the end of the condition. For example, 'Contains:Fred' is equivalent to '*fred*', which could match any of the above terms, but also include Alfredo.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER4" Operators="CONTAINS"/>

WILDCARD_PATTERNAn exact match to the specified term that includes wildcard characters. For example, Wildcardpattern: Fr?d is equivalent to 'Fr?d', which matches: Fred, but not Alfredo.Supported logical types:

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER4" Operators="WILDCARD_PATTERN"/>

NOT_WILDCARD_PATTERNExcludes an exact match to the specified term that includes wildcard characters. For example,Not wildcard pattern: Fr?d matches anything aside from: Fr?d.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER4" Operators="NOT_WILDCARD_PATTERN"/>

EQUAL_TOAn exact match to the specified term.Supported logical types:

• BOOLEAN• DECIMAL• DATE• DATE_AND_TIME• DOUBLE• INTEGER• TIME• SINGLE_LINE_STRING• SUGGESTED_FROM• SELECTED_FROM

Note: The server places a limit on the length of the strings that the operator considers. By default,the limit is 256 characters.

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9, PER15" Operators="EQUAL_TO"/>

NOT_EQUAL_TOExact matches to the specified term should be excluded. For example, Not equal to: Fredmatches anything aside from: Fred.Supported logical types:


Note: The server places a limit on the length of the strings that the operator considers. By default,the limit is 256 characters.

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="NOT_EQUAL_TO"/>

GREATER_THANMatches values that are higher than a set value.Supported logical types:

• DECIMAL• DATE• DATE_AND_TIME• DOUBLE• INTEGER• TIME

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="GREATER_THAN"/>

GREATER_THAN_OR_EQUAL_TOMatches values that are higher than or equal to a set value.Supported logical types:

• DECIMAL

• DATE• DATE_AND_TIME• DOUBLE• INTEGER• TIME

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="GREATER_THAN_OR_EQUAL_TO"/>

LESS_THANMatches values that are less than a set value.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9, PER15" Operators="LESS_THAN"/>

LESS_THAN_OR_EQUAL_TOMatches values that are less than or equal to a set value.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="LESS_THAN_OR_EQUAL_TO"/>

BETWEENMatches values that are within a set range.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="BETWEEN"/>

IS_SETMatches properties with any populated value.Supported logical types:


For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="IS_SET"/>

IS_NOT_SETMatches properties without a value entered.Supported logical types:

• BOOLEAN• DECIMAL• DATE• DATE_AND_TIME

• DOUBLE• INTEGER• TIME• SINGLE_LINE_STRING• SUGGESTED_FROM• SELECTED_FROM

For example:

<Allow ItemTypeId="ET5" PropertyTypeIds="PER9" Operators="IS_NOT_SET"/>

Restricting Visual Query conditionsBy default, all the Visual Query operators are available for all the record types that support them inyour system. To prevent the creation of queries that take too long to produce results, you canconfigure Visual Query to restrict the operators that are valid in conditions.

Procedure

1. Set the rules that you would like to make to your Visual Query conditions:a) Using an XML editor, open the visual-query-configuration.xml file.

You can find this file in the following location: toolkit\configuration\fragments\opal-services-is\WEB-INF\classes.

b) Using the supplied examples, add the rules that you would like to implement.

Note: Ensure that you add the restrictions paying attention to the ordering as later rules willoverride earlier rules if applicable.

c) Save your changes.2. Update the DiscoServerSettingsCommon.properties file to use your configuration rules.

a) Using a text editor, open the DiscoServerSettingsCommon.properties file.You can find this file in the following location: toolkit\configuration\fragments\opal-services\WEB-INF\classes.

b) Set the VisualQueryConfigurationResourceFor example: VisualQueryConfigurationResource=visual-query-configuration.xml

c) Save your changes.

What to do next

After you redeploy i2 Analyze, run a selection of Visual Queries that use conditions.

Restricting the length of Visual Query listsWhen a Visual Query is constructed by a user, certain conditions allow the values to be specified as alist of values. The length of these lists can be restricted to reduce the size of messages from theclient.

About this task

By default, the number of items that can be used in a list condition for a visual query condition is setto 10000. If you reduce this value, the number of values that can be applied to conditions of this typeis reduced.

Procedure

To modify the list length:1. Using a text editor, open the DiscoServerSettingsCommon.properties file. You can find this

file in the following location: toolkit\configuration\fragments\opal-services\WEB-INF\classes.

2. Edit the value of VisualQueryMaxValuesInList.3. Save and close the file.

What to do next

After you complete the instruction in “Redeploying and resetting i2 Analyze” on page 157 to redeployi2 Analyze, run a selection of Visual Queries that use conditions including lists.

Visual Query scheduleWhen the user enables alerting on a saved Visual Query, the query is run automatically on schedule.The default schedule can be changed to suit your performance requirements and the number ofVisual Queries that are saved with alerting enabled.

By default, the Visual Queries that are saved with alerting enabled are run once every 24 hours, at00:00 according to the server time. If the result of a query is different from the last time that thequery ran, the user receives an alert with this information.

You can change or override the default schedule, as follows.

• Change the time of day that the saved Visual Queries run. For more information, see “Changing thedaily schedule for Visual Queries” on page 143.

• Create a custom schedule to specify when the saved Visual Queries run. For more information, see“Creating a custom schedule for Visual Queries” on page 143.

Note: Running Visual Queries on schedule might impact performance for users of the system. Thefollowing factors are examples of the characteristics of Visual Queries that can affect performance.

• Number of queries• Complexity of the queries• Volume of data searched by the queries

In this situation, consider setting the daily schedule for a quiet period, such as overnight, or settingthe custom schedule for a low frequency.


Changing the daily schedule for Visual QueriesYou can change the time of day that i2 Analyze runs Visual Queries that are saved with alertingenabled. By default, these queries are run once every 24 hours at 00:00 according to the server time.

Procedure


2. Edit the value of AlertScheduleTimeOfDay.The default value is 00:00. The required format is HH:mm. HH is the hour of the day in a 24-hourtime format, 00 - 23, and mm is the number of minutes past the hour, 00 - 59.

3. To ensure that the daily schedule value is implemented, check that theAlertScheduleExpression property is not enabled.For more information, see “Creating a custom schedule for Visual Queries” on page 143.


What to do next

After you complete the instruction in “Redeploying and resetting i2 Analyze” on page 157 to redeployi2 Analyze, the Visual Queries that are saved with alerting enabled are run according to the updateddaily schedule.

Creating a custom schedule for Visual QueriesTo create a custom schedule to run the Visual Queries that are saved with alerting enabled, use aUNIX C cron expression. The default schedule to run these Visual Queries is once every 24 hours, at00:00 hours according to the server time.

About this task

You can create a custom schedule in the AlertScheduleExpression property. TheAlertScheduleExpression property requires a value in UNIX C cron expression format.

With the property AlertScheduleExpression, you can override the default daily schedule. Bydefault, this property is not enabled. If the property is enabled, whenever the value of the expressionmatches the current date and time, i2 Analyze runs the Visual Queries that are saved with alertingenabled. For more information, see UNIX C cron format.

When you enable the property AlertScheduleExpression, its value overrides the value of thedefault property, AlertScheduleTimeOfDay. For more information aboutAlertScheduleTimeOfDay, see “Changing the daily schedule for Visual Queries” on page 143.

Procedure


2. Uncomment AlertScheduleExpression.When you uncomment the AlertScheduleExpression property, the value for this property isused instead of the value for the AlertScheduleTimeOfDay property.

3. Edit the value of AlertScheduleExpression.For example, the value 0 0,4,16,20 * * * schedules the Visual Queries that are saved with alertingenabled to run every 4 hours. A short way of expressing this schedule option is 0 */4 * * *.


https://www.ibm.com/support/knowledgecenter/SSEPGG_9.5.0/com.ibm.db2.luw.sql.rtn.doc/doc/c0054381.html?view=kc


What to do next

After you complete the instruction in “Redeploying and resetting i2 Analyze” on page 157 to redeployi2 Analyze, the updated schedule is applied to run Visual Queries that are saved with alerting enabled.

Configuring the i2 Analyze Analysis Repository searchi2 Analyze enables searching of information that is stored in the Analysis Repository. The quality ofthe search results is affected by the index that the platform creates, and the lists of synonyms that itmaintains for common search terms.

By default, i2 Analyze assumes that item data is in US English when it creates the search index, anduses synonym lists that contains US English terms. When you change the language of the searchindex, a default synonym list in the specified language is used to create the alternative term index.

Creating a custom alternative term indexThe deployment toolkit contains files to create a list of alternative terms for every supportedlanguage. You can modify or replace the supplied files to introduce terms that match the needs ofyour deployment.

About this task

In i2 Analyze, three key components enable the alternative term functionality:

• A dictionary of terms that have alternatives• A list of synonyms for each of the terms in the dictionary• A list of terms that are actively ignored when the user attempts to search for them

The supplied dictionary and synonym list are in the search-alternatives directory of thedeployment toolkit, at configuration\environment\common\search-alternatives.

To customize the alternative terms, you can create files that specify different terms from the suppliedfiles.

Procedure

1. Within toolkit\configuration\environment\common, create the following directorystructure:

- search-alternatives-input - my-alternatives - alternatives

Where my-alternatives is a custom name.For example: toolkit\configuration\environment\common\search-alternatives-input\my-alts\alternatives.

Tip: If you are configuring external data sources, you can create more than one directory in thislocation. For example, you might want to tailor the alternative term index differently for data fromdifferent sources.

2. Copy the contents of the existing search-alternatives directory into your new location.3. Set up the dictionary files:


a) Navigate to the dictionary directory inside your new location, and open the directory for thelanguage that you want to customize.

b) Create a text file that specifies the terms that will have alternatives, one per line.For example:

BikeCarTruckVan

c) Save the file with a .txt extension.

Note: Ensure that the saved file is encoded in UTF-8.4. Set up the synonym lists:

a) Navigate to the synonyms directory inside your new location, and open the directory for thelanguage that you want to customize.

b) Create an XML file that defines synonyms in the following format:

<Synonyms VersionMajor="" VersionMinor="" VersionRelease="" VersionBuild=""> <Entry Word="Term" Syn="Synonym1 Synonym2" /></Synonyms>

For example:

<Synonyms VersionMajor="1" VersionMinor="1" VersionRelease="57" VersionBuild="0"> <Entry Word="BIKE" Syn="BICYCLE MOTORBIKE" /></Synonyms>

c) Save the file with a .xml extension.5. Navigate to the toolkit\configuration\environment\topology.xml file, and open it in an

XML editor.6. For each <lucene-index> element in the file, specify the following attributes:


alternative-id The location of the source files for your custom alternative terms. Forexample, alternative-id="my-alts" looks for the files in thefollowing location: toolkit\configuration\environment\common\search-alternatives-input\my-alts\alternatives\.

Note: This setting defaults to the standard files (if available) for thespecified language-country-code.

stop-words A comma-separated list of words to be filtered out of search conditions.For example: stop-words="a,an,and".

Note: This setting defaults to the Lucene stop word list for the specifiedlanguage-country-code.

7. Within each <war> fragment that uses an index, update the <lucene-index-id> to match thespecified <lucene-index>.


For example:

<lucene-index-ids> <lucene-index-id value="my-index" /></lucene-index-ids>

8. Save your changes.

ResultsWhen you run the deployment scripts, the alternative terms index is created with the specifiedsettings.

Specifying the index languageBy default, the deployment toolkit generates indexes and alternative terms in US English. When youneed to, you can change the language of both the generated indexes and the alternative terms.

Procedure

1. Open topology.xml and locate the <lucene-index> element for the index that you want to setthe language for.

2. Add an attribute of the form language-country-code="xx_XX", where xx_XX is the code forthe language that you want to use.For example:

<lucene-index id="ar" main-index-location="C:/IBM/i2analyze/data/ar/main_index" alternatives-location="C:/IBM/i2analyze/data/ar/alternatives" language-country-code="fr_FR" />

Note: Ensure that all file paths use forward slashes (/).3. Save the topology.xml file.

Note: Ensure that the saved topology.xml file is encoded in UTF-8.

Modifying the wildcard minimum character limitWildcard characters are used to match zero or more alphanumeric characters in a search term. Youcan configure the minimum number of characters that must be included in a search term that includeswildcards.

About this taskThe following wildcard characters are available in i2 Analyze:*

Matches zero or more alphanumeric characters in this position.

For example, the search term Tim* matches Tim, Time, and Timely.

?Matches one alphanumeric character in this position.

For example, the search term Tim? matches Time.

Wildcard characters can be used at any position in a search term.


Search terms with wildcard queries might result in a large number of matches, which might causeperformance problems. To reduce the possible matches from a wildcard search, you can ensure thatusers provide a minimum number of characters with a wildcard. For example, the term "*" will matcheverything. If users must provide a minimum of 3 characters with an asterisk, for example the term"abc*", the number of matches is reduced to values that begin with "abc".

If the minimum number of characters is set too high, users might not be able to search for the termsthat they need. For example, in a deployment where the wildcard minimum characters are configuredas follows:

• A minimum of 3 characters other than asterisks (*) must be provided in a term• A minimum of 2 characters other than question marks (?) and asterisks (*) must be provided in a

term

If the user knows only 2 characters of a license plate, they might not be able to use a wildcard search:

• If the user knows the position of the 2 characters, they can use the question mark wildcardcharacter in the search. If the 2 characters are in positions 2 and 3, then the query "?AB*" is valid inthe configuration that is described.

• If the position of the characters is not known, the user might want to search for "*AB*", which isinvalid in the configuration that is described.

To change the minimum number of characters that must be included in a search query with a wildcardcharacter, edit properties in SearchSettings.properties. The properties that specify theminimum number of characters are:WildcardMinCharsWithAsterisk

The minimum number of characters other than asterisks (*) that must be included in a wildcardquery that contains an asterisk.

WildcardMinCharsWithQuestionMarkThe minimum number of characters other than question marks (?) and asterisks (*) that must beincluded in a wildcard query that contains a question mark. This value should be less than, orequal to the value of the WildcardMinCharsWithAsterisk property.

Procedure

1. Using a text editor, open the SearchSettings.properties file. You can find this file in thefollowing location: toolkit\configuration\fragments\common\WEB-INF\classes.

2. Edit the values of the WildcardMinCharsWithAsterisk andWildcardMinCharsWithQuestionMark properties for the Analysis Repository.


What to do next

After you redeploy i2 Analyze, run a selection of wildcard queries. Continue to change the values ofWildcardMinCharsWithAsterisk and WildcardMinCharsWithQuestionMark until you aresatisfied.


Configuring the i2 Analyze Onyx searchTranslation files are used by Enterprise Insight Analysis to convert between Onyx search requests forthe Information Store, and the Cognos reports format. You can generate translation files with the itemtypes that are present in the schema that you are using.

Before you beginThis task assumes that you have IBM i2 Enterprise Insight Analysis installed, and that you havedeployed a system that uses the i2 Analyze Onyx services for the Information Store.

About this task

In a system that uses the i2 Analyze Onyx services to connect to the Information Store, the translationfiles that map between i2 Analyze search requests and Cognos reports need to be updated if youupdate either the schema, or the reports. Enterprise Insight Analysis includes a tool to createtranslation file templates that are tailored to your schema. The template generator allows you tospecify up to three files as inputs:Schema

A complete description of all the entity types, link types, and their associated property types thatare available for items within a system. In order to generate a translation file, you must providethe schema.

A list of item types to ignoreA comma separated list of the item type IDs that are present in the schema but are not used inany of the reports.

Existing ELP translationIf an existing translation tool is specified, any existing translations that relate to item types thatare specified in the schema are moved to the new file, with any new item types appended readyfor you to configure them.

Using the file above, 2 templates are produced:ELP translation

This file has a entry for each of the item types that was specified in the schema. Each of theseentries needs to be updated with the Cognos report information, to allow the translation to beperformed.

Report translationThis file is used to handle source information and grading information to apply to items when theyare returned in search results.

Procedure

1. Using a text editor, open the toolkit\configuration\fragments\cognos-connector\WEB-INF\classes\TemplateGenerationTools.properties.

2. Populate the value of the SchemaFilePath property with the full path, including the file name, tothe i2 Analyze schema file for which you want to generate a translation file.

3. Set the value of the ELPTranslationFilePath property to the full path, including the file name,for the translation file to generate.

4. Run the setup script to generate the translation file:a) On the i2 Analyze server, open a command prompt and navigate to the toolkit\scripts

directory.


b) Run the following command:

setup -t generateTranslation

ResultsYou have generated the translation files using the information stored in your schema.

What to do nextBefore the translation files can be used, you must update the file with the Cognos report informationthat matches your deployment. See“Updating the translation files to match your reports” on page149.

Updating the translation files to match your reportsEach time that you generate a translation file, or change the reports that you would like to run, youneed to populate your translation file with the information it needs to identify items in Cognos. Byproviding this information, you align the item types that are stored within the schema with the Cognosobjects that they represent, allowing i2 Analyze searches to return results.

About this taskWhen you generate translation files from the i2 Analyze schema:

• An entry for each item type is added to the item translation file allowing you to map these to Cognosobjects.

• A list of the reports that relate to these item types.• A list of the available search filters is created in the item translation file.• A separate results translation file is produced allowing you to specify source and grading

information.

Although default values are provided to identify both the Cognos objects and the correspondingreports, these will need to be modified to match the actual values that are present in your deploymentof Cognos.

Procedure

1. Using an XML editor, open the item translation file that you generated.2. For each ItemType element:

a) Remove the element if you do not want to search on this item type.b) Ensure that the CognosItemType attribute is set to the correct identifier for your system.c) Remove any PropertyType elements that are associated with property types you don't want

to search for.d) For all geospatial property types, you must specify the following additional attributes:


GeospatialId The type of geospatial search that can be carried out on properties ofthis type. By default, the available values are CDR (call detail record)and NLD (network location data). These options, and any others youadd, must correspond to the geospatial search types that areconfigured for your deployment.



Note: When you specify the GeospatialId attribute, you must alsoinclude the VisualQueryChain attribute.

VisualQueryChain A comma-separated list that represents the series of item types in thequery. This must specify either a single entity or a linear chain ofalternating entities and links, starting and ending with an entity. Youmust include at least one instance of the item type that is specified inthe parent ItemType element.

3. For each ReportCollection element:a) Remove the element if you do not want to define a search of this type.b) Ensure the xsi:type attribute is set to the type of report:

• ns3:EntityReports - A report about a specific entity type• ns3:DumbellReports - A report about a pair of linked entity types• ns3:ExpandReports - The supplied analytic that allows linked entities to be found for aspecified entity

• ns3:FindPathReports - The supplied analytic that searches for connections between twoentities

c) In the SummaryReport Element enter the Name of the report.d) Depending on the type of search you selected, populate the remainder of theReportCollection attributes:

• ItemTypeId - Identifies a single item type• End1TypeId - Identifies a valid entity type for the first end of a link• LinkTypeId - Identifies a valid link type for the specified link ends• End2TypeId - Identifies a valid entity type for the second end of a link• End2TypeCognosPromptName - Allows you to specify the Cognos prompt to use to select

the valid values for the second end.4. In the SupportedFilterOperators section, review the available search filters, and remove any

that you do not wish to make available.5. Save and Close the file to store your changes.6. Optional: If your system is set up to require mandatory source information or grading, add the

details to your report results file.

Validating translation filesOnce you have created a translation file and updated the contents to match your reports, you canvalidate the files before attempting a full deployment. Validating the files early allows you to detectand resolve any issues.

Procedure

Run the setup script to validate the translation file:a) On the i2 Analyze server, open a command prompt and navigate to the toolkit\scripts

directory.


b) Run the following command:

setup -t validateTranslation

ResultsThe files provided will be checked to ensure that the structure of the xml is valid, and that allmandatory elements and attributes have been specified.

What to do nextModify the deployment toolkit to specify that i2 Analyze uses the new translation files, and thenredeploy the platform and conduct your tests. If necessary, iterate over these steps again until youhave the translation files that you need.

Understanding translation filesEvery deployment of IBM i2 Enterprise Insight Analysis that uses the Onyx services to access data inthe Information Store must include an item translation file. The contents of the file depend on theschema and on the reports that are available in your deployment.

In outline, the XML file that translates item information into a format that can be used by reports hasthe following structure:

<ArgumentTranslation> <ItemTypes> <ItemType> <PropertyTypes> <PropertyType/> ... </PropertyTypes> </ItemType> ... </ItemTypes> <ReportCollections> <ReportCollection> <SummaryReport/> </ReportCollection> ... </ReportCollections> <SupportedFilterOperators> <FilterOperator/> ... </SupportedFilterOperators></ArgumentTranslation>

Inside the <ArgumentTranslation> root element, the XML file has three main sections:

• ItemTypes contains an entry for each available item type. Each entry contains a list of the propertytypes that the reports make available for users to specify in searches.

• ReportCollections enumerates the different reports that can return information for each itemtype that is identified in the first section. When a link type supports different combinations of entitytypes at the ends of the link, you must define a report collection for every combination.


The item and property types that are associated with a report collection define which item andproperty types are available in visual query. For each item, the report collection specifies theanalytic that is used for each link type and end combination.

• SupportedFilterOperators lists the operators that users can specify against items when theycreate a visual query. Values in this list must match constants from the FilterOperatorenumeration. For more information, see the IBM i2 Analyze API

Item typesThe first section of the translation file defines the item and property types that can be included in avisual query. The list of item types in the translation file can be a subset of the types that are availablein the schema.

In the translation file, the item types that the deployment supports are described inside a parent<ItemTypes> element. Each <ItemType> child element defines a translation from an i2 Analyzeitem type to a specific Cognos item type. In turn, the <PropertyType> child elements list theproperty types that are associated with the parent item type.

Item types

For an item of a particular type in the i2 Analyze schema, a search can produces results that containthe corresponding Cognos item type.

Every <ItemType> element has two mandatory attributes:


Id The identifier in the i2 Analyze schema for the specified item type.

CognosItemType The internal database item type. This value is the Cognos item type.

Property types

Inside an <ItemType> element, the mandatory <PropertyTypes> child element contains a list ofthe available property types for that item type.

Note: Only those property types that you want to make available for users to constrain and filter theirsearches must be specified.

If an item type does not have any properties for which users can search, then the <PropertyTypes>element can be left empty. Otherwise, it contains <PropertyType> child elements.

Every <PropertyType> element is identified using the schema Id and can have more attributes:


Id The identifier in the schema for the specified property type. This attribute ismandatory.

Name A name that describes the property type. This optional attribute is provided tohelp you identify the property types more easily.

GeospatialId An attribute that is only available for Indicates that users can search for itemswith property values that are in a defined geospatial area, rather than matchinga specific set of coordinates. This value is a three letter code that allowsgeospatial properties to be grouped within the user interface.

By default, the available values are CDR (call detail record) and NLD (networklocation data). These options and any others you add must match values


http://ibm-i2.github.io/Analyze/docs/com/i2group/apollo/searchservice/transport/FilterOperator.html


specified in the EIAEsriSearchCommands list inApolloEIAClientSettings.xml.

Note: You can enable geospatial searches for only one item type per Cognositem type, and when you specify the GeospatialId attribute, you must alsoinclude the VisualQueryChain attribute.

VisualQueryChain

A comma-separated list that represents the series of item types in the querythat is created when a user defines a geospatial search area.

You use the identifiers in the schema to identify the item types. The querystructure that you define must be either a single entity or a linear chain ofalternating entities and links, starting and ending with an entity.

Note: You must include in the query at least one instance of the item type thatis specified in the parent <ItemType> element.

Report collectionsIn the translation file, the <ReportCollections> element contains information that enablesEnterprise Insight Analysis to select and run the appropriate report. Report collections define thereports that can be run. The choice of which report to run depends on the type and structure of theresults that the user requires.

When a user searches the Information Store, Enterprise Insight Analysis responds by running aCognos report.

The contents of the <ReportCollections> element reflect the different ways that users canrequest data. The following report types are included:

Report Type Description

Entity Searches for information that is specific to a setitem type.

Dumbbell Searches for information that is specific to a pairof linked entity types.

Expand Uses the expand analytic to search for entitiesthat are linked to a selection.

Find Path Uses the find path analytic to search forconnections between entities.

The translation file contains a <ReportCollection> element for each of the structures that anEnterprise Insight Analysis user can request.

Report collections for entity searches

When a user submits a search request, Enterprise Insight Analysis initially runs a summary report.


The translation file contains one <ReportCollection> element for each entity type that can appearin the results. For example:

<ReportCollection xsi:type="ns3:EntityReports" ItemTypeId="ET3"> <SummaryReport Name="VQ_Entity_Vehicle_sp1"/></ReportCollection>

The xsi:type attribute indicates the search structure for which the reports are intended. TheItemTypeId attribute specifies the item type identifier from the item type definition in thetranslation file.

Each <SummaryReport> child element has a Name attribute that identifies the Cognos report. Whenit is appropriate to do so, you can use the same report for different purposes.

Report collections for dumbell searches

The requirements on reports that run in response to searches for links are similar to the requirementson reports for entity searches. In the translation file, the <ReportCollection> elements for a linktype contain more information than for a single entity type. The extra content is required to identifythe entity types that are connected by links of a particular type in the Information Store. For example:

<ReportCollection xsi:type="ns3:DumbbellReports" End1TypeId="ET5" LinkTypeId="LT4" End2TypeId="ET4" End2TypeCognosPromptName="p_pVal1_toEntityType"> <SummaryReport Name="VQ_Link_MemberOf_sp1"/></ReportCollection>

In comparison to the <ReportCollection> element for reports that return entities, the<ReportCollection> element for link reports has different features. The element itself containsextra attributes that precisely specify the items that the reports return:


End1TypeId The identifier from the i2 Analyze schema for the entity type at the"from" end of the link in the structure for which the reportcollection is intended.

LinkTypeId The identifier from the i2 Analyze schema for the link type in thestructure for which the report collection is intended.

End2TypeId The identifier from the i2 Analyze schema for the entity type at the"to" end of the link in the structure for which the report collectionis intended.

End2TypeCognosPromptName This value is used by analytics for conditional rendering of pageobjects. For example, if a link type can have more than one endtype, the value for End2TypeCognosPromptName specifies thefilter that is used to visualize the data for the specified end type.

Supported filter operatorsThe third section of the XML file that translates requests from i2 Analyze into a form that iscompatible with Cognos is a list of operators for search conditions. The presence of an operator in thelist determines whether users can specify that operator when they search the Information Store.

The <SupportedFilterOperators> element has no attributes and the only child elements are<FilterOperator> elements that take values from the FilterOperator enumeration in the i2


Analyze API. In the translation file for most Enterprise Insight Analysis deployments, the<SupportedFilterOperators> element is similar to the following example:

<SupportedFilterOperators> <FilterOperator>STARTS_WITH</FilterOperator> <FilterOperator>EQUAL_TO</FilterOperator> <FilterOperator>GREATER_THAN</FilterOperator> <FilterOperator>GREATER_THAN_OR_EQUAL_TO</FilterOperator> <FilterOperator>LESS_THAN</FilterOperator> <FilterOperator>LESS_THAN_OR_EQUAL_TO</FilterOperator> <FilterOperator>BETWEEN</FilterOperator></SupportedFilterOperators>

Although the "smart match" operator is included in the FilterOperator enumeration in the API,Enterprise Insight Analysis does not support this operator. If you remove a <FilterOperator>element, then users cannot select that operator in the conditions for all searches of the InformationStore. You cannot enable and disable specific operators for individual item types.

Report resultsThe report results translation file is an optional file that can contain grading information andidentifying source information. If this information is supplied, all items displayed in the IntelligencePortal from the Information Store will have the same values for this information.

Grade information

The <Grades> element specifies the grades that users can assign to properties. Each <Grade> childelement has attributes that set the identifier and value of a grade to be assigned:

<Grades> <Grade GradeTypeId="..." Value="..."/> ...</Grades>

For example:

<Grades> <Grade GradeTypeId="G1" Value="A"/> <Grade GradeTypeId="G2" Value="1"/> <Grade GradeTypeId="G3" Value="1"/></Grades>

Note: If the schema defines mandatory grades, then you must ensure that those grades receivevalues in the translation file.


Source information

The <SourceInfo> element specifies the source information that users can assign to cards. The<SourceInfo> element has attributes that set the type and reference values and contains a<Description> child element to allow a larger description to be assigned:

<SourceInfo Type="" Reference=""> <Description> </Description> </SourceInfo>

For example:

<SourceInfo Type="Information Store" Reference="IS1"> <Description>This information was imported from the Information Store. </Description> </SourceInfo>

Moving a deployment toolkit configurationYou can move the configuration directory between installations of the same version of the deploymenttoolkit. When you move your configuration to a new environment, you must update that configurationwith the details of the new system.

About this task

Before you can move a deployment toolkit configuration to a new environment, you must ensure thatthe same version of the deployment toolkit is installed in both the source and destinationenvironment. For more information about how to install the deployment toolkit, see Installing IBM i2Analyze.

Important: If you are copying into a destination environment that is already configured, make a copyof the existing configuration files before you replace the contents.

Important: Any configuration changes that you completed outside of the configuration directorymust be completed again in the new environment.

Procedure

1. In the source deployment, navigate to the toolkit directory.2. Copy the configuration directory to the toolkit directory of the target i2 Analyze installation.3. Update the values in the configuration files to match the new environment.

For more information about modifying the configuration files, see “Modifying the basicdeployment” on page 1.

4. Deploy i2 Analyze on the new system.For more information, see “Deploying i2 Analyze” on page 158.

What to do nextTest that the deployment works correctly in the new environment.


http://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/installing_i2a.html

http://www.ibm.com/support/knowledgecenter/SSXVXZ/com.ibm.i2.eia.install.doc/installing_i2a.html

Redeploying and resetting i2 AnalyzeAny time that you change the configuration of i2 Analyze, you must redeploy the system. Duringdevelopment, it is common also to need to clear data from the i2 data stores. The i2 Analyzedeployment toolkit includes commands that perform both of these operations.

About this task

Significant changes to the schema or the security schema of an i2 Analyze deployment usuallyinvalidate the information in i2 data stores. As you develop your schemas, you often need to removeand re-import your test data.

After any change to the toolkit configuration of a development or production deployment of i2Analyze, you must redeploy in order to push the change to the running deployment.

Performing these actions in sequence is common before your deployment goes live, but rareafterward. If you do run them in sequence, the combination effectively resets the system to its just-deployed state.

Clearing data from the systemThe clearData task can be used to remove data that is stored in both the index and the database.You can use this task to remove test data from a system.

About this task

Important: These instructions are designed to remove data that is used for test purposes. Do not usethe task to clear data in a production system without backing up your data. For more informationabout backing up your data, see “Backing up a deployment” on page 159.

Procedure

1. On the i2 Analyze server, open a command prompt and navigate to toolkit\scripts.2. To clear data and the search index, run the following command:

setup -t clearData

The following message is displayed when you run the clearData task:Are you sure you want to run the 'clearData' task?This will permanently remove data from the system. (y/n)

Enter Y to continue. The data and the search index are removed from the system.

Removing databases from the systemThe dropDatabases task can be used to remove not only the data, but also the underlyingstructures such as tables from your database management system. You can use this task to removeexisting databases before you recreate the databases in a different location.

About this task

Important: These instructions are designed to remove databases that are used for test purposes. Donot use the task to remove databases in a production system without backing up your data. For moreinformation about backing up your data, see “Backing up a deployment” on page 159.


Procedure

1. On the i2 Analyze server, open a command prompt and navigate to toolkit\scripts.2. To clear data and the search index, run the following command:

setup -t dropDatabases

The following message is displayed when you run the dropDatabases task:Are you sure you want to run the 'dropDatabases' task?This will permanently remove data from the system. (y/n)

Enter Y to continue. The data and the search index are removed from the system. The next timethat you deploy the system, a new database is created.

Deploying i2 AnalyzeTo ensure that your configuration changes are included, you need to deploy them. You might need todeploy multiple times whilst building up your configuration.

About this task

The first time that you deploy i2 Analyze on a server, the script run through all the availabledeployment actions. When you redeploy i2 Analyze, the script updates only the areas of thedeployment that need modification. This behavior reduces the time that it takes for subsequentdeployments.

If you have updated the configuration files with the correct information for your deployment, then thesetup script performs the following actions, depending on whether the areas of the deployment aremodified or not:

• Set up your DB2 data stores• Configure IBM HTTP Server to act as a reverse proxy• Create and configure the application server profiles• Create and deploy the specified applications

Note: If you have a system that includes multiple data sources, generally these have been set up touse different server profiles. There are multiple tasks that are able to function in an environment witha single profile that need to identify the correct profile in situations where there are multiple. Tospecify the server profile, you must add the -s flag with the name. For example, to start the serverprofile for the Information Store, run the following command:

setup -t start -s opal-server

To start the server with the Analysis Repository, run the following command:

setup -t start -s onyx-server

Procedure


command:

setup -t stop



setup -t deploy



setup -t start


Backing up a deploymentAn effective backup strategy considers the key components in your deployment and to assess theimpact of creating replica versions versus the cost of replacing those components if the system fails.All live deployments of i2 Analyze should have a backup strategy in place.

The items that you back up can include not only databases, but also search indexes and thecustomized files that are used to deploy the system.

When you create a backup strategy, it is important to consider the impact of data loss. Otherconsiderations include:

• The amount of time, if any, that is acceptable for a system to be offline to create backups.• The amount of time that is acceptable for a system to be offline while recovery is in progress.• The amount of data, if any, that is acceptable to be unrecoverable by the system.

Backing up an offline i2 Analyze systemAn offline back up is taken when the system is not in use. The advantage in taking a backup when thesystem is not in use is that you have confidence that the

About this task

For a deployment that uses the Analysis Repository, back up the Analysis Repository database, andthe Lucene index directory.

For a deployment that uses the Information Store, back up the Information Store database, and theSolr and ZooKeeper directories.

Regardless of which data stores that you are using, your backup procedure might also include backingup the following items:

• The data directory for i2 Analyze.• The i2 Analyze deployment toolkit configuration files.• The home directory for WebSphere Application Server Liberty profile.• The configuration files for the HTTP reverse proxy.

The environment.properties files in the configuration contain the locations for many of theseitems. Each application that is defined in your topology file has an associated folder in the toolkit\configuration\environment\ directory that stores information about the environment that isspecific to that application.


Procedure

1. Ensure that any application servers are stopped.To stop the application server for the Analysis Repository, run the following command:

setup -s onyx-server -t stop

To stop the application server for the Information Store, run the following command:

setup -s opal-server -t stop

2. Create a backup of the databases in your system by following the instructions for your databasemanagement system.

Note: If you are using IBM DB2 as your database management system, the root location of DB2database file storage is specified by the db.database.location.dir.db2 property in theenvironment.properties file.

3. Make a copy of the data directory for i2 Analyze.

The default directory is C:\IBM\i2analyze\data. The data directory is specified by theapollo.data property in the environment.properties file.

By default the Lucene index, Solr, and ZooKeeper directories are located within this directory.4. Optional: If your Lucene index, Solr, and ZooKeeper directories are not in the default locations,

make a copy of the directories.The directory locations are specified in the topology.xml file, which is stored in the toolkit\configuration\environment directory.

The following elements in the topology.xml file contain the directory locations:

• For the Lucene index directories, the locations of each index are specified in a <lucene-index>element as the values of the main-index-location and alternatives-locationattributes.

• For the Solr directories, the locations are specified in the <solr-node> element as the value ofthe data-dir attribute.

• For the ZooKeeper directories, the locations are specified in the <zkhost> element as the valueof the data-dir attribute.

5. Make a copy of the i2 Analyze deployment toolkit directory that contains the configuration files.The default directory is toolkit\configuration\.

6. Make a copy of the home directory for WebSphere Application Server Liberty profile.

The default directory is C:\IBM\i2analyze\deploy\wlp\usr.

The directory name is specified in the wlp.home.dir property in theenvironment.properties file.

7. Make copies of the HTTP reverse proxy configuration files.

Copy the httpd.conf file that is stored in the C:\IBM\HTTPServer\conf directory, and theplugin-cfg.xml file that is stored in the C:\IBM\HTTPServer\plugins\iap\configdirectory.

8. When your backups are complete, restart the application servers for your system.To start the onyx application server, run the following command:

setup -s onyx-server -t start


To start the opal application server, run the following command:

setup -s opal-server -t start

Recovering an offline backupTo recover a backup that is taken from an offline system, you must restore the databases in yoursystem and copy the files that you backed up into their original locations.

Procedure





2. Restore the databases in your system by following the instructions for your database managementsystem.

3. Copy the backups of the following items into their original locations:

• The data directory for i2 Analyze.• The Lucene index directories for the Analysis Repository.• The Solr and ZooKeeper directories for the Information Store.• The i2 Analyze deployment toolkit configuration files.• The home directory for WebSphere Application Server Liberty profile.• The configuration files for the HTTP reverse proxy.

4. Start the application servers for your system.To start the application server for the Analysis Repository, run the following command:


To start the application server for the Information Store, run the following command:



ResultsAfter the application servers start, the system is ready for use.


Backing up an online i2 Analyze systemWhen the system is in use, you can back up the Analysis Repository and Information Store databases.When you restore the databases, you must reindex the data in the data store.

Procedure

Create a backup of the databases in your system by following the instructions for your databasemanagement system.

By default, the Analysis Repository database is named WRITESTO and the Information Store databaseis named ISTORE.

Recovering an online backupTo recover a backup that is taken from an online system, you must restore the databases in yoursystem. After you restore the databases, you must reindex the data in the data store.

Note: Depending on the amount of data in the store, and the specification of the server, the reindexmight take a long time to complete.

Procedure





2. Restore the databases in your system by following the instructions for your database managementsystem.

3. Clear the search index from the system.To clear the search index for the Analysis Repository, run the following command:

setup -s onyx-server -t clearSearchIndex

To clear the search index for the Information Store, run the following command:

setup -s opal-server -t clearSearchIndex

4. Start the application servers for your system.To start the application server for the Analysis Repository, run the following command:


To start the application server for the Information Store, run the following command:


The reindex process for each application server begins when you start the application server. Thefollowing message is displayed in the console: # Starting search index rebuild.


Note: If the reindex process is interrupted, the process continues from where it was interruptedthe next time that you start the application server.


ResultsAfter the reindex process is complete, the system is ready for use.

Setting up a localized deploymenti2 Analyze is translated into a number of languages. To deploy i2 Analyze in a different language, anumber of customizations need to be made.

When you deploy i2 Analyze, it is possible to display the following localized components:Intelligence Portal

The Intelligence Portal contains the i2 Analyze strings that are displayed to users. By default, ifthe language of the operating system is supported, the Intelligence Portal displays in thatlanguage. You can change the language of the Intelligence Portal by adding the followingparameter to the end of your url:

?lang=xx-XX

Where xx-XX is one of the supported language codes. For example:

http:/my_server:8080/apollo/?lang=fr-FR

SchemaSchemas contain information about the item types and their associated property types. For eachof the example schemas that is included with i2 Analyze, localized versions are also included. Theexample schemas can be used directly, or modified to suit the needs of your deployment.

Note: As the schema is stored within the Analysis Repository, only one language is supported foreach deployment. As such, if the Intelligence Portal strings are changed to a different language,the item type, and property type labels remain in the originally specified language.

Search indexWhen data is added to the system, the platform recognizes terms based on files that have beenprovided in a specific language. Although direct matching is supported for data that is provided inother languages, smart matching and synonyms are only provided for that specified language.

In addition, you can set the Intelligence Portal to display text in a left-to-right mode, or a right-to-leftmode, or to automatically detect the display direction based on the context.

Enabling bi-directional text supportFor certain languages, such as Hebrew and Arabic, text is intended to be displayed right to left. Youcan configure the behavior of the Intelligence Portal, to determine the direction in which to displaytext.

About this task

The ApolloClientSettings.xml file contains two settings that you can configure to enable bi-directional support in i2 Analyze.


BidiEnabledWhether to enable bidirectional support for strings that the system provides. If empty, false, orinvalid, bidirectional support for strings is not enabled.

TextDirectionWhether to enable bidirectional support for strings that users provide. Possible values: 0: Left-to-right only 1: Right-to-left only 2: Contextual (determined by the first strong directionalitycharacter)

Procedure

1. Using a text editor, open the ApolloClientSettings.xml file. You can find this file in thefollowing location: toolkit\configuration\fragments\onyx-services-ar.

2. Using the preceding descriptions, populate the property values for the BidiEnabled andTextDirection properties.



Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently availablein your area. Any reference to an IBM product, program, or service is not intended to state or implythat only that IBM product, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right may be used instead.However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product,program, or service.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You cansend license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimerof express or implied warranties in certain transactions, therefore, this statement may not apply toyou.

This information could include technical inaccuracies or typographical errors. Changes areperiodically made to the information herein; these changes will be incorporated in new editions of thepublication. IBM may make improvements and/or changes in the product(s) and/or the program(s)described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do notin any manner serve as an endorsement of those Web sites. The materials at those Web sites are notpart of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM United Kingdom Limited Hursley House Hursley Park Winchester, Hants, SO21 2JN UK

Such information may be available, subject to appropriate terms and conditions, including in somecases, payment of a fee.

The licensed program described in this document and all licensed material available for it areprovided by IBM under terms of the IBM Customer Agreement, IBM International Program LicenseAgreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements mayhave been made on development-level systems and there is no guarantee that these measurementswill be the same on generally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this document should verify theapplicable data for their specific environment.

© Copyright IBM Corp. 2014, 2018 165

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands,and products. All of these names are fictitious and any similarity to the names and addresses used byan actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrateprogramming techniques on various operating platforms. You may copy, modify, and distribute thesesample programs in any form without payment to IBM, for the purposes of developing, using,marketing or distributing application programs conforming to the application programming interfacefor the operating platform for which the sample programs are written. These examples have not beenthoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability,serviceability, or function of these programs. The sample programs are provided "AS IS", withoutwarranty of any kind. IBM shall not be liable for any damages arising out of your use of the sampleprograms.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names mightbe trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks ortrademarks of Adobe Systems Incorporated in the United States, and/or other countries.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation inthe United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracleand/or its affiliates.

Other names may be trademarks of their respective owners. Other company, product, and servicenames may be trademarks or service marks of others.


http://www.ibm.com/legal/copytrade.shtml

ibm i2 enterprise insight analysis configuring a deployment … · 2020. 2. 14. · going live to...

Documents