FICO Blaze Advisor API Developer’s Guide

API Developer’s Guide

For Java FICO™ Blaze Advisor®

business rules management system

Version 6.9

www.fico.com Make every decision count™

This document is the confidential, unpublished property of Fair Isaac Corporation. Receipt or possession
of it does not convey rights to divulge, reproduce, use, or allow others to use it except as expressly
provided in the license agreement between user and Fair Isaac Corporation.
The information in this document is subject to change without notice. If you find any problems in this
documentation, please report them to us in writing. Fair Isaac Corporation does not warrant that this
documentation is error-free, nor are there any other warranties with respect to the documentation except
as may be provided in the license agreement.
© 2000–2010 Fair Isaac Corporation. All rights reserved.
FICO is a registered trademark of Fair Isaac Corporation in the United States and may be a trademark or
registered trademark of Fair Isaac Corporation in other countries. Other product and company names
herein may be trademarks of their respective owners.
FICO™ Blaze Advisor® business rules management system is covered by Fair Isaac U.S. Patents: 6865566,
6965889, 66968328, 6944604, and others listed in Fair Isaac documentation.

FICO Blaze Advisor 6.9 for Java - Service Pack 1

Last Revised May 14, 2010
Version 6.9
Template LG 6.0
Contents

Contents

CHAPTER 1
ROM and PROM APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
The Repository Object Model (ROM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Connecting to a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Exploring the ROM Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Repository Item Typing Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Project Repository Object Model (PROM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The PROM Project (NdPromProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Exploring the PROM Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
PROM Item Content (NdPromItemContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
NdPromEntity (and its sub-interfaces). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
NdPromTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
NdPromInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
NdPromProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Entity Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Accessing Entity Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
SRL Entity Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Ruleflow Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Question Set Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Common ROM API and PROM API Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Specifying a Location (NdLocation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Creating Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Creating a PROM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Loading a PROM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Creating an SRL Ruleset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Creating an SRL Function (NdPromSrlFunction). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Creating a Ruleflow (NdPromFlowRuleflow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Creating a Question Set (NdPromAaiQuestionSet) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Creating an SRL Class (NdPromSrlClassContent) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Creating an SRL Enumeration (NdPromSrlEnumerationContent) . . . . . . . . . . . . . . . . . . . . . . . 24

CHAPTER 2
BOM Admin APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Manipulating Imported External Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
NdPromBomAdmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
NdClassMappingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
NdClassNameCustomizingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Creating a New XML BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Saving a New or Existing BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Saving a New BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Saving an Existing BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Fair Isaac Corporation Confidential and Proprietary Information 3

Contents

Add or Remove Items to or from Existing BOM(unexposed API) . . . . . . . . . . . . . . . . . . . . . . . 29

Customizing a BOM(unexposed API). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

CHAPTER 3
Metaphor APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Loading a Metaphor Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Creating a Metaphor Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Decision Table Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example: Display an Overview of a Decision Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Decision Tree Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example: Create a Subtree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Score Model Editing API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Example: List Contents of a Score Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CHAPTER 4
Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Responsibilities of Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Overview of the Custom Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
NdTemplateValueProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
NdDefaultTemplateValueProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NdConstrainedListProvider Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NdDefaultConstrainedListProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
NdDesignProvider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
NdProvidesDefaultValue Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Creating Custom Provider Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Simple Value List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Simple SRL and Display List Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Customizing Provider Behavior Using Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Defining Argument Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Processing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
The Example Base Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Custom Provider Implementation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

CHAPTER 5.............................................
RMA Service and Session APIs . . . . . . . . . . . . . . . . . . . . . . 59
The RMA Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
The RMA Repository (NdRmaRepository) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
RMA Project (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
RMA Entry (NdRmaEntry). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
RMA Directory (NdRmaDirectory). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
RMA Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
File (NdRmaFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Project (NdRmaProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Subproject (NdRmaSubProject) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Template File (NdRmaTemplateFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Instance File (NdRmaInstanceFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Editable File (NdRmaEditableFile) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
File Content (NdRmaFileContent). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
RMA Template (NdRmaTemplate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
RMA Instance (NdRmaInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Instance Element Node (NdInstanceElementNode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

4 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Versioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Versioning Operations (NdRmaEntryVersioningOperations) . . . . . . . . . . . . . . . . . . . . . . . 75
Versioning Information (NdRmaEntryVersioningInfo) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
RMA Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Query Instance (NdRmaQueryInstance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Query Results (NdRmaQueryResultItem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Filtering Entries in an RMA Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
RMA Entry Filter Manager (NdRmaEntryFilterManager) . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Entry Exclusion Filter (NdRmaEntryExclusionFilter) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
RMA Session API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
RMA Session (NdRmaSession) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
RMA Session Properties (NdRmaSessionProperties) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
RMA View (NdRmaView) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
RMA View Properties (NdRmaViewProperties) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

CHAPTER 6
Base Repository and Version Management APIs . . . . . . . . . 89
Storage Layer Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
About the Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Version Management Client Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Version Management System Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Administration Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Repository Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Repository Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Repository Entry Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Fair Isaac Corporation Confidential and Proprietary Information 5

Contents

6 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 1

ROM and PROM APIs

The FICO™ Blaze Advisor® business rules management system ROM and PROM APIs
allow you to programmatically read, modify and create entries in the repository. You
can use the APIs to navigate a repository, modify or create a project, create directories
and add them to a project, inspect and modify the contents of a repository item, create
fixed entities, and perform various versioning operations.

The PROM API provides the ability to load templates and providers and to load, create,
and modify instances. The PROM API also supports the ability to programmatically
create and modify entities with fixed content. The term fixed content, as used in this
chapter, signifies that an entity’s content does not contain dynamic elements like
placeholders.

The “Entity Creation” example contains Java code which demonstrates how to use the
ROM and PROM APIs to create a named object and add it to an existing project; as well
as how to create a new project with several entities. The example is located in
<ADVISOR_HOME>/examples/repositories/ExamplesRepository/API Examples/
PROM API/Entity Creation.

The Repository Object Model (ROM)

The Repository Object Model (ROM), is a layer that is used to access the repository's
raw data. ROM models the repository with its hierarchy of directories and items within
the directories. It defines typing for repository items. ROM provides methods for
connecting to the repository, navigating and finding items in the repository, as well as
for reading and writing items. ROM accesses items only as raw data, which are
represented as strings. All read and write operations access the repository directly,
rather than being cached.

Connecting to a Repository
The NdRomConnectionManager interface provides methods to connect and disconnect
from a repository. Pass an NdWorkspaceConnection object to the
newRepositoryConnectionManager() method of NdRomFactory to obtain an
NdRomConnectionManager instance. The connection context (NdRomConnectionContext)
is used to access ROM once you are connected.

The example code below shows how to obtain a connection to a file-based repository.

//NdFileRepositoryConnection extends NdWorkspaceConnection

NdFileRepositoryConnection connection = new NdFileRepositoryConnection();

Fair Isaac Corporation Confidential and Proprietary Information 7

CHAPTER 1: ROM and PROM APIs

// Change the path to the repository as appropriate. The repository should exist.
connection.setRepositoryFolder("C:/repository");
// Connect to repository
NdRomConnectionManager connectionMgr =
NdRomFactory.newRepositoryConnectionManager(connection);
connectionMgr.connect();
NdRomConnectionContext conContext = connectionMgr.getConnectionContext();
NdRomDirectory romRoot = conContext.getRoot();

To disconnect from the repository, call the disconnect() method of

NdRomConnectionManager. To shut down the connection manager, call its shutdown()
method.

Exploring the ROM Model

The organization of the repository is similar to that of a file system. It contains a
hierarchy of directories with a single root directory. Directories contain items and other
directories. A repository item, like a file in a file system, has content but does not
contain other items or directories. Directories and items are both repository entries. This
relationship is represented in the ROM API with the classes NdRomDirectory and
NdRomItem, which both extend NdRomEntry.

A client can explore the ROM starting from the root directory, which can be obtained by
calling the getRoot() method on NdRomConnectionContext. From the root, or any other
directory, you can call getEntries() to get all directories and items contained in the
directory.

// connContext is an NdRomConnectionContext
// romRoot is the root directory of the repository.
NdRomDirectory romRoot = connContext.getRoot();
NdRomEntry[] allEntriesInRepository = romRoot.getEntries();

If you know the location of a repository item, you can look up the entry by calling
lookupEntry(NdLocation) on the directory. The location is specified from the root
directory. NdLocation is discussed in “Specifying a Location (NdLocation)” on page 15.

NdLocation itemLocation = NdLocationFactory.createLocation(

"/Prom API Example/Cross-sell Rules/crossSell");
NdRomItem rulesetItem = (NdRomItem) romRoot.lookupEntry(itemLocation);

Repository Item Typing Attributes

A repository schema element describes a particular type of repository item. The typing
information consists of four attributes: the schema element type, its subtype, content
type, and target. The type signifies the nature of the item; an SRL ruleset, for example. A
subtype is a subcategory of the type. For example, a decision table is a subtype of an
SRL ruleset. The content type specifies whether the item contains fixed content, or is a
template, or a provider, or is an instance of the indicated type and subtype. The target
indicates the purpose of the item. An item used in a rules project has an 'SRL' target. An
item used for repository operations has a 'Repository' target.

Here is a list of repository items and their typing information by type, subtype, content
type, and target.

8 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Decision Tree Template: SRL ruleset, Decision tree, Template, SRL

Decision Tree Instance: SRL ruleset, Decision tree, Instance, SRL
Ruleset Template Instance: SRL Ruleset, No subtype, Instance, SRL
SRL Class: SRL Class, No subtype, Fixed, SRL
SRL Function with Fixed Content: Function, No subtype, Fixed, SRL
Custom Date Provider: Date, No subtype, Provider, SRL
Project: Project, No subtype, Fixed, Repository

In the ROM, the four typing attributes are aggregated into NdRomSchemaElementInfo,
which is accessed from NdRomSchemaElement. The schema elements are managed by
NdRomSchemaManager. It contains a list of all schema elements known to the connected
repository and can lookup the schema element for any repository item.
NdRomSchemaManager is obtained from NdRomConnectionContext.

This code retrieves the type and subtype attributes of a repository item.

// connContext is an NdPromConnectionContext & rulesetItem is an NdRomItem

NdRomSchemaManager schemaManager = connContext.getSchemaManager();
NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(rulesetItem);
NdRomSchemaElementInfo info = schemaElement.getSchemaElementInfo();
int type = info.getType();
int subtype = info.getSubType();

NdRomSchemaManager is also used to obtain an NdRomSchemaElement of a particular type.

You can obtain an instance of NdPromItemFactory from the schema element which is the
factory associated with that particular type of repository item. The factory can be used
to create an NdPromItem in a project from entity content.

/ project is an NdPromProject
NdPromSrlEnumerationContent enumeration =
NdPromBomConstructContentFactory.newSrlEnumerationContent(project);
NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(
TYPE_SRL_ENUMERATION, SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory factory = schemaElement.getItemFactory();
NdPromItem enumItem = factory.newItem((NdPromEntity)enumeration, project);
...

The integer constants for the repository schema typing attributes, including those in the
code above, are declared in the NdRomSchemaConstants interface.

Project Repository Object Model (PROM)

The Project Repository Object Model (PROM), is a layer on top of the ROM that is used
to access the objects in a repository with a project in context. The content of a repository
item is represented as an object. The content is also cached in memory, which means
explicit load and save operations are necessary to sync up the content in memory and
that in storage.

The PROM Project (NdPromProject)

A project, represented by NdPromProject, by definition includes a collection of
references to repository directories and other projects which are subprojects of the

Fair Isaac Corporation Confidential and Proprietary Information 9

CHAPTER 1: ROM and PROM APIs

project. Such a definition effectively defines a scope, which includes all the directories
included by this project, and all the directories included by its subprojects. An instance
of NdPromProject gives access to all the repository entries in the scope. These repository
directories and repository items and their contents form the PROM.

To create an instance of NdPromProject for an existing project repository item, first

obtain an instance of NdRomProject by passing the location of the project repository item
to the lookupEntry() method of the NdRomDirectory interface. Use
NdPromProjectFactory, which is obtained from NdRomConnectionContext, to create the
NdPromProject instance. The code below loads a PROM project from the workspace.

// connContext is an NdRomConnectionContext
// “/directory” represents a directory directly under the repository root
NdRomDirectory root = connContext.getRoot();
NdLocation location = NdLocationFactory.createLocation(“/directory/projectItem”);
NdRomProject romProject = (NdRomProject)root.lookupEntry(location);
NdPromProjectFactory factory = context.getProjectFactory();
NdPromProject project = factory.createProject(romProject);

To create a new project at a location, the client should use the same project factory. The
following is an example of creating a new project. The new project repository item is
created in the directory.

NdLocation location = NdLocationFactory.createLocation(“/directory”);

NdPromProjectFactory factory = context.getProjectFactory();
NdPromProject project = factory.createProject(location);
project.save();

The topics of loading and creating a project are discussed in greater detail in “Loading a
PROM Project” on page 18 and “Creating a PROM Project” on page 17.

NdPromProject only defines a scope. It is not specific to any domain. It has a

subinterface NdPromRulesProject, which can provide additional information and
services specific to the rules domain.

Exploring the PROM Model

Using the getDirectories(), getSubProjects(), and lookupEntry() methods defined
in NdPromProject, the client can explore the PROM. The repository directory and
repository item in the PROM are defined as NdPromDirectory and NdPromItem, which
extend from NdRomDirectory and NdRomItem, respectively.

The PROM API builds on the raw access to the repository which is defined in ROM API
by providing access to the repository with typing and caching. The getItemContent()
method in NdPromItem returns a typed object. This is different from NdRomItem which
has content that is always a String.

The content of a repository item is only loaded after the getItemContent() method is
called. The content is loaded to cache. Once loaded, any change to the content is not
persisted to the storage until the save() method of NdPromItem is called. Any change in
the storage is not reflected in the loaded content until revert() is called and
getItemContent() is called again to load the content from storage.

10 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The addItem() method and removeItem() method in NdPromDirectory only affect the in
memory object model until the save() method is called on the NdPromItem.

The following is an example of loading a repository item:

// project is an NdPromProject
NdLocation location = NdLocationFactory.createLocation(“item/location”);
NdPromItem item = (NdPromItem)project.lookupEntry(location);
NdPromItemContent content = item.getItemContent();

Here is an example of creating a repository item and adding it to a project directory.

// project is an NdPromProject
NdLocation location = NdLocationFactory.createLocation(“directory”);
NdPromDirectory directory = (NdPromDirectory)project.lookupEntry(location);
NdPromItem item = factory.newItem(content, project);
directory.addItem(item);
item.save();

Note that content is a specific type of NdPromItemContent, such as the

NdPromEnumerationContent discussed in “Repository Item Typing Attributes” on page
8. factory is the specific NdPromItemFactory associated with that particular type of
repository item, which is discussed in the same section. Refer to “Common ROM API
and PROM API Tasks” on page 15 for several more examples of creating repository
items. directory is an NdPromDirectory that has been previously added to the project,
as described in “Creating Directories” on page 16.

The following is an example of deleting an existing repository item. Note that the item is
removed in PROM and then saved in order to persist the change to storage.

// project is an NdPromProject
NdLocation parentLoc = NdLocationFactory.createLocation(“directory/item”);
NdPromDirectory directory = (NdPromDirectory)project.lookupEntry(parentLoc);
NdLocation itemLoc = NdLocationFactory.createLocation(“item/location”);
NdPromItem item = (NdPromItem)project.lookupEntry(itemLoc);
directory.removeItem(item);
item.save();

PROM Item Content (NdPromItemContent)

“NdPromItemContent is the content of a repository item. An instance of this interface
represents what the content really is disregarding its persistent format. For example, if
the content is an SRL ruleset, the content object is an instance of NdPromSrlRuleset
although it may actually be persisted as a template.” (From the API Reference entry for
the NdPromItemContent interface. The API Reference is available by selecting API
Reference from the Builder Help menu.)

NdPromEntity (and its sub-interfaces)

If the content of the repository item is an entity, the content object must be a specific
instance of NdPromEntity. For example, if the content of the repository item is an SRL
function, the content object is an instance of NdPromSrlFunction, which extends
NdPromEntity.

Fair Isaac Corporation Confidential and Proprietary Information 11

CHAPTER 1: ROM and PROM APIs

More details of the entity API can be found in “Entity Object Model” on page 12.

NdPromTemplate
If the content of the repository item is an Innovator template of an entity, the content
object must be an NdPromTemplate object. NdPromTemplate gives the client access to the
templatized entity through getEntityContent() method, which returns a specific
instance of NdPromEntityContent. For example, if the content of the repository item is
an Innovator template of an SRL ruleset, getEntityContent() method returns an
instance of NdPromSrlRulesetContent, which extends NdPromEntityContent.

NdPromInstance
If the content of the repository item is an instance of template, the content object must be
an NdPromInstance object. NdPromInstance gives the client access to the instantiation
object model, i.e., a tree of instance nodes. It allows access to the entity resolved from
this instance and its linked template. The resolved entity can be obtained through
getResolvedEntity() method, which returns a specific instance of NdPromEntity. For
example, if the content of the repository item is an Innovator instance of an SRL ruleset,
getResolvedEntity() returns an instance of NdPromSrlRuleset, which extends
NdPromEntity.

NdPromProvider
If the content of the repository item is a provider, the content object must be an
NdPromProvider object. NdPromProvider gives client access to the provider's definition,
including the provider class name.

Entity Object Model

The entity object model is used to access entities and their fields. As described in
“PROM Item Content (NdPromItemContent)” on page 11, an entity can be obtained as
the content of an entity repository item loaded as an object in PROM. An entity can also
be obtained as the templatized content of an Innovator template and as the resolved
content of an Innovator instance.

Accessing Entity Content

The entity object model contains two complementary sets of interfaces for accessing the
content of entities. The API Reference refers to these sets of classes as the entity object
model's "string-based" and "content-based" APIs.

The interfaces of the string-based API represent any field that is text in nature as a
String. This set of interfaces is used to access entities that are not templatized, but are
resolved entities. It provides read-only access. It is primarily used for inspecting the
object model.

The interfaces of the content-based API represent any field that is text in nature by
NdPromTextContent, which is a data structure that may contain dynamic elements like

12 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

placeholders. The subinterfaces of NdPromTextContent represent specialized text

content. For example, the body of an SRL function is represented by
NdPromSrlBodyTextContent. The content-based API is used to access templatized
entities. It provides methods to read and write the content of both templatized and
fixed-content entities.

These two sets of APIs are almost parallel to each other. The naming convention is that
the interface names and method names in the content-based API have the word Content
appended to their counterparts in the string-based API. For example, the content-based
counterpart to the string-based interface NdPromSRLRuleset is
NdPromSRLRulesetContent. NdPromSrlRule is the string-based correlary to
NdPromSrlRuleContent, and so on.

The following code demonstrates how to access a ruleset using string-based interfaces.
A ruleset is represented by the string-based NdPromSrlRuleset interface. The method
getName() returns the ruleset name as a String.

// item is an NdPromItem
NdPromSrlRuleset ruleset = (NdPromSrlRuleset) item.getItemContent();
String name = ruleset.getName();

The getSrlRulesetItems() method returns the ruleset items as an array of

NdPromSrlRulesetItem.

NdPromSrlRulesetItem[] items = ruleset.getSrlRulesetItems();

An SRL rule (NdPromSrlRule) is obtained from the array of ruleset items. NdPromSrlRule
and the other types of ruleset items, such as NdPromSrlPattern, subclass
NdPromSrlRulesetItem.

// assumes the ruleset item is a rule

NdPromSrlRule rule = (NdPromSrlRule) items[0];

The rule body (NdPromSrlRuleBody) is obtained from a rule in a ruleset that is not
templatized using the getSrlRuleBody() method.

NdPromSrlRuleBody ruleBody = rule.getSrlRuleBody();

Here is code which performs similar work using the corresponding content-based
interfaces. The ruleset name is obtained as an NdPromTextContent object.
NdPromSrlRuleContent extends NdPromSrlRuleContent and represents an SRL rule
which could be either templatized or contain fixed content. Similarly, the
NdPromSrlRuleBodyTextContent ruleBody can contain templatized content or fixed
content.

// item is an NdPromItem
NdPromSrlRulesetContent ruleset = (NdPromSrlRulesetContent) item.getItemContent();
NdPromTextContent name = ruleset.getNameContent();
NdPromSrlRulesetItemContent[] items = ruleset.getSrlRulesetItemContents();
// assumes the ruleset item content is a rule
NdPromSrlRuleContent rule = NdPromSrlRulesetItemContent[0];
NdPromSrlRuleBodyTextContent ruleBody = rule.getRuleBodyContent();

As already mentioned, the content-based API contains methods for creating and
modifying the entity content. Use the static newTextContent() method of the

Fair Isaac Corporation Confidential and Proprietary Information 13

CHAPTER 1: ROM and PROM APIs

NdPromTextContentFactory class to create NdPromTextContent for text-based entity

properties such as name and comment.

ruleset.setNameContent (NdPromTextContentFactory.newTextContent("Ruleset name");

rule.setNameContent (NdPromTextContentFactory.newTextContent("Rule name");
rule.setCommentContent (NdPromTextContentFactory.newTextContent("// Sample rule");

This example uses the string-based API to find a particular rule in a ruleset, then it casts
the rule to an NdPromSrlRuleContent object, which is content-based, in order to change
the rule body content.

// project is an NdPromProject
NdLocation rulesetLocation = NdLocationFactory.createLocation("Cross-sell Rules/crossSell");
NdPromItem rulesetPromItem = (NdPromItem)project.lookupEntry(rulesetLocation);
NdPromSrlRuleset ruleset = (NdPromSrlRuleset) rulesetPromItem.getItemContent();
NdPromSrlRulesetItem[] rulesetItems = ruleset.getSrlRulesetItems();

for (int i=0; i<rulesetItems.length; i++) {

if (rulesetItems[i] instanceof NdPromSrlRule) {
String ruleName = ((NdPromSrlRule)rulesetItems[i]).getName();
if (ruleName.equals("rule1")) {
// The string-based NdPromSrlRulesetItem ruleset item is cast to
// content-based interfaces are used exclusively.
NdPromSrlRuleContent rule = (NdPromSrlRuleContent) rulesetItems[i];
// replace rule text
NdPromSrlRuleBodyTextContent ruleBody =
NdPromSrlConstructContentFactory.newSrlRuleBodyContent("rule body replacement text");
rule.setSrlRuleBodyContent(ruleBody);
// print new rule text
NdPromSrlRuleBodyTextContent ruleBodyTextContent = rule.getSrlRuleBodyContent();
System.out.println("The replacement rule body text is” +
ruleBodyTextContent.generate());
}
}
}

SRL Entity Object Model

The object model for SRL entities is in the
com.blazesoft.template.repository.objects.rules package. It contains the
interfaces for the SRL entities as well as various constructs like the expressions and
statements.

The SRL entities include:

„ SRL ruleset (NdPromSrlRuleset)
„ The ruleset items within a ruleset (NdPromSrlRulesetItem), which are:
„ SRL rule (NdPromSrlRule)
„ SRL event rule (NdPromSrlEventRule)
„ SRL named object (NdPromSrlNamedObject)
„ SRL pattern (NdPromSrlPattern)
„ SRL variable (NdPromSrlVariable)
„ SRL function (NdPromSrlFunction)

14 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

„ SRL reason code list (NdPromSrlReasonCodeList)

For examples on how to create SRL entities, see “Creating an SRL Ruleset” on page 18,
“Creating an SRL Enumeration (NdPromSrlEnumerationContent)” on page 24 and
“Creating an SRL Function (NdPromSrlFunction)” on page 21.

Ruleflow Object Model

The object model for ruleflow is in the
com.blazesoft.template.repository.objects.flow package. It contains the interfaces
for various ruleflow constructs including the ruleflow entity itself.

For an example of how to create a ruleflow, see “Creating a Ruleflow

(NdPromFlowRuleflow)” on page 22.

Question Set Object Model

The object model for question set is in the
com.blazesoft.template.repository.objects.aai package. It contains the interfaces
for various question set constructs including the question set itself. Both string-based
API and content-based API exist for these constructs.

For an example of how to create a question set, see “Creating a Question Set
(NdPromAaiQuestionSet)” on page 22.

Common ROM API and PROM API Tasks

This section describes how to perform selected tasks using the ROM and PROM APIs.
All the examples of creating entities are confined to entities that are not templatized;
that is, they do not contain dynamic content.

Specifying a Location (NdLocation)

The NdLocation interface describes the location of entities within a repository. The
interface can describe the location of a repository item, which is referred to as an external
location. The interface can also describe the location of an entity defined within a
repository item. That type of location is called a compound location. It is composed of an
external location describing the location of the repository item and an internal location
which describes the location of the entity within the repository item. Internal locations
are intended for use with templates, as they define the path from the root of the
template document to an inner template or template parameter. The discussion of the
NdLocation interface in this chapter is confined to external locations.

NdLocationFactory contains these static methods, as well as others, which are used to
create an NdLocation.

static NdLocation createLocation(String[] components, boolean absolute)

static NdLocation createLocation(String location)

Fair Isaac Corporation Confidential and Proprietary Information 15

CHAPTER 1: ROM and PROM APIs

In the first method, if the location is absolute (in which case the value of the boolean
absolute is true), each element in the String array represents the name of one of the
repository folders in a path from the root of the repository to the item in question, with
the last element of the array being the storage name of the item. When the location is
relative (the value of the boolean absolute is false), the elements in the String array
represent a directory path that is processed in the context of another location.

The following two method calls are equivalent. They create an NdLocation that is a
relative location.

NdLocation topDirectoryLocation = NdLocationFactory.createLocation(String[] {"Prom API Example"}, false);

NdLocation topDirectoryLocation = NdLocationFactory.createLocation("Prom API Example");

These method calls are also equivalent. They create an NdLocation that is an absolute
location.

// projectFactory is an NdPromProjectFactory
NdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(
new String[]{"PROM API Example", "Entity Creation"}, true));
NdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(
"/PROM API Example/Entity Creation"));

In the first method call the components are elements in a String array. The latter
method call represents the components in a String. The leading ‘/’ character indicates
that the location is absolute.

Whether you should specify the location as absolute or relative will depend on the task
at hand. As mentioned, relative locations are processed in the context of another
location. When a directory is created the location is processed in the context of a parent
directory or the root of the repository. For this reason, you must use a relative location
when created a directory. When looking up a repository item or directory in a project
using the lookupEntry() method of the NdPromProject interface, the location is relative
since the project provides the context. The lookupEntry() method of the
NdRomDirectory interface, however, looks up the entry from the root of the respository
when the supplied location is absolute. If the location is relative the lookup is performed
from the directory. The NdPromProject interface addDirectory() method, which is used
to add a directory to the project, requires an absolute location. The Blaze Advisor API 
Reference entry for each method that takes an NdLocation parameter specifies whether to
use an absolute or a relative location.

Creating Directories
You can create directories with the createDirectory() method of the
NdRomMutableDirectory class. NdRomMutableDirectory is a repository directory that is
mutable. NdRomMutableDirectory extends NdRomDirectory. A mutable directory allows
entries to be added or deleted. Recall that a directory contains entries, which are either
other directories or repository items. NdRomMutableDirectory has methods for creating
both. The deleteEntry() method physically deletes the given repository entry from the
directory.

NdRomDirectory createDirectory(NdLocation location)

NdRomItem createItem(NdLocation location)

16 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

void deleteEntry(String name)

To create a directory under the repository root directory, obtain the root
NdRomDirectory by calling getRoot() on the repository context object
(NdRomConnectionContext). Call createDirectory() on the root directory with the
NdLocation parameter that specfies the location of the new directory. Whenever you
create a directory, the location must be relative and contain only one element in the
String array. The absolute parameter to createLocation() is false when the location
is relative. A new directory is always created with the NdRomMutableDirectory object of
the parent directory and therefore the location is relative to the parent directory. See
“Specifying a Location (NdLocation)” on page 15 for discussion of relative and absolute
locations.

// conContext is an NdRomConnectionContext
NdRomDirectory romRoot = conContext.getRoot();
NdLocation topDirectoryLocation = NdLocationFactory.createLocation(
new String[]{"Prom API Example"}, false);
NdRomDirectory topDirectory = ((NdRomMutableDirectory) romRoot).createDirectory(topDirectoryLocation);
((NdRomMutableDirectory) topDirectory).setDisplayName("PROM API Example");

The directory is created in storage immediately. Note that romRoot must be cast to
NdRomMutableDirectory. NdRomDirectory does not contain methods for creating
repository entries. Set the directory's display name in the GUI with setDisplayName().

The steps are similar for creating a directory in another directory. First, create an
NdLocation that is a relative location with one component. Pass the NdLocation object to
the NdRomMutableDirectory createDirectory() method of the NdRomMutableDirectory
object obtained for the parent directory.

// topDirectory is an NdRomDirectory
NdLocation projectLocation = NdLocationFactory.createLocation(new String[]{"Entity Creation"}, false);
NdRomDirectory entityCreationDirectory =
((NdRomMutableDirectory) topDirectory).createDirectory(projectLocation);

Add the directory to a PROM project and obtain an NdPromDirectory.

// project is an NdPromProject
NdPromDirectory projectDirectory = project.addDirectory(entityCreationDirectory.getLocation());

The next section, “Creating a PROM Project” on page 17, completes the discussion of
creating a directory structure for your project.

Creating a PROM Project

To create a PROM project (NdPromProject), first obtain an NdPromProjectFactory
instance by calling the getProjectFactory() method of the connection context object
(NdRomConnectionContext). Create an NdPromProject by passing an NdLocation to the
factory's createProject() method. The NdLocation must be an absolute location.
Specify each directory component in the String array, including the top level directory
contained in the repository's root directory.

This code creates a PROM project in the Entity Creation directory and adds the
directory to the project.

Fair Isaac Corporation Confidential and Proprietary Information 17

CHAPTER 1: ROM and PROM APIs

// Create a PROM project in the "Entity Creation" directory

// conContext is an NdRomConnectionContext
// entityCreationDirectory is an NdRomDirectory
NdPromProjectFactory projectFactory = conContext.getProjectFactory();
NdPromProject project = projectFactory.createProject(NdLocationFactory.createLocation(
new String[]{"Prom API Example", "Entity Creation"}, true));
project.setDisplayName("Entity Creation");
// Add directory to project
NdPromDirectory projectDirectory = project.addDirectory(entityCreationDirectory.getLocation());

When the project is saved, a repository item of type Project is created in the Entity
Creation directory (entityCreationDirectory). Note that the directory must still be
added to the project by passing the directory location to the NdPromProject
addDirectory() method. As you create more directories for your project, each directory
must be added to the project in this manner.

In like fashion, you can add any directory within the repository to a project. The
NdLocation must be an absolute location. All repository directories that are traversed
from the repository root must be named in component parameter's String array.

NdLocation salariesLocation = NdLocationFactory.createLocation(

new String[]{"Business Object Models","Java","Imported Java BOMs","Salaries"}, true);
NdPromDirectory salariesDirectory = project.addDirectory(salariesLocation);

Loading a PROM Project

To load an existing PROM project (NdPromProject), obtain an NdPromProjectFactory
instance by calling the getProjectFactory() method on the connection context
(NdRomConnectionContext). Create a location (NdLocation) which includes the directory
components from the repository root as well as the PROM project repository item. The
NdLocation must be an absolute location. Obtain an NdRomProject by calling
lookupEntry() on the ROM root directory. Create the PROM project by passing the
NdRomProject object to the factory’s createProject() method.

// conContext is an NdRomConnectionContext
NdPromProjectFactory projectFactory = conContext.getProjectFactory();
NdLocation projectLocation = NdLocationFactory.createLocation(
new String[]{"PROM API Example", "Entity Creation", "Entity Creation"}, true));
NdRomProject romProject = (NdRomProject)romRoot.lookupEntry(projectLocation);
NdPromProject project = projectFactory.createProject(romProject);

Note When you use the PROM API to work with multiple projects, you can release the
resources that a project holds on to by calling the dispose() method of the
NdPromProject interface. To access the project after calling dispose() you must load the
project again.

Creating an SRL Ruleset

The interfaces for creating a ruleset and ruleset items are defined by the object model for
SRL entities in the blazesoft.template.repository.objects.rules package. The
object model is introduced in “Entity Object Model” on page 12. The package contains a
factory class named NdPromSrlConstructContentFactory which is used to create
content-based objects for various SRL constructs.

18 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The example in this section creates a fixed-content SRL ruleset. The public PROM APIs
in the current release of the FICO Blaze Advisor do not support creating templatized
content.

The NdPromSrlConstructContentFactory method newSrlRulesetContent() is used to

create a ruleset, which is an NdPromSrlRulesetContent object. Among the methods
available in NdPromSrlRulesetContent are setNameContent(), setCommentContent(),
and insertSrlRulesetItemContentAt(). The later method is used to add the ruleset
items to the ruleset.

Ruleset items (NdPromSrlRulesetItem) are contained within a ruleset. A ruleset is a

repository item, but ruleset items are not repository items. The two senses of the term item
should not confused. The content of ruleset items are represented by the
NdPromSrlRulesetItemContent interface and include SRL rule
(NdPromSrlRuleContent), SRL named object (NdPromSrlNamedObjectContent), SRL
pattern (NdPromSrlPatternContent), SRL event rule (NdPromSrlEventRuleContent), and
SRL variable (NdPromSrlVariableContent).

Creating a ruleset and ruleset items follows the general pattern of creating the ruleset
with the rewSrlRulesetContent() of NdPromSrlConstructContentFactory interface;
creating each ruleset item with the appropriate NdPromSrlConstructContentFactory
method; creating the content for the ruleset item, usually with methods of
NdPromSrlConstructContentFactory and NdPromTextContentFactory; setting the
content on the ruleset item; and then inserting the ruleset item into the ruleset and
saving the ruleset.

A rule is created with the newSrlRuleContent() method of the

NdPromSrlConstructContentFactory interface. The newTextContent() and
newSrlRuleBodyContent() methods of the NdPromTextContentFactory interface are
used to create content for the rule name and rule body, respectively. After setting the
content on the rule, the rule is added to the ruleset with the ruleset's
insertSrlRulesetItemContentAt() method.

Both NdPromPattern (a pattern) and NdPromParameter (a parameter) extend the

NdPromSrlTypedContent interface and contain typed content. Typed content can be a
simple type reference to a primitive type, a class, or an enumeration. Typed content is
obtained with the NdPromSrlConstructContentFactory interface
newSrlGenericTypeContent() method. The typed content is set on the pattern with
setSrlGenericTypeContent() method which is inherited from
NdPromSrlTypedContent. The example code shows how to set a collection and a
constraint on a pattern.

// project is an NdPromProject
// Create 'Cross-sell' ruleset, with rule and two patterns, in 'Cross-sell Rules' directory
NdPromSrlRulesetContent ruleset = NdPromSrlConstructContentFactory.newSrlRulesetContent(project);
ruleset.setNameContent(NdPromTextContentFactory.newTextContent("crossSell"));

// Create 'rule1' rule

NdPromSrlRuleContent rule = NdPromSrlConstructContentFactory.newSrlRuleContent(project);
// set rule name
rule.setNameContent(NdPromTextContentFactory.newTextContent("rule1"));
// set rule body

Fair Isaac Corporation Confidential and Proprietary Information 19

CHAPTER 1: ROM and PROM APIs

String ruleBodyString = "if boughtProducts.primaryDemographic = promoProducts.primaryDemographic \n" +

"then { \n" +
"print(\"Shopper: \"shopper.name\", bought: \"boughtProducts.name\", rec: \"promoProducts.name).\n" +
"shopper.recommendedProducts.append(promoProducts),\n ignore(boughtProducts).\n}";
NdPromSrlRuleBodyTextContent ruleBody =
NdPromSrlConstructContentFactory.newSrlRuleBodyContent(ruleBodyString);
rule.setSrlRuleBodyContent(ruleBody);
// A rule is a ruleset item (NdPromSrlRuleContent extends NdPromSrlRulesetItemContent)
ruleset.insertSrlRulesetItemContentAt(rule, 0);

// Add 'shopper' parameter to ruleset

NdPromSrlParameterContent parameter = NdPromSrlConstructContentFactory.newSrlParameterContent();
parameter.setNameContent(NdPromTextContentFactory.newTextContent("shopper"));
NdPromSrlGenericTypeContent parameterType =
NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Shopper");
parameter.setSrlGenericTypeContent(parameterType);
ruleset.insertSrlParameterContentAt(parameter,0);

// Create 'boughtProducts' pattern

NdPromSrlPatternContent boughtPattern =
NdPromSrlConstructContentFactory.newSrlPatternContent(project);
boughtPattern.setNameContent(NdPromTextContentFactory.newTextContent("boughtProducts"));
NdPromSrlGenericTypeContent patternType =
NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Product");
boughtPattern.setSrlGenericTypeContent(patternType);
// set collection
NdPromSrlCollectionTextContent collection =
NdPromSrlConstructContentFactory.newSrlCollectionContent("shopper.purchasedProducts");
boughtPattern.setSrlCollectionContent(collection);
// A pattern is a ruleset item (NdPromSrlPatternContent extends NdPromSrlRulesetItemContent)
ruleset.insertSrlRulesetItemContentAt(boughtPattern, 0);

// Create 'promoProducts' pattern

NdPromSrlPatternContent promoPattern =
NdPromSrlConstructContentFactory.newSrlPatternContent(project);
promoPattern.setNameContent(NdPromTextContentFactory.newTextContent("promoProducts"));
//set the type
NdPromSrlGenericTypeContent patternType1 =
NdPromSrlConstructContentFactory.newSrlGenericTypeContent("Product");
promoPattern.setSrlGenericTypeContent(patternType1);
//set the constraint
NdPromSrlConstraintTextContent constraint =
NdPromSrlConstructContentFactory.newSrlConstraintContent("promotion = true");
promoPattern.setSrlConstraintContent(constraint);
ruleset.insertSrlRulesetItemContentAt(promoPattern, 1);

// Create NdPromItem for the ruleset, add to a PROM directory and save.
// schemaManager is an NdRomSchemaManager
NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_RULESET,
SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory rulesetFactory = schemaElement.getItemFactory();
NdPromItem rulesetItem = rulesetFactory.newItem((NdPromItemContent)ruleset, project);
// crossSellDiretory is an NdPromDirectory
crossSellDirectory.addItem(rulesetItem);
rulesetItem.save();
// project is an NdPromProject
project.save();

20 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Creating an SRL Function (NdPromSrlFunction)

An SRL function (NdPromSrlFunction) is defined in the object model for SRL entities in
the blazesoft.template.repository.objects.rules package. The package contains a
factory class named NdPromSrlConstructContentFactory. To create a fixed-content SRL
function, use the factory to create a function object (NdPromSrlFunctionContent) and set
the function name. Define a String that contains the body of the function. Use the
NdPromSrlConstructContentFactory factory again to create the function body as
content-based NdPromSrlBodyTextContent from the String. Set the function body on
the function object. Finally, create an NdPromItem for the function and add it to a project
directory.

// Create 'main' function in 'Test' directory

NdPromSrlFunctionContent function =
NdPromSrlConstructContentFactory.newSrlFunctionContent(project);
function.setNameContent(NdPromTextContentFactory.newTextContent("main"));
String functionBodyString = "s1 is a Shopper initially { \n" +
" name = \"Chris Camper\", \n" +
" purchasedProducts = an array of Product, \n" +
" purchasedProducts.append(tent),\n" +
" recommendedProducts = an array of Product.\n" +
"}.\n" +
"s2 is a Shopper initially { \n" +
" name = \"Grace Gardener\", \n" +
" purchasedProducts = an array of Product, \n" +
" purchasedProducts.append(weeder),\n" +
" recommendedProducts = an array of Product.\n" +
"}.\n" +
"s3 is a Shopper initially { \n" +
" name = \"Harry Homeowner\", \n" +
" purchasedProducts = an array of Product, \n" +
" purchasedProducts.append(bigscreen),\n" +
" recommendedProducts = an array of Product.\n" +
"}.\n" +
"s4 is a Shopper initially { \n" +
" name = \"Samantha Socialite\", \n" +
" purchasedProducts = an array of Product, \n" +
" purchasedProducts.append(tiara),\n" +
" recommendedProducts = an array of Product.\n" +
"}.\n" +
"for each Shopper do { \n" +
" apply crossSell(it). \n" +
" printRecommendations(it). \n" +
"}.";

NdPromSrlBodyTextContent functionBody =
NdPromSrlConstructContentFactory.newSrlBodyContent(functionBodyString);
function.setSrlBodyContent(functionBody);
// Create NdPromItem for function and add to "Test" directory
schemaManager = project.getRomConnectionContext().getSchemaManager();
schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_FUNCTION, SUB_TYPE_NONE,
CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory functionItemFactory = schemaElement.getItemFactory();
NdPromItem functionItem = functionItemFactory.newItem((NdPromItemContent)function, project);
testDirectory.addItem(functionItem);
functionItem.save();

Fair Isaac Corporation Confidential and Proprietary Information 21

CHAPTER 1: ROM and PROM APIs

Creating a Ruleflow (NdPromFlowRuleflow)

The factory class for creating various ruleflow constructs is
NdPromFlowConstructContentFactory. To create a ruleflow with a flow and task, use
the factory to create the ruleflow (NdPromFlowRuleflowContent), then set the name of
the ruleflow, as NdTextContent, on the ruleflow object. Use the same factory to create a
flow (NdPromFlowFlowContent) and set the flow on the ruleflow. Use
NdPromFlowConstructContentFactory again to create a task (NdPromFlowTaskContent).
Set name and implementation name on the task, then insert a parameter and flow input
on the task. Insert the task into the flow. Finally, create an NdPromItem for the ruleflow
and save it with the project.

// project is an NdPromProject
// testDirectory is an NdPromDirectory that has been added to the project
NdPromFlowRuleflowContent ruleflow =
NdPromFlowConstructContentFactory.newFlowRuleflowContent(project);
ruleflow.setNameContent(
NdPromTextContentFactory.newTextContent("newRuleflow"));

// Create a flow.
NdPromFlowFlowContent flow =
NdPromFlowConstructContentFactory.newFlowFlowContent();
ruleflow.setFlowFlowContent(flow);

// Create a task.
NdPromFlowTaskContent task =
NdPromFlowConstructContentFactory.newFlowTaskContent();
task.setNameContent(
NdPromTextContentFactory.newTextContent("newTask"));
task.setImplementationNameContent(
NdPromTextContentFactory.newTextContent("newRuleset"));
task.insertFlowParameterContentAt(
NdPromFlowConstructContentFactory.newFlowParameterContent("param1"), 0);
task.insertFlowInputContentAt(
NdPromFlowConstructContentFactory.newFlowInputContent("foo"), 0);
flow.insertFlowFlowItemContentAt(task, 0);

schemaManager = project.getRomConnectionContext().getSchemaManager();
schemaElement = schemaManager.lookupSchemaElement(TYPE_RULEFLOW, SUB_TYPE_NONE,
CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory factory = schemaElement.getItemFactory();
NdPromItem item = factory.newItem((NdPromFlowRuleflow) ruleflow, project);
testDirectory.addItem(item);
item.save();

Note The getType() method in the NdPromFlowTask interface has been renamed
getImplementationType().

Creating a Question Set (NdPromAaiQuestionSet)

The factory class for creating content-based objects for various question set constructs is
NdPromAaiConstructContentFactory. To create a question set with a question, use the
factory to create the question set (NdPromAaiQuestionSetContent), then set the name
and comment as NdTextContent on the question set. Create a question
(NdPromAaiQuestionContent) with the same factory and set NdTextContent prompt

22 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

content on question, as well as NdPromAaiClassPropertyContent. Insert the question

into the question set. Finally, create an NdPromItem for the question set.

// project is an NdPromProject
// testDirectory is an NdPromDirectory that has been added to the project
NdPromAaiQuestionSetContent questionSet =
NdPromAaiConstructContentFactory.newAaiQuestionSetContent(project);
questionSet.setNameContent(
NdPromTextContentFactory.newTextContent("newQuestion"));
questionSet.setCommentContent(
NdPromTextContentFactory.newTextContent("Sample question set"));

// Add a question.
NdPromAaiQuestionContent question =
NdPromAaiConstructContentFactory.newAaiQuestionContent();
question.setPromptContent(
NdPromTextContentFactory.newTextContent("What is the driver's age?"));
NdPromAaiClassPropertyContent classProperty =
question.getAaiClassPropertyContent();
classProperty.setClassNameContent(
NdPromTextContentFactory.newTextContent("Driver"));
classProperty.setPropertyNameContent(
NdPromTextContentFactory.newTextContent("age"));
questionSet.insertAaiQuestionContentAt(question, 0);

schemaManager = project.getRomConnectionContext().getSchemaManager();
schemaElement = schemaManager.lookupSchemaElement(TYPE_QUESTION_SET, SUB_TYPE_NONE,
CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory factory = schemaElement.getItemFactory();
NdPromItem item = factory.newItem((NdPromAaiQuestionSet) questionSet, project);
testDirectory.addItem(item);
item.save();

Creating an SRL Class (NdPromSrlClassContent)

The com.blazesoft.template.repository.objects.bom package contains interfaces for
the business object model, which includes the SRL class. The NdPromSrlClassContent
interface provides content section-based read/write access to the properties of an SRL
class definition. NdPromSrlClassContent class content is created with the
newSrlClassContent() method of the NdPromBomConstructContentFactory class,
which is included in the package. The insertSrlPropertyContentAt() method
(inherited from NdPromSrlPropertiesContainerContent) is used to insert property
content (NdPromSrlPropertyContent) into the class content
(NdPromSrlClassContent). The newSrlPropertyContent() method of the
NdPromBomConstructContentFactory class is used to create NdPromSrlPropertyContent.
The name and type of the property content, which correspond to a field name and type,
is set with the NdPromSrlPropertyContent interface setNameContent() and
setSrlGenericType() methods.

This code creates class content for the SRL class, inserts a field definition into the
content, and saves the class as a PROM item in the appropriate directory which has
been previously added to the project.

NdPromSrlClassContent classContent =
NdPromBomConstructContentFactory.newSrlClassContent(project);
NdPromTextContent className =
NdPromTextContentFactory.newTextContent("SimpleSRLClass");

Fair Isaac Corporation Confidential and Proprietary Information 23

CHAPTER 1: ROM and PROM APIs

classContent.setNameContent(className);

NdPromSrlPropertyContent prop =
NdPromBomConstructContentFactory.newSrlPropertyContent();
NdPromTextContent propName = NdPromTextContentFactory.newTextContent("customerName");
prop.setNameContent(propName);
NdPromSrlGenericTypeContent propType =
NdPromSrlConstructContentFactory.newSrlGenericTypeContent("string");
prop.setSrlGenericTypeContent(propType);
classContent.insertSrlPropertyContentAt(prop, 0);

// Save the new class.

// project is an NdPromProject & targetDirectory is an NdPromDirectory
schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_CLASS, SUB_TYPE_NONE,
CONTENT_TYPE_FIXED, TARGET_SRL);
factory = schemaElement.getItemFactory();
NdPromItem classItem = factory.newItem((NdPromEntity)classContent, project);
targetDirectory.addItem(classItem);
classItem.save();

Creating an SRL Enumeration (NdPromSrlEnumerationContent)

As noted in the previous section, the factory class for creating various content-based
constructs in the business object model is NdPromBomConstructContentFactory, which
is part of the com.blazesoft.template.repository.objects.bom package. To create an
SRL enumeration and enumeration items, use the factory to create the enumeration
object (NdPromSrlEnumerationContent), then set the name on the enumeration object.
Use NdPromBomConstructContentFactory to create SRL enumeration items
(NdPromSrlEnumerationItemContent) and insert each item into the enumeration. Create
the NdPromItem for the enumeration and add the NdPromItem to an existing project
directory and save.

// Create 'DemographicSegments' enumeration with four enumeration items.

NdPromSrlEnumerationContent enumeration =
NdPromBomConstructContentFactory.newSrlEnumerationContent(project);
// Create content-based NdPromTextContent text and set the enumeration name.
NdPromTextContent enumName = NdPromTextContentFactory.newTextContent("DemographicSegments");
enumeration.setNameContent(enumName);
// Create SRL enumeration items
NdPromSrlEnumerationItemContent enumItem1 =
NdPromBomConstructContentFactory.newSrlEnumerationItemContent("outdoorsman");
NdPromSrlEnumerationItemContent enumItem2 =
NdPromBomConstructContentFactory.newSrlEnumerationItemContent("homeowner");
NdPromSrlEnumerationItemContent enumItem3 =
NdPromBomConstructContentFactory.newSrlEnumerationItemContent("gardener");
NdPromSrlEnumerationItemContent enumItem4 =
NdPromBomConstructContentFactory.newSrlEnumerationItemContent("socialite");
// Insert the SRL enumeration items on the SRL enumeration
enumeration.insertSrlEnumerationItemContentAt(enumItem1, 0);
enumeration.insertSrlEnumerationItemContentAt(enumItem2, 1);
enumeration.insertSrlEnumerationItemContentAt(enumItem3, 2);
enumeration.insertSrlEnumerationItemContentAt(enumItem4, 3);

// Create the NdPromItem for the enumeration

// project is an NdPromProject
NdRomSchemaManager schemaManager = project.getRomConnectionContext().getSchemaManager();
NdRomSchemaElement schemaElement = schemaManager.lookupSchemaElement(TYPE_SRL_ENUMERATION,
SUB_TYPE_NONE, CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory enumItemFactory = schemaElement.getItemFactory();

24 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

NdPromItem enumItem = enumItemFactory.newItem((NdPromEntity)enumeration, project);

// Add the SRL enumeration to an existing project directory
// projectDirectory is a NdPromDirectory
projectDirectory.addItem(enumItem);
// Save the SRL enumeration
enumItem.save();

Fair Isaac Corporation Confidential and Proprietary Information 25

CHAPTER 1: ROM and PROM APIs

26 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 2

BOM Admin APIs

The FICO™ Blaze Advisor® business rules management system BOM Admin APIs
allow you to o programmatically update imported external classes represented as BOM
project-level item contents in a repository. The APIs enable you to obtain mapping
information, customize a class name, or create and save a new XML BOM. This chapter
provides an introduction to some of those capabilities. Consult the Blaze Advisor API 
Reference for more detailed information. The API Reference is available by selecting API
Reference from the Builder Help menu.

Manipulating Imported External Classes

There are two layers of admin APIs for imported external class management. The
PROM layer BOM Admin APIs and the engine layer class admin APIs.

The BOM Admin APIs are used to programmatically access and manipulate the
imported external classes represented in a Blaze Advisor repository as BOM PROM
item contents. The engine layer APIs are used to manage the imported classes within an
engine layer class provider resource.

You can use these APIs to add imported classes from an external object model resource,
remove classes from the BOM and its associated class provider resource, customize the
imported classes by renaming them in the BOM, and retrieve imported class mapping
information.

Note The code snippets provided show how to use the APIs and are not necessarily
complete working examples.

NdPromBomAdmin
The main entry point for BOM manipulation is the NdPromBomAdmin class.

Package name: com.blazesoft.template.repository.admin

NdClassMappingInfo
Mapping information is used to provide the names of the raw input to the underlying
BOM. This means that mapping information is different for each BOM supported by
Blaze Advisor. For example, you would need to use the API differently to obtain
mapping information for a Java BOM than to obtain mapping information for an XML
BOM.

Package names:

Fair Isaac Corporation Confidential and Proprietary Information 27

CHAPTER 2: BOM Admin APIs

com.blazesoft.engine.rules
com.blazesoft.engine.rules.java (for NdJavaClassMappingInfo)
com.blazesoft.engine.rule.xml (for NdXmlClassMappingInfo)

Example:

NdJavaClassMappingInfo ji = new NdJavaClassMappingInfo();

or
NdXmlClassMappingInfo xi = new NdXmlClassMappingInfo();
xi.setXmlSchema(“mySchema.xsd”);

NdClassNameCustomizingInfo
If you want to customize a class name during BOM manipulation, you use the
NdClassNameCustomizingInfo class. The NdClassNameCustomizingInfo class has a
name pair holder for the native class name and the customized Blaze Advisor class
name.

Package name: com.blazesoft.engines.rules

Example:

NdClassNameCustomizingInfo ci = new NdClassNameCustomizingInfo();

ci.setNativeClassName(“ACCT”);
ci.setCustomizedAdvisorClassName(“ACCT_TYPE”);
xi.setXmlSchema(“mySchema.xsd”);

You can provide an array of customization information to the mapping information.

Creating a New XML BOM

Use the following APIs to create a new XML BOM.

Package names:
com.blazesoft.template.repository.objects.bom.NdPromBomConstructContentFactory
com.blazesoft.template.repository.objects.NdPromTextContent

Example:
...
_bomType = 24; //XML BOM Type
NdPromExternalBomContent bomContent = NdPromBomConstructContentFactory.
newExternalBomContent((NdPromRulesProject) _project, _bomType);
NdPromTextContent pc = NdPromTextContentFactory.newTextContent(_bomItemName);
bomContent.setNameContent(pc);
...

Saving a New or Existing BOM

Use the following APIs to save a new BOM or an existing BOM.
„ “Saving a New BOM”
„ “Saving an Existing BOM” on page 29.

Saving a New BOM

You can save a new BOM using the following API:

28 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Package names:
com.blazesoft.template.repository.PromItemContent
com.blazesoft.template.repository.PromItem

Example:

...
//Save the BOM item-- needs to change
NdPromItemContent itemContent = (NdPromItemContent) bomContent;
//Create a NdPromItem for the BOM and add it to a directory
schemaManager = project.getRomConnectionContext().getSchemaManager();
schemaElement = schemaManager.lookupSchemaElement(TYPE_BUSINESS_OBJECT_MODEL,
SUB_TYPE_XML_BOM, CONTENT_TYPE_FIXED, TARGET_SRL);
NdPromItemFactory itemFactory = schemaElement.getItemFactory();
NdPromItem promItem = itemFactory.newItem(itemContent, _project);

_projectDirectory.addItem(promItem);
promItem.save();
...

Saving an Existing BOM

Save an existing BOM using the following API:

Package names:
com.blazesoft.template.repository.PromItemContent
com.blazesoft.template.repository.PromItem

Example:

...
//Save the BOM item
NdPromItemContent itemContent = (NdPromItemContent) bomContent;
NdPromItem promItem = itemFactory,getItem();
promItem.save();
...

Add or Remove Items to or from Existing BOM(unexposed API)

Add items to or remove items from an existing BOM using the following API.
...
NdPromBomAdmin _bomAdmin = new NdPromBomAdmin();
NdPromItem bomItem = (NdPromItem)
_projectDirectory.lookupEntry(NdLocationFactory.createLocation(_bomItemName));
NdPromExternalBomContent bomContent = (NdPromExternalBomContent)
bomItem.getItemContent();
NdClassMappingInfo mappingInfo = some mapping info...
_bomAdmin.addImportedClasses(bomContent, mappingInfo);
_bomAdmin.removeImportedClasses(bomContent, mappingInfo);
...

Customizing a BOM(unexposed API)

Customize a BOM using the following API.
...
NdPromItem bomItem = (NdPromItem)
_projectDirectory.lookupEntry(NdLocationFactory.createLocation(_bomItemName));
NdPromExternalBomContent bomContent = (NdPromExternalBomContent)
bomItem.getItemContent();

Fair Isaac Corporation Confidential and Proprietary Information 29

CHAPTER 2: BOM Admin APIs

NdClassMappingInfo mappingInfo = some mapping info with customizations...

_bomAdmin.customizeImportedClasses(bomContent, mappingInfo);
...

30 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 3

Metaphor APIs

The FICO™ Blaze Advisor® business rules management system Metaphor APIs
provide programatic access to the Blaze Advisor metaphors: decision table, decision
tree, and score model. The APIs enable you to examine and edit the contents of
metaphor instances as well as create new instances. This chapter provides an
introduction to some of those capabilities. Consult the Blaze Advisor API Reference for
more detailed information. The API Reference is available by selecting API Reference
from the Builder Help menu.

Loading a Metaphor Instance

The initial steps for loading an instance is the same for each type of Blaze Advisor
metaphor. The procedure for connecting to your repository and opening the project that
contains your metaphor instance is detailed in Chapter 1, “ROM and PROM APIs.”

Once a project has been opened, you can load the metaphor instance in this fashion:

NdLocation location = NdLocationFactory.createLocation("directory/instanceFileName");

NdPromItem promItem = (NdPromItem)(project.lookupEntry(location));
NdPromItemContent content = promItem.getItemContent();
NdInstantiationElement instantiationElt = null;
if (content instanceof NdInstantiation) {
instantiationElt = (NdInstantiationElement)content;
}

In the example code throughout this chapter instantiationElt will refer to the
instance. If the instance is global (i.e. the metaphor instance is a direct child of a
repository directory), then this is sufficient. The metaphor instance will be what
instantiationElt refers to. Otherwise, you need to navigate the instance to find the
instantiation element that corresponds to the metaphor instance, as shown here:

instanceElt = instantiationElt.safeLookup(metaphorInstanceName);

The NdMetaphorSupport class contains methods to determine which type of metaphor

the instance is: isDecisionTableInstance(), isDecisionTreeInstance(), and
isScoreModelInstance().

if (NdMetaphorSupport.isDecisionTableInstance(instanceElt)) {
// execute code to deal with decision tables
}

Creating a Metaphor Model

Each metaphor model has a factory class for creating instances of its metaphor model.

Fair Isaac Corporation Confidential and Proprietary Information 31

CHAPTER 3: Metaphor APIs

„ NdDecTableModelFactory.createDecTableModel()
Creates a new instance of a decision table model, returned as an NdDecTableModel.
„ NdDecTreeModelFactory.createDecTreeModel()
Creates a new instance of a decision tree model, returned as an NdDecTreeModel.
„ NdScoreModelModelFactory.createScoreModelModel()
Creates a new instance of a score model, returned as an NdScoreModelModel.

Each factory class has a method to set the instantiation element on the model.
„ For a decision table, call the NdDecTableModelFactory.setDecTableInstance()
method.
„ For a decision tree, call the NdDecTreeModelFactory.setDecTreeInstance()
method.
„ For a score model, call the NdScoreModelModelFactory.setScoreModelInstance()
method.

The methods above may throw an NdMetaphorModelException in the event something

is wrong with the instance and cannot be corrected. This is a terminal error, and will
prevent the metaphor model from using the metaphor instance. These methods may
also throw an NdMetaphorWarningException in case an erroneous situation was found,
but could be corrected. A NdMetaphorModifiedException is thrown when the metaphor
instance was modified by the metaphor model to fix possible problems. This would
happen, for example, if the metaphor template was changed.

The decision table model instance decTableModel in the code below is used to edit the
decision table, as described in the following section, “Decision Table Editing API” on
page 32. Similar code is used to create decision tree and score model instances. These
models are discussed in “Decision Tree Editing API” on page 34 and “Score Model
Editing API” on page 37.

if (NdMetaphorSupport.isDecisionTableInstance(instanceElt)) {
NdDecTableModel decTableModel = NdDecTableModelFactory.createDecTableModel();
NdDecTableModelFactory.setDecTableInstance(decTableModel, instanceElt);
}

Decision Table Editing API

Th NdDecTableModel interface provides methods for editing a decision table instance.
NdDecTableModel includes methods for inserting and deleting columns and rows in the
decision table instance, for obtaining the number of columns and rows, for moving
columns and rows within the table, and for copy-and-paste of a range of cells.

The “Decision Table Import” example demonstrates how to use the Decision Table
Editing APIs to create an instance of a single-axis (columns) decision table template and
populate it with data obtained from a CSV file that was generated in Microsoft Excel.
The example is located in <ADVISOR_HOME>/examples/ExamplesRepository/API
Examples/Metaphor APIs/Decision Table Import.

The getTableInfo() method of NdDecTableModel returns an NdDecTableInfo object,

which contains information about the layout of the decision table, including the number

32 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

of condition and action rows or columns in a decision table. The getTableLayout()

method of NdDecTableInfo returns a constant that indicates the layout, such as
NdDecisionMetaphorConstants.DECTABLE_LAYOUT_SINGLE_AXIS_COLS.

NdDecTableInfo tableInfo = decTableModel.getTableInfo();

int layout = tableInfo.getTableLayout()

The setCellFieldValue() method sets the field value of the cell. A

NdMetaphorModelException is thrown if the value is not of the appropriate type. For
example, the exception is thrown if a value that is not a number is used in a cell that has
a cell template display name that specifies a number, such as = 'integer'.

Several of the methods in NdDecTableModel access cells in a decision table by row and
column coordinates. NdDecTableCellCoordinates represents the coordinates of a cell.
This statement sets the field value of the cell at row 2, col 3 in a decision table. The cell
template for this cell is = ‘string’, which has only one placeholder. The index of the
placeholder, or field, within the cell is 0.

decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 0, "Medical");

When you specify a numeric range, set the first number at placeholder index 0 and the
second number at placeholder index 1 of the cell. The cell template display name for this
cell is 'real1' < .. <= 'real2', which has two placeholders. These statements set the
range 1.0 < .. <= 3.5 on the cell.

decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 0, 1.0);

decTableModel.setCellFieldValue(new NdDecTableCellCoordinates(2, 3), 1, 3.5);

The getCellInfo() method returns an NdDecTableCellInfo object that supplies all

information necessary to render and edit a cell. The getTemplatesInfo() method of
NdDecTableCellInfo returns an NdRangeTableCellTemplatesInfo object.

NdRangeTableCellTemplatesInfo has the getAllowedCellTemplateDisplayNames()

method, which obtains the list of allowed cell template display names for the cell. The
getCurrentCellTemplateDisplayName() method of NdRangeTableCellTemplatesInfo
returns the cell template display name that is selected for the cell.

// getCellInfo(int row, int column)

NdDecTableCellInfo cellInfo = decTableModel.getCellInfo(2, 3);
String cellTemplateDisplay Name =
cellInfo.getTemplatesInfo().getCurrentCellTemplateDisplayName();

The NdDecTableCellInfo method getRenderingInfo() returns an

NdRangeTableCellRenderingInfo object. The isEmpty() method returns true if the cell
has no content. The isLabel() methods indicates whether the cell contains a label. The
getRole() method of the NdRangeTableCellRenderingInfo returns a constant that
indicates the role of the cell.

The selectCellTemplate() method selects the cell template display name on the cell at
the specified coordinates. This process is called binding. The cell template display name
selected must be one of the allowed cell templates specified for the cell, just as a user in
the GUI selects a cell template from a drop-down list of allowed cell templates. The
allowed cell templates have been defined in the decision table wizard or manually in

Fair Isaac Corporation Confidential and Proprietary Information 33

CHAPTER 3: Metaphor APIs

the decision table template designer. A NdMetaphorModelException is thrown if the cell

template is not allowed or if the same cell template is already defined for that cell.

decTableModel.selectCellTemplate(new NdDecTableCellCoordinates(row, col), "= 'real'");

Example: Display an Overview of a Decision Table

This example code loops though the rows and columns of a decision table and lists the
label or role for each cell.

for (int row = 0; row < decTableModel.getRowCount(); row++) {

for (int col = 0; col < decTableModel.getColumnCount(); col++) {
NdDecTableCellInfo info = decTableModel.getCellInfo(row, col);
NdRangeTableCellRenderingInfo renderingInfo = info.getRenderingInfo();
if (renderingInfo.isEmpty()) {
System.out.print(" ");
}
else if (renderingInfo.isLabel()) {
System.out.print("H");
}
else {
switch (renderingInfo.getRole()) {
case NdDecisionMetaphorConstants.METAPHOR_ACTION:
System.out.print("A");
break;
case NdDecisionMetaphorConstants.METAPHOR_CONDITION:
System.out.print("C");
break;
}
}
}
}

Decision Tree Editing API

The NdDecTreeModel interface provides methods for editing a decision tree instance in
the customary tree format as a network of nodes and links. The operations you perform
when editing a decision tree in the GUI have correlary methods in the API which are
used in a fashion that should be familiar to you.

To begin editing a decision tree, obtain an NdDecTreeModel instance as described in

“Loading a Metaphor Instance” on page 31. The code for obtaining the instance is part
of the decision tree example in “Example: Create a Subtree” on page 36

The root node of a decision tree is obtained by creating an instance of NdDecTreePath.

This class represents a path. The location of a node in a tree is represented by an
NdDecTreePath path to the node. You can begin traversing the nodes of a tree by using
the getNodeOutgoingNodeAt() method of NdDecTreeModel to obtain the path of one of
the node's child nodes; and then continue traversing the tree via one of its child nodes,
and so on. The second parameter to the getNodeOutgoingNodeAt() method is the index
(base-0) of the child.

// decTreeModel is an NdDecTreeModel
NdDecTreePath root = new NdDecTreePath();
NdDecTreePath path1 = decTreeModel.getNodeOutgoingNodeAt(root, 0);
NdDecTreePath path2 = decTreeModel.getNodeOutgoingNodeAt(path1, 0);

34 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

path2 is the first child of the first child of the root node. For the decision tree diagramed
below, that is the path to the "Model Year" node for "Charger".

The image below depicts a portion of the decision tree in the “Decision Tree with
Patterns” example in <ADVISOR_HOME>/examples/repositories/ExamplesRepository/
Metaphors and Templates/Decision Trees/Decision Tree with Patterns.

You can obtain the incoming link condition value ("Charger") and the node label
("Model Year") with these methods:

// returns "Charger"
String condition = decTreeModel.getIncomingLinkConditionValue(path2,0));
// returns "Model Year"
String label = decTreeModel.getNodeLabel(path2));

The “incoming link selected condition format label” is the name of template that is used
with the incoming link condition value. Use the
getIncomingLinkSelectedConditionFormatLabel() method to obtain it.

//returns "Model = 'string'"

String format = decTreeModel.getIncomingLinkSelectedConditionFormatLabel(path2));

You can examine a template to determine the number of placeholders. There is one
placeholder for a string value in Model = 'string'. You can use the
setIncomingLinkConditionValue() method to change the value of the incoming link
condition from "Charger" to "Corvette". The middle parameter is the placeholder index.

decTreeModel.setIncomingLinkConditionValue(path2, 0, "Corvette");

The set of allowed condition group labels for outgoing links for this node is obtained
with the getAllowedConditionGroupLabelsForOutgoingLinks() method.

// returns "Make", "Model", "Model Year"

String[] allowedLabels =
decTreeModel.getAllowedConditionGroupLabelsForOutgoingLinks(path2);

You can change the condition group to any of the allowed values using the
selectConditionGroupForOutgoingLinks() method.

decTreeModel.selectConditionGroupForOutgoingLinks(path2, "Model Year");

Call the getNodeOutgoingLinksCount() method to obtain the number of outgoing links.

// returns: 2
int count = decTreeModel.getNodeOutgoingLinksCount(path2));

This example code uses the getNodeOutgoingNodeAt() method to obtain the first
outgoing child node (path3) of the node at path2.

NdDecTreePath path3 = decTreeModel.getNodeOutgoingNodeAt(path2, 0);

Fair Isaac Corporation Confidential and Proprietary Information 35

CHAPTER 3: Metaphor APIs

NdDecTreeNodeRenderingInfo contains a variety information about a node. We learn

that path3, is an action node.

NdDecTreeNodeRenderingInfo renderInfo = decTreeModel.getNodeRenderingInformation(path3);

// Prints: "Is Rating: 4 an action node? true"
System.out.println("Is " + renderInfo.getLabel() + " an action node? " +
renderInfo.isActionNode());

The getIncomingLinkAllowedConditionFormatLabels() method of NdDecTableModel

returns an array of the allowed incoming link condition format labels for path3.

// returns:
// "Model Year = 'integer'", "Model Year > 'integer'", "Model Year < 'integer'",
// "Model Year >= 'integer'", "Model Year <= 'integer',
// "Model Year 'integer1' <= .. <= 'integer2', "otherwise"
String[] allowedFormats = decTreeModel.getIncomingLinkAllowedConditionFormatLabels(path3);

To change the condition to 1962 - 1964, select the appropriate condition format label
from the allowed list. Then, set the value on each placeholder separately.

decTreeModel.selectIncomingLinkConditionFormat(
path3,"Model Year 'integer1' <= .. <= 'integer2'");
decTreeModel.setIncomingLinkConditionValue(path3,0, "1962");
decTreeModel.setIncomingLinkConditionValue(path3,1, "1964");

To obtain the current action value (the rating), use the getActionValue() method.

// returns: 4
int actionValue = decTreeModel.getActionValue(path3, 0, 0));

To change the rating from 4 to 3 and set the node label appropriately, use this code.

decTreeModel.setActionValue(path3, 0, 0, "3.0");
decTreeModel.setNodeLabel(path3, "Rating: 3");

Example: Create a Subtree

This example removes a subtree of nodes from the example decision tree discussed in
the previous section. It then re-constructs the entire subtree. The example also
demonstrates how to connect to the repository, find the decision tree instance repository
item, and how to use NdDecTreeModelFactory to obtain an instance of NdDecTreeModel.

public class ReconstructSubtree implements NdRomSchemaConstants

{

public static void main(String[] argv)

throws Exception, NdMetaphorModelException
{

NdFileRepositoryConnection connection = new NdFileRepositoryConnection();

// change the path to your repository as appropriate
connection.setRepositoryFolder("C:/repositories/ExamplesRepository");
NdRomConnectionManager connectionMgr =
NdRomFactory.newRepositoryConnectionManager(connection);
connectionMgr.connect();
NdRomConnectionContext conContext = connectionMgr.getConnectionContext();
NdRomDirectory romRoot = conContext.getRoot();
NdRomProject romProject = (NdRomProject)romRoot.lookupEntry( NdLocationFactory.createLocation(
"/Metaphors and Templates/Decision Trees/Decision Tree with Patterns/Decision Tree with
Patterns_java"));

36 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

NdPromProjectFactory projectFactory = conContext.getProjectFactory();

NdPromProject project = projectFactory.createProject(romProject);
NdPromItem decisionTreeInstanceItem = (NdPromItem)project.lookupEntry(
NdLocationFactory.createLocation("Decision Tree with Patterns/oldCarsDecisionTree Instance"));
NdPromItemContent content = (NdPromItemContent) decisionTreeInstanceItem.getItemContent();
NdDecTreeModel decTreeModel = null;
if (NdMetaphorSupport.isDecisionTreeInstance((NdInstantiationElement)content)) {
decTreeModel = NdDecTreeModelFactory.createDecTreeModel();
}
else {
System.exit(1);
}
NdDecTreeModelFactory.setDecTreeInstance(decTreeModel, (NdInstantiationElement)content);
NdDecTreePath root = new NdDecTreePath();
NdDecTreePath path1 = decTreeModel.getNodeOutgoingNodeAt(root, 0);
NdDecTreePath path2 = decTreeModel.getNodeOutgoingNodeAt(path1, 0);
NdDecTreeNodeRenderingInfo renderInfo = decTreeModel.getNodeRenderingInformation(path2);

// TASK: Delete the subtree at this node; then re-create it.

decTreeModel.deleteSubtree(path2);
NdDecTreePath newPath = decTreeModel.insertNewNode(path1, 0, "Model");
decTreeModel.selectConditionGroupForOutgoingLinks(newPath, "Model Year");
decTreeModel.selectIncomingLinkConditionFormat(newPath,"Model = 'string'");
decTreeModel.setIncomingLinkConditionValue(newPath,0, "Charger");
// first condition
NdDecTreePath cond1 = decTreeModel.insertNewNode(newPath, 0, "Model Year");
decTreeModel.selectIncomingLinkConditionFormat(cond1,"Model Year = 'integer'");
decTreeModel.setIncomingLinkConditionValue(cond1,0, "1968");
decTreeModel.insertAction(cond1, 0);
decTreeModel.selectActionFormat(cond1, 0, "adjustRating(arg0, ...) ");
decTreeModel.setActionValue(cond1, 0, 0, "4.0");
decTreeModel.setNodeLabel(cond1, "Rating: 4");
// second condition
NdDecTreePath cond2 = decTreeModel.insertNewNode(newPath, 1, "Model Year");
decTreeModel.selectIncomingLinkConditionFormat(cond2,"Model Year < 'integer'");
decTreeModel.setIncomingLinkConditionValue(cond2,0, "1968");
decTreeModel.insertAction(cond2, 0);
decTreeModel.selectActionFormat(cond2, 0, "adjustRating(arg0, ...) ");
decTreeModel.setActionValue(cond2, 0, 0, "0.0");
decTreeModel.setNodeLabel(cond2, "Rating: 0");
decisionTreeInstanceItem.save();
project.save();
}
}

Score Model Editing API

The NdScoreModelModel interface provides the methods for editing a score model
instance. Most of the methods get and set string and integer values on an instance using
indices to characteristics, to the bins within characteristics, and to the ranges within
bins. For example, to obtain the label of the first characteristic in the “Academic Score”
score model, supply the index value 0 (base-0) as the parameter to
getCharacteristicLabel().

// returns: "GPA_Score"
int chr = 0;
String characteristicLabel = scoreModel.getCharacteristicLabel(chr));

Fair Isaac Corporation Confidential and Proprietary Information 37

CHAPTER 3: Metaphor APIs

Similarily, to obtain the label of the same characteristic’s first bin, supply the index of
characteristic and the index of the first bin (0) as parameters to the getBinLabel()
method.

// returns: "Between 3.6 and 4.0"

int bin = 0;
String binLabel = scoreModel.getBinLabel(chr, bin));

To obtain the number of characteristics in the score model and number of bins defined
for a particular characteristic, use the getCharacteristicCount() and getBinCount()
methods.

// returns: 4
int characteristicCount = scoreModel.getCharacteristicCount();
// returns: 5
int binCount = scoreModel.getBinCount(chr);

The Academic Score Instance file is part of the “Basic Score Model” example in
<ADVISOR_HOME>/examples/repositories/ExamplesRepository/
Metaphors and Templates/Score Models/Basic Score Model.

The NdScoreModelModel interface includes methods to add and delete characteristics

and bins. Other methods get and set values for: characteristic labels and descriptions,
the characteristic baseline score, the bin label, and the score weight and reason code for
a bin. Those methods are: addNewCharacteristic(), insertNewCharacteristic(),
deleteCharacteristic(), addNewBin(), insertNewBin(), deleteBin(),

38 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

getCharacteristicLabel(), setCharacteristicLabel(),
getCharacteristicDescription(), setCharacteristicDescription(),
getCharacteristicBaselineScore(), setCharacteristicBaselineScore(),
getBinLabel(), setBinLabel(), getBinScoreWeight(), setBinScoreWeight(),
getBinReasonCodeName(), and setBinReasonCodeName().

Each bin in a score model contains one or more ranges. The

NdRangeTableCellTemplatesInfo class is used to supply information about the current
cell template used by a range table cell, as well as the allowed cell templates for the cell.
To obtain a cell’s range format template, first call getRangeFormatTemplatesInfo() to
obtain an NdRangeTableCellTemplatesInfo instance, then call
getCurrentCellTemplateDisplayName() on the instance. This example code obtains the
range cell template used in the “Between 3.6 and 4.0” bin. The template defines
placeholders for two real values.

int range = 0;
NdRangeTableCellTemplatesInfo templatesInfo =
scoreModel.getRangeFormatTemplatesInfo(chr, bin, range);
// returns: "GPA_Score 'real1' <= .. <= 'real2'"
String cellTemplate = templatesInfo.getCurrentCellTemplateDisplayName());

The NdRangeTableCellRenderingInfo class is used to supply the information necessary

to render a table range cell. To get the values for the placeholders in a range, obtain an
NdRangeTableCellRenderingInfo instance by calling getRangeRenderingInfo(). The
getValue() of NdRangeTableCellRenderingInfo returns the placeholder values in a
String array.

NdRangeTableCellRenderingInfo renderingInfo =
scoreModel.getRangeRenderingInfo(chr, bin, range);
// returns: “3.6” and “4”
String[] cellPHValues = renderingInfo.getValues();

In the example score model, the GPA range is between 3.6 and 4.0, inclusive. Suppose
you want to change the bin to accomodate some advanced placement students whose
GPA can exceed 4.0. You will change the bin label of the “Between 3.6 and 4.0” bin to
“Greater than 3.6”, as well as replace the cell range template and placeholder value.

You may want to begin by obtaining the list of allowed cell template display names by
calling getAllowedCellTemplateDisplayNames() on the
NdRangeTableCellTemplatesInfo object.

String allowedTemplates[] = templatesInfo.getAllowedCellTemplateDisplayNames();

for (int template = 0; template < allowedTemplates.length; template++) {
System.out.println(allowedTemplates[template]);
}

For the example, the print output of this code is:

GPA_Score 'real1' <= .. < 'real2'

GPA_Score > 'real'
GPA_Score < 'real'
GPA_Score >= 'real'
GPA_Score <= 'real'
GPA_Score 'real1' < .. <= 'real2'
GPA_Score 'real1' < .. < 'real2'

Fair Isaac Corporation Confidential and Proprietary Information 39

CHAPTER 3: Metaphor APIs

The appropriate cell template is GPA_Score >= 'real': GPA is greater than the
placeholder value, inclusive. For the example, the value of the placeholder will be “3.6”.
The following code sets the new bin label, selects the appropriate template for range
cell, and sets the value of the single placeholder defined in the template.

scoreModel.setBinLabel(chr, bin, "Greater than 3.6");

scoreModel.selectRangeFormat(chr, bin, range, "GPA_Score >= 'real'");
scoreModel.setRangeFieldValue(chr, bin, range, 0, "3.6");

After running the completed API application and reopening the project in the GUI, you
can confirm that the bin is redefined.

The NdScoreModelModel interface has a several other methods that pertain to ranges
which have not been discussed, including: getRangeCount(), getRangeDescription(),
deleteRange(), and insertNewRange().

The NdScoreModelModel interface has methods which are used to move characteristics,
bins, and ranges in a score model. Those methods are: moveBinUp(), moveBinDown(),
moveCharacteristicsUp(), moveCharacteristicsDown(), moveRangeUp(),
moveRangeDown().

Example: List Contents of a Score Model

The example code below can be used with any score model to list all of the model’s
characteristics and bins; as well the range cell template names defined for each bin and
the corresponding placeholder values.

NdRangeTableCellTemplatesInfo templatesInfo;
NdRangeTableCellRenderingInfo renderingInfo;
String[] cellPHValues;

int characteristicCount = scoreModel.getCharacteristicCount();

for (int chr = 0 ; chr < characteristicCount; chr++) {
System.out.println("\n" + "Characteristic: " + scoreModel.getCharacteristicLabel(chr));
int binCount = scoreModel.getBinCount(chr);
for (int bin = 0; bin < binCount; bin++) {
System.out.print(" Bin #" + bin + " '" + scoreModel.getBinLabel(chr, bin));
System.out.print("' Weight: " + scoreModel.getBinScoreWeight(chr, bin));

40 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

System.out.println(" Reason Code: " + scoreModel.getBinReasonCodeName(chr, bin));

int rangeCount = scoreModel.getRangeCount(chr, bin);
for (int range = 0; range < rangeCount; range++) {
templatesInfo = scoreModel.getRangeFormatTemplatesInfo(chr, bin, range);
System.out.print(" ");
System.out.println(templatesInfo.getCurrentCellTemplateDisplayName() + " (");
renderingInfo = scoreModel.getRangeRenderingInfo(chr, bin, range);
cellPHValues = renderingInfo.getValues();
for (int ph = 0; ph < cellPHValues.length; ph++) {
System.out.print(cellPHValues[ph]);
if (ph < cellPHValues.length - 1) {
System.out.print(" - ");
}
}
System.out.println(")");
}
}
}

This is the output of the code when run against the “Academic Score” score model:

Characteristic: GPA_Score
Bin #0 'Between 3.6 and 4.0' Weight: 50 Reason Code: ACAD01
GPA_Score 'real1' <= .. <= 'real2' (3.6 - 4)
Bin #1 'Between 2.9 and 3.6' Weight: 30 Reason Code: ACAD02
GPA_Score 'real1' <= .. < 'real2' (2.9 - 3.6)
Bin #2 'Between 2.1 and 2.9' Weight: 20 Reason Code: ACAD03
GPA_Score 'real1' <= .. < 'real2' (2.1 - 2.9)
Bin #3 'Less than 2.1 ' Weight: 5 Reason Code: ACAD05
GPA_Score 'real1' <= .. < 'real2' (0 - 2.1)
Bin #4 'All Other' Weight: 0 Reason Code: UEXP

Characteristic: SAT_Score
Bin #0 'Greater than 1400' Weight: 50 Reason Code: ACAD01
SAT_Score >= 'real' (1,400)
Bin #1 'Between 1200 and 1400' Weight: 30 Reason Code: ACAD02
SAT_Score 'real1' <= .. < 'real2' (1,200 - 1,400)
Bin #2 'Between 1000 and 1200' Weight: 20 Reason Code: ACAD03
SAT_Score 'real1' <= .. < 'real2' (1,000 - 1,200)
Bin #3 'Between 800 and 1000' Weight: 10 Reason Code: ACAD04
SAT_Score 'real1' <= .. < 'real2' (800 - 1,000)
Bin #4 'Less than 800' Weight: 5 Reason Code: ACAD05
SAT_Score 'real1' <= .. < 'real2' (0 - 800)
Bin #5 'All Other' Weight: 0 Reason Code: UEXP

<..portion removed..>
Characteristic: Academic Honors
Bin #0 'National Honors' Weight: 50 Reason Code: ACAD01
Academic Honors = 'string' (AP_Scholar)
Academic Honors = 'string' (National_Merit_Scholar)
Academic Honors = 'string' (National_Honors_Scholar)
Bin #1 'Local Honors' Weight: 40 Reason Code: ACAD01
Academic Honors = 'string' (Honor_Roll)
Academic Honors = 'string' (Deans_Award)
Academic Honors = 'string' (Citizenship_Award)
Bin #2 'Service Awards' Weight: 20 Reason Code: ACAD02
Academic Honors = 'string' (Merit_Award)
Bin #3 'No Awards' Weight: 0 Reason Code: ACAD06
Academic Honors = 'string' (none)
Bin #4 'All Other' Weight: 0 Reason Code: UEXP

Fair Isaac Corporation Confidential and Proprietary Information 41

CHAPTER 3: Metaphor APIs

42 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 4

Custom Provider API

This chapter is an introduction to understanding and developing

FICO™ Blaze Advisor® business rules management system custom providers. The
topics in this chapter include:
„ “Responsibilities of Provider Classes”
„ “Overview of the Custom Provider API” on page 44
„ “Creating Custom Provider Classes” on page 47
„ “The Example Base Class” on page 55
„ “Custom Provider Implementation Guidelines” on page 56

Responsibilities of Provider Classes

Blaze Advisor provider classes are invoked by the Innovator engine as part of the
process of generating SRL and other content from a template and an instantiation file. In
the case of a rule template, the template file is responsible for defining the logical
structure of the rules, and for defining the placeholders within that structure which
allow the rules to be modified. The instantiation file provides the values that will be
supplied for the placeholders when content is generated from a template's content
section. Providers are responsible for providing the Innovator engine with the values
necessary to instantiate a template that contains value holders. When a template
contains only fixed content and no values holders, then the data the Innovator engine
processes comes from the fixed content section and providers are not involved.
Providers must implement the following functions:
„ They are responsible for any transformation of values that should occur when a
template is resolved against an instantiation. Provider beans are invoked by the
Innovator engine during the resolving process and are passed a value retrieved
from the instantiation object model.
„ They are responsible for verifying that the value to be passed back to the Innovator
engine is of the correct type.
„ Certain templates might require that the values supplied to the template be
constrained to being one value out of a set of enumerated values. This is the case
with the custom providers that are discussed in this chapter. If a provider is
supplying values for such a template, they must implement an additional interface,
the NdConstrainedListProvider interface, which allows the Innovator engine to
determine what the constraints are. The provider should return a list of the values
that are acceptable.

Fair Isaac Corporation Confidential and Proprietary Information 43

CHAPTER 4: Custom Provider API

„ Certain templates might require that the behavior of a provider is customizable.

This is the case with value holders in templates (defined in the parameters element
of the XML template document) which optionally override the arguments passed to
providers by the Innovator engine. The example custom providers discussed in this
chapter, as well as the example custom providers in the <ADVISOR_HOME>/
examples/customProviders/java/stateProvince directory, demonstrate the use of
arguments to customize how the provider processes values.

Overview of the Custom Provider API

This section provides an overview of the most important classes and interfaces of the
Custom Provider API for building custom providers. This overview does not describe
all methods in the classes and interfaces. Refer to the API Reference for information on
these methods. The API Reference for the Innovator Custom Provider API is available by
selecting API Reference from the Builder Help menu.

NdTemplateValueProvider Interface
All providers implement the NdTemplateValueProvider interface. The interface
defines the basic features of a provider. The interface includes conversion methods
which every provider must support. The methods allow the values passed in from the
Innovator engine to be transformed in a manner determined by the provider. The
convertToDisplayValue() method returns the value that should be used for display
purposes in an RMA for a given instantiation value. Conversely,
convertFromDisplayValue() returns the value that should be stored in the
instantiation object for a given display value. (The instantiation object is the binary
representation of the instantiation file.) The convertToContentValue() method is used
to convert an instantiation value to the content value. However, when the instantiation
value and SRL value are the same, which is usually the case with custom providers, no
translation occurs and the method simply returns the instance value that is passed to it.

An NdProviderContext object is an argument in all of the methods of this interface. The

context argument allows the provider to obtain information about the context in which
the provider is being invoked. The NdProviderContext class includes the
getContentLocale() method which returns locale information as a java.util.Locale
object. The convert methods can use the locale information to perform locale-based
conversion.

The setArgs() method sets the values of control variables that customize the behavior
of the provider. For a discussion on designing custom providers with arguments see
“Creating Custom Provider Classes” on page 47.

The validateInstantiationValue() method returns true if the supplied value from

the instantiation object satisfies all of the constraints that the provider has placed on the
value. Your supplied instantiation value must be valid. Therefore this method should
return true.

Other methods return descriptive information about the provider to the Innovator
engine. getProviderType() returns the type of the provider class as a String.

44 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

getValueType() returns a constant which indicates the type of value provided by the
provider.
com.blazesoft.template.engine
public interface NdTemplateValueProvider
{
public void checkInstantiationValue(NdProviderContext context, String instantiationValue);
public String convertFromDisplayValue(NdProviderContext context, Object displayValue);
public String convertFromJavaObject(NdProviderContext context, Object javaObject);
public String convertToContentValue(NdProviderContext context, String instantiationValue);
public Object convertToDisplayValue(NdProviderContext context, String instantiationValue);
public Object convertToJavaObject(NdProviderContext context, String instantiationValue);
public Class getDisplayValueClass(NdProviderContext context);
public String getProviderType(NdProviderContext context);
public Class getValueClass(NdProviderContext context);
public int getValueType(NdProviderContext context);
public void reset(NdProviderContext context);
public void setArgs(NdProviderContext context, NdProviderStaticArg[] args);
}

NdDefaultTemplateValueProvider
NdDefaultTemplateValueProvider is an abstract class that provides default
implementations of the methods in the NdTemplateValueProvider interface. The
convert methods (convertToDisplayValue(), etc.) pass values without change.
validateInstantiationValue() does not apply any constraints on the instantiation
value. It returns true for any instantiation value passed to it. setArgs() does not process
any arguments.

As a convenience, providers can subclass this class and override only those methods
needed to define their specific functionality.

NdConstrainedListProvider Interface
NdConstrainedListProvider is a subinterface to the NdTemplateValueProvider
interface. This interface is implemented by a provider when the value it provides must
be constrained to one of a discrete set of values.

The getAllowedInstantiationValues() method returns an array of all the values that

can be legally stored in the nodes of the instantiation object for which the provider is
providing values. The getAllowedDisplayValues() method returns an array of all the
values that can be legally displayed for the nodes of the instantiation object for which the
provider is providing values. The getAllowedJavaValues() method returns an array
of all values that can be legally supplied to a Java client for the nodes of the instantiation
object. Each method should return null if the provider does not implement the constraint
that the value be a member of a set of discrete values.
com.blazesoft.template.engine
public interface NdConstrainedListProvider extends NdTemplateValueProvider
{
public String[] getAllowedInstantiationValues(NdProviderContext context);

Fair Isaac Corporation Confidential and Proprietary Information 45

CHAPTER 4: Custom Provider API

public Object[] getAllowedDisplayValues(NdProviderContext context);

public Object[] getAllowedJavaValues(NdProviderContext context);
}

NdDefaultConstrainedListProvider
NdDefaultConstrainedListProvider is an abstract class that extends
NdDefaultTemplateValueProvider and implements the
NdConstrainedListProvider interface. It provides default implementations for two of
the methods in the NdConstrainedListProvider interface,
getAllowedDisplayValues() and getAllowedJavaValues(). Providers that extend
NdDefaultContrainedListProvider must implement
getAllowedInstantiationValues(). The getAllowedDisplayedValues() method
first invokes the getAllowedInstantiationValues() method (on the subclass which
implements it) to obtain an array of the allowed instantiation values, and then invokes
convertToDisplayValue() on each element of the array to generate the array of
allowed display values. The default implementation of getAllowedJavaValue() is
identical to getAllowedDisplayValues(). Both methods return an array of allowed
display values.

The validateInstantiationValue() method overrides the default implementation

inherited from NdDefaultTemplateValueProvider. validateInstantiationValue()
invokes the getAllowedInstantiationValues method and checks that the supplied
value matches one of the items in the array of allowed values.
com.blazesoft.template.engine
public abstract class NdDefaultContrainedListProvider extends NdDefaultTemplateValueProvider
implements NdConstrainedListProvider
{
public Object[] getAllowedDisplayValues(NdProviderContext ctxt);
public Object[] getAllowedJavaValues(NdProviderContext ctxt);
public boolean validateInstantiationValue(NdProviderContext ctxt, String value);
}

NdDesignProvider Interface
The NdDesignProvider interface defines the methods that supply meta information
about the provider. This interface is implemented by every standard Blaze Advisor
provider, as well as the example custom providers in the <ADVISOR_HOME>/examples/
customProviders/java/stateProvince directory. The Custom Provider API does not
include a class that provides default implementation of these methods. Your provider
must implement each of these methods.

The NdDesignProvider interface defines the methods that supply meta information
about the provider. This interface is implemented by every standard Blaze Advisor
provider, as well as the example custom providers in the <ADVISOR_HOME>/examples/
customProviders/java/stateProvince directory. The Custom Provider API does not
include a class that provides default implementation of these methods. Your provider
must implement each of these methods.

The getDisplayName() method returns the display name of the provider. The display
name of the provider appears in the provider editor. The getDisplayKey() method

46 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

returns a key value which identifies the provider’s icon bitmap and its label.
getDescription() returns the description of the provider. The description is displayed
In New Provider dialog box when the provider’s icon is selected. This method is not used
with custom providers, since custom provider icons do not appear in the New Provider
dialog box.

The getArgumentDescriptors() method returns the description for the provider's

arguments. If no arguments are supported this method must return an array of zero
length (i.e., return NdDesignProviderArg[0];).
com.blazesoft.template.engine.provider
public interface NdDesignProvider
{
public String getDisplayName(NdProviderContext context);
public String getDescription(NdProviderContext context);
public String getDisplayKey(NdProviderContext context);
public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext context);
}

NdProvidesDefaultValue Interface
The NdProvidesDefaultValue interface defines the way for value providers to provide
the default values. Providers implement this interface if they are capable of providing a
meaningful default value for the type of value that they represent.

The provideDefaultValue() method returns a default value for the type of value
represented by this value provider. provideUniqueDefaultValues() returns a
sequence of unique default values for the type of value represented by this value
provider. If the provider cannot generate the number of values specified in the
numValues parameter, then it should return an array of smaller size that contains all of
the values that it was able to generate.
com.blazesoft.template.engine
public interface NdProvidesDefaultValue
{
public String provideDefaultValue(NdProviderContext context);
public String[] provideUniqueDefaultValues(NdProviderContext context, int numValues);
}

Creating Custom Provider Classes

The custom providers in the custom providers example (see the example in
<ADVISOR_HOME>/examples/customProviders/java) demonstrate how to use the
Custom Provider API to create your own constrained value list custom provider. This
section focuses on the key elements of creating custom providers, with reference to the
example code. You may want to open the source code in an editor and change the
values or attempt to add capability by implementing an appropriate interface. The
source code for the example custom providers is available in a subdirectory of the
example directory noted above.

Two very simple custom providers are presented first. These custom providers
demonstrate some of the essential features of the Custom Provider API with minimal

Fair Isaac Corporation Confidential and Proprietary Information 47

CHAPTER 4: Custom Provider API

code. The source code for the simple custom providers is not included in the custom
providers example folder.

Simple Value List Provider

The SimpleValueListProvider custom provider provides a String value that is
constrained to one of a discrete set of values. This custom provider is functionally
similar to a value list provider that has been configured to supply a value from a list of
String values.

The getAllowedInstantiationValues method returns the set of discrete values that is

defined for the provider. SimpleValueListProvider requires very little code because it
is derived from classes that supply default implementations of the interface methods
that are required for constrained list providers.

// SimpleValueListProvider.java
public class SimpleValueListProvider extends NdDefaultConstrainedListProvider
{
public final static String PROVINCES_ABBREV[] =
{"AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT"};

public SimpleValueListProvider()
{
}
public String[] getAllowedInstantiationValues(NdProviderContext context)
throws com.blazesoft.template.engine.NdTemplateException
{
return PROVINCES_ABBREV;
}
}

The list of allowed display values appears in the provider editor, as shown below.

48 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Recall that the NdContrainedListProvider interface is implemented by a provider

when the value it provides must be constrained to one of a discrete set of values (see
“NdConstrainedListProvider Interface” on page 45). The three methods of this interface
return the allowed sets of instantiation, display, and Java values. All constrained list
providers must implement the getInstantiationValues() method of the interface,
which returns a String array of all values that can be legally stored in the instantiation
object for which the provider is providing values. The Custom Provider API does not
supply a default implementation of this method since the array would always be
unique to the provider.

The Innovator engine determines the list of display values which appear in a drop-
down list in an RMA by calling convertToDisplayValue() for every value in the array
returned by getInstantiationValues(). The default implementation of
convertToDisplayValue() in NdDefaultTemplateValueProvider returns the value
that is passed to it, so no conversion occurs. The display value is the same as the
instantiation value.

Simple SRL and Display List Provider

The SimpleSRLAndDisplayListProvider custom provider is a constrained list
provider just as is SimpleValueListCustomProvider. Both providers provide a String
value that is constrained to one of a discrete set of values. The key difference between
the two is that SimpleSRLAndDisplayListCustomProvider also provides a unique
RMA display value for each instantiation value.

DisplayValuesProvider is the base class for the custom providers examples, which are
described in “Custom Providers Example” on page 33 of Examples.pdf.
DisplayValuesProvider is discussed in “The Example Base Class” on page 55.

Providers that extend DisplayValuesProvider must implement

getInstantiationValues() and getDisplayedValues().
getInstantiationValues() returns the array of allowed instantiation values. The
getDisplayedValues() method returns the array of valid display values that
correspond to the array of allowed instantiation values. The two arrays correspond in the
sense that for a given array index, a valid instantiation value and the corresponding
valid RMA display value for that instantiation value may be obtained.

public class SimpleSRLAndDisplayListProvider extends DisplayValuesProvider

implements NdDesignProvider
{
public final static String PROVINCES_ABBREV[] =
{ "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" };
public final static String PROVINCES[] =
{ "Alberta", "British Columbia", "Manitoba", "New Brunswick",
"Newfoundland and Labrador", "Northwest Territories", "Nova Scotia",
"Nunavut", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan",
"Yukon" };
private String[] instantiationValues;
private String[] displayValues;

public SimpleSRLAndDisplayListProvider()
{
}
protected String[] getInstantiationValues() throws NdTemplateException

Fair Isaac Corporation Confidential and Proprietary Information 49

CHAPTER 4: Custom Provider API

{
instantiationValues = PROVINCES_ABBREV;
return instantiationValues;
}
protected String[] getDisplayedValues() throws NdTemplateException
{
displayValues = PROVINCES;
return displayValues;
}
public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext parm1)
throws com.blazesoft.template.engine.NdTemplateException
{
return new NdDesignProviderArg[0];
}
public String getDisplayName(NdProviderContext parm1)
throws com.blazesoft.template.engine.NdTemplateException
{
return "";
}
public String getDescription(NdProviderContext parm1)
throws com.blazesoft.template.engine.NdTemplateException
{
return "SRL and display value provider for list of Canadian provinces and
territories.";
}
public String getDisplayKey(NdProviderContext parm1)
throws com.blazesoft.template.engine.NdTemplateException
{
return "Custom Provider";
}
}

The DisplayValuesProvider class overrides the default implementation of the

NdTemplateValueProvider interface convert methods. Each of these methods use the
value lists returned by getDisplayValues() and getInstantiationValues() to
perform the necessary value conversion.

As applied to the SimpleSRLAndDisplayListProvider provider, the

convertToDisplayValue() method returns the display value in the PROVINCES array
returned by getDisplayValues() that corresponds to a given instantiation value which
is present in the PROVINCES_ABBREV array returned by getInstantiationValues().

// from DisplayValuesProvider.java
public Object convertToDisplayValue(NdProviderContext context, String value)
throws NdTemplateException
{
String displayValue = "";
String[] displayedValues = getDisplayedValues();
String[] storedValues = getInstantiationValues();
if (displayedValues != null && storedValues != null) {
for (int index = 0; index < storedValues.length; index++) {
if (storedValues[index].equals(value)) {
displayValue = displayedValues[index];
break;
}
}
}
return displayValue;
}

50 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

Customizing Provider Behavior Using Arguments

The SimpleSRLAndDisplayListProvider provider discussed in the previous section
(“Simple SRL and Display List Provider” on page 49) is functionally identical to the
default behavior of the ConstantDisplayValuesProvider example provider, as
determined by the provider’s default argument settings. The
ConstantDisplayValuesProvider provider supports U.S. states as well as Canadian
provinces and territories.

The ConstantDisplayValuesProvider provider’s default setting for the Display Value

argument configures the provider to display the full names, rather than the abbreviated
names, of either states or provinces in the RMA. The default List Contents setting
restricts the provider to providing values for Canadian provinces and territories only.
The List Contents drop-down list allows users to select between State, Province/territory
and Both. The ability to customize the behavior of the provider sets
ConstantDisplayValuesProvider apart from the SimpleValueListProvider which
does not support provider arguments.

Provider argument descriptors are defined in the provider’s

getArgumentDescriptors() method. You can change the default values of the
arguments in the provider editor. You can override the default values in a provider
value holder by using the value holder’s Set Arguments dialog box. When argument
values change, the Innovator engine calls the provider’s setArgs() method. setArgs()
is also called whenever a value must be provided to a value holder. setArgs() is passed
an array of provider arguments. In the course of processing the arguments, setArgs()
will typically set the values of variables which are used elsewhere in the provider code
to control the required behavior.

Fair Isaac Corporation Confidential and Proprietary Information 51

CHAPTER 4: Custom Provider API

Defining Argument Descriptors

The getArgumentDescriptors() method of ConstantDisplayValuesProvider
defines two NdDesignProviderSelectableArg argument descriptors, displayType
and listType. The NdDesignProviderSelectableArg class defines a single-valued
argument that can take its value from a list of choices presented to the user in a drop-
down box. displayType describes an argument that is named “DisplayType” in the
constructor, as you can observe in the code below for the getArgumentDescriptors()
method. The setArgs() method identifies the argument by this name, as described in
the next section. setDisplayName() sets the label for the argument in the provider
editor, which is “Display Value.” setDescription() sets the description of the
argument. setChoices() sets the actual choice values that setArgs() obtains using the
argument’s getValue method. The argument is defined with two choice values: “Full
name” and “Abbreviated name.” (Note that String constants are used in place of
String literals in the code.) The same values are used in setDisplayChoices(), which
sets the displayed choice labels as they appear in the provider editor. The
setDefaultValue() method is called to set the default value of the argument to “Full
name”. setMandatory() sets whether or not the argument is mandatory.

The listType NdDesignProviderSelectableArg is set up in the same fashion. The

name of the argument being defined is “ListType.” The label for the argument in the
provider editor is “List Contents.” The list of choices which will appear in a drop-down
box in the editor is “State,” “Province/territory.” and “Both.” The default choice is
“State”.

Compare the code below with the image of the ConstantDisplayValuesProvider editor
in the previous section (“Customizing Provider Behavior Using Arguments” on page
51).

// from ConstantDisplayValuesProvider.java
public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext parm1)
throws com.blazesoft.template.engine.NdTemplateException
{
NdDesignProviderSelectableArg displayType = new NdDesignProviderSelectableArg("DisplayType");
displayType.setDisplayName("Display Value");
displayType.setDescription("Display the full name or abbreviation");
// displayType.setChoices(new String[] {"Full name", "Abbreviated name");
displayType.setChoices(new String[] {DISPLAY_TYPE_FULL, DISPLAY_TYPE_ABBREV});
displayType.setDisplayChoices(new String[] {DISPLAY_TYPE_FULL, DISPLAY_TYPE_ABBREV});
// displayType.setDefaultValue("Full name");
displayType.setDefaultValue(DISPLAY_TYPE_FULL);
displayType.setMandatory(true);

NdDesignProviderSelectableArg listType = new NdDesignProviderSelectableArg("ListType");

listType.setDisplayName("List Contents");
listType.setDescription("Display the states, provinces, or both");
// listType.setChoices(new String[] {"State", "Province/territory", "Both"});
listType.setChoices(new String[] {LIST_TYPE_STATE, LIST_TYPE_PROVINCE, LIST_TYPE_BOTH});
listType.setDisplayChoices(new String[] {LIST_TYPE_STATE, LIST_TYPE_PROVINCE, LIST_TYPE_BOTH});
// listType.setDefaultValue("State");
listType.setDefaultValue(LIST_TYPE_STATE);
listType.setMandatory(true);

return new NdDesignProviderArg[] { listType, displayType } ;

}

52 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

As described above, the ConstantDisplayValuesProvider provider uses single-

valued NdDesignProviderSelectableArg() argument descriptors that define
arguments that can take their value from a list of choices. The
UserDefinedDisplayValuesProvider provider in the custom providers example uses
single-value NdDesignProviderTypeArg arguments descriptors. This class defines a
single-valued argument that is not restricted to selection from a pre-determined set of
choices. Values are entered in a text box.

The example UserDefinedDisplayValuesProvider provider uses a multi-valued

argument descriptor (NdDesignProviderMultiArg), labeled Element, that is composed
of two single arguments of type NdDesignProviderTypedArg, which are labeled
“Stored Value” and “Displayed Value.” The user who is configuring the provider can
create any number of Element arguments in the provider editor. Each Element specifies
a state or provence abbreviation with the displayed name, such as AB and Alberta.

In the code below for the getArgumentDescriptors() method of the

UserDefinedDisplayValuesProvider, the names of the two
NdDesignProviderTypedArg single arguments are specified in the calls to the
constructor. The names, “StoredValue” and “DisplayedValue”, identify the arguments
when they are processed in the setArgs method. The setDisplayName() method is
called to set the display names of the arguments, which are “Content Value” and
“Display Value”. These values are used as labels for the single arguments in the
Element shown in the image above. setDescription() is called to set the description of
each argument, but the description does not appear in the provider editor. setType() is
called to set the argument type to String. setDefaultValue() sets the default value of
the argument to an empty string.

As mentioned above, the NdDesignProviderMultiArg class describes a provider's

multi-valued argument. The stored name of the argument is set to “Element” in the
constructor. This is the name the setArgs() method uses to identify the argument. The
setDisplayName() method is called to set the display name of the elements, which is
“Element”, as shown in the image above. The setNewCmdName() method is called to set
the value of the tooltip, which is “New Element”. The setMultiple() method is called
to set whether the argument can be multiple, which is true in the case of this multiple
argument. The setArgumentDescriptors() method is passed an array of

Fair Isaac Corporation Confidential and Proprietary Information 53

CHAPTER 4: Custom Provider API

NdDesignProviderArg which includes the two single NdDesignProviderTypeArg

arguments. Finally, the getArgumentDescriptors() method returns the
NdDesignProviderArg element argument descriptor that has been defined.

// from UserDefinedDisplayValuesProvider.java
public NdDesignProviderArg[] getArgumentDescriptors(NdProviderContext context)
throws NdTemplateException
{
NdDesignProviderTypedArg storedValue = new NdDesignProviderTypedArg("StoredValue");
storedValue.setDisplayName("Content Value");
storedValue.setDescription("SRL value generated during runtime");
storedValue.setType(NdTemplateManager.BUILTIN_STRING_PROVIDER);
storedValue.setDefaultValue("");

NdDesignProviderTypedArg displayedValue = new NdDesignProviderTypedArg("DisplayedValue");

displayedValue.setDisplayName("Display Value");
displayedValue.setDescription("Value displayed to the user");
displayedValue.setType(NdTemplateManager.BUILTIN_STRING_PROVIDER);
displayedValue.setDefaultValue("");

NdDesignProviderMultiArg element = new NdDesignProviderMultiArg("Element");

element.setDisplayName("Element");
element.setDescription("List Element");
element.setDisplayKey("Value");
element.setGroup("Element");
element.setNewCmdName("New Element");
element.setMultiple(true);
element.setArgumentDescriptors(new NdDesignProviderArg[]{storedValue, displayedValue});

return new NdDesignProviderArg[]{element};

}

Processing Arguments
As mentioned above, the setArgs() method of a provider is called by the Innovator
engine. The setArgs() method is passed NdProviderStaticArg arguments which are
processed in the method.

The ConstantDisplayValuesProvider provider defines two String variables,

displayType and listType. The variables are used to customize the behavior of the
provider. The provider’s setArgs() method assigns the value in the argument named
“DisplayType” to displayType and the value of the argument named “ListType” to
listType.

// from ConstantDisplayValuesProvider.java
public void setArgs(NdProviderContext context, NdProviderStaticArg[] args)
throws NdTemplateException
{
if (args != null & args.length > 0) {
for (int index = 0; index < args.length; index++) {
if (args[index].getName().equals("DisplayType")) {
displayType = args[index].getValue();
}
else if (args[index].getName().equals("ListType")) {
listType = args[index].getValue();
}
}
}
}

54 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The provider’s getInstantiationValues and getDisplayValues methods use

displayType and listType to determine the appropropriate array to return. For
example, the getInstantiationValues method returns the STATE_ABBREV array if
listType equals “States”. It returns the PROVINCE_ABBREV array if listType equals
“Province/territories” and it concatenation of both arrays if listType equals “Both”.

// from ConstantDisplayValuesProvider.java
protected String[] getInstantiationValues()
throws NdTemplateException
{
if(listType.equals(LIST_TYPE_STATE)) {
initializationValues = STATES_ABBREV;
}
else if(listType.equals(LIST_TYPE_PROVINCE)) {
initializationValues = PROVINCES_ABBREV;
}
else {
String[] allowedValues = new String[STATES_ABBREV.length + PROVINCES_ABBREV.length];
System.arraycopy(STATES_ABBREV, 0, allowedValues, 0, STATES_ABBREV.length);
System.arraycopy(PROVINCES_ABBREV, 0, allowedValues, STATES_ABBREV.length,
PROVINCES_ABBREV.length);
initializationValues = allowedValues;
}
return initializationValues;
}

The Example Base Class

The DisplayValuesProvider class is useful for creating many custom providers. The
class is not part of the Custom Provider API. It is included with the custom providers
example. The source code and class files for all example custom providers are available
in the <ADVISOR_HOME>/examples/customProviders/java/stateProvince folder. The
class extends NdDefaultContrainedListProvider. The example custom providers in
the example extend DisplayValuesProvider, which is an abstract class.

Providers that extend DisplayValuesProvider class must implement the two abstract
methods that are declared in the class, getInstantiationValues() and
getDisplayValues(). getInstantiationValues() returns a String array that
contains the allowed instantiation values. The provider’s content values are the same as
the instantiation values unless the provider overrides the default implementation of the
convertToContent() method, which ensures they are the same value. The
getDisplayValues() method returns a String array that contains the allowed display
values. The String arrays returned by getInstantiationValues() and
getDisplayValues() are constructed in parallel, such that for a given array index, a
valid instantiation value (again, this is also the content or SRL value) and the
corresponding valid RMA display value may be obtained.

Recall that it is the responsibility of a constrained list provider to define the valid
values. Each provider is free to obtain the values it provides in any fashion. The
example providers demonstrate different methods for obtaining value lists.The
StaticClassMethodProvider obtains values by calling static accessor methods on a
class that defines the appropriate String arrays as constants. The name of the class that
holds the values and the names of the appropriate accessor methods are specified when

Fair Isaac Corporation Confidential and Proprietary Information 55

CHAPTER 4: Custom Provider API

the provider is configured in the provider editor. The

UserDefinedDisplayValuesProvider is passed values that a user defines in elements
in the provider editor. The values are passed as arguments to the provider’s setArgs()
method. Finally, the ConstantDisplayValuesProvider obtains values from String
arrays defined in the class.

The implementations of getAllowedDisplayValues() and getAllowedJavaValues()

methods in the DisplayValuesProvider class both return a String array obtained by
calling getDisplayedValues(). Compare this implementation to the default
implementation described in “NdDefaultConstrainedListProvider” on page 46, which
obtains display values by invoking convertToDisplay() on each element of the String
array returned by getAllowedInstantiationValues().

The getAllowedInstantiationValues() method of the DisplayValuesProvider

class returns an array of all the values that can be legally stored in the nodes of the
instantiation object, as described in “NdConstrainedListProvider Interface” on page 45.
The getAllowedInstantiationValues() method calls getInstantiationValues() to
obtain the allowed instantiation values. getAllowedInstantiationValues() is called
by the provider’s validateInstantiationValue() method, which returns true if its
parameter value is contained in the array of valid instantiation values returned by this
method.

The DisplayValuesProvider class overrides the default implementation (in

NdDefaultConstrainedListProver) of all the NdConstrainedListProver interface
convert methods. For description of these methods see “NdTemplateValueProvider
Interface” on page 44. The DisplayValuesProvider implementation of these methods
each make use of the allowed instantiation values returned by
getInstantiationValues(), as well as the allowed display values returned by
getDisplayedValues().

Custom Provider Implementation Guidelines

When creating custom provider classes consider the following general implementation
guidelines:
„ Custom Provider classes get instantiated once per project and per user. So for
instance, if you have 10 concurrent users of an RMA, this will result into 10
instances of that Custom Provider class being created.
„ When providers are called by our code, they're typically always used in this
sequence:
„ First, the reset() method is called.
„ Then, the setArgs() method is called.
„ Finally the operation of choice is called (such as getAllowedDisplayValues(),
or convertToContentValue(), or validateValue(). for instance).
The bottom line is that the reset() and setArgs() methods are called very often.
Sometimes just to get the type of provider or the type of value returned by the
provider. So care must be taken to avoid doing costly operations in the reset() and

56 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

setArgs() methods. Also those methods should not throw any runtime exception.
Any operation that is costly to compute or may fail should be done only as the
result of calling one of the other methods.
„ If some operation done by a custom provider class is very costly (for instance,
reading information from a database, or returning a list of SRL entities of a
particular type in the current project), then care must be taken to avoid doing the
same operation too many times. Caching information in a local, private, non-static
Hashtable field for instance is a common way to keep and re-use previous results if
those results do not change between invocations of the provider.
„ Even if results may change between invocations, you may still use caching
techniques, but you must also worry about invalidating the cache if part of it
becomes invalid. For instance, if you've read information from files that reside on
your file system and kept that information in some local cache, indexed by the file
location, you should invalidate the information associated with that file if you
detect that file has been modified (using the Last Modified attribute of the file for
instance to detect whether a file has changed).
„ For implementing caches, it's important to note that it is the same Custom Provider
class that is shared between all RMA sessions, so care must be taken if the
information is stored in a static field. It might be OK to use a static field for such
cached data, but only if the cached data is constant and can indeed be shared across
all sessions. Also the code that reads from or writes to that cache must be
synchronized to prevent multiple threads/sessions to access that data at the same
time in an uncoordinated fashion (thrashing).
„ If the cached data could grow to a large amount over time, you could add
additional techniques to partially release the memory kept by the oldest parts of
your cache, such as using weak references or weak hashmaps to keep references to
cached data.
„ In the particular case where the data being retrieved is stored in a database, you
should consider not only caching the data retrieved from that database but also
sharing or pooling of connections (to avoid having each session result into a new
database connection).
„ In the particular case where the data being retrieved comes from the current project
content, you should use the new NdPromProviderUtil.getPromProject() method
to retrieve the current NdPromProject, and from that get the list of directories, items,
and entities that are relevant to the provider (instead of using methods such as
NdTemplateManager.loadInstantiation()). The main benefits of using the new
PROM APIs are that they give a fully objectified view of what's in the current
project, as well as cache all necessary information.

Fair Isaac Corporation Confidential and Proprietary Information 57

CHAPTER 4: Custom Provider API

58 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 5

RMA Service and Session APIs

The FICO™ Blaze Advisor® business rules management system RMA API is a high-
level API for developers building rule maintenance applications (RMAs). The API is
independent of the execution environment, so it is not limited to web-based
applications, but can be used to build RMAs in other environments including Java
Swing.

The RMA API is composed of the RMA Service API and the RMA Session API. The
RMA Service API includes interfaces which offer a means of connecting to a repository,
opening a project, finding relevant instances, editing instances, and saving those
instances in the repository. The purpose of the RMA Session API is to supplement the
RMA Service API by providing a state-holding interface while still not being tied to any
one client technology or execution environment.

The RMA Service API

The RMA Service API offers a simple set of interfaces geared towards editing instances
of templates. As with the PROM API, the RMA API operations are always performed in
the context of a project. The API provides a simple means of connecting to either a
versioned or non-versioned repository, opening a project, navigating the contents of the
project in order to find relevant instances, and then making it possible to edit and save
those instances. The API also allows the creation of new instances from templates found
in the project, as well the execution of queries to find entries of interest within the
project. Proper collaboration with the versioning system is provided by the API as well.

The RMA Repository (NdRmaRepository)

An RMA application which uses the RMA API begins by obtaining an instance of
NdRmaRepository by passing a repository connection object to the
connectToRepository() method of NdRmaRepositoryFactory. The NdRmaRepository
instance is used to open an RMA project (see “RMA Project (NdRmaProject)” on page
60). NdRmaRepository supplies two methods for opening a project.

NdRmaProject openProject(String projectFullDisplayPath)

NdRmaProject openProject(NdLocation projectAbsoluteLocation)

Both methods accept a parameter which specifies the location of the project as an
absolute location from the root directory of the repository. The difference between the
two is that the parameter to the openProject(String projectFullDisplayPath)
method is a String path which is built with display names, as they appear in the

Fair Isaac Corporation Confidential and Proprietary Information 59

CHAPTER 5: RMA Service and Session APIs

Builder IDE. In contrast, the openProject(NdLocation projectAbsoluteLocation)

method opens the project at the location specified by an absolute NdLocation. File
system names are used when creating an NdLocation, rather than display names. The
later method is used when file system names are preferred over display names and in
those cases where the location of the project was obtained by using the ROM and PROM
APIs, but it was deemed preferable to deal with that project as an NdRmaProject. See
“Specifying a Location (NdLocation)” on page 15 for discussion on creating an absolute
NdLocation.

The NdRmaRepository interface consists primarily of methods which supply information

about the repository connection and the repository.

boolean isVersionControlled()
boolean isPrivateWorkspaceUsed()
boolean isConnected()
void disconnect()
Date getConnectionDate()
NdRepositoryConnection getRepositoryConnection()

The isVersionControlled() method returns true if the repository supports versioning

operations. isPrivateWorkspaceUsed() returns true if the repository uses a private
workspace. isConnected() returns true if the repository is connected. disconnect()
disconnects from the repository. getConnectionDate() returns the connection date.
The getRepositoryConnection() method returns the NdRepositoryConnection object
that was used to connect to the repository. You can obtain information about the
repository connection with this object, such as the name of the repository or the user
name.

NdRmaRepository also contains these utility methods for displaying dates and obtaining
the display Calendar.

String formatDateForDisplay(Date date)

String formatDateForDisplay(Date date, Locale locale, TimeZone timeZone)
NdCalendar getDisplayCalendar()

The formatDateForDisplay(Date date) method returns the supplied Date as a

localized String representation of the connection date. formatDateForDisplay(Date
date, Locale locale, TimeZone timeZone) returns the supplied Date as a display-
friendly String, localized according to the supplied locale and time zone. The
getDisplayCalendar() method returns the displayCalendar using the default, server-
side locale.

RMA Project (NdRmaProject)

An RMA project is represented by NdRmaProject, which is obtained by calling
openProject() method of the NdRmaRepository interface.

NdFileRepositoryConnection connection = new NdFileRepositoryConnection();

connection.setUser("Template Developer");
connection.setRepositoryFolder("../../workspaces/MerchWksp");
NdRmaRepository rmaRepository = NdRmaRepositoryFactory.connectToRepository(connection);
NdRmaProject rmaProject = rmaRepository.openProject("/Business Library/MerchandisingRMA");

60 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The following methods are provided to support subproject navigation and multi-project
detection:

NdRmaSubProject[] getSubProjects()
boolean isMultiProject()
void refresh()

The getSubProjects() method returns the subprojects belonging to this project as an

array of NdRmaSubProject. A project may include one or more subprojects, as well as
imported directories and directories of its own. A “multi-project” is a project that is
composed of two or more subprojects and does not have directories of its own, although
it may have imported directories.The isMultiProject() method returns true if this
project is a multi-project. The list of subprojects returned by getSubProjects() is
cached by the project object, so the same list is assured every time getSubProjects() is
invoked. To obtain an accurate subdirectory list in the event the project subdirectories
in the repository change, call refresh() to reset the cached lists. The refresh() method
simultaneously refreshes the cached directory lists returned by the getDirectories()
and getAllDirectories(), which are decribed below.

The NdRmaProject interface provides a number of methods to navigate the directories

referenced by the project, as well as their contents.

NdRmaDirectory[] getDirectories(boolean includeSystemDirectories)

NdRmaDirectory[] getAllDirectories(boolean includeSystemDirectories)
NdRmaDirectory addDirectory(String directoryDisplayName)
void deleteDirectory(NdRmaDirectory directory)

The getDirectories() method returns the directories which are imported by the
project and the project’s subprojects. getAllDirectories() returns the directories
imported by the project and the project’s subprojects, as well as all the subdirectories of
the project and its subprojects. Set the boolean includeSystemDirectories parameter of
the methods to true to include directories that are located in system directories and
their subdirectories. (Any Entry Exclusion or Entry Inclusion Filters which are defined
for the current project will restrict which directories are returned by these methods.) As
noted above, the list of directories is cached, so every time these methods are invoked
the same results are assured. To obtain accurate lists in the event the project directories
and subprojects in the repository change, call refresh() to reset the cached lists.

Invoke the addDirectory() and deleteDirectory() methods to add a directory or

remove a directory from the project, respectively. The directory is created at the root of
the repository. A new directory is typically used for saving query instances from the
RMA. A directory must be empty before deleting it.

For convenience, specific methods are provided to obtain all the entries representing
templates, instances, query templates and query instances in the project. Set the boolean
includeSystemDirectories parameter of the methods to true to include templates that
are part of system directories and their subdirectories.

NdRmaTemplate[] getAllTemplates(boolean includeSystemDirectories)

NdRmaTemplate[] getFilterTemplates(boolean includeSystemDirectories)
NdRmaQueryTemplate[] getAllQueryTemplates(boolean includeSystemDirectories)
NdRmaQueryTemplate[] getSearchQueryTemplates(boolean includeSystemDirectories)

Fair Isaac Corporation Confidential and Proprietary Information 61

CHAPTER 5: RMA Service and Session APIs

NdRmaQueryTemplate[] getComparisonQueryTemplates(boolean includeSystemDirectories)

NdRmaQueryTemplate[] getVerificationQueryTemplates(boolean includeSystemDirectories)
NdRmaInstance[] getAllInstances(boolean includeSystemDirectories)
NdRmaInstance[] getFilterInstances()boolean includeSystemDirectories
NdRmaQueryInstance[] getAllQueryInstances(boolean includeSystemDirectories)
NdRmaQueryInstance[] getSearchQueryInstances(boolean includeSystemDirectories)
NdRmaQueryInstance[] getComparisonQueryInstances(boolean includeSystemDirectories)
NdRmaQueryInstance[] getVerificationQueryInstances(boolean includeSystemDirectories)
dispose()

The getAllTemplates() method returns all the templates in the project, including Filter
and Query templates. getFilterTemplates() returns all the Filter templates in the
project. The output of this method is unaffected by any current inclusion filter.
getAllQueryTemplates() returns all the Query templates in the project.
getSearchQueryTemplates() returns all the Search Query templates in the project.
getComparisonQueryTemplates() returns all the Comparison Query templates in the
project. getVerificationQueryTemplates() returns all the Verification Query
templates in the project. getAllInstances() returns all the instances in the project.
getFilterInstances() returns all the Filter instances in the project. The output of this
method is unaffected by any current inclusion filter. getAllQueryInstances() returns
all the Query instances in the project. getSearchQueryInstances() returns all the
Search Query instances in the project. getComparisonQueryInstances() returns all the
Comparison Query instances in the project. getVerificationQueryInstances() returns
all the Verification Query instances in the project. The dispose() method releases the
project resources. Any subsequent attempt to use the disposed project will result in an
assert Exception

The methods described above return by default all the entries that are found when
traversing the directories imported by the project (aside from directories that are
explicitly excluded with an Exclusion Filter). However, a method of the project’s Filter
Manager, NdRmaEntryFilterManager.setEntryExclusionFilter(), allows client code
to provide an NdRmaEntryExclusionFilter to automatically filter out unwanted results
when these entry-collecting methods are used. Passing null to
setEntryExclusionFilter() will remove the filter and thus reset the behavior of those
methods to the default. See “RMA Entry Filter Manager (NdRmaEntryFilterManager)”
on page 79.

NdRmaProject includes a method for obtaining the project’s Filter Manager:

NdRmaEntryFilterManager getEntryFilterManager()

Invoke the project’s getEntryFilterManager() method to obtain the Filter Manager.

NdRmaProject provides a method for obtaining an entry by its location.

NdRmaEntry lookupEntryByLocation(NdLocation absoluteLocation)

The lookupEntryByLocation() method obtains the NdRmaEntry at the supplied absolute

location (NdLocation) from the repository root. The method is convenient for switching
to the RMA API after having navigated the repository using the ROM and PROM APIs.
Note that an NdRmaEntry may be either a file or a directory. This method will return
null when an entry cannot be found at the provided absolute location. The method will

62 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

throw an exception if the absolute location belongs to a storage folder for sub-instances
stored-separately, or if it is not an absolute location, or if the project has been previously
disposed of. NdRmaEntry has a complementary method, getLocation(), which returns
the NdLocation corresponding to the entry. For a discussion on the distinction between
an absolute and relative NdLocation, see “Specifying a Location (NdLocation)” on page
15.

Errors that may occur when dealing with the project may be handled with the following
methods:

boolean hasErrors()
NdRMAException[] getErrors()
void clearErrors()

The hasErrors() method returns true if errors were found while performing any
operation on the project. getErrors() returns the errors that were found while
performing any operation on the project. clearErrors() clears the list of errors that
were kept since the last call to this method. Consider clearing the cached list of errors
prior to performing a discrete set of operations on the project, so that the successive calls
to hasErrors() and getErrors() reflect only the errors in the immediate set.

NdRmaProject supports versioning by virtue of extending NdRmaEntry, which has

methods for obtaining versioning information and versioning operations.

A project in a versioned repository provides versioning information and supports

versioning operations, but not the getVersion(), promote(), and restore() methods.
(See “Versioning” on page 75.)

RMA Entry (NdRmaEntry)

An NdRmaEntry is either a project directory or a file in a project. This is similar to an
NdPromEntry in the PROM API, that is either a directory or an item, which is the ROM
API and PROM API term for a file.

The NdRmaEntry interface includes the following methods:

String getDisplayName()
String[] getDisplayPath()
NdLocation getLocation()
NdRmaDirectory getParentDirectory()
NdRmaProject getProject()

The getDisplayName() method returns the display name of the file as it appears in the
Builder IDE. getDisplayPath() returns the display path of the file, as an array of
String. Each element represents a node in the hierarchy. The hierarchy starts at the
project node. The last element in the array is the display name of the file. getLocation()
returns an NdLocation object that is the absolute location of the entry from the root of
the repository. getParentDirectory() returns the directory that contains the entry.
null is returned if the entry has no parent; which would be the case if, for example, the
entry were a project or one of the top-level project directories. Note that the
getDisplayPath(), getLocation(), and getParentDirectory() methods cannot be used
if the entry is a transient Query instance (one whose isTransient() method returns

Fair Isaac Corporation Confidential and Proprietary Information 63

CHAPTER 5: RMA Service and Session APIs

true). An exception will be thrown in this case. getProject() returns the project the
entry belongs to.

The following methods are used to obtain the entry’s repository schema typing attribute
values, which are defined by the
com.blazesoft.templates.repository.NdRomSchemaConstants interface. See
“Repository Item Typing Attributes” on page 8.

int getType()
int getSubType()
int getContentType()
int getTarget()

The getType() method returns the NdRomSchemaConstants “type” value for this entry,
such as TYPE_SRL_ENUMERATION. getSubType() returns the “subType” value for this
entry, such as SUB_TYPE_NONE. getContentType() returns the “contentType” value for
this entry, such as CONTENT_TYPE_FIXED. The getTarget() method returns the “target”
value for this entry, such as TARGET_SRL.

An entry also supplies methods to deal with versioning and authorization:

NdRmaEntryVersioningInfo getVersioningInfo()
NdRmaEntryVersioningOperations getVersioningOperations()

The getVersioningInfo() method returns the versioning information

(NdRmaEntryVersioningInfo) for the entry. If the repository does not support
versioning, or there is no versioning information for the entry, this method returns null.
getVersioningOperations() returns the versioning operations
(NdRmaEntryVersioningOperations) that may be performed on the entry. If the
repository does not support versioning, or the entry does not support any versioning
operation, this method returns null. For the current release of the RMA Service API,
versioning operations are supported for only two kinds of entries: instances
(NdRmaInstance) and projects (NdRmaProject). For projects, only the update() operation
is presently supported.

RMA Directory (NdRmaDirectory)

NdRmaDirectory provides the following methods in addition to those inherited from
NdRmaEntry:

boolean hasEntries()
NdRmaEntry[] getEntries()
void resetEntries()
NdRmaDirectory createDirectory(String directoryDisplayName)
void deleteEntry(NdRmaEntry entry)
rename(String name)
NdRmaGloballyDeletedFile[] getGloballyDeletedFiles()
void resetGloballyDeletedFiles()
boolean hasGloballyDeletedFiles()

The hasEntries() method returns true if the directory has any content. getEntries()
returns all the entries in the directory. The list of entries is cached. If any entry exclusion
filter was defined at the project level, then the result provided by these methods will

64 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

depend on the filter. Projects and subprojects will never be in the list of entries returned
by getEntries(). The reason is that directories are fetched in the context of some
project, and other projects that may be contained in those directories are invisible to the
root project. The resetEntries() method clears the cache of entries. This is useful so
that the next call to getEntries() returns an up-to-date list of entries. The
createDirectory() method creates a subdirectory of the specified name. The
deleteEntry() method deletes the supplied entry. rename(String name) renames the
directory. The new name must not contain any illegal characters and cannot be a
duplicate of another directory within the same parent directory.
getGloballyDeletedFiles() returns all the files in this directory that have been deleted
and then checked into the versioning system. resetGloballyDeletedFiles() clears the
cache of files that have been deleted then checked into the versioning system. The
hasGloballyDeletedFiles() method returns true if the directory has any file that has
been deleted then checked into the versioning system.

Versioning operations are not provided for a directory in the current release, even
though NdRmaDirectory extends NdRmaEntry, which supports versioning. However,
NdRmaDirectory does provide the following method for obtaining versioning
information for all the entries in a directory:

public NdRmaDirectoryVersioningInfos getVersioningInfos()

The getVersioningInfos() method returns an instance of

NdRmaDirectoryVersioningInfos which may be used to obtain the versioning status
and lock information for all the entries in the directory. This method is provided so that
a more efficient retrieval of versioning information can be performed when such
information is needed for more than one entry. The NdRmaDirectoryVersioningInfos
interface is discussed in “Versioning Information (NdRmaEntryVersioningInfo)” on
page 76.

RMA Files
As described in “RMA Entry (NdRmaEntry)” on page 63, an entry in a repository is
either a project directory or a file in a project. Files are always contained by a directory,
with the exception of projects. The four types of files supported by the RMA API are
listed below. Each interface extends NdRmaFile.
„ project (NdRmaProject)
„ subproject (NdRmaSubProject)
„ template file (NdRmaTemplateFile)
„ instance file (NdRmaInstanceFile)

File (NdRmaFile)
The NdRmaFile interface provides the following methods.

Date getLastModifiedDate()
boolean isLogicallyDeleted()
boolean isNew()
void reloadContent()

Fair Isaac Corporation Confidential and Proprietary Information 65

CHAPTER 5: RMA Service and Session APIs

NdRmaEntry getOriginalTipEntry()
NdRmaInstanceFile getRootInstanceFile()
String getSubInstancePath()
String getSubInstanceSectionName()

The getLastModifiedDate() method returns the date the file was last modified. To
obtain a display-friendly, localized String for that Date, call
NdRmaRepository.formatDateForDisplay(). The isLogicallyDeleted() method
returns true if the file has been logically deleted. A logically deleted file is one that is
either deleted locally in the workspace or deleted globally in the versioning system.
isNew() returns true if the file was just created and never saved. The reloadContent()
method reloads the content of the file and discards changes which have not been saved.
getOriginalTipEntry() returns the working copy, or “tip” entry file if the file is a
version of an entry, otherwise null is returned. getRootInstanceFile() returns the root
instance (parent) file if this entry represents the entry for a sub-instance stored-
separately. This method returns null if this entry does not represent an instance stored-
separately. The getSubInstancePath() method returns the path to the sub-instance
stored-separately within the instance contained by this file.
getSubInstanceSectionName() returns the section name of the sub-instance stored-
separately within the instance contained by this file. Both getSubInstancePath() and
getSubInstanceSectionName() are used by entries representing instances stored-
separately, so that with the root instance file, the sub-instance path, and sub-instance
section name it is possible to find the sub-instance linking to the instance stored-
separately.

Project (NdRmaProject)
Projects (NdRmaProject) and subprojects (NdRmaSubProject) are not included in the list
of entries returned by the getEntries() method of NdRmaDirectory (see “RMA
Directory (NdRmaDirectory)” on page 64). The reason is that directories are fetched in
the context of some project, and other projects that may be contained in those directories
are invisible to the root project which provides the context.

NdRmaProject and NdRmaSubProject extend NdRmaFile so that it can supply versioning

information, and so that versioning operations can be performed. For the current
release, however, only instances support all versioning operations. Projects support
some versioning operations, as described in “Versioning” on page 75.

The methods available in NdRmaProject are discussed in “RMA Project

(NdRmaProject)” on page 60.

Subproject (NdRmaSubProject)
A subproject is simply a project contained by another project. NdRmaProject and
NdRmaSubProject extend NdRmaFile so that it can supply versioning information. This
extension also allows versioning operations to be performed on an NdRmaProject, like
any other entry. However, NdRmaSubProject objects are read-only; no operations are
allowed that can change its state. Versioning is not supported. To operate on a
subproject, open the subproject as a project using the NdRmaRepository.openProject()
method described in “RMA Project (NdRmaProject)” on page 60. Alternatively, obtain

66 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

the NdRmaProject instance by calling getRmaProject() (inherited from NdRmaEntry) on

the subproject instance.

To limit the ability to modify the subproject, the following methods inherited from
NdRmaFile are overridden:

NdRmaEntryVersioningOperations getVersioningOperations()
void reloadContent()

The getVersioningOperations() method returns null. Calling reloadContent() on a

subproject will result in an NdRMAException being thrown.

Template File (NdRmaTemplateFile)

The NdRmaTemplateFile interface represents a file which contains a template.
NdRmaTemplateFile supplies these methods.

NdRmaTemplate getTemplate()
NdRmaFile saveAs(NdRmaDirectory targetDirectory, String name)

The getTemplate() method returns the template that this file contains. saveAs() saves a
copy of the file in the specified target directory. The copy that was created is returned.
The new name must not contain any illegal characters and cannot be a duplicate of
another file within the same directory.

Instance File (NdRmaInstanceFile)

The NdRmaInstanceFile interface represents a file that contains an instance.
NdRmaInstanceFile provides this method:

NdRmaInstance getInstance()

The getInstance() method returns the instance that this file contains.

NdRmaInstanceFile extends NdRmaEditableFile which provides the editing capability

for the instance. See “Editable File (NdRmaEditableFile)” below.

Editable File (NdRmaEditableFile)

NdRmaEditableFile is implemented by files that allow editing. For the current release,
only instances instances are editable. NdRmaEditableFile extends NdRmaFile.

void save()
NdRmaFile saveAs(NdRmaDirectory targetDirectory, String name)
boolean isModified()
rename(String displayName)
boolean isStoredSeparately()

The save() method saves the file. If the file is read-only or is a transient Query instance,
this method will fail. The saveAs() method saves a copy of the file, with a new name, in
the specified target directory. The copy that is created is returned as an NdRmaFile. The
isModified() method returns true if the file has been modified. After the file is saved,
isModified() will return false. Saving a modified file with a new name using

Fair Isaac Corporation Confidential and Proprietary Information 67

CHAPTER 5: RMA Service and Session APIs

saveAs() will result in isModified() returning true, since a copy will have been saved
and not the original file. The rename() method is used to rename the file. The file will be
marked as modified, and will not be saved.isStoredSeparately() returns the true if
this file is an instance that is currently stored separately.

File Content (NdRmaFileContent)

The file content interfaces are NdRmaTemplate and NdRmaInstance, as well as
NdRmaQueryTemplate and NdRmaQueryInstance. These interfaces extend
NdRmaFileContent, which contains the following method:

NdRmaFile getFile()

The NdRmaFile getFile() method returns the file that contains the content.

The NdRmaTemplate and NdRmaInstance interfaces are discussed in the following

sections.

RMA Template (NdRmaTemplate)

NdRmaTemplate provides the following methods in addition to the getFile() method
inherited from NdRmaFileContent:

NdRmaInstance generateInstance(NdRmaDirectory targetDirectory, String instanceDisplayName)

String getDisplayName()
boolean isComparisonQueryTemplate()
boolean isFilterTemplate()
boolean isQueryTemplate()
boolean isSearchQueryTemplate()
boolean isVerificationQueryTemplate()
boolean isTransient()

The generateInstance() method generates a new instance of the template in the

specified target directory and saves it. If the instance is created in a versioned repository
it must be checked in. The new instance may be edited, as described in “Editing the
Contents of an Instance” on page 71. The getDisplayName() method returns the display
name of this template entry. isComparisonQueryTemplate() returns true if this
template is a Comparison Query template. isFilterTemplate() returns true if this
template is a Filter template. isQueryTemplate() returns true if this template is a Query
template. isSearchQueryTemplate() returns true if this template is a Search Query
template. The isVerificationQueryTemplate() method returns true if this template is
a Verification Query template.

The isTransient() method returns true if this template is in a transient state. When
NdRmaInstance.getTemplate() returns an NdRmaTemplate, it may need to return a
template in a “transient” state - meaning the template can only be used to test its
properties and to obtain the display name of the template. This is necessary when the
template has been excluded from the project and yet we still want to supply an
NdRmaTemplate from the instance's getTemplate() method. For example, the Standard
Business Query template has been excluded when generating the RMA, and yet we
want to still be able to group instances of that template under the template's display

68 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

name, even though a new instantiation of the template can not be made. (Excerpted
from the API Reference entry for the NdRmaTemplate interface.)

Versioning information regarding the template file may obtained through the
NdRmaFile object which is returned by calling getFile(). For the current release,
however, version operations are not supported for templates. Subprojects do not
implement versioning operations. See “Versioning” on page 75.

RMA Instance (NdRmaInstance)

NdRmaInstance extends NdRmaFileContent, and as such, it inherits the getFile()
method which ultimately gives access to the versioning information and versioning
operations for that file.

NdRmaInstance provides a method for obtaining the template for this instance:

NdRmaTemplate getTemplate()

The getTemplate() method returns the NdRmaTemplate entry that the instance was
generated from. If the project directory containing the template has been excluded or
filtered out, the NdRmaTemplate object returned will be in a transient state. That is, the
template’s isTransient() method will return true, and its getFile() and
generateInstance() methods will throw an exception. getTemplate() returns null if
the template could not be obtained due to a linking error.

An instance can be obtained by calling the getInstance() method of the

NdRmaInstanceFile interface. The NdRmaInstanceFile object you use can be obtained
by calling the lookupEntryByLocation(NdLocation location) method of
NdRmaProject, as shown in the code below. You can obtain all instances in a project by
calling the getAllInstances() method of the NdRmaProject.

This code shows how to obtain an instance by two methods. The first obtains the
instance specified by its absolute location from the repository root. The second obtains
the instance by iterating through all instances in the project to find its display name.

// Obtain an instance by location

// rmaProject is an NdRmaProject
String instanceLocation = "/Business Library/Region_3/Merchandising Region_3";
NdRmaInstance rmaInstance = null;
NdLocation location = NdLocationFactory.createLocation(instanceLocation);
NdRmaEntry rmaEntry = rmaProject.lookupEntryByLocation(location);
if (rmaEntry instanceof NdRmaInstanceFile) {
rmaInstance = ((NdRmaInstanceFile)rmaEntry).getInstance();
}

// Obtain an instance by display name

String instanceName = "Merchandising Region_3";
NdRmaInstance[] rmaInstances = rmaProject.getAllInstances(true);
for (int i = 0; i < rmaInstances.length; i++) {
rmaFile = ((NdRmaFileContent)rmaInstances[i]).getFile();
if (rmaFile.getDisplayName().equals(instanceName)) {
rmaInstance = rmaInstances[i];
break;
}
}

Fair Isaac Corporation Confidential and Proprietary Information 69

CHAPTER 5: RMA Service and Session APIs

These methods help identify if the instance is one of a special type of instance:

boolean isFilterInstance()
boolean isQueryInstance()

The isFilterInstance() method returns true if this instance is an instance of a Filter

template. isQueryInstance() returns true if this instance is an instance of a Query
template.

When instances are loaded from the repository some linking errors may occur. This can
happen when the template of the instance might have changed, or might not exist
anymore. These errors are dealt with using the following NdRmaInstance methods:

boolean hasLinkingErrors()
NdRMAException[] getLinkingErrors()
void clearLinkingErrors()
boolean hasLinkingFixes()
NdInstantiationFix[] getLinkingFixes()
void fixLinkingErrors()

The hasLinkingErrors() method returns true if linking errors occurred while loading
the instance. getLinkingErrors() returns a list of the linking errors that may have
occurred while loading the instance. If no error occurred, an empty array is returned.
clearLinkingErrors() clears the list of linking errors. This is useful if
fixLinkingErrors() is not called and you wish to ignore the errors. hasLinkingFixes()
returns true if there are linking fixes available for the instance. getLinkingFixes()
returns an array of NdInstantiationFix objects which can provide information about
the linking fixes that exist on the instance and which can be fixed by calling
fixLinkingErrors(). If no fixes are needed an empty array is returned. Call the
fixLinkingErrors() method to automatically fix the linking issues if there are any. The
list of linking fixes is then cleared. Note that this method does not fix validation errors,
which are errors that may occur during the editing of the instance.

Displaying the Contents of an Instance

The following NdRmaInstance methods are used to get the contents of an instance:

NdInstanceElementNode[] getInstanceElementNodes()
NdInstanceElementNode[] getInstanceElementNodes(NdInstanceElementNode node)
NdInstanceElementNode[] getInstanceElementNodesForTOC()
NdInstanceElementNode[] getInstanceElementNodesForTOC(NdInstanceElementNode node)
NdInstanceElementNode lookupInstanceElementNode(String instanceSectionName,
String nodePath, boolean resultForTOC)

The getInstanceElementNodes() method returns the top-level nodes of the instance as

an array of NdInstanceElementNode. To get the sub-nodes, call
getInstanceElementNodes(NdInstanceElementNode node) on each node.

The getInstanceElementNodesForTOC() method returns the instance element nodes

that are used to display the table of contents of the instance. (An example of a “table of
contents” is the table of contents in a generated RMA.) A variant of this method takes an
NdInstanceElementNode as a parameter and will supply the instance nodes for the
passed node. lookupInstanceElementNode() returns the instance node at the supplied

70 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

path in the instance section of the supplied name. To lookup this node in the context of
a table of contents, set resultForTOC to true. See “Instance Element Node
(NdInstanceElementNode)” on page 74.

Editing the Contents of an Instance

This section describes the NdRmaInstance methods which are available for editing an
instance. Editing errors may occur during the execution of these methods (see “Editing
Errors” on page 73).

void setNodeValue(NdInstanceElementNode node, String displayValue)

NdInstanceElementNode[] getAffectedInstanceElementNodes()
void setNodeInstance(NdInstanceElementNode node, String templateDisplayName)
void addListValue(NdInstanceElementNode list, String displayValue)
void addListValueBefore(NdInstanceElementNode list, String displayValue,
NdInstanceElementNode targetNode)
void addListValueAfter(NdInstanceElementNode list, String displayValue,
NdInstanceElementNode targetNode)

The setNodeValue(NdInstanceElementNode node, String displayValue) method sets

the value of the supplied node to the passed display value. If the displayValue is not
different than the current displayValue then the value will not be applied.
getAffectedInstanceElementNodes() returns the nodes that have been secondarily
and consequentially changed due to the most-recent use of the setNodeValue() method.
This list will not include the instanceElement node directly modified by the most-
recent use of the setNodeValue() method. This method will return an empty array if no
nodes have been affected by the most-recent setNodeValue() usage.setNodeInstance()
replaces the instance in the specified node with a new instance of the specified template
name. This method can only used for nodes configured by a template list provider. The
template name must be the display name of one of the templates listed in that template
list provider.

The addListValue() method adds the supplied display value to the supplied list node.
addListValueBefore() adds the supplied display value to the supplied list
immediately before the existing element targetNode. Editing errors may occur during
the execution of this method. addListValueAfter() adds the supplied display value to
the supplied list immediately after the existing element targetNode. Editing errors may
occur during the execution of this method.

The addListValueXXX() methods described above add only String values. In contrast,
the following addListInstanceXXX() methods are used to add instances of templates to
the supplied list.

void addListInstance(NdInstanceElementNode list)

void addListInstance(NdInstanceElementNode list, String templateDisplayName)
void addListInstanceBefore(NdInstanceElementNode list, NdInstanceElementNode targetNode)
void addListInstanceBefore(NdInstanceElementNode list, String templateDisplayName,
NdInstanceElementNode targetNode)
void addListInstanceAfter(NdInstanceElementNode list, NdInstanceElementNode targetNode)
void addListInstanceAfter(NdInstanceElementNode list, String templateDisplayName,
NdInstanceElementNode targetNode)

Fair Isaac Corporation Confidential and Proprietary Information 71

CHAPTER 5: RMA Service and Session APIs

The addListInstance(NdInstanceElementNode list) method is used when the list

may only contain instances of the same template. The
addListInstance(NdInstanceElementNode list, String displayValue) method is
used when the list may only contain instances of different templates. (Examples of both
usages are found in AddSegmentExample.java, which is part of the RMA API example.)

The addListInstanceBefore(NdInstanceElementNode list, NdInstanceElementNode

targetNode) method adds an instance element to the supplied list immediately before
the existing element targetNode. The addListInstanceBefore(NdInstanceElementNode
list, String templateDisplayName, NdInstanceElementNode targetNode) method
adds an instance element of the template type identified by the given
templateDisplayName to the supplied list immediately before the existing element
targetNode. A corresponding set of addListInstanceAfter() methods work in the
identical fashion as the addListInstanceBefore() methods, except the instance element
is added after the existing element, rather than before.

The position of existing nodes within their containing lists may be changed using the
following methods:

void moveListNodeUp(NdInstanceElementNode node)

void moveListNodeDown(NdInstanceElementNode node)
void moveListNodesUp(NdInstanceElementNode[] nodes)
void moveListNodesDown(NdInstanceElementNode[] nodes)

The moveListNodeUp(NdInstanceElementNode node) method moves the node up within

its containing list (i.e., its index in the list is decremented by 1).
moveListNodeDown(NdInstanceElementNode node) moves the node down within its
containing list (i.e., its index in the list is incremented by 1). The
moveListNodesUp(NdInstanceElementNode[] nodes) method moves the nodes up
within their containing list. The nodes retain their relative position within the list and
the node in the nodes with the highest index will be located just before the node above the
node with the lowest index in the list. If the node with the lowest index is at the top of the
list no action will occur. moveListNodeDown(NdInstanceElementNode[] nodes) moves
the nodes down within their containing list. The nodes retain their relative position
within the list and node in the nodes with the lowest index will be located just after the
node below the node with the highest index in the list. If the node with the highest index is
at the bottom of the list no action will occur.

void moveListNodesBefore(NdInstanceElementNode[] nodes, NdInstanceElementNode targetNode)

void moveListNodesAfter(NdInstanceElementNode[] nodes, NdInstanceElementNode targetNode)

The moveListNodesBefore() method moves the nodes before the targetNode in their
containing list (i.e. each of the nodes’ index in the list will be less than the targetNodes'
index with the final node from nodes having an index that is 1 less than the targetNodes'
index. The relative position of each node in nodes will be maintained. The
moveListNodesAfter() method moves the nodes after the targetNode in their
containing list (i.e. each of the nodes’ index in the list will be greater than the
targetNodes' index with the first node from nodes having an index that is 1 greater than
the targetNodes' index. The relative position of each node in nodes will be maintained.

Nodes are deleted with these methods:

72 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

void deleteListNode(NdInstanceElementNode node)

void deleteListNodes(NdInstanceElementNode[] nodes)

deleteListNode() deletes the supplied node from its containing list.

deleteListNodes(NdInstanceElementNode[] nodes) deletes the supplied nodes from
their containing list.

Editing Errors
Editing errors may occur during the execution of any of the methods described in the
previous section (“Editing the Contents of an Instance” on page 71). An editing error
will occur, for example, when an incorrect template display name is supplied to the
addListInstance(NdInstanceElementNode list, String templateDisplayName)
method. The errors may be obtained with the following NdRmaInstance methods.

boolean hasEditingErrors()
boolean hasEditingError(NdInstanceElementNode node)
NdRmaException getEditingError(NdInstanceElementNode node)
NdRmaException getEditingError(String nodePath)
String[] getPathsOfNodesWithEditingErrors()
void clearEditingErrors()

The hasEditingErrors() method returns true if the editing of this instance generated
errors. hasEditingError(NdInstanceElementNode node) returns true if the editing of
this instance generated an error caused by the provided node.
getEditingError(NdInstanceElementNode node) returns the editing error that may
have occurred by calling one of the editing methods on the supplied node. If no error
occurred, null is returned. getEditingError(String nodePath) returns the editing
error that may have occurred by calling an editing method for the node located by the
supplied node path. If no error occurred, null is returned.
getPathsOfNodesWithEditingErrors() returns an array of nodePaths for the nodes that
currently have editing errors. If no nodes have an error then an empty array is returned.
clearEditingErrors() clears all the editing errors that may have occurred.

Validation Errors
When changes are made to an instance, those changes need to be validated in order to
verify that the instance conforms to the constraints put in place by the template. The
following NdRmaInstance methods are related to validation.

void validate()
void validate(NdInstanceElementNode)
boolean hasValidationErrors()
boolean hasValidationError(NdInstanceElementNode node)
NdRMAException getValidationError(NdInstanceElementNode node)
NdRMAException getValidationError(String nodePath)
NdRMAException[] getNodeValidationErrors()
String[] getPathsOfNodesWithValidationErrors()
NdRMAException[] getOtherValidationErrors()
void clearValidationErrors()

Fair Isaac Corporation Confidential and Proprietary Information 73

CHAPTER 5: RMA Service and Session APIs

Begin validation by calling one of the validate() methods. This will generate a list of
validation errors in cache. You may want to call the clearValidationErrors() method
before calling validate() in order to clear any existing list.

The validate() method tries to validate this instance. A variant of validate() takes an
NdInstanceElementNode as a parameter to only validate that node, and its sub-nodes,
and not the whole instance. hasValidationErrors() returns true if the validation of
this instance generated validation errors. hasValidationError(NdInstanceElementNode
node) returns true if the validation of this instance generated an error caused by the
provided node. getValidationError(NdInstanceElementNode node) and
getValidationError(String nodePath) return the validation error that occurred on
the supplied node. If no error occurred on that node, either method returns null.
getNodeValidationErrors() returns the node-specific validation errors that occurred
on the instance. If no node-specific errors occurred on the instance, this method returns
an empty array. getPathsOfNodesWithValidationErrors() returns an array of
nodePaths for the nodes that currently have validation errors that occurred on the
instance. If no node-specific errors occurred on the instance, this method returns an
empty array. getOtherValidationErrors() returns the validation errors for which
there is no associated node. If no such error occurred, this method returns an empty
array. The clearValidationErrors() method clears the list of editing errors.

Instance Element Node (NdInstanceElementNode)

NdInstanceElementNode is the base interface for all nodes returned by the
getInstanceElementNodes() and getInstanceElementNodesForTOC() methods of the
NdRmaInstance interface. The NdInstanceElementNode interface provides only one
method:

NdRmaInstance getInstance()

The getInstance() method returns the root instance this node belongs to.

Several interfaces which represent nodes extend NdInstanceElementNode. These

interfaces include:
„ NdWhitespaceNode
„ NdStringNode
„ NdErrorNode
„ NdMetaphorNode
„ NdAbstractInstanceNode

The NdWhitespaceNode interface represents a whitespace node and provides the

getWhitespace() method which returns the whitespace character of the node. The
NdStringNode interface represents a string node and provides the getString() method
which returns the String value of the node. The NdErrorNode interface represents an
error node and provides the getError() method which returns the NdError for the
node. The NdMetaphorNode interface wraps the information needed to display one of the
metaphors (decision table, decision tree, or score model). The NdAbstractInstanceNode
interface represents a generic instance node which could be a single instance node or a
list node.

74 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The NdAbstractInstanceNode interface represents a generic instance node which could

be a single instance node or a list node. Several interfaces which represent nodes extend
NdAbstractInstanceNode. These interfaces are:
„ NdInstantiationNode
„ NdInstanceNode
„ NdTableRowNode
„ NdAbstractInstanceListNode
„ NdInstanceListNode
„ NdTableNode

The NdInstantiationNode interface represents an instantiation node. NdInstanceNode

represents a generic instance node which could be a single instance node or a list node.
NdTableRowNode represents a row in the table. NdAbstractInstanceListNode represents
an instance list node, as opposed to a single instance node. The NdInstanceListNode
and NdTableNode interfaces extend NdAbstractInstanceListNode.
NdInstanceListNode defines the instance list node interface and NdTableNode
represents an instance list node that would be displayed in a table. For details on these
interfaces refer to the Blaze Advisor API Reference.

Versioning
The RMA Service API supports versioning of repository entries through two interfaces,
NdRmaEntryVersioningOperations and NdRmaEntryVersioningInfo.

The NdRmaEntry interface provides the getVersioningOperations() method for

obtaining NdRmaEntryVersioningOperations for the entry. The method returns null if
the repository does not support versioning or if the entry cannot be versioned. In the
current release, only instances (NdRmaInstance) support all versioning operations.
Projects (NdRmaProject) support some versioning operations, but not the getVersion(),
promote(), and restore() methods. Versioning is not supported by subprojects.

The getVersioningInfo() method of NdRmaEntry obtains versioning information

(NdRmaEntryVersioningInfo) which is provided for all entries in a versioned
repository. The method returns null if the repository does not support versioning.

Versioning Operations
(NdRmaEntryVersioningOperations)
The NdRmaEntryVersioningOperations interface declares the following methods:

void update()
void checkOut()
void cancelCheckOut()
void checkIn(String comment)
NdRmaEntry getVersion(String versionId)
void promote()
void restore()

The update() method updates the entry by fetching the latest version from the
versioning system. checkOut() checks out the entry from the versioning system.

Fair Isaac Corporation Confidential and Proprietary Information 75

CHAPTER 5: RMA Service and Session APIs

cancelCheckOut() cancels a previous check out from the versioning system. checkIn()
checks the entry into the versioning system with the supplied comment. getVersion()
returns a version of the entry that corresponds to the supplied version ID. promote()
promotes the entry in the versioning system so that it becomes the top version.
restore() restores the entry that was previously deleted.

Versioning Information (NdRmaEntryVersioningInfo)

The NdRmaEntryVersioningInfo interface provides methods which return instances of
classes and interfaces in the com.blazesoft.repository.base package that provide
versioning information.

NdRepositoryVersionHistory[] getVersioningHistory()
NdRepositoryEntryLockInfo getVersioningLockInfo()
NdRepositoryVersionResultSet getVersioningStatusInfo()

The getVersionHistory() method returns an array of NdRepositoryVersionHistory

which represents each element in the repository entry’s versioning history. This class
contains methods for obtaining the version ID, user ID, timestamp, comment, location
and deletion status.

The getVersioningLockInfo() method returns NdRepositoryEntryLockInfo which

provides current lock information on the versioned entry. This interface has methods
for obtaining and setting the status of the lock (not locked, locked by user, locked by
user in another workspace, locked by another user), the user ID of the owner of the lock,
the date of the lock, and the location of the entry.

The getVersioningStatusInfo() returns an NdRepositoryVersionResultSet which

defines the result set returned by the invocation of methods in the repository version
manager interface. For further information, consult the Blaze Advisor API Reference
entry for NdRepositoryVersionResultSet.

The versioning status and lock information for all entries in a directory can be obtained
quite efficiently using the getVersioningInfos() method of the NdRmaDirectory
interface which returns an instance of NdRmaDirectoryVersioningInfos. Versioning
operations are not available for the directory itself in the current release. A list of
directories in a project can be obtained by calling NdRmaProject.getDirectories(). See
“RMA Project (NdRmaProject)” on page 60.

The NdRmaDirectoryVersioningInfos interface contains these methods:

NdRepositoryEntryLockInfo[] getVersioningLockInfos()
NdRepositoryVersionResultSet[] getVersioningStatusInfos()

The getVersioningLockInfos() method returns the versioning lock information for all
the entries in this directory. getVersioningStatusInfos() returns an array of
NdRepositoryVersionResultSet which defines the result set returned by the invocation
of methods in the repository version manager interface.

76 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

RMA Queries
The RMA Service API supports the execution of existing queries at the project level.
Query results are returned as an array of NdRmaQueryResultItem. Query results can be
instances as well as the contents of instances.

Query instances are obtained through the getAllQueryInstances() method of

NdRmaProject (“RMA Project (NdRmaProject)” on page 60). The method returns all the
Query instances that can be found in the project.

NdRmaQueryInstance[] getAllQueryInstances(boolean includeSystemDirectories)

Query Instance (NdRmaQueryInstance)

The NdRmaQueryInstance interface extends NdRmaInstance, so that it can be displayed,
edited, and versioned just like any other instance. The interface supplies methods used
to run the query and gets its results:

void executeQuery()
void executeQueryAsynchronously()
void executeQueryForTOC()
void executeQueryAsynchronouslyForTOC()
int getQueryExecutionStatus()
boolean hasQueryResults()
NdRmaQueryResultItem[] getQueryResults()
void stopQueryExecution()

The executeQuery() and executeQueryForTOC() methods execute the query. The later
method accumulates only the results that are relevant for a table of contents. Both
methods execute the query synchronously. This means that the thread in which the
method is invoked waits until execution is complete. The corresponding
executeQueryAsynchronously() and executeQueryAsynchronouslyForTOC() methods
execute the query asynchonously. This means that the thread in which this method is
invoked will not wait until its execution is completed, but the query status will be
updated as the execution progresses. An entry exclusion filter can be set on the project
to filter query results. The getQueryExecutionStatus() method returns the status of the
query execution. The status can be one of: EXEC_STATUS_NOT_STARTED,
EXEC_STATUS_COMPLETE, EXEC_STATUS_EXECUTING, EXEC_STATUS_CANCELLED, or
EXEC_STATUS_ABORTED. The hasQueryResults() method returns true if the execution of
the query delivered results. getQueryResults() returns the results of the query
execution as an array of NdRmaQueryResultItem. The stopQueryExecution() method
stops the execution of this query. This is only applicable to asynchronously executed
queries.

Errors that may occur when executing queries may be obtained with the following
methods:

boolean hasQueryExecutionErrors()
NdRMAException[] getQueryExecutionErrors()
void clearQueryExecutionErrors()

Fair Isaac Corporation Confidential and Proprietary Information 77

CHAPTER 5: RMA Service and Session APIs

The hasQueryExecutionErrors() method returns true if any error occurred while

trying to execute the query. getQueryExecutionErrors() returns the errors that
occurred during the execution of the query. If no error occurred, an empty array will be
returned. The clearQueryExecutionErrors() method clears the errors that may have
occurred during the execution of the query.

These methods identify which special subtype of Query instance this Query instance is:

boolean isComparisonQueryInstance()
boolean isSearchQueryInstance()
boolean isVerificationQueryInstance()

The isComparisonQueryInstance() method returns true if this instance is an instance

of Comparison Query. isSearchQueryInstance() returns true if this instance is an
instance of Search Query. The isVerificationQueryInstance() method returns true if
this instance is an instance of Verification Query.

This method indicates if the Query instance is a “transient” Query instance:

boolean isTransient()

A Transient Query instance is created using

NdRmaQueryTemplate.generateTransientQueryInstance(). It serves as a lightweight,
on-the-fly, use-and-lose query tool. A Transient Query instance cannot be saved.
Attempting to use the NdRmaEntry methods save(), getLocation(), getDisplayPath(),
or getParentDirectory() will result in an Exception. Transient Query instances are
excluded from results returned by NdRmaDirectory.getEntries(), but are included
with the results returned by the NdRmaProject getXXX() query-related methods.

This method allows the transient Query instance to be deleted. It cannot be deleted in
the way a regular instance can be because that requires knowing the parent directory:

void deleteTransientQueryInstance()

The deleteTransientQueryInstance() method deletes a “transient” Query instance.

Internally it obtains the parent directory and deletes it from there in the usual fashion.
Of course, once this method has been used, this transient Query instance becomes
invalid and can no longer be used.

Query Results (NdRmaQueryResultItem)

The NdRmaQueryResultItem interface, used for returning query results, is a tag interface
that is extended by NdRmaInstance. This means that query results will consist of
instances, including query instances, as well as instance contents.

Filtering Entries in an RMA Project

The RMA Entry Filter Manager provides the ability to apply filtering to the current
RMA Project. The NdRmaEntryFilterManager interface includes methods for working
with both exclusion filters and inclusion filters. As the names imply, an exclusion filter
will leave the item in question unfiltered if it does not match the condition for exclusion.

78 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

An inclusion filter will leave the item in question unfiltered if it does match the
condition for inclusion.

A second type of inclusion filter exists for RMA projects. From the Blaze Advisor IDE, a
filter can be applied to the PROM Project. That filter exists as a PROM project property.
When an RMA project object is created, the RMA Entry Filter Manager is created and
automatically applies the existing PROM project inclusion filter (if any). This filter
cannot be set or removed by using the RMA Service APIs. When filtering has been
applied, items that have been created new or have been modified will not be excluded
due to the filtering.

RMA Entry Filter Manager (NdRmaEntryFilterManager)

An instance of NdRmaEntryFilterManager is obtained for the project by calling
getEntryFitlerManager() method of NdRmaProject.

The RMA Filter Manager declares the following methods:

void setEntryExclusionFilter(NdRmaEntryExclusionFilter rmaEntryExclusionFilter)

NdRmaEntryExclusionFilter getEntryExclusionFilter()
void setSecondaryEntryExclusionFilter(NdRmaEntryExclusionFilter secondaryRmaEntryExclusionFilter)
void setEntryInclusionFilter(String filterAbsoluteLocationAsString)
NdRmaEntry getEntryInclusionFilter()
boolean isAnyFilterApplied()
boolean isAnyInclusionFilterApplied()

The setEntryExclusionFilter() sets the given NdRmaEntryExclusionFilter as the

current RMA Project exclusion filter. Passing null to setEntryExclusionFilter() will
remove the filter. Use the getEntryExclusionFilter() method to obtain the current
RMA Project exclusion filter. The return value is null if none currently set.

Use setSecondaryEntryExclusionFilter() to apply a second, additional RMA entry

exclusion filter to the RMA project. This is intended to be used for temporary additional
filtering. If no filter was previously applied using the setEntryExclusionFilter()
method then this will be the only filter. Passing null to
setSecondaryEntryExclusionFilter() will remove the secondary filter, leaving the
exclusion filter previously set using setEntryExclusionFilter(), if any, untouched.

The setEntryInclusionFilter(String filterAbsoluteLocationAsString) method

sets an RMA entry inclusion filter on the RMA project. The parameter is the absolute
location (full pathname) of the entry inclusion filter. An inclusion filter is implemented
as a type of Query instance that must have already been instantiated in Builder or the
RMA. The getEntryInclusionFilter() method returns the current RMA Project’s
inclusion filter as an NdRmaEntry or null if none has been set. The NdRmaEntry object
allows information about the inclusion filter, such as its location or display name or
display path, to be easily obtained.

The isAnyFilterApplied() method returns true if any inclusion or exclusion filter is

currently applied to the RMA Project. isAnyInclusionFilterApplied() returns true if
any inclusion filter is currently applied to the RMA Project. The method will return

Fair Isaac Corporation Confidential and Proprietary Information 79

CHAPTER 5: RMA Service and Session APIs

true even when there is only an automatically applied, IDE-set, PROM project inclusion
filter.

Entry Exclusion Filter (NdRmaEntryExclusionFilter)

The NdRmaEntryExclusionFilter interface is used in filtering the set of items that are
returned by a number of methods in the RMA API. The filtering is performed by your
own custom exclusion filter class, which must implement NdRmaEntryExclusionFilter.
You can use an exclusion filter to filter the results obtained from the
getAllTemplates(), getAllInstances(), getAllQueryTemplates(),
getAllQueryInstances(), getAllDirectories(), and getDirectories() methods in
the NdRmaProject interface; as well as the getEntries() method in the NdRmaDirectory
interface; and the executeQuery() and executeQueryForTOC() methods in the
NdRmaQueryInstance interface.

The NdRmaEntryExclusionFilter interface contains two methods.

boolean isEntryToBeExcluded(NdRmaEntry entry)

boolean isExcludedDirectoryToBeBrowsed(NdRmaDirectory directory)

The isEntryToBeExcluded() method returns true if the supplied entry is to be excluded

from the results of methods navigating the project.
isExcludedDirectoryToBeBrowsed() returns true if the supplied directory, which is to
be excluded from the results of methods navigating the project, should itself be browsed
in case its entries are not to be excluded.

Here is an example of a simple implementation of NdRmaEntryExclusionFilter that

filters out entries whose path is in a list of paths to exclude:

public class RmaEntryExcludedPathsFilter implements NdRmaEntryExclusionFilter

{
private Vector _excludedPaths;

public RmaEntryExcludedPathsFilter(Vector excludedPaths)

{
_excludedPaths = excludedPaths;
}
public boolean isEntryToBeExcluded(NdRmaEntry rmaEntry)
{
NdLocation entryLocation = rmaEntry.getLocation();
entryLocation = rmaEntry.getLocation();
if (entryLocation == null) {
return false;
}
String path = entryLocation.toString();
for (int i = 0; i < _excludedPaths.size(); i++) {
String excludedPath = (String) _excludedPaths.elementAt(i);
// If the path equals an excludedPath or starts with an exludedPath + "/"
// then it is either exactly an excluded path, or it is a subdirectory of
// one and thus it should be excluded.
if (path.equals(excludedPath) || (path.startsWith(excludedPath + "/"))) {
return true;
}
}
return false;
}

80 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

public boolean isExcludedDirectoryToBeBrowsed(NdRmaDirectory directory)

{
// If a directory is to be excluded then so should its contents.
return false;
}
}

Only one custom exclusion filter may be set on a project at a time. Use the
setEntryExclusionFilter(RmaEntryExcludedPathsFilter filter) method of
NdRmaEntryFilterManager to set the filter. One may, of course, switch to another filter
by calling the method again. Pass null to the method to indicate that no filtering should
be performed. Obtain an instance of NdRmaEntryFilterManager with the
getEntryFilterManager() method of NdRmaProject. Use the
getEntryExclusionFilter() method of NdRmaEntryFilterManager to obtain the
current NdRmaEntryExclusionFilter. See “RMA Entry Filter Manager
(NdRmaEntryFilterManager)” on page 79.

The sample client code below passes a Vector of excluded paths to the constructor of
the filter class. It sets the project filter by passing the filter to
setEntryExclusionFilter(). The call to getAllQueryInstances() returns all query
instances available to the project, except those in the /Business Library/Asia and
/Business Library/Europe directories and their subdirectories.

// rmaProject is an NdRmaProject
Vector excludedPaths = new Vector();
excludedPaths.addElement("/Business Library/Asia");
excludedPaths.addElement("/Business Library/Europe");
RmaEntryExcludedPathsFilter myFilter = new RmaEntryExcludedPathsFilter(excludedPaths);
NdRmaEntryFilterManager filterManager = rmaProject.getEntryFilterManager();
filterManager.setEntryExclusionFilter(myFilter);
NdRmaQueryInstance[] queries = rmaProject.getAllQueryInstances(true);

RMA Session API

A Rule Maintenance Application is designed to enable a user to create and modify
instance files. The RMA Service API is designed to accommodate those RMA needs by
providing functionality which interacts with the ROM and PROM APIs and results in
changes to the project which are persisted in the repository. The purpose of the RMA
Session API is to supplement the RMA Service API by providing a state-holding
interface while still not being tied to any one client technology or execution
environment. Note that the term “session” used in the name of this API refers to a “user
session” implying “this application as used by one user”, as opposed to a web session.

During a user's application session, there are two types of information which are
needed and/or modified by both the application layer (the RMA Service API), and the
presentation medium (the application's user interface). Some of that information is
static for the duration of the session, such as the current project; and some of it changes
frequently with each change to the user interface view. The RMA Session API supports
both types of information and is an interface between the application and presentation
levels.

Fair Isaac Corporation Confidential and Proprietary Information 81

CHAPTER 5: RMA Service and Session APIs

The RMA Session API defines the methods for keeping necessary state information in a
Java class. The Java class can then be kept in a web session variable for web clients, or
used directly by a fat client. Having all the state information gathered, organized, and
supported by this API enables all the items required to maintain state to be held in a
single NdRmaSession session object (see “RMA Session (NdRmaSession)” on page 82).

When a state-inducing action is performed on behalf of an RMA user, the RMA Session
API can enable the retention and use of that state information for the life of the user's
session. Additionally, the API provides a facility for client RMA applications to supply
a set of properties, defined by the RMA developer, which can be saved as part of the
session state information (see “RMA Session Properties (NdRmaSessionProperties)” on
page 84). Also, to enable recovery from application errors, there are commands for
capturing a backup of the state information so that, if needed, another provided
command can restore the session state to its last-cached configuration.

An application commonly has a consistent framework for maintaining application

presentation, composed of one or parts that are the main “working“ area. A typical
framework could consist of a title or banner area at the top, followed by a toolbar of
global commands common to the application at any time such as “Help,“ “Sign In,“
“Sign Out, “ and a main area that is sensitive to and displays the application's current
context. We call this dynamic area a “View.“ An RMA View is represented by the
NdRmaView interface (see “RMA View (NdRmaView)” on page 84).

Often, there is a need to display only one View area, such as when a list of the project’s
files and directories is being displayed. At other times the user may choose to have
more than one View open simultaneously, such as when editing an instance in one
View and comparing it to a version of that instance in a second View.

Different Views have different requirements. Sometimes a View will be a single pane
such as when a sign-in or login page is displayed. Other times a View is more complex,
such as the View of an Instance editor. That View can even have other sub-areas that are
dependent upon the state of the main area such as a “Table of Contents,” a context-
sensitive command bar, or a navigation mechanism that reflects the item in the View’s
location. The actual design and needs of an application’s Views will vary from one
RMA design implementation to the next.

RMA Session (NdRmaSession)

The RMA Session (NdRmaSession) contains only methods that support the state
maintenance needs which are common to every RMA application, while recognizing
that not all RMA applications will have the same needs. To accomplish these disparate
goals, the RMA Session provides methods that set or access objects of known and
expected types.

Where the state information may be specific to a custom RMA, the design may be
organized into a class where the class name is pre-defined (NdRmaSessionProperties),
but the definition of the class is decided by the developer of the RMA. See “RMA
Session Properties (NdRmaSessionProperties)” on page 84.

82 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

The NdRmaSession interface defines methods for accessing the session properties object
defined by the RMA developer. Other methods are provided to open a View or an
array of views, close a single View or close all open Views, and to retrieve a particular
open View or an array of all open Views, etc.

“Opening a View” is simply the act of handing the View object, which was
independently created in other server-side code, to the RMA Session API so that it can
keep it as state information.

To assist in error recovery, the RMA Session API provides the captureRecoveryState()
method to take a snapshot of the NdRmaSession object, and the
restoreRecoveryState() method to replace the current state with the most recently
captured state.

The NdRmaSession interface defines these methods:

void setRepository(NdRmaRepository rmaRepository)

void setProject(NdRmaProject rmaProject)
NdRmaSessionProperties getSessionProperties()
void openView(NdRmaView view)
void openViews(NdRmaView[] views)
boolean hasAnyView()
NdRmaView getView(String viewId)
NdRmaView[] getAllViews()
void closeView(String viewId)
void closeAllViews(String viewId)
void closeAllViews()
void captureRecoveryState()
void restoreRecoveryState()
NdRmaSession cloneSession()

The setRepository() method saves the provided RMA repository entry as the
repository for the session. setProject() saves the provided RMA project entry as the
project for the session. getSessionProperties() retrieves the client-defined
NdRmaSessionProperties object. openView() saves the provided, client-obtained view
(NdRmaView) object, thus establishing an open view in this session state object. If an open
view with the same viewId value as this view exists, it is replaced with this view object.
The relative order of the open views is maintained. openViews() saves the supplied
array of client-obtained view (NdRmaView) objects thus establishing them as open views
in this session state object. If an existing open view with the same viewId value as one
of these views in the provided array already exists, it is replaced with the new view
object. Note that the relative order of open views is maintained. hasAnyView() returns
true if any view is currently open for this session. The getView() method retrieves the
view object identified by the given viewId.

getAllViews() retrieves an array of all currently opened view objects within this
session. The relative order of open views is maintained. That is, if View ʺaʺ is opened,
and then View ʺbʺ and View ʺcʺ are opened, then the array returned is: views[0] ==
View ʺaʺ, views[1] == View ʺbʺ, and views[2] == View ʺcʺ. If View ʺbʺ is closed, then
the array returned is: views[0] == View ʺaʺ and views[1] == View ʺcʺ.

Fair Isaac Corporation Confidential and Proprietary Information 83

CHAPTER 5: RMA Service and Session APIs

The closeView() method closes the view identified by the given viewId. If the view is a
child view then the child is closed and the child's parent will, once again, be open and
own the same viewId. closeAllViews() closes all currently opened view objects
identified by the given viewId. That is, a family of views will be closed if the viewId
points to either a parent or a child. closeAllViews() closes all currently opened view
objects within this session. captureRecoveryState() saves the current state of this
session. This method is called by clients of the RMA Session API in order to preserve
the current state. A client might use this method prior to handling any new requested
action caused by an RMA user so that if the action caused an error, then the error page
could offer a recovery (“back”) link to a state that did not cause an exception.
restoreRecoveryState() replaces all current state with the state that was most-recently
saved. The cloneSession() method returns a new NdRmaSession with all session-level
objects and properties copied from this session to the new session object. No view-level
information is copied to the new session.

RMA Session Properties (NdRmaSessionProperties)

Different RMAs will have different needs depending on varied factors, such as what
platform the RMA is targeting, or what features the user interface will support, etc. The
RMA Session APIs can not anticipate those needs, and will not directly support any
feature targeted to a particular deployment. However, the need does exist for those
properties to become part of the session state so that they can be accessed on both the
server and client sides.

To accommodate this need, an instance of the NdRmaSessionProperties object is created

and cached by NdRmaSession’s constructor. A method to access the session properties
object is provided in the NdRMASession (see “RMA Session (NdRmaSession)” on page
82). These methods simply allow the properties to be saved along with the other
current stateful information and will never be accessed by the RMA Session API.

RMA View (NdRmaView)

An RMA application typically has a framework that remains relatively unchanged
throughout the session. In addition to that framework there are commonly one or more
areas of the application which are the main presentation panes. These main areas are
termed Views.

The RMA Service API defines the NdRmaEntry interface, which represents the main
“visual” component, if you will, of an RMA such as a project, a directory, or an instance.
An RMA View (NdRmaView) presents one of those NdRmaEntry objects as a View in the
RMA. There can be more than one representation of NdRmaEntry object in the same
RMA. For example, one View of an instance could be represented as the instance being
edited. Another View of that same object might be represented as the instance being
saved as a new instance in the “Save As" pane, or as the object whose version history is
being displayed in the “History" pane.

A View may not be representing object at all, such as when the “Sign In” dialog, which
gathers user information prior to establishing a repository connection, is being
displayed. That is still a View.

84 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

A View can represent just a single pane, or page, such as a web page; and it can
represent an NdRmaEntry object where that object is being presented in a particular
context such as in its editor or in its History viewer. The RMA Session API’s NdRmaView
interface names these parts of the View. String viewerName is the name of the viewer
for this View. It names the means by which the View is rendered. In web enviroment
that is the web page name. NdRmaEntry viewEntry is the NdRmaEntry object that is the
subject of the View (it may be null).

Note that an NdRmaEntry object can access both the project and the repository objects.
That is useful because at any time, while a View is open, those objects are available to
display information about themselves. When a View does not have a viewEntry there is
also no project or repository available such as when the View is of the “Sign In” page.

To accommodate customizations and design-specific state information, the RMA View

has a properties object associated with it. The definition of that object is up to the RMA
developer. See “RMA View Properties (NdRmaViewProperties)” on page 87.

The NdRmaView interface provides set and access methods for the NdRmaEntry object in
the view, as well for the name of the viewer/renderer. A refresh method is provided to
refresh the underlying ROM/PROM object that is the represented by the viewEntry. The
refresh applies only to Views holding NdRmaEntry objects (not null). It will update that
object from the repository and additionally, it will refresh any other open View.

Because a user may wish to have multiple Views open simultaneously, the NdRmaView
constructor creates, and caches as part of the View, a string ID that is guaranteed to be
unique throughout the lifetime of the current session. An accessor method provides the
viewId. The value of the viewId is not important to the RMA, it is just a differentiator
and a means to refer to and access a particular View.

There are times when an RMA design may call for creating a View that is a copy of an
existing View, such as the RMA “Split View” command. To support this need,
NdRmaView provides the cloneView() method which returns a new NdRmaEntry object
with identical data except it has its own, unique viewId.

There are times when one may wish to create a View that spawns from, and replaces,
the current View without losing the original View; such as when an instance is being
edited and the user wants to navigate to a sub-instance (rule) where that rule is stored
(versioned) separately from the parent instance. One may wish to close the child View
and be able to view the parent at a later time, in the same state it had been when the
child was first open. To support this, the cloneChildView() method which creates a
clone of the current View, as does the cloneView method with a few exceptions. The
cloned child View uses the same viewId as its parent, it caches the parent view, and the
child does not inherit the parent’s errors. Its Exceptions array is always initially empty.
When a View is created in this manner, the boolean method isChildView() returns
true, otherwise it returns false. The getParentView() method returns the parent View,
or null if isChildView() returns false.

The NdRmaView interface provides state-related methods pertaining to Views of

NdRmaEntry objects. The createView() method of the NdRmaViewFactory class is used to

Fair Isaac Corporation Confidential and Proprietary Information 85

CHAPTER 5: RMA Service and Session APIs

create an NdRmaView instance and the NdRmaView constructor takes an NdRmaSession

object.

The NdRmaView interface defines these methods:

NdRmaSession getSession()
NdRmaViewProperties getViewProperties()
String getViewId()
void setViewEntry(NdRmaEntry viewEntry)
NdRmaEntry getViewEntry()
void setViewNodePath(String viewNodePath)
String getViewNodePath()
void setViewInstanceSectionName(String viewInstanceSectionName)
String getViewInstanceSectionName()
void setViewerName(String viewerName)
String getViewerName()
NdRmaView cloneView()
NdRmaView cloneChildView()
NdRmaView getParentView()
boolean isChildView()
void resetProperties()
void refresh()
void addException(NdRMAException exception)
void addExceptions(NdRMAException[] exception)
boolean hasException()
NdRMAException[] getExceptions()
void clearExceptions()

The getSession() method returns the session object that this View belongs to.
getViewProperties() retrieves the client-defined NdRmaViewProperties object.
getViewId() returns the auto-generated, session-unique identifier assigned to this
NdRmaView object when it was created. setViewEntry() sets the NdRmaEntry object which
this View will be representing (may be null). getViewEntry() returns the NdRmaEntry
object which this View is currently representing. The method returns null if no
viewEntry has been set.

setViewNodePath() sets the path to the current sub-instance node belonging to the
current viewEntry where the sub-instance is not one that is stored-separately. This
value should be set to null when the View is not for a sub-instance. getViewNodePath()
returns the nodePath to the current sub-instance which is not stored-separately. The
nodePath value should be null when the View is not currently of a sub-instance.

setViewNodePath() sets the path to the current sub-instance node belonging to the
current viewEntry where the sub-instance is not one that is stored-separately. This
value should be set to null when the View is not for a sub-instance. getViewNodePath()
returns the nodePath to the current sub-instance which is not stored-separately. The
nodePath value should be null when the View is not currently of a sub-instance.

setViewInstanceSectionName() sets the instance section name for the current sub-
instance node belonging to the current viewEntry where the sub-instance is not one that
is stored-separately. This value must be one of the
NdAbstractInstanceNode.INSTANCE_SECTION_XXX values; or null when the View is not
for a sub-instance. getViewInstanceSectionName() returns the instanceSectionName

86 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

value that was most-recently set using setViewInstanceSectionName(). The

instanceSectionName value should be null when the View is not currently of a sub-
instance. setViewerName() sets the name of the viewer (page name) that will be used to
present this View. getViewerName() returns the name of the viewer (page name) that
will be used to present this View, or its default value, an empty String, if none has been
set. cloneView() returns a clone of the current View, however the viewId of the clone
will be unique. cloneChildView() returns a child clone of the current View. The viewId
of the child clone will be the same as this View’s viewId. The Exceptions array will be
empty. This View will be cached as the parent View of the new child View.
getParentView() returns the NdRmaView object which is the parent View of this View, or
null if this View is not a child View. isChildView() returns true if this View has a
parent View. resetView() resets the values of all the View properties, including the
NdRmaViewProperties properties, to their original, default values. refresh() refreshes
the current project and all open Views from the repository.
addException(NdRMAException exception) adds the given NdRMAException object to
the array of previously saved exception objects (if any).
addExceptions(NdRMAException[] exception) adds the given array of NdRMAException
objects to the array of previously saved exception objects (if any). hasException()
returns true if any NdRMAException objects have been saved (and not cleared) for this
session. getExceptions() returns an array of previously saved NdRMAException objects.
If there is only one Exception, then the array will have only one item. If there are no
Exceptions, then the array will be empty. clearExceptions() clears all previously
saved exception objects.

RMA View Properties (NdRmaViewProperties)

Different Views will have different needs depending on varied factors, such as whether
a particular viewer has any dependent sub-areas or panes, or if a View should be
readonly or not. The RMA View API can not anticipate those needs, and will not
directly support any feature targeted to a particular View’s needs. However, the need
does exist for those properties to become part of the View state so that they can be
accessed on both the server and client sides.

To accommodate this need, an instance of the NdRmaViewProperties object is created

and cached by NdRmaView’s constructor. A method to access the view properties object
is provided in the RMA View API. See “RMA View (NdRmaView)” on page 84.

These methods simply allow the properties to be saved along with the other current
stateful information and will never be accessed by the RMA View API.

Fair Isaac Corporation Confidential and Proprietary Information 87

CHAPTER 5: RMA Service and Session APIs

88 Fair Isaac Corporation Confidential and Proprietary Information

CHAPTER 6

Base Repository and Version Management

APIs

The FICO™ Blaze Advisor® business rules management system base repository and
version management interfaces and APIs support:
„ Implementing a custom repository storage layer that Blaze Advisor can make use.
These interfaces are referred to as the base repository interfaces.
„ Implementing an interface to a third party content management system that
Blaze Advisor can make use of. These interfaces are referred to as the version
management interfaces.

These APIs are used to implement the repository, and are separate from the APIs used
by clients of the repository. They clearly define the semantics of repository and version
management operations so that all implementations behave in the same way.

Storage Layer Interfaces

The base repository package is com.blazesoft.repository.base. The JavaDoc is in the
Innovator section. You can find the JavaDoc by going to Help > API Reference in
Builder. These base repository interfaces are responsible for the storage and retrieval of
information stored in the repository:
„ NdRepositoryEntry
This interface is the base interface from which all other interfaces in the storage
layer are derived.
„ NdRepositoryItem
This interface is used to represent entries in the storage layer that have content (i.e.
are not directories).
„ NdRepositoryDirectory
This interface is used to represent directories within the storage layer.
„ NdRepository
This interface represents the entire repository as it is represented in the storage
layer.

Fair Isaac Corporation Confidential and Proprietary Information 89

CHAPTER 6: Base Repository and Version Management APIs

About the Workspace

The workspace represents the view of and interaction with the physical storage layer
and the version manager, authorization manager and lock managers that have been
configured on the repository.

You should not need to implement the workspace interfaces for a custom repository.
Blaze Advisor includes complete implementations that it uses for these operations.

The workspace layer is responsible for:

„ All interactions with the version manager. This removes the need for
implementations of the storage layer to be aware of the version manager, therefore
simplifying the implementations.
„ All interactions with the authorization and lock managers. This removes the need
for the version manager implementations to be aware of these concepts, therefore
simplifying the implementations.

The workspace interfaces are extensions of the storage layer interfaces that include
versioning operations. They delegate to whatever version manager has been configured
on the repository.

Version Management Client Interfaces

The interface for version management is NdWorkspaceVersionManager, named to
emphasize the fact that this version manager is responsible for interactions between
items that exist physically in the workspace and the versioning system. Most of the
methods return either a boolean value or are declared to be void methods. If an
operation cannot complete successfully, the methods are expected to throw an
NdRepositoryVersionException that can contain an array of
NdRepositoryVersionResultSet objects that summarize the status of the operation for
repository entries that were involved in the operation. Only the location, success status
and command output attributes of these result sets will be inspected by upper layers of
the Advisor code.

It should be noted that the workspace version manager is responsible for the versioning
of repository entries and their associated repository entry attributes, which implies that
the versioning system needs to know how repository entry attributes are represented in
the storage layer. For example, in the file repository that is supplied with Advisor an
entry's attributes are stored in a file that is in the same directory and that has the file
extension .innovator_attbs.
„ NdWorkspaceVersionManager
„ NdWorkspaceVersionManagerListener
Whenever a workspace version manager causes a modification to be made to the
workspace, it is responsible for sending an event to any listeners that have
registered interest in such changes. Typically, the only such listener would be the
workspace itself. This allows implementations of the workspace version manager to

90 Fair Isaac Corporation Confidential and Proprietary Information

 FICO Blaze Advisor
API Developer’s Guide

inform the workspace that it needs to synchronize itself with the current state of the
repository as reflected in the storage layer.
„ NdWorkspaceVersionManagerEvent
This event is sent whenever the workspace version manager causes a change to be
made to the representation of a repository entry in the storage layer. The event
object contains two items of information:
„ The location of the repository entry that was affected.
„ An integer code indicating if the repository entry was modified, added to or
removed from the storage layer.

Version Management System Interfaces

These interfaces are used for access to the versioning system outside the context of a
workspace. The primary use is to provide a mechanism, via the
NdVersioningSystemVersionManager interface, for browsing through the contents of
the versioning system. The implementation of this interface is free to determine how
much of the versioning system should be revealed to the client of the interface. The
main use that will be made of this interface in Advisor will be to allow the browsing of
items that have been deleted in the versioning system such that they no longer appear
in the workspace whenever a repository is checked out.
„ NdVersioningSystemVersionManager
The implementation class for this interface will be a configurable item within the
version manager configuration, which specifies both the workspace and system
version managers. The interface contains the following methods:
„ NdRepositoryEntryFactory
This interface is used to create repository entries that are returned from the
repository system version manager. This interface is implemented by the
workspace layer and passed to the repository system version manager. The
workspace implementation will create workspace entries which, since they do not
correspond to entries in the physical storage layer, will all be virtual entries, i.e.
their isVirtual method will return a true value.

Administration Interfaces
There are two administration interfaces, one associated with the storage layer and the
other associated with the versioning system. They are separated out from the other
interfaces so as not to confuse the roles of software that accesses the storage layer or
versioning system from the workspace layer versus software that needs to perform
administrative functions on a workspace.
„ NdRepositoryAdmin
„ NdRepositoryVersionSystemAdmin

Fair Isaac Corporation Confidential and Proprietary Information 91

CHAPTER 6: Base Repository and Version Management APIs

Repository Connections
Connections are made to a repository via an NdRepositoryConnection instance. During
the process of establishing a connection to a repository, the repository configuration
will be loaded from persistent storage in the repository, and will be used to configure
the repository and any versioning system.

Repository Configurations
Repository configurations are serialized into an XML document that is stored at a well-
known location within the repository. Instances of the repository configuration class are
created from the contents of this XML document via the Blaze dynamic object model.
For example, the portion of the repository configuration that specifies the repository
connection will appear as follows:

<RepositoryConfig>
…
<RepositoryConnection>
<Factory>com.blazesoft.repository.file.NdFileRepositoryConnection</Factory>
<RepositoryName>MyRep</RepositoryName>
<RepositoryFolder>c:\xyz\MyRep</RepositoryFolder>
…
</RepositoryConnection>
…
</RepositoryConfig>

Repository Entry Filters

Repository entry filters are instances of NdRepositoryEntryFilter. They filter the entries
within a directory to remove any administrative files that the versioning system may
have placed there, and which are not logically part of the repository content. The
workspace uses these filters to remove entries from the storage layer before presenting
the entries to the ROM layer.

92 Fair Isaac Corporation Confidential and Proprietary Information

Index

B score model 37
Entity Object Model 12
BOM 27 entry exclusion filter 80
BOM Admin APIs
manipulating imported external
classes 27 I
BOM manipulation APIs 27 imported external classes
manipulating
C programmatically 27
connecting to repository 7
ConstantDisplayValuesProvider 51,
L
56 loading a PROM project 18
content-based API 12
create M
custom provider 47
decision table 32 Metaphor APIs
creating a model 31
decision tree 34
enumeration 24 loading an instance 31
Metaphor Model 31
NdLocation 8 N
NdPromItem 9 NdConstrainedListProvider 45
NdRomDirectory 16 NdContrainedListProvider 49
PROM project 17 NdDecTableModelFactory 32
question set 22 NdDecTreeModelFactory 32
ruleflow 22 NdDecTreeNodeRenderingInfo 36
score model 37 NdDecTreePath 34
SRL class 23 NdDefaultConstrainedListProvider
SRL function 21 46
SRL ruleset 18 NdDefaultTemplateValueProvider
custom provider 45
caching 57 NdDesignProvider 46
creating 47 NdDesignProviderMultiArg 53
implementation guidelines 56 NdDesignProviderSelectableArg 52
NdDesignProviderTypedArg 53
D NdLocation 8
NdMetaphorModelException 32
decision tables NdPromEntity 11
editing 32 NdPromInstance 12
decision trees NdPromItemContent 11
editing 36 NdPromProject 9, 57
DisplayValuesProvider 49, 55 NdPromProvider 12
NdPromSrlRuleContent 13
E NdPromSrlRuleset 13
edit NdPromTemplate 12
decision table 32 NdPromTextContent 12
decision tree 34 NdProviderStaticArg 54

Fair Isaac Corporation Confidential and Proprietary Information 93

Index

NdProvidesDefaultValue 47
NdRmaEntryExclusionFilter 80
NdRmaQueryInstance 77
NdRmaQueryResultItem 78
NdRomConnectionContext 8
NdRomConnectionManager 7
NdRomSchemaManager 9
NdScoreModelModelFactory 32
NdTemplateValueProvider 44

P
performance
custom providers 56
Project Repository Object Model
(PROM) 9
PROM item content 11
PROM task
create enumeration 24
create question set 22
create ruleflow 22
create SRL class 23
create SRL function 21
create SRL ruleset 18
creating a PROM Project 17
loading a PROM project 18
release project resources 18

Q
Question Set Object Model 15

R
release PROM project resources 18
repository item
find location 8
typing attributes 8
Repository Object Model (ROM) 7
RMA query 77
Ruleflow Object Model 15

S
score models
editing with API 37
SRL Entity Object Model 14
string-based API 12

T
typing attributes of repository item 8

U
UserDefinedDisplayValuesProvider 53

94 Fair Isaac Corporation Confidential and Proprietary Information