Simple Tpae IF Connector

Introduction

The Tivoli Process Automation Engine (Tpae), also known as Base Services, is a collection of core Java classes and is used as a base to build Java applications. The Integration Framework, a Tpae feature, contains standard integration objects (Object Structures and interfaces) and outbound/inbound objects. The Simple Tpae IF Connector connects Tivoli® Directory Integrator to the Tpae Integration Framework to exchange information.

The Simple Tpae IF Connector reads from and writes to the Integration Framework. It supports Maximo® Business Object (MBO) and is processed through an integration object. This connector uses the MBO layer for validating imported or exported objects. The Simple Tpae IF Connector can be used in various AssemblyLine modes such as Iterator, AddOnly, Update, Lookup, and Delete.

Tivoli Process Automation Engine

The benefit of using the Tpae architecture is that the core function used in many Java applications does not need to be coded by the applications. Each application depends on base classes to provide core function rather than coding it into each application. The Tpae layer is a middleware and is not directly used as an application by the user. Key functions include:

• Chart of accounts
• Sites
• Organizations
• Reports
• Users
• Security groups
• Workflow
• Administrative applications
• Configuration applications

A few Tpae applications are:

• Maximo Asset Management (MAM)
• Tivoli Service Request Manager (TSRM)
• Tivoli Asset Management for IT (TAMIT)
• Change and Configuration Management Database (CCMDB)

An application, which is built on Tpae, uses the base system security tools for user, role, and group management. Key features of Tpae are:

• Integration Framework, formerly known as Maximo Enterprise Adapter (MEA)
• Custom cron task scheduling and processing
• Custom workflow processing
• Custom email listeners
• Birt J2EE reporting
• Application Server Security Integration (LDAP)
• Dynamic data retrieval

Integration Framework

The Integration Framework (IF) is a set of applications that facilitates integration between the system and framework applications. IF is a part of base Tivoli Process Automation Engine and is available in all major products that use Tpae. For example, MAM, and SRM.

The IF is a part of Tpae. It is an XML-based integration framework and supports both XML and delimited files. IF allows synchronization and integration of data between an external system and applications that use the Tpae common architecture and run under an application server. Using IF, you can exchange data synchronously and asynchronously, using various communication protocols.

IF provides a set of outbound (channels) and inbound (services) integration interfaces. It supports multiple communication methods, such as:

• XML/flat files
• Database interface tables
• XML over HTTP
• Web services
• Java Message Service (JMS) messaging

Figure 1. Tpae Integration Framework

You can use the following IF services to integrate Tpae product and the external systems:

Standard Service

Provides fine-grained, object specific service. For example, asset move, and change status. This service is available only for annotated Java methods. Addition of Standard Service requires code changes.

Object Structure Service

Provides general insert, update, delete, and query capabilities. This service is used when queuing or customization layers are not needed.

Enterprise Service

Provides general insert, update, delete, and query capabilities. This service is used when queuing or customization (Java/XSL) layers are needed.

IF allows data to flow in and out of applications (MAM or CCMDB), and data to flow in and out of external systems. The Simple Tpae IF Connector uses the IF feature to integrate data.

Maximo Business Object

The Maximo Business Object (MBO) defines a set of fields and business rules and updates one or more Maximo database tables. If multiple object structures use the same MBO, each structure definition repeats these details.

The IF uses MBOs to extract data from and load data into underlying tables. The MBO enforces one or more business rules on the data being received. If the rules cannot be applied successfully to the data, the MBO fails to perform the required operation. For example, changing the status of a Purchase Order or inserting a new workflow process. The MBO layer is used when integrating data with Tpae.

MIF Object Structure

The MIF Object Structure (MOS) is made up of one or more subrecords, which make up the content of an integration message sent to or received from an external system. Each subrecord contains fields from the MBO. The MBO and the corresponding subrecord have the same name. A MOS can include any number of subrecords. The Object Structures can be hierarchical, representing a parent-child relationship between pairs of subrecords in the Object Structure. The topmost MBO is called a primary object or root MBO.

Figure 2. The Purchase Order predefined Object Structure

An Object Structure is the common data layer that IF uses for outbound and inbound application data processing. You can use the message content of a single Object Structure to support both inbound and outbound message processing. Standard Service and REST APIs (see Figure 1) do not go through the Object Structure layer.

Using the Connector

The Simple Tpae IF Connector uses XML over HTTP to integrate data with IF. It provides the following two types of integration:

• Using Object Structure Services
• Using Enterprise Services

Using Object Structure Services

The Object Structure Services provide capabilities to perform the following operations over a specified Object Structure:

• Update
• Query
• Create
• Sync
• Delete
• Publish
• Invoke

The Simple Tpae IF Connector supports the operations that are indicated in preceding list. Object Structure Services can be used to create, read, update, or delete operations and are the default behavior of the connector. These services are managed by the Object Structure application. Maximo comes with several predefined Object Structures, for example, MXASSET:

When reading assets, the connector receives a structure, similar to the following XML file, where the relationships are represented as nested elements:

<ASSET>
	<ASSETNUM>7112</ASSETNUM>
	-
	<ASSETMETER>
		<METERNAME>RUNHOURS</METERNAME>
		-
	</ASSETMETER>
	<ASSETMETER>
		<METERNAME>KILOMETERS</METERNAME>
		-
	</ASSETMETER>
	-
</ASSET>

Using Enterprise Services

The Enterprise Service associates an operation and an Object Structure. The Enterprise Service defines the operations that are performed on the specified Object Structure. These operations are requested from Maximo as XML messages over HTTP. The Enterprise Service provides the following functions:

• Queue support
• Processing classes
• User exits
• Rules for skipping
• Customization of the flow

Using Enterprise Services for integration requires configuration of queues and external system information. These services are managed by the Enterprise Services application.

External systems are managed by the External Systems application. An external system identifies a specific external application involved in outbound or inbound data synchronization with Maximo. It defines all the Enterprise services available to the external application. The following figure illustrates the basic concept:

Figure 3. Tpae Enterprise Services example

MBO parameter

The Simple Tpae IF Connector works only with flat entries. An Object Structure is composed of several MBOs arranged in hierarchy. Therefore, the connector can work with only one MBO at a time. In the Configuration Editor, you need to specify the MBO name in the MBO field. If this parameter is not defined, the connector works with the root MBO of the Object Structure. The selected MBO has to be a part of the specified Object Structure.

For example, the predefined Object Structure MXASSET is composed of MBOs such as ASSET, ASSETMETER, ASSETUSERCUST, and ASSETSPEC.

Use the MBO parameter with the following syntax:

<Top-Level MBO>[@<Child MBO Level 1>[@<Child MBO Level 2>[@<Child MBO Level N>]]] 

Example:

The selected MBO is used in all connector modes.

Use the TpaeIFConnector.getMboList() method to retrieve a list of available MBOs in the specified Object Structure. For more information about this method, see the Javadocs.

Connector Modes

The Simple Tpae IF Connector operates in various modes such as Iterator, AddOnly, Update, Lookup, and Delete.

Iterator Mode

In the Iterator mode, the connector sends a Query XML request to the IF server and receives a Query XML response. For example, Maximo returns the following XML as a result of a query operation on the predefined MXASSET Object Structure:

<ASSET>
	<ASSETNUM>7111</ASSETNUM>
	<BUDGETCOST>1000.0</BUDGETCOST>
	<ASSETSPEC>
		<ASSETATTRID>RAMSIZE</ASSETATTRID>
		<MEASUREUNITID>MBYTE</MEASUREUNITID>
		<NUMVALUE>512.0</NUMVALUE>
		-
	</ASSETSPEC>
	<ASSETSPEC>
		<ALNVALUE />
		<ASSETATTRID>DISKSIZE</ASSETATTRID>
		<MEASUREUNITID>GBYTE</MEASUREUNITID>
		<NUMVALUE>100.0</NUMVALUE>
		-
	</ASSETSPEC>
	<ASSETSPEC>
		<ASSETATTRID>PROSPEED</ASSETATTRID>
		<MEASUREUNITID>GHZ</MEASUREUNITID>
		<NUMVALUE>1.5</NUMVALUE>
		-
	</ASSETSPEC>
	-
</ASSET>
<ASSET>
	<ASSETNUM>7115</ASSETNUM>
	<BUDGETCOST>1500.0</BUDGETCOST>
	<ASSETSPEC>
		<ASSETATTRID>RAMSIZE</ASSETATTRID>
		<MEASUREUNITID>MBYTE</MEASUREUNITID>
		<NUMVALUE>2048.0</NUMVALUE>
		-
	</ASSETSPEC>
	<ASSETSPEC>
		<ALNVALUE />
		<ASSETATTRID>DISKSIZE</ASSETATTRID>
		<MEASUREUNITID>GBYTE</MEASUREUNITID>
		<NUMVALUE>250.0</NUMVALUE>
		-
	</ASSETSPEC>
	<ASSETSPEC>
		<ASSETATTRID>PROSPEED</ASSETATTRID>
		<MEASUREUNITID>GHZ</MEASUREUNITID>
		<NUMVALUE>3.2</NUMVALUE>
		-
	</ASSETSPEC>
	-
</ASSET>

The query returns two assets, each with three asset specifications. The resulting Entry object depends on the value defined for the MBO parameter.

If the MBO parameter is ASSET, the result is two Entry objects with the following attribute names and values:

If the MBO parameter is ASSET@ASSETSPEC, the result is six Entry objects with the following attribute names and values:

AddOnly mode

When adding Entries using Simple Tpae IF Connector, specify the attributes marked as Required. The Tpae also accepts empty strings. If any of the attributes are missing, the connector throws an exception and the add operation fails.

Update mode

When modifying entries with the Simple Tpae IF Connector, specify only the attributes marked as Required. If any of the attributes are missing, the connector throws an exception and the modification fails.

Delete mode

When deleting Entries using Simple Tpae IF Connector, specify only the attributes marked as Required. If any of the attributes are missing, the connector throws an exception and the deletion fails.

Lookup mode

To find a specific record in Maximo, provide the Link Criteria with attributes that uniquely identify the record.

The following attributes uniquely identify an asset in Maximo.

The following attributes uniquely identify an asset meter in Maximo.

The Simple Tpae IF Connector supports only Link Criteria of type AND, and the following match operators:

• "=" - binary equals operator;
• "!" - binary non-equals operator; both operands must be different.

Schema

The schema of the returned entries depends on the selected Object Structure and MBO. Each MBO has a set of unique attributes that needs to be specified when creating, updating, or deleting it. These attributes are marked as Required in the Configuration Editor.

Error handling

The Simple Tpae IF Connector handles all exceptions that occur through the normal server hooks. If a failure cannot be handled, the corresponding AssemblyLine Error hook is started. The following exceptions are unique to this connector:

• MxConnectorRuntimeException
  • MxConnConfigException
• MxConnectorException
  • MxConnIOException
    • MxConnHttpException
    • MxConnTimeoutException
  • MxConnSchemaException
    • MxConnExcedentSizeException
    • MxConnTypeConvertionException
  • MxConnXmlParsingException

If an Assembly line with a Simple Tpae IF Connector fails, you can retrieve additional information about the error as follows:

1. Add the following code in the Default On Error hook. Name the Connector as mxConn:

   task.logmsg("ERROR", "An exception occurred.");
   mxConn.connector. extractMaximoException(error);
   task.dumpEntry(error);

2. When an exception occurs, the following message is displayed:

   19:31:44  CTGDIS003I *** Start dumping Entry
   19:31:44  	Operation: generic 
   19:31:44  	Entry attributes:
   19:31:44   exception (replace):	'com.ibm.di.connector.maximo.exception.
              MxConnHttpException: response: 404 - Not Found'
   19:31:44   targetUrl (replace):	'http://9.156.6.14/meaweb/schema
              /service/MXPersonService.xsd'
   19:31:44  class (replace):	'com.ibm.di.connector.maximo.
             exception.MxConnHttpException'
   19:31:44  operation (replace):	'update'
   19:31:44  status (replace):	'fail'
   19:31:44  connectorname (replace):	'AddPerson'
   19:31:44  body (replace):	'Error 404: BMXAA1513E - 
             Cannot obtain resource /meaweb/schema/service/MXPersonService.xsd.'
   19:31:44  responseCode (replace):	'404.0'
   19:31:44  responseMessage (replace):	'Not Found'
   19:31:44  message (replace):	'The HTTP server did not returned "HTTP OK".'
   19:31:44  CTGDIS004I *** Finished dumping Entry

   Note:

   The task.dumpEntry(error) prints information about the error.

Configuring external systems

Configuration

The Simple Tpae IF Connector parameters are:

Base URLs

Use this parameter to specify a list of URLs to send messages to Tpae products. If Tpae is on the same system as Tivoli Directory Integrator, use http://localhost. Else, use the IP address of the Tpae server. Use the same port to login to the Tpae application. For example, use port 9080 if the login URL ishttp://192.168.80.128:9080/maximo/webclient/login/login.jsp. The list uses space as a separator between URLs.

Note:

Using a list of URLs, instead of a single URL, is a high-availability requirement. If the first server on the list throws an exception, the second URL is used, and so on, until a server is valid. If the last URL is also invalid, an exception is thrown and the connection fails.

Authentication Required

Use this parameter to include user ID and password in the HTTP request header. Only a server with HTTP Basic Authentication option (enabled) supports this parameter.

User ID

Use this parameter to specify a valid user ID to login to the Tpae application.

Note:

In the Configuration Editor, the User ID field is enabled only when you select the Authentication Required check box.

Password

Use this parameter to specify a valid password to login to the Tpae application.

Note:

In the Configuration Editor, the Password field is enabled only when you select the Authentication Required check box.

Object Structure

Use this parameter to specify name of the Object Structure to be used for the integration. Since every Operating System contains a set of predefined MBOs, this parameter limits the range of possible values for the MBO parameter.

MBO

Use this parameter to specify name of the MBO object used to be for the integration. If this parameter is not specified, the connector uses the root object of the specified Object Structure. For more information about this parameter, see section MBO parameter. The following two fields are associated with the MBO parameter:

Get MBOs

To select a valid MBO parameter:

1. Click the Get MBO button to get a list of possible MBO names for the specified Object Structure.
2. Select a name from the list as MBO parameter.

Clear

The Connector internally caches the schemas of all used Object Structures to minimize the time needed to display the MBO list. Click the Clear button to remove all saved schemas. This operation is useful when the schema of an Object Structure is changed (XSD generation) and when you need to update the local representation of this schema. After the schema cache is cleared, subsequent calls to the Get MBOs script for a different Operating System is delayed. The delay is due that each schema must be retrieved from the server again.

Note:

The Clear button clears the schema cache used at design time. When the Configuration Editor runs the AssemblyLine on the server, another schema cache is created. The schema can be deleted by calling the clearSchemaCache() method in the connector. For example, you can add the text to the After initialize hook in to clear the cache before using the Connector: thisConnector.connector.clearSchemaCache();.

Query criteria

Use this parameter to filter the result set of iteration. This parameter contains the selection criteria for the Iterator mode. Specify the queries in XML syntax. You can select records based on a single value or a range of values.

Note:

The query criteria can apply only to the root MBO in the Object Structure.

The format of the query criteria parameter is:

<MBO> 
  <FIELD1 operator="oper"> </FIELD1> 
  <FIELD2> </FIELD2>
  ...
</MBO>

where:

MBO - represents the business object to be searched.
FIELD - name of the MBO field.
oper - conditional operator for the search.

For more information and sample query criteria, see Iterator Mode.

Page Size

Use this parameter to limit the number of records retrieved from Tpae. The connector makes several requests to get all the records selected by the query criteria.

Note:

The page size applies only to the root MBO in the Object Structure.

For example, if Maximo has 1000 assets in its database and the page size is defined as 100, a query against the predefined MXASSET Object Structure is accomplished by 10 requests.

The default value is 100.

Validate field size

Use this parameter to throw an error when a text field exceeds the maximum size. In the Configuration Editor, if the Validate field size check box is not selected, the text gets truncated.

XML Character Validation

Use this parameter to remove invalid Unicode characters from XML content before parsing it.

IF Version

Use this parameter to specify the version of IF that each message exchanged with the server must contain. The Configuration Editor provides a suitable default value.

Transaction Language

Use this parameter to specify the transaction language in which the content values for multi-language enabled fields are supplied. The default value is EN. For a complete list of the language acronyms, see the ISO 639-1 alpha-2 codes at http://www.loc.gov/standards/iso639-2/php/English_list.php.

The possible choices are:

• DE - indicates German language
• EN - indicates English language
• ES - indicates Spanish language
• FR - indicates French language
• IT - indicates Italian language
• KO - indicates Korean language
• PT - indicates Portuguese language
• ZH - indicates Chinese language

Timeout

Use this parameter to communicate with the IF server. If the timeout expires before establishing the connection or before reading the available data, the MxConnTimeoutException is thrown. A timeout of zero (default) is considered as an infinite timeout.

External System

Use this parameter to specify the name of the external system, which groups and exposes Enterprise Services for Create, Update, Delete, or Query operations, for the selected mode.

MAXOBJECT/MAXATTRIBUTE Object Structure

Use this parameter to specify the name of the Object Structure that exposes the MAXOBJECT and MAXATTRIBUTE MBOs. This Object Structure is used to obtain the metadata of complementary MBO such as the maximum allowed size for an attribute. The default value is MXOBJECTCFG.

MAXOBJECT/MAXATTRIBUTE QUERY Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Query operations on the MAXOBJECT Object Structure. This Object Structure is used to obtain the metadata of complementary MBO such as the maximum allowed size for an attribute.

Note:

This parameter is enabled only when you specify the External System parameter.

The default value is MXMaxObjectQuery.

CREATE Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Create operations on the specified Object Structure.

Note:

This parameter is enabled only when you specify the External System parameter and when the connector is in AddOnly or Update operation mode.

SYNC Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Sync operations on the specified Object Structure.

Note:

This parameter is enabled only when you specify the External System parameter and when the connector is in Delete operation mode.

QUERY Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Query operations on the specified Object Structure.

Note:

This parameter is enabled only when you specify the External System parameter.

UPDATE Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Update operations on the specified Object Structure.

Note:

This parameter is enabled only when you specify the External System parameter and when the connector is in Update operation mode.

Comment

Use this parameter to add your comments. The comment is not considered while parsing data.

Detailed Log

Use this parameter to generate detailed log messages.

Examples

Go to the TDI_install_dir/examples/SimpleTpaeIFConnector directory of your IBM® Tivoli Directory Integrator installation.

See Also