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

java.lang.Object
  extended by com.ibm.di.connector.Connector
      extended by 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