Tpae IF Connector

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 Tpae IF Connector connects Tivoli® Directory Integrator to the Tpae Integration Framework to exchange information.

The 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 Tpae IF Connector can work with hierarchical Entries and is based on Simple Tpae IF Connector. The Tpae IF Connector can be used in various AssemblyLine modes such as Iterator, AddOnly, Update, Lookup, and Delete.

Using the Connector

The Tpae IF Connector is associated with Simple Tpae IF Connector and works with hierarchical Entries. It supports integration through Object Structure Services and Enterprise Services. The Connector reads or writes a complete Object Structure and does not require any MBO to be specified.

The following table provides a comparison of Simple Tpae IF Connector and Tpae IF Connector.

Iterator mode

In the Iterator mode, the Tpae IF Connector sends a Query XML request to the IF server and receives a Query XML response. For example, Maximo returns the following XML response 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>
		<ASSETATTRID>DISKSIZE</ASSETATTRID>
		<MEASUREUNITID>GBYTE</MEASUREUNITID>
		<NUMVALUE>100.0</NUMVALUE>
		-
	</ASSETSPEC>
	<ASSETSPEC>
		<ASSETATTRID>PROSPEED</ASSETATTRID>
		<MEASUREUNITID>GHZ</MEASUREUNITID>
		<NUMVALUE>1.5</NUMVALUE>
		-
	</ASSETSPEC>
	-
</ASSET>

The above XML representation is translated into a Tivoli Directory Integrator Entry object as follows:

Figure 7. Hierarchical Entry object from Maximo

The returned Entry contains all child MBOs (the tree asset specifications). You can use the toString() method of Entry to view a complete string representation of this hierarchy.

AddOnly, Update, and Delete modes

The Tpae IF Connector uses both Object Structure and Enterprise Services to modify MBOs. To configure Tpae IF Connector, a single configuration parameter is used. The Object Structure Service or Enterprise Service offers function to encapsulate Create, Update, and Delete operations. In Update mode, the Connector checks the attribute operations and sets appropriate actions in the resulting XML payload sent to Tpae. If an attribute is not tagged with an Add, Modify, or Delete operation, no action is set.

The following example shows a delta-tagged Entry that is to be modified, and the corresponding request sent to the Tpae IF server.

{
  "#type": "generic",
  "#count": 7,
  "PERSON": {
    "#type": "replace",
    "#count": 0,
    "PERSONID": [
	"#type": "replace",
	"#count": 1,
	"#replace": "JOHN"
    ],
    "FIRSTNAME": [
	"#type": "replace",
	"#count": 1,
	"#replace": "John"
    ],
    "LASTNAME": [
	"#type": "replace",
	"#count": 1,
	"#replace": "Jones"
    ],
    "PHONE": {
	"#type": "add",
	"#count": 0,
	"PHONENUM": [
	    "#type": "replace",
	    "#count": 1,
	    "#replace": "0888776455"
		],
	"TYPE": [
	    "#type": "replace",
	    "#count": 1,
	    "#replace": "WORK"
	],
	"ISPRIMARY": [
	    "#type": "replace",
	    "#count": 1,
	    "#replace": "1"
	]
	},
    "PHONE": {
	"#type": "delete",
	"#count": 0,
	"PHONENUM": [
	    "#type": "replace",
	    "#count": 1,
	    "#replace": "555244458"
	]
    },
    "EMAIL": {
	"#type": "replace",
	"#count": 0,
	"EMAILADDRES": [
	    "#type": "replace",
	    "#count": 1,
	    "#replace": "jjones@mail.com"
		]
	}
    }

<?xml version='1.0' encoding='UTF-8'?>
<SyncMXPERSON
    xmlns="http://www.ibm.com/maximo"
    creationDateTime="2010-11-05T16:44:20+02:00"
    transLanguage="EN"
    messageID="1288968260482"
    maximoVersion="7 1 Harrier 072 7100-001">
    <MXPERSONSet>
	<PERSON action="Change">
	   <PERSONID>JOHN</PERSONID>
	   <FIRSTNAME>John</FIRSTNAME>
	   <LASTNAME>Jones</LASTNAME>
	   <PHONE action="Add">
	     <PHONENUM>0888776455</PHONENUM>
	     <TYPE>WORK</TYPE>
	     <ISPRIMARY>1</ISPRIMARY>
	   </PHONE>
	   <PHONE action="Delete">
	     <PHONENUM>555244458</PHONENUM>
	   </PHONE>
	   <EMAIL>
	     <EMAILADDRESS>
			jjones@mail.com
	     </EMAILADDRESS>
	     <ISPRIMARY>1</ISPRIMARY>
	   </EMAIL>
	</PERSON>
    </MXPERSONSet>
</SyncMXPERSON>

In AddOnly and Update modes, specify the values for all unique attributes of MBOs that are being added or updated. Attributes also support empty strings as values. In Delete mode, provide the values for all unique attributes of the root MBO. If any unique key is missing, the Connector throws an exception and operation fails.

In the Update mode, the Tpae IF Connector supports Skip Lookup function. The Skip Lookup function allows you to skip querying the Object Structure before updating or deleting it. Every query operation sends an HTTP request over the network. When updating AssemblyLines or deleting multiple Entries, enabling Skip Lookup improves the performance.

Lookup mode

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

Error handling

The 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 AssemblyLinee with a 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.

External system configuration

Configuration

The 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.

User ID

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

Password

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

Object Structure

Use this parameter to specify name of the Object Structure to be used for the integration. In the Configuration Editor, the Clear button is associated with the Object Structure parameter.

Clear

The Connector internally saves the schemas of all Object structures used 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, the subsequent calls to the Get MBOs script for a different Operating System is delayed because 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 starting 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 selects attributes from the top two levels of MBOs 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.

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.

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.

SYNC Enterprise Service

Use this parameter to specify the name of Enterprise Service that performs Sync operations on the specified Object Structure. This service is used to Create, Update, and Delete operations on the specified Object Structure for the selected Connector mode.

Note:

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

Comment

Enter your own comments here. The comments are not considered during the operation of this component.

Detailed Log

If this parameter is checked, more detailed log messages are generated.

Examples

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

See also