Question & Answer
Question
How do I retrieve, update, and delete content from InfoSphere Information Analyzer and run tasks in InfoSphere Information Analyzer using REST API functions?
Answer
Table of contents
GET functions that retrieve the contents from InfoSphere Information Analyzer
Get a list of published analysis results
Get the contents of a particular project including metrics and benchmarks
Get the content of the validity benchmark for rules
Get the list of existing published rules or rule sets
Get the content of published data rule definitions or rule set definitions
Get the contents of metrics
Get the benchmark results included with the execution history and execution results of executable rules
Get the execution history and the execution results of metrics
Get the column analysis results of a column
Get the key analysis results (primary key information)
Get the foreign key and cross-domain analysis results
Get the referential integrity analysis results
POST functions that add content to or update content in InfoSphere Information Analyzer
Create new data rules, rule definitions, or executable rules with folder support
Create rule set definitions that include benchmarks
Modify benchmarks for existing rule set definitions
Copy a published rule to a project
Create new metrics for a project
Modify metrics
DELETE functions that remove content from InfoSphere Information Analyzer
Delete published analysis results
Delete published data rule definitions or rule set definitions
Delete metrics
Process functions that run tasks in InfoSphere Information Analyzer
Start a key analysis
Start a foreign key and cross-domain analysis
Start a referential integrity analysis job
Publish analysis results
Run metrics
Get a list of published analysis results
Command: GET publishedResults
Parameters:
projectName: The name of the project whose table with published analysis results should be listed.
Return value:
An XML document that contains a <PublishedResults> element and specifies one entry for each table that has published analysis results.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/publishedResults?projectName=myProject Example output xml:
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><PublishedResults>
<Table name="BANK.BANK2.TABLE1"/>
</PublishedResults>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getPublishedResults -projectName myProject
Get the contents of a particular project including metrics and benchmarks
Command: GET project
Parameters:
projectName: The name of the project to retrieve
Return value: An XML document that contains all of the properties and defined artifacts of the specified project, including metrics and benchmarks.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/project?projectName=myProjectExample output:
This XML document contains the values for a project that includes elements of type <Metrics>, <ConfidenceBenchmark>, and <BaselineComparisonBenchmark>.
For more information about the <Metrics> elements, go to the topic “Schema file elements for metrics” in the Information Center: http://publib.boulder.ibm.com/infocenter/iisinfsv/v8r7/topic/com.ibm.swg.im.iis.ia.restapi.doc/topics/r_xsd_metrics.html
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><DataSources>
(...)
</DataSources>
<DataRuleDefinitions>
(...)
</DataRuleDefinitions>
<Metrics>
<Metric name=”Unique_accounts”>
<description>Account ID must be unique</description>
<expression>AccountID_Unique % Met</expression>
<MetricBenchmark operator=”greater_or_equal” value=”100”/>
</Metric>
(...)
</Metrics>
<DataRuleDefinitions>
(…)
<RuleSetDefinition name="RuleSet1Def">
<description>Description of Rule1Def</description>
<Benchmarks>
<ConfidenceBenchmark percentRulesNotMetLimit=”0.5” percentRecordsAllowedOverLimit=”0.1”/>
<BaselineComparisonBenchmark benchmarkType=”similarity” operator=”less_than” value=”0.15”/>
</Benchmarks>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getProject -projectName myProject
Get the content of the validity benchmark for rules
Commands:
GET ruleDefinition
GET executableRule
Parameters:
projectName: The name of the project that contains the rule definitions.
ruleName: The name of a rule definition or a comma-separated list of rule definition names. Enclose any name that contains a comma in double quotes.
Return value:
An XML document that contains all the of the properties of the specified items, in particular their benchmarks. Note that a data rule definition and an executable rule can contain different <ValidityBenchmark> elements. And a rule set definition and the executable rules in a rule set definition can contain different <ValidityBenchmark> elements.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/executableRule?projectName=myProject?ruleName= AccountID_Unique,rule2,rule3Example output xml:
An XML document that describes a project that contains <ValidityBenchmark> elements.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><DataRuleDefinitions>
<DataRuleDefinition name="AccountID_Unique_Def">
<ExecutableRules>
<ExecutableRule name="AccountID_Unique">
<description>Account ID must be unique.</description>
<OutputDefinition type="FailingRecords">
<OutputColumn name="Account_ID" type="variable" value="account_id”/>
</OutputDefinition>
<Bindings>
<Binding var="account_id"><Column name="BANK.BANK_SCHEMA.ACCOUNTS"/></Binding>
</Bindings>
<Benchmarks>
<ValidityBenchmark metric=”percent_met” operator=”greater_than” value=”0.99”/>
</Benchmarks>
</ExecutableRule>
</ExecutableRules>
<Benchmarks>
<ValidityBenchmark metric=”nb_not_met” operator=”less_than” value=”5”/>
</Benchmarks>
</DataRuleDefinition>
(...)
</DataRuleDefinitions>
(...)
</DataRuleDefinitions>
</iaapi:Project>
Example CLI commands:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getRuleDefinition -projectName myProject -ruleName myRule
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getExecutableRule -projectName myProject -ruleName myRuleExecutable
Get the list of existing published rules or rule sets
Command: GET publicRules
Parameters:
None
Return value:
An XML document that lists the basic properties of all published rules and rule set definitions.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/publicRulesExample output xml:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:PublicArea xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi"><DataRuleDefinitions>
<DataRuleDefinition name="Rule1Def">
<description>Description of Rule1Def</description>
</DataRuleDefinition>
<DataRuleDefinition name="Rule2Def">
<description>Description of Rule2Def</description>
</DataRuleDefinition>
<RuleSetDefinition name="RuleSet1Def">
<description>Description of Rule1Def</description>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:PublicArea>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml –getPublicRules
Get the content of published data rule definitions or rule set definitions
Command: GET publicRule
Parameters:
ruleName: The name of the rule or rule set to retrieve, or a comma-separated list of rule names. Enclose any name that contains a comma in double quotes.
Return value:
An XML document that contains all of the details of the selected rule or rule set definitions. (output.xml)
Example HTTP request: Retrieving a published data rule definition
GET
https://server:9443/InformationAnalyzer/publicRule?ruleName=ageExample 1: The following XML document is the output returned by the request retrieving a data rule definition.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:PublicArea xmlns:iaapi="
<DataRuleDefinitions>
<DataRuleDefinition name="age">
<description/>
<expression>if age < 18 then marital_status = 'child'</expression>
<Variables>
<Variable dataType="numeric" name="age"/>
<Variable dataType="string" name="marital_status"/>
</Variables>
</DataRuleDefinition>
</DataRuleDefinitions>
</iaapi:PublicArea>
Example HTTP request: Retrieving a published rule set definition
GET
https://server:9443/InformationAnalyzer/publicRule?ruleName=ruleSetExample 2: The following XML document is the output returned by the request retrieving a rule set definition.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:PublicArea xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi"><DataRuleDefinitions>
<RuleSetDefinition name="ruleset" separateVariablesByRule="false">
<description/>
<Variables>
<Variable dataType="numeric" name="age"/>
<Variable dataType="string" name="bankcard"/>
<Variable dataType="string" name="marital_status"/>
<Variable dataType="string" name="profession"/>
</Variables>
<RuleDefinitionReference ruleName="age"/>
<RuleDefinitionReference ruleName="profession"/>
<RuleDefinitionReference ruleName="bankcard"/>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:PublicArea>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getPublicRule -ruleName myPublicRule
Get the contents of metrics
Command: GET metrics
Parameters:
projectName: The name of the project from which to retrieve metrics.
metricName (optional): The name of a metric, or a comma-separated list of metric names. Enclose any name that contains a comma in double quotes. If you omit this parameter, all metrics for the specified project are returned.
Return value:
An XML document that contains one or more metrics.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metrics?projectName=myProjectExample output:
This XML document contains an element on metrics (<Metrics>). For more information about the <Metrics> elements, go to the topic “Schema file elements for metrics” in the Information Center: http://publib.boulder.ibm.com/infocenter/iisinfsv/v8r7/topic/com.ibm.swg.im.iis.ia.restapi.doc/topics/r_xsd_metrics.html
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><Metrics>
<Metric name=”Unique_accounts”>
<description>Account ID must be unique.</description>
<expression>AccountID_Unique % Met</expression>
<MetricBenchmark operator=”greater_or_equal” value=”100”/>
</Metric>
(...)
</Metrics>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getMetrics -projectName myProject -metricName myMetric|
Get the benchmark results included with the execution history and execution results of executable rules
Command: GET executableRule/executionHistory
Parameters:
projectName: The name of the project that contains the rules.
ruleName: A comma-separated list of executable rule names. Enclose any name that contains a comma in double quotes. If you omit this parameter, the execution history for all executable rules is retrieved.
Return value:
An XML document that has the following structure. You can get benchmark results for the <ValidityBenchmark>, <BaselineComparisonBenchmark>, and the <ConfidenceBenchmark>.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/executableRule/executionHistory?projectName=myProject&ruleName=Rule1Exec1,RuleSetExec1Example output xml:
The following document contains the execution history for a rule and a rule set and includes benchmark results.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><DataRuleDefinitions>
<!-- Example for a simple rule -->
<DataRuleDefinition name="Rule1Def">
<ExecutableRules>
<ExecutableRule name="Rule1Exec1">
<ExecutionHistory>
<RuleExecutionResult
startTime="2010-02-09T18:56:31+01:00"
endTime="2010-02-09T18:57:02+01:00"
id=”1”
status="successful"
nbOfRecords="10"
nbPassed="10"
percentPassed="1.0"
nbFailed="0"
percentFailed="0.0"
<ValidityBenchmarkResult result=”passed”
percentVariance=”0.5”
absoluteVariance=”104”>
<ValidityBenchmark metric=”percent_met” operator=”greater_than” value=”0.6”/>
</ValidityBenchmarkResult>
runBy="admin"/>
</ExecutioHistory>
</ExecutableRule>
</ExecutableRules>
</DataRuleDefinition>
<!-- Example for a rule set -->
<RuleSetDefinition name="RuleSetDef">
<ExecutableRules>
<ExecutableRule name="RuleSetExec1">
<ExecutionHistory>
<RuleSetExecutionResult
startTime="2010-02-09T18:56:31+01:00"
endTime="2010-02-08T14:34:26+01:00"
id=”1”
status="successful"
nbOfRecords="100"
runBy=”admin”
nbRules=”10”
meanNbFailedRulesPerRecord=”1.15”
stddevNbFailedRulesPerRecord=”0.13”
meanPercentFailedRulesPerRecord=”0.115”
stddevPercentFailedRulesPerRecord=”0.013”>
<AbsoluteFailureDistribution>
<DiscreteDistributionItem value=”0” percentFrequency=”0.35”
absoluteFrequency=”35”/>
<DiscreteDistributionItem value=”1” percentFrequency=”0.60”
absoluteFrequency=”60”/>
<DiscreteDistributionItem value=”3” percentFrequency=”0.5”
absoluteFrequency=”5”/>
<DiscreteDistributionItem value=”4” percentFrequency=”0.0”
absoluteFrequency=”0”/>
</AbsoluteFailureDistribution>
<RuleExecutionResult id=”rule1”
nbPassed="85" percentPassed="0.85" nbFailed="15" percentFailed="0.15"/>
<RuleExecutionResult id=”rule2”
nbPassed="80" percentPassed="0.80" nbFailed="20" percentFailed="0.20"/>
<RuleExecutionResult id=”rule3”
nbPassed="90" percentPassed="0.90" nbFailed="10" percentFailed="0.10"/>
<ValidityBenchmarkResult result=”passed”
percentVariance=”0.5”
absoluteVariance=”104”>
<ValidityBenchmark metric=”percent_met” operator=”greater_than” value=”0.8”/>
</ValidityBenchmarkResult>
<ConfidenceBenchmarkResult result=”passed”
rulesPercent=”0.55”
maxRecOverLimit=”20”
actRecOverLimit=”13”
percentVariance=”0.72”
absoluteVariance=”23”>
<ConfidenceBenchmark percentRulesNotMetLimit=”0.3”
percentRecordsAllowedOverLimit=”0.05”/>
<ConfidenceBenchmarkResult/>
<BaselineComparisonBenchmarkResult result=”passed”
percentSimilarity=”0.55”
percentDegradation=”0.2”
percentImprovement”0.16”
variance=”0.18”/>
<BaselineComparisonBenchmark benchmarkType=”improvement”
operator=”less_than” value=”0.05”/>
</BaselineComparisonBenchmarkResult>
</RuleSetExecutionResult>
</ExecutionHistory>
</ExecutableRule>
</ExecutableRules>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getExecutionHistory -projectName myProject -ruleName myRule
Get the execution history and the execution results of metrics
Command: GET metric/ExecutionHistory
Parameters:
projectName: The name of the project that contains the metrics.
metricName: A comma-separated list of metric names. Enclose any name that contains a comma in double quotes. If you omit this parameter, the execution history for all metrics is retrieved
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metric/executionHistory?projectName=myProject&metricName=myMetricReturn value:
An XML document with the following structure. For more information about the <Metrics> elements, go to the topic “Schema file elements for metrics” in the Information Center: http://publib.boulder.ibm.com/infocenter/iisinfsv/v8r7/topic/com.ibm.swg.im.iis.ia.restapi.doc/topics/r_xsd_metrics.html
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><Metrics>
<Metric name="myMetric">
<ExecutionHistory>
<MetricExecutionResult
id=”0”
timeStamp="2010-02-09T18:56:31+01:00"
status=”successful”
value=”0.01956”
runBy="admin">
<MetricBenchmarkResult result=”passed” variance=”0.0023”>
<MetricBenchmark operator=”greater_or_equal” value=”98”/>
</MetricBenchmarkResult>
</MetricExecutionResult>
<MetricExecutionResult
id=”1”
timeStamp="2010-02-09T19:23:00+01:00"
status=”successful”
value=”0.0234”
runBy="admin">
<MetricBenchmarkResult result=”passed” variance=”0.0012”>
<MetricBenchmark operator=”greater_or_equal” value=”98”/>
</MetricBenchmarkResult>
</MetricExecutionResult>
</ExecutionHistory>
</Metric>
</Metrics>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output -output.xml -getMetricExecutionHistory -projectName myProject -metricName myMetric
Get the column analysis results of a column
Command: GET columnAnalysis/results
Parameters:
projectName: The name of the project that contains the columns.
columnName: The name of the column for which the frequency distribution is retrieved. The names must be fully qualified (DATASOURCE.SCHEMA.TABLE.COLUMN). The detailed column analysis results of several columns can be retrieved in one operation by providing a comma-separated list of column names or by using a wild card character (*).
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metric/columnAnalysis/results?projectName=myProject&columnName=TEST.TEST.SCALAR.FLOAT_EXPReturn value:
An XML document that has the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><DataSource name="TEST">
<Schema name="TEST">
<Table name="SCALAR">
<Column name="FLOAT_EXP">
<ColumnAnalysisResults>
<ColumnAnalysisResultsProperties reviewed=”true”>
<DataType>
<InferredDataType name=”SFLOAT” count=”9” percent=”90”>
<InferredDataType name=”INT8” count=”1” percent=”10”>
</DataType>
<Length minimum=”1” median=”11” average=”9.9 maximum=”11” range=”10”
standardDeviation=”2.98”/>
<Precision defined=”8” inferred=”10” selected=”10”
minimum=”1” median=”9” average=”8.5” maximum=”10” range=”9”
standardDeviation=”2.5788”/>
<Nullability defined=”yes” inferred=”no” selected=”no”
percentNull=”0” threshold=”1” />
<Scale defined=”0” inferred=”9” selected=”9”
minimum=”0” median=”9” average=”7.8” maximum=”9” range=”9”
standardDeviation=”2.638”/>
<CardinalityType defined=”NotConstrained” inferred=”Unique” selected=”Unique”
absoluteRecords=”10” absoluteCardinality=”10”
percentCardinality=”1” percentUnique=”1” thresholdUnique=”0.99”
percentConstant=”0.1” thresholdConstant=”0.99”/>
</ColumnAnalysisResultsProperties>
<ColumnAnalysisResultsProperties reviewed=”true”>
<ColumnAnalysisResultsFormat reviewed=”true”>
<GeneralFormat format=”9.999999999” count=”6” percent=”0.6” status=”conform”>
<DistinctValue value=”0.000453” count=”1” percent=”0.1”>
(...)
</GeneralFormat>
(...)
</ColumnAnalysisResultsFormat>
</ColumnAnalysisResults>
</Column>
</Table>
</Schema>
</DataSource>
</DataSources>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getColumnAnalysisResult -projectName myProject -columnName mySource.mySchema.myTable.mycolumn
Get the key analysis results (primary key information)
Command: GET keyAnalysis/results
The compositeMax element, which is optional, indicates the maximum number of columns in the analysis.
Parameters:
projectName: The name of the project that contains the tables that were analyzed.
tableName: A comma-separated list of table names for which key analysis results are retrieved. The names must be fully qualified (DATASOURCE.SCHEMA.TABLE). Use a wild card character (*) to include all tables in a schema or database.
percentagesAbove: Optional The threshold for percentages of uniqueness (between 0 and 1) to retrieve the key results for.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metric/keyAnalysis/results?projectName=myProject&columnName=BANK.BANK1.BANK_CLIENTSReturn value:
An XML document that has the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi"><description>IAPROJECT</description>
<DataSources>
<DataSource name="SRCDB">
<Schema name="DB2ADMIN">
<Table name="ALLTYPES">
<KeyAnalysisResult>
<SingleColumnKeys>
<SingleColumnKey percentDuplicate="0.5" percentUnique="99.5">
<Column name="DATEOFBIRTH"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="100.0" percentUnique="0.0">
<Column name="DEPENDENTS"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="GROSSSALES"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="LASTNAME"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="QUANTITY"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="FIRSTNAME"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="SALESCODE"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="HOUSENUMBER"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="STREET"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="PASSWORD"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="GENDER"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="ETA"/>
</SingleColumnKey>
<SingleColumnKey percentDuplicate="0.0" percentUnique="0.0">
<Column name="ID"/>
</SingleColumnKey>
</SingleColumnKeys>
<MultiColumnKeys>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="HOUSENUMBER"/>
<Column name="FIRSTNAME"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentDuplicate="2.0" percentUnique="98.0">
<Column name="HOUSENUMBER"/>
<Column name="GENDER"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="HOUSENUMBER"/>
<Column name="SALESCODE"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentDuplicate="2.0" percentUnique="98.0">
<Column name="HOUSENUMBER"/>
<Column name="STREET"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentDuplicate="2.0" percentUnique="98.0">
<Column name="HOUSENUMBER"/>
<Column name="GROSSSALES"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="ID"/>
<Column name="SALESCODE"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="FIRSTNAME"/>
<Column name="GENDER"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="FIRSTNAME"/>
<Column name="LASTNAME"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="FIRSTNAME"/>
<Column name="ETA"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="FIRSTNAME"/>
<Column name="DATEOFBIRTH"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="FIRSTNAME"/>
<Column name="PASSWORD"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="ID"/>
<Column name="GENDER"/>
</MultiColumnKey>
<MultiColumnKey nbOfColumns="2" percentUnique="100.0">
<Column name="ID"/>
<Column name="LASTNAME"/>
</MultiColumnKey>
</MultiColumnKeys>
</KeyAnalysisResult>
</Table>
</Schema>
</DataSource>
</DataSources>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getKeyAnalysisResults -projectName myProject -tableName mySource.mySchema.myTable
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getKeyAnalysisResults -projectName myProject -tableName mySource.mySchema.*
Get the foreign key and cross-domain analysis results
Command: GET crossDomainAnalysis/results
Parameters:
projectName: The name of the project that contains the tables that were analyzed.
columnName: A comma-separated list of column names for which the cross-domain analysis results is retrieved. The names must be fully qualified (DATASOURCE.SCHEMA.TABLE.COLUMN). Use a wild card character (*) to include all columns of a table or schema.
percentOverlapThreshold: (Optional) Minimum percentage of overlap that overlap candidate pairs must have to be retrieved either from base-to-paired or from paired-to-base.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metric/crossDomainAnalysis/results?projectName=myProject&columnName=BANK.BANK_SCHEMAReturn value:
An XML document that has the following structure. The XML document contains a set of <OverlapCandidate> elements either when the percentPairedToBased or the percentBaseToPaired is above the threshold.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><OverlapCandidate baseColumn="BANK.BANK_SCHEMA.BANK_CLIENTS.CLIENT_ID"
pairedColumn="BANK.BANK_SCHEMA.BANK_ACCOUNTS.CLIENT"
absolutePairedToBase="2631"
percentPairedToBase="0.99"
absoluteBaseToPaired="2631"
percentBaseToPaired="0.19"
date="11/5/2009 3:04:00 PM"/>
(...)
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getCrossDomainAnalysisResults -projectName myProject -columnName mysource.mySchema.myTable.myColumn -percentOverlapThreshold 90
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getCrossDomainAnalysisResults -projectName myProject -columnName mysource.mySchema.myTable.* -percentOverlapThreshold 90
Note that the CLI supports only one column.
Get the referential integrity analysis results
Command: GET referentialIntegrityAnalysis/results
Parameters:
projectName: The name of the project that contains the tables that were analyzed.
baseColumnName: The name of the base column that acts as the foreign key whose corresponding referential integrity analysis results should be retrieved. The name must be fully qualified (DATASOURCE.SCHEMA.TABLE.COLUMN).
pairedColumnName: The name of the column that acts as the primary key. The name must be fully qualified (DATASOURCE.SCHEMA.TABLE.COLUMN).
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/metric/crossDomainAnalysis/results?projectName=myProject&baseColumnName=BANK.BANK1.CLIENTS.CLIENT_ID&pairedColumnName=BANK-BANK1.ACCOUNTS.CLIENT_IDReturn value:
An XML document that has the following structure The outermost <Project> element can contain several <ForeignKeyCandidate> elements, each of which documents its primary key and foreign key. For each of the two directions of the foreign key candidate, a sub-element comprises a set of properties. The <ForeignKeyToPrimaryKey> direction can include <Violation> elements that document the foreign key values to which referential integrity does apply.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><ForeignKeyCandidate>
<PrimaryKey>
<Column name="BANK.BANK1.CLIENTS.CLIENT_ID"/>
</PrimaryKey>
<ForeignKey>
<Column name="BANK.BANK1.ACCOUNTS.CLIENT_ID"/>
<ForeignKey/>
<ForeignKeyToPrimaryKey violationsDistinct="3" violationsTotal="4"
integrityDistinct="2,040" integrityTotal="3,179"
...>
<Violation foreignKeyValue="9999/9" records="2" percentage="0.0628"/>
<Violation foreignKeyValue="9999/8" records="1" percentage="0.0314"/>
...
</ForeignKeyToPrimaryKey>
<PrimaryKeyToForeignKey matchingValuesDistinct="2,040" matchingValuesTotal="2,040" .../>
<ForeignKeyCandidate/>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -xml -output output.xml -getReferentialIntegrityAnalysisResults -projectName myProject -baseColumnName mysource.mySchema.myTable.myBaseColumn -pairedColumnName mysource.mySchema.myTable.myPairedColumn
Note that the CLI only supports one base to one paired column name.
Create or add new data rules, rule definitions, or executable rules with folder support
Command: POST create
Parameters:
projectContent: An XML document that describes the rules to create or add. The XML document follows the same syntax that you use to create a new project, but you specify only the information that is necessary to create or add the new rule. To add a new rule, you specify only the <DataRuleDefinition name=> property.
Note that rule definitions, rule sets, and executable rules can be assigned to folders. The value of the folder attribute can be a specific folder name or a folder path in the format folder1/folder2.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><DataRuleDefinitions>
<DataRuleDefinition name="Rule1Def" folder=”folder1/folder2”>
<description>Description of Rule1Def</description>
<expression>y contains 's'</expression>
</DataRuleDefinition>
</DataRuleDefinitions>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -create -projectContent input.xml
Create rule set definitions that include benchmarks
Command: POST create
Parameters:
projectContent: An XML document that describes the rules to create. The XML document uses the same syntax that you use to create a new project, but includes only the information required to create the new rule.
Example input xml:
The following document creates a new rule set definition that includes a <ConfidenceBenchmark> and a <BaselineComparisonBenchmark> element. Note that you cannot create a <ValidityBenchmark>.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><DataSources>
(...)
</DataSources>
<DataRuleDefinitions>
(…)
<RuleSetDefinition name="newRuleSetDef">
<description>Description of newRuleSetDef</description>
<Benchmarks>
<ConfidenceBenchmark percentRulesNotMetLimit=”0.3” percentRecordsAllowedOverLimit=”0.05”/>
<BaselineComparisonBenchmark benchmarkType=”improvement” operator=”less_than” value=”0.05”/>
</Benchmarks>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -create -projectContent input.xml
Modify benchmarks for existing rule set definitions
Command: POST update
Parameters:
projectContent: An XML document that describes the content of the rules to update. The XML document uses the same syntax that you use to create a new rule, but includes only the attributes to update.
Example input xml:
The following document modifies the <ConfidenceBenchmark> and <BaselineComparisonBenchmark>. Note that you cannot modify a <ValidityBenchmark>.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><DataRuleDefinitions>
<RuleSetDefinition name="existingRuleSetDef">
<Benchmarks>
<ConfidenceBenchmark percentRulesNotMetLimit=”0.2” percentRecordsAllowedOverLimit=”0.05”/>
<BaselineComparisonBenchmark benchmarkType=”degradation” operator=”less_than” value=”0.15”/>
</Benchmarks>
</RuleSetDefinition>
</DataRuleDefinitions>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -update -projectContent input.xml
Copy a published rule to a project
Command: GET copyPublicRule
Use this command to copy a published rule to a project. You can rename the rule to avoid conflicts with rules that already exist in the specified project.
Parameters:
ruleName: The name of the rule or rule set. Names containing a comma should be put between double quotes.
projectName: The name of the project where the rule is published.
newRuleName: (Optional) The new name for the rule.
Example HTTP request:
GET
https://server:9443/InformationAnalyzer/copyPublicRule?projectName=myProject&ruleName=myPublicRule&newRuleName=myNewRuleExample CLI command:
IAAdmin -user admin -password admin -host localhost -copyPublicRule -ruleName myPublicRule -projectName myProject -newRuleName myNewRule
Create new metrics for a project
Command: POST create
Parameters:
projectContent: An XML document that describes the metrics to create.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input:
The following metric is added to the project myProject. For more information about the <Metrics> elements, go to the topic “Schema file elements for metrics” in the Information Center: http://publib.boulder.ibm.com/infocenter/iisinfsv/v8r7/topic/com.ibm.swg.im.iis.ia.restapi.doc/topics/r_xsd_metrics.html
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><Metrics>
<Metric name=”Country_code_validation”>
<description>Country code must be valid</description>
<expression>Country code validation exec % Met</expression>
<MetricBenchmark operator=”greater_or_equal” value=”90”/>
</Metric>
(...)
</Metrics>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -create -projectContent input.xml
Modify metrics
Command: POST update
Parameters:
projectContent: An XML document that describes the metrics to modify. You use the same syntax that you use to create a new metric, but you specify only the attributes that you want to modify.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input:
The operator attribute of the MetricBenchmark for the following metric is changed. For more information about the <Metrics> elements, go to the topic “Schema file elements for metrics” in the Information Center: http://publib.boulder.ibm.com/infocenter/iisinfsv/v8r7/topic/com.ibm.swg.im.iis.ia.restapi.doc/topics/r_xsd_metrics.html
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="myProject"><Metrics>
<Metric name=”Country_code_validation”>
<MetricBenchmark operator=”greater_or_equal” value=”98”/>
</Metric>
(...)
</Metrics>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -update -projectContent input.xml
Delete published analysis results
Command: DELETE publishedResults
Parameters:
projectName: The name of the project that contains the table whose published analysis results are to be deleted.
tableName: The name of the tables whose published analysis results should be deleted. The names must be fully qualified (DATASOURCE.SCHEMA.TABLE). The published analysis results of several columns can be retrieved in one operation by providing a comma separated list of table names and/or using wildcards *.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example HTTP request:
DELETE
https://server:9443/InformationAnalyzer/publishedResults?projectName=myProject&tableName=mySource.mySchema.myTableExample CLI command:
IAAdmin -user admin -password admin -host localhost -deletePublishedResults -projectName myProject -tableName mySource.mySchema.myTable
Delete published data rule definitions or rule set definitions
Command: DELETE publicRule
Parameters:
ruleName: The name of a rule definition or rule set definition, or a comma-separated list of rule names to delete if more than one project should be deleted. Enclose any name that contains a comma in double quotes.
Return value:
None if the operation ran without problems. If problems occurred, it will return an XML document containing the eventual warnings or errors that was thrown during the execution.
Example HTTP request:
DELETE
https://server:9443/InformationAnalyzer/publicRule?ruleName=myPublicRuleExample CLI command:
IAAdmin -user admin -password admin -host localhost -deletePublicRule -ruleName myPublicRule
Delete metrics
Command: DELETE metric
Parameters:
projectName: The name of the project that contains one or more metrics to delete.
metricName: The name of a metric, or a comma-separated list of metric names. Enclose any name that contains a comma in double quotes.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example HTTP request:
DELETE
https://server:9443/InformationAnalyzer/metric?projectName=myProject&metricName=myMetricExample CLI command
IAAdmin -user admin -password admin -host localhost -deleteMetric -projectName myProject -metricName myMetric
Start a key analysis
Command: POST executeTasks
Parameters:
Content: An XML document that specifies the name of the project and the task to run.
The launch of a key analysis is specified by using a <RunMultiColumnKeyAnalysis> element that can contain one or more references to tables to analyze for single-column or multi-column keys. The compositeMax element indicates the maximum number of columns in the analysis.
The names of tables are fully qualified (DATASOURCE.SCHEMA.TABLE). A <Table> element can contain an optional <Column> element that restrict the scope of the multi-column key analysis to a subset of the columns in a table.
You can use a wild card character (*) to represent the database, schema, or table. For example, “BANK.BANK1.*” specifies everything under BANK.BANK1. “BANK.*” specifies everything under the data source BANK.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input xml:
This document starts the multi-column key analysis on all of the tables in the schema BANK1 of the database BANK and on the table BANK.BANK2.TABLE1.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><Tasks>
<RunMultiColumnKeyAnalysis compositeMax="2">
<Table name="BANK.BANK1.*"/>
<Table name="BANK.BANK2.TABLE1">
<Column name="COL1">
<Column name="COL2">
<Column name="COL5">
<Column name="COL8">
</Table>
</RunMultiColumnKeyAnalysis>
</Tasks>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -runTasks -content input.xml
Start a foreign key and cross-domain analysis
Command: POST executeTasks
Parameters:
Content: An XML document that specifies the name of the project and the task to run.
The launch of a foreign key relationship analysis is specified by using a <RunCrossDomainAnalysis> element, which can contain a set of <ColumnPair> elements. The <ColumnPair> elements can contain <BaseColumns> and <PairedColumns> elements. The element <BaseColumns> comprises <Column> elements with fully qualified names. These column names have the form DATASOURCE.SCHEMA.TABLE.COLUMN. The element <PairedColums> contains columns to be paired with the ones in <BaseColumns>.
You can use a wild card character (*) to represent the database, schema, or table. For example, “BANK.BANK1.*” specifies everything under BANK.BANK1. “BANK.*” specifies everything under the data source BANK.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input xml:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><Tasks>
<RunCrossDomainAnalysis excludeColContainingNulls=”false”
excludeByMinimumUniquenessPercent=”0.1”
excludeDateDataClass=”false”
excludeIndicatorsDataClass=”false”
excludeTestDataClass=”false”
excludeByMaximalLength=”1000”
excludeColumnsMissingColumnAnalysisResults=”true”>
<ColumnPair>
<BaseColumns>
<Column name="BANK.BANK_SCHEMA.CUSTOMER.CLIENT_ID "/>
</BaseColumns>
<PairedColumns>
<Column name="BANK.BANK_SCHEMA.ACCOUNTS.*"/>
</PairedColumns>
</ColumnPair>
</RunCrossDomainAnalysis>
</Tasks>
</iaapi:Project>
This task will start a foreign key and cross domain relationship analysis between the SCHEMA.CUSTOMER.CLIENT_ID and all compatible columns in the table BANK.BANK_SCHEMA.ACCOUNT.
The <RunCrossDomainAnalysis> element can also contain optional job property elements to specify sampling and scheduling.
Example CLI command:
IAAdmin -user admin -password admin -host localhost -runTasks -content input.xml
Start a referential integrity analysis job
Command: POST executeTasks
Parameters:
Content: An XML document that specifies the name of the project and the task to run.
The launch of a referential integrity analysis is specified by using a <RunReferentialIntegrityAnalysis> element which can contain one or more foreign key candidate sub-elements. The referential integrity analysis is performed for these foreign key candidates. Note that a referential integrity analysis can be started only if the specified primary column has the status of a selected primary key.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input xml:
This document starts the referential integrity analysis on the foreign key candidate with the primary key BANK.BANK1.CLIENTS.CLIENT_ID and the foreign key BANK.BANK1.ACCOUNTS.CLIENT_ID. The <RunReferentialIntegrityAnalysis> element can also contain an optional job property element to specify scheduling.
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><Tasks>
<RunReferentialIntegrityAnalysis>
<ForeignKeyCandidate>
<PrimaryKey>
<Column name="BANK.BANK1.CLIENTS.CLIENT_ID"/>
</PrimaryKey>
<ForeignKey>
<Column name="BANK.BANK1.ACCOUNTS.CLIENT_ID"/>
</ForeignKey>
</ForeignKeyCandidate>
</RunReferentialIntegrityAnalysis>
</Tasks>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -runTasks -content input.xml
Publish analysis results
Command: POST publishResults
Parameters:
content: An XML document that specifies the name of the tables and the results to publish.
The publishing of analysis results is specified by using a <PublishResult> element that can contain one or more references to tables whose current analysis results are to be published.
The names of tables are fully qualified (DATASOURCE.SCHEMA.TABLE) and can contain wild card characters (*) that represent none to several characters.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input xml:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"><Tasks>
<PublishResults>
<Table name="BANK.BANK1.* "/>
<Table name="BANK.BANK2.TABLE1"/>
</PublishResults>
</Tasks>
</iaapi:Project>
Example CLI command:
IAAdmin -user admin -password admin -host localhost -publishResults -content input.xml
Run metrics
Command: POST executeTasks
Parameters:
projectContent: An XML document that describes the metrics to run.
Return value:
None, if the operation runs without problems. If problems occur, an XML document that contains warnings and errors is returned.
Example input xml:
<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="
http://www.ibm.com/investigate/api/iaapi" name="projectName"> <Tasks>
<RunMetrics>
<Metric name="metric11"/>
<Metric name="metric12"/>
<Metric name="metric13"/>
</RunMetrics>
</Tasks>
</iaapi:Project>
The <RunMetrics> element can also contain an optional job properties element to specify scheduling.
Example CLI command:
IAAdmin -user admin -password admin -host localhost -runTasks -content input.xml
[{"Product":{"code":"SSZJLG","label":"InfoSphere Information Analyzer"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.7","Edition":"All Editions","Line of Business":{"code":"","label":""}}]
Was this topic helpful?
Document Information
Modified date:
16 June 2018
UID
swg21516335