Chapter 3   Repository


This chapter describes the UIF Repository and the UIF Repository Browser. For a description of the repository schematics and abstractions, refer to the Chapter 1 "Concepts". For a detailed description on the EIS specific content, see your specific iPlanet Enterprise Connector Developer's and Administrator's Guides.

This chapter contains the following sections:

• UIF Repository

• About the UIF Repository Browser

• Using the UIF Repository Browser

• Troubleshooting Tips

UIF Repository

---

UIF stores information in the repository which defines the EIS business functions available to an iPlanet Application Server Servlet, JSP, or EJB. Repository data includes metadata definitions that are one of two types, as follows:

• Connector Types (adapterTypes) - Defines the enterprise connector specific characteristics including supported function object types and logical connection types (service provider types). This forms the basis for defining the datasources of this connector type.

• Datasources - Defines a logical datasource and represents a specific EIS instance (system). A datasource definition specifies the business functions available on a specific EIS. The datasource defines the actual functions available (function objects), the supported connections (service providers), and other information.

Connector Types

The connector type (adapterTypes) definitions correspond to each installed enterprise connector on an iPlanet Application Server. They form the basis of a datasource definition in the repository. A connector type contains one or more function object types, a service provider type, and configuration information. A type definition is created when the enterprise connector is installed. Figure 3-1 shows a typical R/3 (R3) connector type.

Figure 3-1    Connector Types

Datasources

A datasource represents a single EIS instance and defines the business functions available for execution. For example, an organization might have two systems or subsystems, one for personnel (human resources) and one for accounting. You can choose to represent each as a different datasource even if both run on the same connector type.

An application developer writing a J2EE (Servlet, JSP, or EJB) component uses the datasource definition in the respository to determine the function objects and service provider available on a particular datasource system. Figure 3-2 shows a datasource's basic components.

Figure 3-2    Datasource Components

A datasource consists of the datasource configuration information, data type definitions, service provider definitions, function object definitions, pool definitions, and user mapping information. The following sections describe these components in more detail.

Datasource Configuration Information

The datasource configuration information is the EIS specific configuration settings which the enterprise connector interprets and uses to control its interaction with a specific EIS. In addition, each datasource specifies the character set and passes the data back and forth through the enterprise connector. For a detailed description of the default character set, available EIS character sets and how to specify them, see your specific iPlanet Enterprise Connector Developer's and Administrator's Guides.

The values of the datasource configuration settings control the enterprise connector's interaction with the EIS instance corresponding to this datasource.

Data Type Definitions

Data type definitions are used by the metadata service to instantiate data objects. All information between the application and the enterprise connector is passed using data objects. The definitions represent structured EIS data types and are mined from the EIS metadata. Each specific EIS may have its own set of data types, which is why they are associated with the datasource and not the connector type. Data types may represent parameter blocks, messages, events, etc. - depending on the specific EIS. The enterprise connector is responsible for marshalling and unmarshalling data objects, to and from the specific EIS formats.

Service Provider Definitions

A service provider represents a connection to an EIS system. It contains configuration information required to create a connection. For example, it may define host, port, username, and password. A service provider type may also specify additional information required to open or manage a connection.

The definition includes default EIS specific configuration settings, whether the connection is pooled or not, which pool is assigned, duration of the service provider connection binding, binding timeouts, and thread handoff settings. Figure 3-3 shows a typical service provider connection for R/3.

Figure 3-3    Service Provider Connections

Function Object Definitions

Function objects provide logical definitions of business functions available on the EIS datasource. A specific business function object represents a specific EIS type, for example:

• BAPI - R/3

• RFC - R/3

• psft message - PeopleSoft

• CICS txn - CICS

• and so on, depending on the specific EIS

Each EIS may have its own set of business functions which is why they are associated with the datasource and not the connector type.

Function object creation in the repository uses an EIS specific data mining tool supplied with each enterprise connector. Figure 3-4 shows a typical function object.

Figure 3-4    Function Object

Operations
A function object itself exposes one or more named operations. For example, a message function object may expose three operations - SEND, POLL, RECEIVE. However, most systems only need one operation (default). Each operation has an associated propertySet and dataBlock.

Property Sets
A property set is a data object used to target a specific EIS business function and describe the various operational parameters. For example a property set may specify: BAPI name, peopleSoft message identifier, program name, queue name, EIS host/port/URL, etc. The enterprise connector uses the property set contents to identify a specific EIS business function.

Data Blocks
A data block is a data object used to encapsulate all inputs and outputs between the application and the EIS. This object can have a default or initial value(s). The enterprise connector is responsible for marshalling and unmarshalling data blocks, to and from specific EIS formats. Therefore, a function object targeting a specific business method has its own specific associated data block type.

A data block describes each business logic program's input and output parameters. In UIF, each data block has two child nodes - input and output.

Function Object Template
A function object template is a function object instance. A function object template contains a data block definition and a property set whose values define access to a specific EIS transaction. A data block represents the operation's parameter block and holds the input and output information for the operation's execution.

dosearch - is a named function object, representing a specific EIS business function which accepts an account number as input and returns activity details as output. The application points to the named function object and creates a runtime function object instance. When the execute method is called on this object, the enterprise connector executes the EIS business function.

Pool Definitions

Pool definitions are service provider pools and their controlling attributes. A datasource may define several connection pools, though usually, there is only a single pool. Each service provider defines which pool it uses. Each pool is controlled by a pool configuration block, which contains the following:

• DebugLevel

• MaxPoolSize

• MaxWait

• MonitorInterval

• SteadyPoolSize

• UnusedMaxLife

For more information about pooling, see Chapter 4 "Pooling Concepts". Figure 3-5 shows the relationship between a service provider and the pool configuration information.

Figure 3-5    Pool Configuration Information

User Mapping Information

User mapping information are definitions of user mapping tables from a web domain to an EIS domain for specific EISs. The user mapping table content is managed via the management console. Refer to your specific iPlanet Enterprise Connector Administrator's Guide for details.

About the UIF Repository Browser

---

The UIF Repository Browser's main function is to provide a UIF abstraction view of the UIF Repository. In addition, UIF Repository browser provides Import, Export, Delete, Refresh and Import Root functionality on the UIF Repository.

The repository browser is divided into left and right panes. The view hierarchy appears in the left pane and the contents in the right pane. The actual contents depend on which node is selected in the view hierarchy. For the semantic details on the repository content, please refer to your iPlanet Enterprise Connector Administrator's Guide.

Figure 3-6 shows an example of the UIF repository browser.

Figure 3-6    Repository Browser Example

View Hierarchy

Click on the folders in the outline view in the left pane to expand and collapse the repository view. Initially, the hierarchy shows the following information:

• Root node (bsp)

• Connector types (adapterTypes)

• Datasources

Icons in the view hierarchy have different meanings, as follows:

Icon	Description
Double arrow	Reference to another object
Bullet	Leaf node, which cannot be traversed further
Folder	Non leaf node

An X appearing on a node indicates the node either does not exist or is invalid. To fix a node, refer to your specific connector documentation for details.

Each node type is represented by a different color. Primitive non data object image (leaf) nodes are yellow. Colors for the data object nodes are identified in the following section.

Data Object views

The repository browser allows the viewing of data object templates, data object types, and data object image folders in different ways. The node color specifies the view currently being displayed. Nodes are color coded, as follows:

Color	Contains
Red	data object type definition
Blue	data object template
Green	data object image

To switch between views, click the right mouse button on a folder and it changes to the desired view. The views available depend on the kinds of data objects available, as follows:

• A data object template can display type information, data, or an image. The data is the type's default value. The image is a value that overrides the default.

• A data object type can display type information or data. The data is the type's default value.

• A data object image can only display its image, which is its value.

Typically, you view the type definition return values and the data object template for values passed as parameters from a Servlet, JSP, or EJB. Refer to Chapter 5 "Programming Model" for more information on data object images, templates, etc.

Using the UIF Repository Browser

---

The UIF Repository Browser is used to perform the following operations:

• Import a node and its subnodes

• Export a node and its subnodes

• Delete a node and its subnodes

• Refresh the UIF repository browser, so that it reflects changes made to the LDAP storage from the management console

• Import the root node

Import a Node and its Subnodes

A node is imported with its subnodes into the specified repository node. A typical use of this functionality is to import the data source XML prepared on a development machine UIF Repository to a deployment machine UIF Repository.

---

Note	An imported XML file describes a repository node or data object node. An XML file cannot be imported from within a data object node. Please refer to your specific Enterprise Connector Administrator's Guide for the repository.dtd to be used.

---

To import a node:

1. Select a node from the view hierarchy. When Import process is done, all data from the input XML file is added to the node.

2. Click the Import icon in the menu bar.

3. Specify or browse the XML file to be imported.

4. Specify a log file or keep the default.

5. Click OK to start the import.

6. View the log file for messages or errors in the XML file.

Import Notes:

• The XML file imported must exist in the same directory as the repository.dtd file. Otherwise, an error occurs.

• Importing deletes an existing subtree with the same root node as the imported XML file. For example, if bsp.A.B already exists and an XML file with root B is being imported under bsp.A, it first deletes the bsp.A.B subtree and then imports the XML subtree specified in the import file under bsp.A.

Export a Node and its subnodes

A UIF Repository Node and all its subnodes can be exported to an XML file which is often used to export the datasource configurations on the development machine as XML files. The XML files are imported on to the deployment machine, as part of the deployment process.

---

Note	A repository node or data object node may be exported as a whole; but a node within a data object node cannot be exported

---

To export from a node, select from the view hierarchy the node to export.

1. Click the Export icon in the menu bar.

2. Specify a name of the destination XML file.

3. Specify a log file or keep the default.

4. Click OK to start the export operation.

5. View the log file for messages and errors in the XML file.

Delete a Node and its subnodes

Deleting a node also deletes all subnodes underneath it. For example, a node may need to be deleted because it was created in the wrong hierarchy location.

---

Note	A repository node or data object node can be deleted; but a node cannot be deleted from within a data object node.

---

To delete a node:

1. Select from the view hierarchy the node to be deleted.

2. Click the Delete icon in the menu bar.

3. Click Yes when the warning message appears.

4. View the log file for messages and errors.

Refresh the UIF Repository

Refreshing the UIF Repository Browser brings the Repository browser in sync with the LDAP storage. A typical usage of Refresh is after using the Enterprise Connector Management Consoles. Since the Management Console populate the UIF repository directly, the UIF Repository Browser might go out of sync with the UIF Repository.

As mentioned above, the Refresh functionality brings the UIF Repository browser in sync with the UIF Repository. In order for the UIF runtime to make use of the new content in the Repository, the iPlanet Application Server need to be restarted.

Import the Root Node

To import a root node and its subtrees:

1. Click the Import Root icon in the menu bar.

2. Specify or browse for the XML file that defines the subtree.

3. Specify the log file or keep the default.

4. Click OK to start the import.

5. View the log file for any messages or errors in the XML file.

View the Log

Use any ASCII text editor to view the log file. By default, the log file is called bspbrowser.log in the APPS subdiretory where UIF is installed.

Troubleshooting Tips

---

The following errors can occur when importing or exporting XML files:

• If a FileNotFound exception is received make sure the given file location is a valid location.

• If a parsing error is received, it may be that the XML file is not validating against repository.dtd. Examine and correct the XML file.

• If a ClassNotFound error is received, the xml.jar file may not be in the classpath. Although the installation setup handles setting the classpath, modify the classpath if the file's location is not in the classpath.