com.ibm.di.connector.maximo.core
Class SimpleTpaeIFConnector

java.lang.Object
  com.ibm.di.connector.Connector
      com.ibm.di.connector.maximo.core.SimpleTpaeIFConnector

All Implemented Interfaces:

ConnectorInterface, VersionInfoInterface

Direct Known Subclasses:

TpaeIFConnector

public class SimpleTpaeIFConnector
extends Connector

IBM Tivoli Directory Integrator connector for TPAE IF.

Supported Modes:

Iterator, Lookup, AddOnly, Delete, Update

Note: The basic functionality of this connector has been tested with TPAE 7.1.1.5 and 7.1.1.7.

Overview

Maximo is a very powerful framework that allows the creation of rich web-based applications, such as CCMDB and other IBM products. Inside Maximo, every business rule is defined by a Maximo Business Object or MBO. A MBO instance has its entire life cycle controlled by Maximo and to avoid inconsistence, no external application should directly access it. Because of that, Maximo has its own integration mechanism, called Maximo Enterprise Adapter or MEA.

The TPAE IF Connector provides access to any MBO properly exposed by the MEA.

Maximo Enterprise Adapter

It is beyond the scope of this document an explanation about MEA, however, the TPAE IF Connector relies entirely upon it, making a brief presentation of its main concepts necessary.

The Maximo Enterprise Adapter or MEA is a set of applications that provide integration between Maximo and other external systems. From the connector's perspective, the Object Structure application, the Enterprise Service application and the External System application are the most important.

Object Structure Application

The Object Structure Application manages object structures. An object structure defines which MBO and relationships will be exposed.

Maximo comes with several predefined object structures. One of them is MXASSET, which is described below as an example:

MBO	Parent Object	Location Path	Relationship
ASSET		ASSET
ASSETMETER	ASSET	ASSET/ASSETMETER	INT_ASSETMETER
ASSETUSERCUST	ASSET	ASSET/ASSETUSERCUST	ASSETUSERCUST
ASSETSPEC	ASSET	ASSET/ASSETSPEC	ASSETSPECCLASS

The result is an XML structure where the relationships are represented as nested elements:

 <ASSET>
    <ASSETID>1</ASSETID>
    ...
    <ASSETMETER>
       <ASSETMETERID>1</ASSETMETERID>
       ...
    </ASSETMETER>
    <ASSETMETER>
       <ASSETMETERID>2</ASSETMETERID>
       ...
    </ASSETMETER>
    ...
 </ASSET>
 

Enterprise Service Application

The Enterprise Service Application manages enterprise services. An enterprise service associates an operation and an object structure, in other words, an enterprise service defines which operations can be performed on a given object structure. These operations are requested to Maximo as XML messages over HTTP.

Maximo supports a set of operations, but just some are interesting from the connector's perspective:

Operation	Description
Create	Create new objects
Delete	Delete existing objects
Query	Query existing objects
Update	Update existing objects

Note: Every operation is performed over the object structure's top-level MBO and cascaded to the related child MBOs.

External System Application

The External System Application manages external systems. 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.

Modes

Iterator Mode

Required Parameters

Base URL, External System, MAXOBJECT Object Structure, MAXOBJECT QUERY Enterprise Service, Object Structure, MBO, QUERY Enterprise Service, Page Size

Optional Parameters

Query Criteria

About the MBO Parameter

Suppose Maximo returns the following XML as a result of a query operation on the predefined object structure MXASSET:

 <ASSET>
    <ASSETID>1</ASSETID>
    <ASSETNUM>A1</ASSETNUM>
    ...
    <ASSETMETER>
       <ASSETMETERID>11</ASSETMETERID>
       ...
    </ASSETMETER>
    <ASSETMETER>
       <ASSETMETERID>12</ASSETMETERID>
       ...
    </ASSETMETER>
    ...
 </ASSET>
 <ASSET>
    <ASSETID>2</ASSETID>
    <ASSETNUM>A2</ASSETNUM>
    ...
    <ASSETMETER>
       <ASSETMETERID>21</ASSETMETERID>
       ...
    </ASSETMETER>
    <ASSETMETER>
       <ASSETMETERID>22</ASSETMETERID>
       ...
    </ASSETMETER>
    ...
 </ASSET>
 

Although the query returns 2 assets, each one with 2 asset meters, the resulting Entry objects will depend on the value defined for the MBO parameter.

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

ASSETID	ASSETNUM
1	A1
2	A2

On the other hand, if the MBO parameter is ASSET@ASSETMETER, the result would be 4 Entry objects with the following attribute names and values:

ASSETID	ASSETNUM	ASSETMETER@ASSETMETERID
1	A1	11
1	A1	12
2	A2	21
2	A2	22

Lookup Mode

Required Parameters

Base URL, External System, MAXOBJECT Object Structure, MAXOBJECT QUERY Enterprise Service, Object Structure, MBO, QUERY Enterprise Service, Page Size

About the Link Criteria

In order to find a specific record inside Maximo, the Link Criteria must be provided with attributes that uniquely identify the record.

Examples

The following attributes uniquely identify an asset in Maximo.

Attribute Name	Value
ASSETNUM	1001
SITEID	BEDFORD

The following attributes uniquely identify an asset's meter in Maximo.

Attribute Name	Value
ASSETNUM	1001
SITEID	BEDFORD
ASSETMETER@METERNAME	RUNHOURS

AddOnly Mode

Required Parameters

Base URL, External System, MAXOBJECT Object Structure, MAXOBJECT QUERY Enterprise Service, Object Structure, MBO, CREATE Enterprise Service, UPDATE Enterprise Service

About the MBO Parameter

If the MBO parameter targets the object structure's top-level MBO, then the connector will use the enterprise service defined by the CREATE Enterprise Service parameter.

Nonetheless, if the MBO parameter targets a child MBO at any level of the object structure, then the connector will use the enterprise service defined by the UPDATE Enterprise Service parameter. Besides, the key attributes of all MBOs until the object structure's top-level MBO must be provided and must reference existent records, except the MBO target by the MBO parameter (the one to be created).

For example, the predefined object structure MXASSET exposes the ASSET and the ASSETMETER MBOs. So, to create a new meter for an asset, a work entry with, at least, the attributes below must be provided:

Attribute Name	Value
ASSETNUM	1001
SITEID	BEDFORD
ASSETMETER@METERNAME	RUNHOURS

ASSETNUM and SITEID identify an existent asset and ASSETMETER@METERNAME is the name of the new meter.

Delete Mode

Required Parameters

Base URL, External System, MAXOBJECT Object Structure, MAXOBJECT QUERY Enterprise Service, Object Structure, DELETE Enterprise Service, UPDATE Enterprise Service

About the MBO Parameter

If the MBO parameter targets the object structure's top-level MBO, then the connector will use the enterprise service defined by the DELETE Enterprise Service parameter.

Nonetheless, if the MBO parameter targets a child MBO at any level of the object structure, then the connector will use the enterprise service defined by the UPDATE Enterprise Service parameter. Besides, the key attributes of all MBOs until the object structure's top-level MBO must be provided and must reference existent records.

For example, the predefined object structure MXASSET exposes the ASSET and the ASSETMETER MBOs. So, to delete an asset's meter, a work entry with the attributes below must be provided:

Attribute Name	Value
ASSETNUM	11430
SITEID	BEDFORD
ASSETMETER@METERNAME	RUNHOURS

ASSETNUM and SITEID identify an existent asset and ASSETMETER@METERNAME identifies the meter to be deleted.

Update Mode

Required Parameters

Base URL, External System, MAXOBJECT Object Structure, MAXOBJECT QUERY Enterprise Service, Object Structure, MBO, QUERY Enterprise Service, CREATE Enterprise Service, UPDATE Enterprise Service

No further observation.

Since:

7.1

See Also:

MxConnConfiguration, AbstractMxConnMode, MxConnAddOnly, MxConnDelete, MxConnIterator, MxConnLookup, MxConnUpdate

Field Summary

protected MxConnConfiguration	cfg
protected MxConnIterator	connIterator
protected MxConnLookup	connLookup
static String	PROPERTIES_FILE Component properties.
protected Log	proxyLog Log object for logging in all classes used by the TPAE IF Connector.

Fields inherited from class com.ibm.di.connector.Connector

ALL_MODES, myLog, PROPERTY_MESSAGE, PROPERTY_READER, PROPERTY_WRITER

Constructor Summary

SimpleTpaeIFConnector()
Default constructor.

Method Summary

void	clearSchemaCache() Clears the cache of the schema.
void	deleteEntry(Entry entry, SearchCriteria sc) Deletes an existing entry.
void	extractMaximoException(Entry error) This method extracts additional information about a Maximo exception.
Entry	findEntry(SearchCriteria searchCriteria) Finds an existing entry.
MxConnFunctions	getFc() Returns the object that provides utility functions.
Vector	getMboList() Returns a list of the available MBOs in the object structure.
Entry	getNextEntry() Returns the next Entry from the connector.
static ResourceHash	getResHash()
String	getVersion() Version information.
void	initialize(Object obj) Initialize the connector.
void	modEntry(Entry newEntry, SearchCriteria searchCriteria, Entry oldEntry) Modifies an existing entry.
void	putEntry(Entry newEntry) Adds a new entry to the data source
Object	querySchema(Object obj) This method populates the input and output map of the connector with the schema of the chosen MBO.
void	selectEntries() Prepare the Connector for sequential read.
void	setParam(String key, String value) Adds or replaces a connector configuration parameter.
void	terminate() Terminate the connector.

Methods inherited from class com.ibm.di.connector.Connector

addFindEntry, allModes, clearFindEntries, debug, debugMode, findEntry, getBoolean, getClassInstance, getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getLog, getMaxDuplicateEntries, getModes, getModes, getName, getNextClient, getNextFindEntry, getParam, getParser, getProperty, getPushbackEntry, getRawConnectorConfiguration, getRSInterface, getUI, hasConfigValue, hasParser, initParser, isDeltaSupported, isExceptionFatal, isIOException, logError, logmsg, modEntry, pushback, queryOperations, queryReply, queryTables, reconnect, reconnect, registerScriptBeans, replyEntry, setConfiguration, setContext, setCurrent, setDebugMode, setLog, setMaxDuplicateEntries, setModes, setModes, setName, setParser, setProperty, setRSInterface, terminateServer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTIES_FILE

public static final String PROPERTIES_FILE

Component properties.

See Also:

Constant Field Values

cfg

protected MxConnConfiguration cfg

connIterator

protected MxConnIterator connIterator

connLookup

protected MxConnLookup connLookup

proxyLog

protected Log proxyLog

Log object for logging in all classes used by the TPAE IF Connector.

Constructor Detail

SimpleTpaeIFConnector

public SimpleTpaeIFConnector()

Default constructor.

Method Detail

initialize

public void initialize(Object obj)
                throws Exception

Initialize the connector. The connector may be passed a parameter of any kind by the user. It is up to the connector to determine whether this object can be used or not. The parameter is typically provided by a user script. When an AssemblyLine initializes it's Connectors, they are passed a ConnectorMode object.

Specified by:

initialize in interface ConnectorInterface

Overrides:

initialize in class Connector

Parameters:

obj - User provided parameter

Throws:

Exception - if the initialization of this connector fails.

selectEntries

public void selectEntries()
                   throws MxConnectorException

Prepare the Connector for sequential read. If necessary, create a result set to be used for getNextEntry(). When the Connector is used as an Iterator in an AssemblyLine, this method will be called. Default is an empty method.

Specified by:

selectEntries in interface ConnectorInterface

Overrides:

selectEntries in class Connector

Throws:

MxConnectorException

getNextEntry

public Entry getNextEntry()
                   throws MxConnectorException

Returns the next Entry from the connector. The entry is populated with attributes and values from the next entry in the input set.

Example:

 var ctor = input.getConnector();
 var entry = ctor.getNextEntry();
 
 for (; entry != null; entry = ctor.getNextEntry()) {
        main.logmsg("Read entry...");
        main.dumpEntry(entry);
 }
 

Specified by:

getNextEntry in interface ConnectorInterface

Overrides:

getNextEntry in class Connector

Returns:

- the next Entry, or null if no more data

Throws:

MxConnectorException

See Also:

ConnectorInterface.selectEntries()

putEntry

public void putEntry(Entry newEntry)
              throws MxConnectorException

Adds a new entry to the data source

Example:

 var ctor = write.getConnector();
 
 for (i = 0; i < 10; i++) {
        var entry = system.newEntry();
        entry.setAttribute("linenumber", i);
        entry.setAttribute("line", i + " line of text...");
 
        main.logmsg("Writes entry to output...");
        main.dumpEntry(entry);
        ctor.putEntry(entry);
 }
 

Specified by:

putEntry in interface ConnectorInterface

Overrides:

putEntry in class Connector

Parameters:

newEntry - The entry data to add

Throws:

MxConnectorException

findEntry

public Entry findEntry(SearchCriteria searchCriteria)
                throws Exception

Finds an existing entry. The search criteria specifies which entry to locate

Here is an example of how to find all people with names starting with 'J' which are from IBM organization in US.

Example:

 var ctor = input.getConnector();
 var crit = new com.ibm.di.SearchCriteria("$dn",
                com.ibm.di.SearchCriteria.SUBSTRING, "c=US,o=IBM");
 crit.addCriteria("name", com.ibm.di.SearchCriteria.INITIAL_STRING, "J");
 crit.addCriteria("objectclass", com.ibm.di.SearchCriteria.SUBSTRING, "person");
 
 var res = ctor.findEntry(crit);
 if (res != null) {
        main.logmsg("Found entry:");
        main.dumpEntry(res);
 } else {
  if( getFindEntryCount()> 1 ){
   main.logmsg("Found these entries:");
   while ( (entry = ctor.getNextFindEntry()) != null ) {
     main.dumpEntry(entry);
   }
  }
  else {
         main.logmsg("Entry not found!");
  }
 }
 

Specified by:

findEntry in interface ConnectorInterface

Overrides:

findEntry in class Connector

Parameters:

searchCriteria - The search criteria used to locate the entry to be modified

Returns:

The entry found, or null if no or multiple entries found

Throws:

Exception - if an error occurs.

modEntry

public void modEntry(Entry newEntry,
                     SearchCriteria searchCriteria,
                     Entry oldEntry)
              throws MxConnectorException

Modifies an existing entry. The new entry data is given by the entry parameter and the search criteria specifies which entry to modify.

Specified by:

modEntry in interface ConnectorInterface

Overrides:

modEntry in class Connector

Parameters:

newEntry - The entry data

searchCriteria - The search criteria used to locate the entry to be modified

oldEntry - The old entry found by the search criteria

Throws:

MxConnectorException

deleteEntry

public void deleteEntry(Entry entry,
                        SearchCriteria sc)
                 throws MxConnectorException

Deletes an existing entry. The search criteria specifies which entry to modify. Some connectors may silently ignore the search criteria. For example, the LDAP connector will use the distinguished name ($dn) from the entry parameter (if it exists) rather than expanding the search criteria and search for the entry. Each connector's inner semantics governs whether the search parameter is used or not.

Specified by:

deleteEntry in interface ConnectorInterface

Overrides:

deleteEntry in class Connector

Parameters:

entry - The entry data

sc - The search criteria used to locate the entry to be deleted

Throws:

MxConnectorException

querySchema

public Object querySchema(Object obj)
                   throws Exception

This method populates the input and output map of the connector with the schema of the chosen MBO. All unique attributes from the schema are marked as "Required" in the CE.

Note: This method does not return a Vector of entries because the schema is directly updated.

Specified by:

querySchema in interface ConnectorInterface

Overrides:

querySchema in class Connector

Parameters:

obj - The object on which to discover schema. This may be an Entry or a string value

Returns:

A Vector of com.ibm.di.entry.Entry objects describing each entity

Throws:

Exception - if an error while retrieving the schema occurs.

See Also:

Entry, Vector

getFc

public MxConnFunctions getFc()

Returns the object that provides utility functions.

Returns:

object that provides utility functions

clearSchemaCache

public void clearSchemaCache()

Clears the cache of the schema.

getMboList

public Vector getMboList()
                  throws MxConnectorException

Returns a list of the available MBOs in the object structure.

Returns:

list of the available MBOs in the object structure

Throws:

MxConnectorException - if any of the required parameters is missing (Base URL, External System, MaxObject/MaxAttribute Object Structure, MaxObject/MaxAttribute QUERY Enterprise Service, Object Structure) or if it is not possible to obtain the schema data

See Also:

MBO Parameter

extractMaximoException

public void extractMaximoException(Entry error)

This method extracts additional information about a Maximo exception. It is particularly useful to call from an error hook since the predefined bean "error" contains an entry with the exception .
For example:

 task.logmsg("ERROR", "An exception occurred.");
 mxConn.connector.extractMaximoException(error);
 
 // print detailed information about error
 task.dumpEntry(error);
 

Parameters:

error - an Entry object containing the exception in its "exception" attribute.

setParam

public void setParam(String key,
                     String value)

Adds or replaces a connector configuration parameter.

Specified by:

setParam in interface ConnectorInterface

Overrides:

setParam in class Connector

Parameters:

key - The parameter name

value - The parameter value

terminate

public void terminate()
               throws Exception

Terminate the connector. This function closes all connection and releases all resources used by the connector. This function also calls the parser's closeParser() method if a parser is active.

Specified by:

terminate in interface ConnectorInterface

Overrides:

terminate in class Connector

Throws:

Exception - if an error occurs.

getResHash

public static ResourceHash getResHash()

Returns:

ResourceHash object holding messages for this connector.

getVersion

public String getVersion()

Version information.

Returns:

version information