Maximo Integration Client The Missing Manual.

Created by: KISS Programming blog (Mike Chrisman) Creation date: November 20, 2008 Last update date: November 25, 2008 Version: 1.0

INTCLIENT- The Missing Manual

Page 1

Table of Contents
Purpose of this Document .....................................................................................................................3 What is the Maximo Integration Client? ................................................................................................4 Installation ............................................................................................................................................5 Starting .................................................................................................................................................6 Main Screen ..........................................................................................................................................7 EJB .......................................................................................................................................................8 HTTP ....................................................................................................................................................9 IFACETABLE .................................................................................................................................... 10 FLATFILE .......................................................................................................................................... 11 SOAPRPC .......................................................................................................................................... 12 SOAPDOC ......................................................................................................................................... 14 UDDI .................................................................................................................................................. 16 JMSQUEUE ....................................................................................................................................... 17 RMI .................................................................................................................................................... 19 STRIPEMPTYTAGS .......................................................................................................................... 20 STOPWATCH .................................................................................................................................... 21 Appendix A: The Maximo XML Message Format .............................................................................. 22 Appendix B: RMI URL ....................................................................................................................... 26 Appendix C: Errors ............................................................................................................................. 27

INTCLIENT- The Missing Manual

Page 2

Purpose of this Document

This document is design to be a reference guide for using the Integration Client tool. It is designed as a help in using the INTCLIENT. This is a work in progress document and as such, may contain inaccuracies. If you find any, please contact the author so that it can be updated and shared with all. This document is released free to the public. The INTCLIENT is the property of IBM and this document in no way implies ownership or responsibility for this tool.

INTCLIENT- The Missing Manual

Page 3

What is the Maximo Integration Client?

The Integration client (INTCLIENT) is a tool that comes with Maximo and can be used to testing of integration interfaces with Maximo. Although the tool is created by IBM and comes with Maximo, it is an unsupported tool. This means that IBM will not offer help if the tool does not work correctly. It also means that it is undocumented. As such, it should never be used in any production level activity. The INTCLIENT offers various types of methods you can use for testing your Maixmo interfaces. But the power of this tool does not stop there. You can use this tool to test other applications (other than Maximo). For example, the INTCLIENT has the ability to test a web service. This can be any web service, not just the those from Maximo.

INTCLIENT- The Missing Manual

Page 4

Installation
The INTCLIENT is installed as part of the full Maximo application. Sadly, this means that you have to install Maximo on the computer you want to run the INTCLIENT. There is (currently) no way to install just the INTCLIENT as it uses many of the class files included with Maximo.

INTCLIENT- The Missing Manual

Page 5

Starting
To start the INTCLIENT, run the INTCLIENT.BAT (or INTCLIENT.SH) file found in the %maximohome%/tools/maximo/internal folder. The INTCLIENT is a java application. Please note that there is another INTCLIENT.bat(sh) file in the %maximohome%/tools/maximo/J2eeclient folder, but do not run this one.

INTCLIENT- The Missing Manual

Page 6

Main Screen
When you start the INTCLIENT, it opens the main screen with the Enterprise Java Beans interface showing:

Let's look at some of the common features: Client Type: This is where you will select what type of interface. Options include EJB, SOAPDOC, SOAPRPC, HTTP Post, etc. Choose File: You pass data into Maximo through a file (usually XML format). Strip Empty Tags: This option will remove any empty tags from the file when it is submitted (it will not affect your file) Field Area: This area will have fields that are specific to each Client Type. Bottom part of the screen: (the big white area) This is where any reply from the client is displayed. Test (button): this is the submit button. The bottom part of the screen will change depending on what client type you have chosen.

INTCLIENT- The Missing Manual

Page 7

EJB
Purpose: This allows you to test EJB interfaces.

The Screen:

Fields: URL: This is the URL to the application server userid: this is the user id to use for security (if required) password: this the password part of the security access (if required) Server: this is the type of server (Weblogic or Websphere) sender: This is the SenderID (aka the External System name) Interface: this is the name of the interface JNDI Name: this is the name of the JNDI Iface Type: this is the name of the Maximo adapter Usage: Fill out the fields you need too, select the file with the message and press TEST.

INTCLIENT- The Missing Manual

Page 8

HTTP
Purpose: This allows you to test the HTTP Post interface. The Screen:

Fields: URL: this is the url to the maximo server. It is in the format of: http:://servername:port/meaweb/measervlet/maximoAdapter/interfacename. Unless you created your own adapter, then the maximoadapter will be MAXIMO (all in caps). userid: this is the user id to use for security (if required) password: this the password part of the security access (if required) Usage: Fill out the fields you need too, select the file with message and press TEST. The INTCLIENT will either display "success" or the actual error message returned by Maximo.

INTCLIENT- The Missing Manual

Page 9

IFACETABLE
Purpose: This allows you to populate the Interface tables using a Maximo XML file. The Screen:

Fields: endpointname: This is the name of the end point in Maximo (MXIFACETABLE). RMI url: this is the url to the RMI server. Usage: Enter both fields and press Test. The MEA will then load the XML file into the Interface table. It will return Success if it loaded the data. You can use this to load sample data into the interface tables.

INTCLIENT- The Missing Manual

Page 10

FLATFILE
Purpose: This will create a flat file on the Maximo server based on an XML file. The Screen:

Fields: Separator: the character that is used separate values in the file Folder: the name of the folder on the server where the flat file is to be created. Be sure to include drive letter RMI url: this is the url to the RMI server. Usage: Fill in all the fields and press Test. The file that you choose must be an XML file. This interface will convert your XML file to a Maximo flat file in the desired directory. The name of the flat file will be the same as the XML file, but will have a .DAT extension. Note: If you get an MXSystemException: iface#could_not_write error, then the server had trouble creating the file in the folder location you specified.

INTCLIENT- The Missing Manual

Page 11

SOAPRPC
Purpose: This allows you to test any web service using the RPC method. The Screen:

Fields: WSDL url: This is the URL to the WSDL of the web service service name: This is the name of the service portname: This is the portname of the web service TNamespace: This is the URL to the namespace definition userid: this is the user id to use for security (if required) password: this the password part of the security access (if required) sender: This is the SenderID (aka the External System name) Interface: this is the name of the interface Iface Type: this is the name of the Maximo adapter Usage: Fill in all needed fields, select a file and press Test. The file must have the XML formatted as needed by the Web service. This will be a different format than the standard XML message. Anything returned by the web service will be displayed in the message area. INTCLIENT- The Missing Manual Page 12

Note: This method is deprecated in Maximo. Maximo prefers the SOAPDOC method.

INTCLIENT- The Missing Manual

Page 13

SOAPDOC
Purpose: This allows you to test any web service (not just Maximo web services) using the DOC method. The Screen:

Fields: endpoint url: this is the url to the end point. This is in the form of http://servername:port/meaweb/services/interfacename service name: this is the name of the interface (interface name). TNamespace: This is the URL to the namespace definition userid: this is the user id to use for security (if required) password: this the password part of the security access (if required) soapaction: this is the soap action. Unless you need to fill in this value, just leave it blank. onewayws: No idea what this field is. I have always left it blank. Usage: INTCLIENT- The Missing Manual Page 14

Fill in all needed fields, select your xml file and press test. The Message area will either display success or the error that was returned by the web service.

INTCLIENT- The Missing Manual

Page 15

UDDI
Purpose: This allows you to query a Universal Description, Discovery and Integration (UDDI). The Screen:

Fields: Inquiry URL: This is the URL for inquiring the UDDI. Tmodel Name: This is the name to query from the UDDI. userid: this is the user id to use for security (if required) password: this the password part of the security access (if required) Usage: Fill in the URL and Tmodel Name fields, select the file and press Test.

INTCLIENT- The Missing Manual

Page 16

JMSQUEUE
Purpose: This allows you to query and delete items a particular JMSQueue. The Screen:

Fields: JNDI Name: This is the queue name (on the server) that you want to query. RMI url: this is the url to the RMI server. Selector: This is the id of the record you want to access. (This is mainly used for delete.) Action: You can choose either VIEW or DELETE Count: ???? Maximo Uuser: this is a Maximo user id to use for security (if required) Maximo Password: this the Maximo password part of the security access (if required) Usage: Enter values for the fields. An attached file is not needed. If you select the Action VIEW then when you press TEST, the application server will write the contents of the

INTCLIENT- The Missing Manual

Page 17

queue to the Maximo Globals directory. If you select the action DELETE, then the queue will delete the Selector record.

INTCLIENT- The Missing Manual

Page 18

RMI
Purpose: This allows you to call a Maxio interface using the Java RMI method. The Screen:

Fields: RMI url: this is the url to the RMI server. sender: This is the name of the external system. interface: This is the name of the Maximo interface Iface Type: This is the adapter name. Maximo Uuser: this is a Maximo user id to use for security (if required) Maximo Password: this the Maximo password part of the security access (if required) Usage: Enter all fields. The attached file is an XML version of the method and parameters to pass in. When you press TEST, the system will either display the results, or display any error message.

INTCLIENT- The Missing Manual

Page 19

STRIPEMPTYTAGS
Purpose: I assume this will remove empty tags from an XML file, but I cannot get it to work. It only throws an error. Plus, since there is check box that will strip the empty tags upon submission, I am not sure what value this option would have. The Screen:

Fields: None Usage: Since I cannot get it to work, I dont know its usage.

INTCLIENT- The Missing Manual

Page 20

STOPWATCH
Purpose: To be honest, I have no idea what this does, but I can get it to work. The Screen:

Fields: Timer Level: This is the value of the timer level. RMI url: this is the url to the RMI server Usage: Once you enter the RMI url, and enter the value for Timer Level, press test. It will return Success if it worked. What this does, I have no idea. I tried several values for the Timer Level and could not tell any difference in the application server.

INTCLIENT- The Missing Manual

Page 21

Appendix A: The Maximo XML Message Format

The Out of the Box Maximo Message format (from the MAXIMO Adapter) consists of two parts. The first is the XML for the Integration Object. The second is a wrapper for the Integration Interface. Integration Object This is where the actual data is formatted. In this example, well look at MXItem Integration object.
1: <?xml version=1.0 encoding=UTF-8?> 2: <MXITEM xmlns=http://www.mro.com/mx/integration> 3: <ITEM> 4: <ITEMNUM /> 5: <DESCRIPTION /> 6: <ROTATING /> 7: <LOTTYPE /> 8: <CAPITALIZED /> 9: <MSDSNUM /> 10: <OUTSIDE /> 11: <IN19 /> 12: <IN20 /> 13: <IN21 /> 14: <IN22 /> 15: <IN23 /> 16: <SPAREPARTAUTOADD /> 17: <INSPECTIONREQUIRED /> 18: <SOURCESYSID /> 19: <OWNERSYSID /> 20: <EXTERNALREFID /> 21: <IN24 /> 22: <IN25 /> 23: <IN26 /> 24: <IN27 /> 25: <SENDERSYSID /> 26: <ITEMSETID /> 27: <ORDERUNIT /> 28: <ISSUEUNIT /> 29: <DESCRIPTION_LONGDESCRIPTION /> 30: <CONDITIONENABLED /> 31: <GROUPNAME /> 32: <METERNAME /> 33: <COMMODITYGROUP /> 34: <COMMODITY /> 35: <ITEMTYPE /> 36: <PRORATE /> 37: <ITEMID /> 38: <ISKIT /> 39: <ATTACHONISSUE /> 40: <TRANS_LANGCODE /> 41: <CONVERSION>

INTCLIENT- The Missing Manual

Page 22

42: <CONVERSIONID /> 43: <FROMMEASUREUNIT /> 44: <TOMEASUREUNIT /> 45: <CONVERSION /> 46: <CHANGEBY /> 47: <CHANGEDATE /> 48: </CONVERSION> 49: <ITEMCONDITION> 50: <CONDITIONCODE /> 51: <DESCRIPTION /> 52: <STOCKTYPE /> 53: <CONDRATE /> 54: <DESCRIPTION_LONGDESCRIPTION /> 55: <COMMODITYGROUP /> 56: <COMMODITY /> 57: <ITEMCONDITIONID /> 58: </ITEMCONDITION> 59: </ITEM> 60: </MXITEM>

The base tag (lines 2 and 60) are the name of the integration object. Next comes the main object (lines 3 and 59). Each attribute (field) in the MBO is a separate tag where the tag name is the attribute name. Remember that an Integration Object and consist of more than one MBO. In this example, Conversion and ItemCondition MBO are related MBOs. In the XML, you can see that Conversion (lines 41 thru 48) and ItemCondition (lines 49 thru 58) are where this data goes. Since the relationship between Item and these two MBOs is a Zero to Many, each of these sections will be repeated for each child record. Integration Interface An Integration Interface XML message wraps a few tags around the Integration Object XML message.
1: <?xml version=1.0 encoding=UTF-8?> 2: <MXITEMInterface xmlns=http://www.mro.com/mx/integra tion xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance language=EN> 3: <Header operation=Notify event=0> 4: <RecipientID>EXTSYS1</RecipientID> 5: <SenderID type=MAXIMO majorversion=6 minorversion=2 build=142 dbbuild=V600502>MX</SenderID> 6: <CreationDateTime>2008-06-19T14:32:47-06:00</CreationDateTime> 7: </Header> 8: <Content> 9: <MXITEM> 10: <ITEM> 11: <ITEMNUM /> 12: <DESCRIPTION /> 13: <ROTATING /> 14: <LOTTYPE /> 15: <CAPITALIZED /> 16: <MSDSNUM /> 17: <OUTSIDE /> 18: <IN19 /> 19: <IN20 /> 20: <IN21 />

INTCLIENT- The Missing Manual

Page 23

21: <IN22 /> 22: <IN23 /> 23: <SPAREPARTAUTOADD /> 24: <INSPECTIONREQUIRED /> 25: <SOURCESYSID /> 26: <OWNERSYSID /> 27: <EXTERNALREFID /> 28: <IN24 /> 29: <IN25 /> 30: <IN26 /> 31: <IN27 /> 32: <SENDERSYSID /> 33: <ITEMSETID /> 34: <ORDERUNIT /> 35: <ISSUEUNIT /> 36: <DESCRIPTION_LONGDESCRIPTION /> 37: <CONDITIONENABLED /> 38: <GROUPNAME /> 39: <METERNAME /> 40: <COMMODITYGROUP /> 41: <COMMODITY /> 42: <ITEMTYPE /> 43: <PRORATE /> 44: <ITEMID /> 45: <ISKIT /> 46: <ATTACHONISSUE /> 47: <TRANS_LANGCODE /> 48: <CONVERSION> 49: <CONVERSIONID /> 50: <FROMMEASUREUNIT /> 51: <TOMEASUREUNIT /> 52: <CONVERSION /> 53: <CHANGEBY /> 54: <CHANGEDATE /> 55: </CONVERSION> 56: <ITEMCONDITION> 57: <CONDITIONCODE /> 58: <DESCRIPTION /> 59: <STOCKTYPE /> 60: <CONDRATE /> 61: <DESCRIPTION_LONGDESCRIPTION /> 62: <COMMODITYGROUP /> 63: <COMMODITY /> 64: <ITEMCONDITIONID /> 65: </ITEMCONDITION> 66: </ITEM> 67: </MXITEM> 68: </Content> 69: </MXITEMInterface>

The first thing to notice is from line 8 thru line 67 is the Integration Object XML Message. Now the base tag is the name of the interface. The MEA uses this to route the message to the proper interface for processing. This message is now divided into two sections. A header (lines 3 thru 7) and the content (lines 8 thru 68). In this case, the content is just the Integration INTCLIENT- The Missing Manual Page 24

Object XML Message. The really important thing here is in the Header section. Line 3, the Header tag has one very important attribute: OPERATION. This tells Maximo or you what to do with the information in the message. For messages going into Maximo this will either be Notify (telling Maximo to update or sync the data) or Query (used to query Maximo data). For messages going out of Maximo this will be either Notify (telling the other system to sync or update the data) or Response (which is the results from the Query). The next two lines (4 and 5) are very import to Maximo. The RecipientID is the name of the system that is receiving the message. For inbound messages, then needs to be MX (or whatever you have your MXSYSID setup as). For outbound, this will be the name of the External System the interface is attached to. The SenderID is the name of the system that is sending the message. For inbound, this MUST be the name of the External System the Interface is enabled on. For Outbound, this will be MX (or whatever you have your MXSYSID setup as). For a developer, the key to these two tags is that if you export a record, change it and want to send it back into Maximo to test your interface, then you just have to switch the values of these two tags. The CreationDate tag (line 6) is optional.

INTCLIENT- The Missing Manual

Page 25

Appendix B: RMI URL

To find out what the RMI url is for your server, you need to look at the log file when the application server starts. Just before you get the message that the server is ready, you will see a message about the RMI URL.

In the above sample, see the Bound rmi: line. This what you will use when the IntClient asks for the RML URL.

INTCLIENT- The Missing Manual

Page 26

Appendix C: Errors

Error: UsernamePasswordCredentials class not found Solution: This error occurs when you try to use a web service call. The error appears in the command window (the one that ran the INTCLIENT), but nothing shows up in the INTCLIENT message area or in the application log on the server. Step one is to download two jar files: commons-httpclient-3.1.jar commons-codec-1.3.jar If you google, you can find the files to download for free (they are part of the apache project). Place the two jar files in the %MaximoHome%/applications/maximo/lib folder. Step two is to add these two jars to the classpath for the intclient. Edit the file: %MaximoHome%/tools/maximo/internal/commonEnv.bat (or commonEnv.sh). Search for: set MAXIMO_COMMON_LIBS. Now, at the end of this line, add the following: ;%MAXIMO_LIB_PATH%\commons-httpclient3.1.jar;%MAXIMO_LIB_PATH%\commons-codec-1.3.jar Save the changes. Now restart the intclient and you should be good.

INTCLIENT- The Missing Manual

Page 27