Page 1 IBM Maximo Asset Management 7.1 IBM Tivoli Asset Management for IT 7.1 IBM Tivoli Change and Configuration Management Database 7.1.1 IBM Tivoli Service Request Manager 7.1 Integration Guide...
Page 2 This edition applies to version 7, release 1, modification 0 of IBM Maximo Asset Management, IBM Tivoli Asset Management for IT, and IBM Tivoli Service Request Manager, and version 7, release 1, modification 1 of IBM Tivoli Change and Configuration Management Database and to all subsequent releases and modifications until otherwise indicated in new editions.
Page 4 Object Structure Identification ............33 User Exit Preprocessing .
Page 5 The changed Attribute ..............68 The glorder Attribute .
Page 6 IMPORTMESSAGE Column ............104 TRANSLANGUAGE Column .
Page 7 IBM WebSphere MQ ........
Page 8 Securing Enterprise Bean Access ............179 HTTP Servlet .
Page 9 User Exit Postprocessing ............. . . 217 XSL Mapping .
Page 10 Web Service Deployment Actions............. . . 253 XML Schema Generation .
Page 11 Default Collaboration Switches ..............290 Collaboration Switch Retrieval .
Page 12 Integration Guide...
Page 13: Intended Audience
This guide describes the integration framework and how to configure, integrate, and create business flows between the system and your framework applications. Intended Audience The guide is intended for the following people: Developers Implementation analysts Support personnel System administrators xiii © Copyright IBM Corp. 2007, 2008...
Page 14 Integration Guide...
Page 15 Chapter 2: Integration Framework Architecture Chapter 3: Inbound Integration Processing Chapter 4: Outbound Integration Processing Chapter 5: Integration XML and Schemas Chapter 6: Interface Tables Chapter 7: Message Tracking Chapter 8: Error Management Chapter 9: Basic Configuration © Copyright IBM Corp. 2007, 2008...
Page 17: Chapter 1: What Is The Integration Framework
Support for the integration to operational management products (OMPs). Support for the bulk export of data by using a user-defined SQL query. Support for the bulk imports of XML or flat files. © Copyright IBM Corp. 2007, 2008...
Page 18 Dynamic XML schema generation for all integration interfaces. Dynamic generation of Web Services Interoperability (WS-I) compliant Web services, including Web Service Definition Language (WSDL). Provides the concept of an adapter that is used to group related integration framework components. You can configure and deploy adapters for enterprise connectivity with various external systems.
Page 19: Chapter 2: Integration Framework Architecture
Anyone involved in the implementation or day-to-day administration of the integration framework applications must be familiarized with the integration framework architecture. Familiarity with the architectural concepts is essential for using the application and implementing framework components. © Copyright IBM Corp. 2007, 2008...
Page 20: Integration Framework Overview
The integration framework also provides features that support the integration ® ® with operational management products, such as IBM Tivoli Provisioning Manager. You also can use a system application user interface to launch an external application user interface.
Page 21 Integration Framework Overview Component Description Web services Query message and receive data by the integration framework. Content System content that is configured to enable various integration components. Operational Management Operational management product integration facilitates the automation of Product Integration information technology services, such as software deployment. A process management product calls an integration module which in turn communicates with the operational management product to perform a logical management operation.
Page 22: Integration Framework For Data Exchange
Integration Framework for Data Exchange Component Description Actions You use actions to implement an automated or semi-automated invocation of integration modules and operational management products by a process management product. You can initiate actions from user interface applications, escalations, and workflows. Integration Framework The integration framework provides a mechanism for you to navigate from a for UI Integration...
Page 23: Publish Channels
Integration Framework for Data Exchange The object structure is the building block of the integration framework that lets framework applications to perform the following functions: Publish and query application data Add, update, and delete application data Import and export application data You also can use the object structure as a service to support inbound message processing.
Page 24: Invocation Channels
Integration Framework for Data Exchange Invocation Channels The Service Oriented Architecture (SOA) enables the use of external services to process data from multiple sources. Invocation channels support a generic service-oriented architecture capability by enabling the system to call an external service synchronously.
Page 25: Enterprise Services
Integration Framework for Data Exchange invocation channel can be configured to ignore the response that is returned from the external service and return no data to the caller of the channel. Enterprise Services The enterprise service is a pipeline for querying system data and importing data into the system from an external system.
Page 26: Web Services
Integration Framework for Data Exchange To create an external system, you specify an endpoint, the queues, and the integration control values in the External System application. You can also define the following properties on the external system: The endpoint that identifies how and where the integration framework exchanges data with the system The Java Message Service (JMS) queues that the system uses Whether the external system is ready to begin integration processing...
Page 27: Data Import And Data Export
Integration Framework for Operational Management Product Integration Data Import and Data Export With the integration framework, you can load data from either flat files, such as comma separated, or XML files. You can initiate the data load through an application user interface. You also can start a data load from a scheduled background process by using a system cron task.
Page 28: Action
Integration Framework for Operational Management Product Integration operations and integration modules. The process management product provides an action class that initiates the call to an integration module, and subsequently the operational management product. The process management product then processes the response from the operational management product. Process management product processing can involve saving a value to the system database or displaying the response to you from a user interface, or both.
Page 29: Operational Management Products
® perform information technology services. IBM Tivoli Application Dependency ® Discovery Manager (TADDM), Tivoli Provisioning Manager (TPM), and IBM ® Tivoli Configuration Manager (TCM) are examples of operational management products. Operational management products provide services that external applications (integration modules) can invoke to initiate operational management product actions.
Page 30: Land In Context
Integration Framework for User Interface Integration the classification value of current data being processed in the user interface) Operational management product-specific features including the automatic substitution of operational management product host name, and the configuration item source token into the URL based on configuration item the system processes in the user interface Land in Context You can use the land in context to have an external application open a system...
Page 31 Integration Framework for User Interface Integration Integration Framework Architecture...
Page 32 Integration Framework for User Interface Integration Integration Guide...
Page 33: Chapter 3: Inbound Integration Processing
The integration framework returns a response to the external application that confirms success or failure of the processed message. The integration framework expects all XML messages to be encoded in a Unicode format. © Copyright IBM Corp. 2007, 2008...
Page 34: Asynchronous Inbound Integration Processing
Asynchronous Inbound Integration Processing Asynchronous Inbound Integration Processing The following prerequisites apply to asynchronous inbound processing: All applicable object structures, services, and external systems must be defined. The following entities must be enabled: External system Applicable enterprise services with operations other than QUERY If applicable, the cron task that polls the inbound sequential queue If applicable, the message-driven beans that process messages from the continuous queue...
Page 35: Inbound Integration Process Initiation
Asynchronous Inbound Integration Processing Inbound Integration Process Initiation Summary An external system can use the following methods to send asynchronous messages to the system: Method Availability XML that uses the integration All external systems with enabled framework that uses HTTP Post, enterprise services.
Page 36 Asynchronous Inbound Integration Processing A client can use the Java Naming and Directory Interface (JNDI) name of the Enterprise JavaBean (ejb/maximo/remote/enterpriseservice) to look up the Enterprise JavaBean reference and to invoke the method. The client also needs the following settings: Access to the Home and Remote class files Access to the J2EE jar files for the server The URL of the server that hosts the Enterprise JavaBean...
Page 37 Asynchronous Inbound Integration Processing If the verification fails, the integration framework issues an error and does not process the message. If the verification is successful, the integration framework identifies the inbound JMS queue that is assigned to the enterprise service and the external system.
Page 38: Inbound Queue Message Retrieval
Asynchronous Inbound Integration Processing Data Import Cron Task The following steps describe the initiation of inbound processing that uses a data import cron task. The XMLFILECONSUMER cron task or the FLATFILECONSUMER cron task regularly polls the source directory that is specified in its corresponding configuration.
Page 39: User Exit Preprocessing
Asynchronous Inbound Integration Processing The following framework activities identify the object structures that are associated with the message: The integration framework retrieves the record from the inbound queue. The integration framework identifies the enterprise service from the retrieved record. The enterprise service definition lists the object structures that the processing service uses.
Page 40: Enterprise Service Class Processing
Asynchronous Inbound Integration Processing Output The following table shows the possible user exit preprocessing outcomes. Condition Output No user exit class exists. The unchanged enterprise service. The user exit class skips the record None; processing ends and the (due to non-applicable data). message is deleted from the queue.
Page 41: User Exit Postprocessing
Asynchronous Inbound Integration Processing Condition Output The processing class completes The object structure. successfully, with mapping. User Exit Postprocessing Summary The integration framework applies predefined processing logic in the user exit class to the output from the preceding activity. A user exit processing class typically customizes the object structure after the execution of any predefined enterprise service processing logic.
Page 42: Object Structure Multiplication
Asynchronous Inbound Integration Processing Output The following table shows the possible XSL map processing outcomes. Condition Output No XSL map exists. The unchanged enterprise service. An XSL map exists. The updated enterprise service. The XML message must be in the format that the object structure schema defines.
Page 43: Object Structure Processing Rules
Asynchronous Inbound Integration Processing Object Structure Processing Rules Summary The integration framework applies processing rules to the object structures before it builds the objects. Object structure processing rules define conditions under which the system can skip or stop a message, or change data in the object structure before the objects are created.
Page 44: Object Structure Processing Class
Asynchronous Inbound Integration Processing Output The following table shows the possible object rule processing outcomes. Condition Output No object processing rules exist. The object. The processing rules skip the record. None; processing ends and the message is deleted from the queue. If there are multiple records in one XML file, the class skips the current record and processes the next record.
Page 45: Object Processing
Asynchronous Inbound Integration Processing The same processing class contains the enterprise service user exit preprocessing, enterprise service user exit postprocessing, and user exit object processing methods. Output The following table shows the possible user exit object processing outcomes. Condition Output No user exit processing.
Page 46: Synchronous Inbound Integration Processing
Synchronous Inbound Integration Processing Synchronous Inbound Integration Processing Enterprise services that support query and create operations, return XML content as part of the synchronous response. The response processing layer supports Java and XSL customization, but the response does not support processing rules. Any operation can be processed synchronously, but only query and create operations return data to the caller.
Page 47: Object Structure Identification
Synchronous Inbound Integration Processing You can use the following code to invoke the Enterprise JavaBean to process the enterprise service message synchronously: public byte{} processExternalDataSync(byte[] extData, String serviceName, String sender) A client can use the Java Naming and Directory Interface name of the Enterprise JavaBean (ejb/maximo/remote/enterpriseservice) to look up the Enterprise JavaBean reference and to invoke the method.
Page 48: User Exit Preprocessing
Synchronous Inbound Integration Processing The integration framework inbound integration can process numbers in either standard or scientific notation. To see the processing sequence of multiple object structures associated with an enterprise service, go to the Add/Modify Additional Object Structures dialog box in the Enterprise Services application. Look for the processing order field on the Object Structure Sub-Records table window.
Page 49: Enterprise Service Class Processing
Synchronous Inbound Integration Processing Enterprise Service Class Processing Summary The integration framework applies predefined enterprise service processing logic in the processing class to the enterprise service. The MAXIMO adapter does not provide any predefined enterprise service processing classes. It implements all its integration rules through the object structure processing and processing rules.
Page 50: Object Structure Multiplication
Synchronous Inbound Integration Processing Output The following table shows the possible user exit postprocessing outcomes. Condition Output No user exit class exists. The unchanged enterprise service object. The user exit class skips the record. None; processing ends. If there are multiple records in one XML file, the class skips the current record and processes the next record.
Page 51: Object Structure Processing Rules
Synchronous Inbound Integration Processing in the data, apply the stop action to all of the object structures that are created (every copy of the original object structure). To see if a cross-reference control exists, go to the Enterprise Service tab in the Enterprise Services application.
Page 52: Object Creation
Synchronous Inbound Integration Processing Object Creation Summary The integration framework builds the objects by using the information in the object structure. Output The output of this activity is the objects. Object Processing Rules Summary If specified, the integration framework applies processing rules to the objects it has built, before saving the objects.
Page 53: User Exit Object Processing
Synchronous Inbound Integration Processing Condition Output The object structure class stops the None; processing ends and an error is record. sent to the caller. The predefined enterprise services do not implement the stop action; object structure processing exceptions stop processing. The object structure processing The updated object.
Page 54: Enterprise Service Web Services
Synchronous Inbound Integration Processing For the create operation, the keys of the primary object of the object structure are returned. The entire object structure is returned based on the results of the Query operation. When you use an enterprise service you can implement customizations on the response of the query by using Java and XSL.
Page 55: Object Structure Services
Synchronous Inbound Integration Processing Object Structure Services The following diagram illustrates an overview of the synchronous object structure service processing activities. Inbound Integration Process Initiation Summary An object structure service can use HTTP Post, Enterprise JavaBean invocation, and Web service invocation methods to receive synchronous object structure service messages.
Page 56: Object Structure Identification
Synchronous Inbound Integration Processing Access to the Home and Remote class files Access to the J2EE jar files for the server The URL of the server that hosts the Enterprise JavaBean The context factory class name The client code must instantiate the default IntialContext object. The context derives the provider URL and the context factory from the environment.
Page 57: Object Structure Web Services
Synchronous Inbound Integration Processing Object Processing Summary The objects are passed to the system, and standard system processing is applied. If the system identifies an error in processing, it sends the object structure to the caller of the service. Object Structure Web Services You can access object structure services by using HTTP or an enterprise bean.
Page 58: Standard Services
Synchronous Inbound Integration Processing Standard Services The following diagram illustrates an overview of the synchronous standard service processing activities. Inbound Integration Process Initiation Summary A standard service can be accessed by using an HTTP Post, an Enterprise JavaBean invocation, and a Web service invocation to receive synchronous standard service messages.
Page 59: Standard Web Services
Synchronous Inbound Integration Processing Access to the J2EE jar files for the server The URL of the server that hosts the Enterprise JavaBean The context factory class name The client code must run the default IntialContext object. The context derives the provider URL and the context factory from the environment.
Page 60 Synchronous Inbound Integration Processing Integration Guide...
Page 61: Chapter 4: Outbound Integration Processing
Synchronous messages are not processed through the JMS queue. A direct connection is established between the integration framework and the external application. The external application returns a response to the service invoker that confirms success or failure of message processing. © Copyright IBM Corp. 2007, 2008...
Page 62: Asynchronous Outbound Integration Processing
Asynchronous Outbound Integration Processing Asynchronous Outbound Integration Processing The following prerequisites apply to all asynchronous outbound integrations: All applicable object structures, publish channels, and external systems must be defined. The external systems must be configured with an endpoint. The following entities must be enabled: External systems Applicable publish channels Applicable event listeners...
Page 63: Outbound Integration Process Initiation
Asynchronous Outbound Integration Processing Outbound Integration Process Initiation Summary You initiate the outbound integration process by using event-based activities or by using the data export feature that you access in the External Systems application. Event-based messages are sent when a record is updated using an application or a process such as workflow or escalation.
Page 64: Object Structure Identification
Unique message identifier. creationDateTime System datetime. Output The output of this activity is an object structure with the following format and header data: <PublishObjectStructureName creationDateTime="system" messageID="null" event="0" xmlns:xsi="http://www.w3.org/2001/ XMLSchema-instance" xmlns="http://www.ibm.com/maximo"> <ObjectStructureNameSet> <ObjectName> </ObjectName> </ObjectStructureNameSet> </PublishObjectStructureName> Object Structure Processing Rules Summary Object structure processing rules define conditions under which the system can skip or stop a message.
Page 65: Object Structure Multiplication
The outcome of this activity is one object structure per combination of publish channel and external system. The following format and header data appears: <PublishChannelName creationDateTime="system" messageID="MessageID per external system – publish channel" event="0" xmlns:xsi="http:// www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/ maximo"> <ObjectStructureNameSet> <ObjectName>...
Page 66: Publish Channel Class Processing
Asynchronous Outbound Integration Processing User Exit Preprocessing Summary The integration framework applies the custom processing logic in the user exit class to the object structure. You can use a preprocessing method in a user exit class to manipulate the object structure before any predefined processing takes place on the publish channel.
Page 67: User Exit Postprocessing
Asynchronous Outbound Integration Processing Output The following table shows the possible publish channel class processing outcomes. Condition Output No processing class exists. The existing object structure, unchanged. The processing class skips the record. None; processing ends. The processing class stops the record. None;...
Page 68: Send The Publish Channel Data To The External System
Asynchronous Outbound Integration Processing XSL Map Summary The integration framework applies any custom mapping to the publish channel. XSL mapping lets you map user-defined publish channels or customize the mapping done by predefined publish channel processing classes. Both the object structure and publish channel are available.
Page 69: Synchronous Outbound Integration Processing
Synchronous Outbound Integration Processing Synchronous Outbound Integration Processing As a prerequisite, you must define all applicable object structures and endpoints on the invocation channel. Invocation Channels The following diagram illustrates an overview of the synchronous invocation channel processing activities. Not every activity applies to every outbound message.
Page 70: Request Object Structure Definition
The name of the object structure. messageID Unique message ID. creationDateTime System datetime. Output The output of this activity is an object structure with the following format and header data: <InvokeObjectStructureName creationDateTime="system" messageID="1234444" event="0" xmlns:xsi="http://www.w3.org/2001/ XMLSchema-instance" xmlns="http://www.ibm.com/maximo"> <ObjectStructureNameSet> <ObjectName> </ObjectName> </ObjectStructureNameSet> </InvokeObjectStructureName> Integration Guide...
Page 71: Request Class Processing
Synchronous Outbound Integration Processing Request Class Processing Summary The integration framework applies predefined invocation channel request class processing logic in the processing class to the request object structure. An invocation channel request processing class typically implements additional processing logic and converts data from an object structure format to an invocation channel format.
Page 72: Request Xsl Map
Synchronous Outbound Integration Processing Output The following table shows the possible request user exit preprocessing outcomes. Condition Output No preprocessing method exists. The existing object structure or invocation channel, unchanged. The preprocessing method skips the None; processing ends. record. The preprocessing method stops the None;...
Page 73: Response Class Processing
Synchronous Outbound Integration Processing Response Class Processing Summary The integration framework applies predefined invocation channel response class processing logic in the processing class to the response object structure. An invocation channel response processing class typically implements additional processing logic and converts data from an invocation channel to an object structure format.
Page 74: Response Xsl Mapping
Synchronous Outbound Integration Processing Output The following table shows the possible response user exit preprocessing outcomes. Condition Output No preprocessing method exists. The existing object structure or invocation channel, unchanged. The preprocessing method skips the None; processing ends. record The preprocessing method stops the None;...
Page 75: Chapter 5: Integration Xml And Schemas
XML messages. The content of an XML message is based on the object structure that you associate with a service or a channel. Additionally, the elements are formed based on the service or the channel operation behavior. © Copyright IBM Corp. 2007, 2008...
Page 76: Integration Xml Structure
Integration XML Structure Integration XML Structure The standard format for all integration XML messages that are exchanged through the integration framework is an object structure within a root element. Standard services do not support the use of object structures. For example, the XML has the following format which is based on the PERSON object structure: <syncMXPERSON>...
Page 77: Root Element
Integration XML Content The following operations are available. Create Delete Invoke Publish Query Sync Update Root Element The root element of an XML message contains one or more object structures. The name of the root element is the concatenation of the operation and the name of the associated object structure.
Page 78 Integration XML Content Attribute Description Type Applicable to event The origin of an outbound XML eventType All output operations message. Valid values are: 0 (false)—Generated by the Data Export feature. 1 (true)—Generated by an outbound integration event listener (that is, data entry in an application).
Page 79 Integration XML Content Attribute Description Type Applicable to rsStart In responses to queries: integer Responses (output) This value matches the rsStart value in the corresponding query. If the corresponding query contains a maxItems value, the rsStart value in requests for additional records is rsStart + rsCount + 1.
Page 80 Integration XML Content The following examples illustrate a root element with attributes. <?xml version="1.0" encoding="UTF-8"?> <max:QueryMXPERSON xmlns:max="http://www.ibm.com/maximo" creationDateTime="2008-09-28T21:49:45" baseLanguage="EN" transLanguage="EN" messageID="11876346770938768" maximoVersion=" 7 1 Harrier 060 HARRIER-066" uniqueResult="0" maxItems="201" rsStart="100"> <max:MXPERSONQuery> <max:PERSON> </max:PERSON> </max:MXPERSONQuery> </max:QueryMXPERSON> <?xml version="1.0" encoding="UTF-8"?> <max:QueryMXPERSONResponse xmlns:max="http://www.ibm.com/maximo"...
Page 81: Key Fields
Object Structure Element Object Structure Element Every XML document contains one or more object structure elements. The following table lists the attributes that can apply to the object structure element. All attributes in this table are optional. Attribute Description Type Applicable to action The value is derived from action...
Page 82: Field Attributes
Object Structure Element Field Attributes The following attributes apply at the field level on outbound XML messages: changed glorder langenabled maxvalue maxencrypted These attributes apply to messages that are generated by an outbound integration event. The changed attribute does not apply to messages that are generated by the Data Export feature.
Page 83: The Langenabled Attribute
Object Structure Element In outbound XML the value of a GL type field, including delimiters, appears in the VALUE child element within the field. The outbound XML also places the GL type field components, based on the database definition of the components, in the GLCOMP element.
Page 84: The Maxvalue Attribute
Object Structure Element The maxvalue Attribute Fields that are associated with a synonym type domain can specify the corresponding maxvalue. This value is available for customization or exit processing. It is informational only and is not used for processing. <MXITEM> <ITEM>...
Page 85 Object Structure Element Value Description Null Add records or replace records in the receiving system, depending on whether the primary record exists in the database. The Change, Replace, and AddChange actions differ in the information that they include in the XML message and the processing that they require of the receiving system.
Page 86 Object Structure Element object. If the parent object does not exist in the database, no error is reported to the sending system. Update actions The change and replace actions indicate that the existing database records are updated. The AddChange action can result in an update when the record that is to be processed exists in the receiving system.
Page 87 Object Structure Element AddChange action The AddChange action is like the replace action, except that any existing child record that is not specified in the message is not deleted. An AddChange action on the primary object adds the primary record and all the sub-records that are provided in the message, if the primary record does not exist in the database.
Page 88 Object Structure Element Deletion of POLINE3 and, by default, its child POCOST records Records accompanying In the diagram, the PO with the action value equal to Change or AddChange has the change action records that accompany a change action on the primary PO object. For the sample PO, the following records are sent from sending system: A change action on the PO record (PO 101), due to the changes in its child POLINE and POCOST records...
Page 89 Object Structure Element For the sample PO, the sending system sends the following records. Some may contain updated information; some may contain the same data that are in the database. The PO header POLINE 1 and POCOST lines 1 and 2 POLINE 2 and POCOST lines 1 and 2 The XML message does not include the POCOST 3 record for POLINE 1, or the POLINE 3 record, so the receiving system deletes these records and POLINE 3...
Page 90: Additional Considerations
Object Structure Element Additional Considerations Boolean columns In inbound transactions, a tag that represents a boolean field must contain a value of 0 (false) or 1 (true). If the tag does not contain a 0 or a 1, the object generates an error.
Page 91: Viewing Xml
Integration Schemas Viewing XML To view XML, select the Generate Schema/View XML action from the Select Action menu in the following applications: Enterprise Services Invocation Channels Object Structures Publish Channels You also can view XML on the Web Service Library tab in the Web Services Library application.
Page 92: Xml Validation
System Properties application. The default name space property value is: http://www.ibm.com/maximo If you change the name space property, the system regenerates the MXMeta.xsd file, which contains the core reusable types that the system uses to build all the other schemas.
Page 93: Schema Directory And Files
Integration Schemas Schema Directory and Files The generated schema files are in the subdirectories in the schema directory on the server. Group Subdirectory Description Metadata schema/common/meta Metadata schema file (MXMeta.xsd) Object schema/common/mos Object structure schema files Structure Object schema/common/mbo Object schema files Service schema/service Service level schema files (for...
Page 94: Content, Query Data, And Supporting Data Types
Integration Schemas Group Attributes Applies to QueryContentGroup maxItems The root element of all query input schema rsStart types. uniqueResult ResponseContentGroup rsCount The root element of all response output schema rsStart types. rsTotal Content, Query Data, and Supporting Data Types The following tables list the content, query data, and supporting data types. Type Description Attributes...
Page 95 Integration Schemas Type Description Attribute MXBooleanQueryType Extension of integer operator MXDateTimeQueryType Extension of dateTime operator MXDomainQueryType Extension of string operator maxvalue MXDoubleQueryType Extension of double operator MXFloatQueryType Extension of float operator MXGLAccountQueryType Complex type with value “VALUE” operator MXGLComponentQueryType Extension of string operator MXIntQueryType Extension of integer...
Page 96: Object Structure Schemas
Integration Schemas Object Structure Schemas Object structure schemas define the content of an object structure. Each object structure has a distinct schema that includes all the configured persistent and nonpersistent fields that are defined for each object in the structure. Object structure schemas are not used directly as input or output for any service.
Page 97 Integration Schemas These elements are referenced in service level schemas and only the MXPERSON and MXPERSONSet can be outside the context of a service level schema. For example, internal applications such as Deployment Manager use schemas comparable to MXPERSON and MXPERSONSet. Integration users must use object structure services within the context of a service level schema.
Page 98: Object Schemas
Integration Schemas Object query content You can use query elements only within the context of a service level schema. The following content format is in the object query element: Element MXPERSONQuery is type MXPERSONQueryType. Complex type MXPERSONQueryType has elements for all the configured attributes of the top object (PERSON) of the object structure.
Page 99: Schema Generation
Integration Schemas Schema Generation The system generates the files when you generate the following components: Object structure schema that contains the object Object structure service or enterprise service schema where the object structure referenced by the service includes the object Standard service schema that contains the object All object schemas include the MXMeta.xsd schema file.
Page 100: Service Level Schemas
Integration Schemas Service Level Schemas Service level schemas apply to enterprise services, object structure services, and standard services. The same schema describes enterprise services and object structure services. A different schema describes standard services. Enterprise services, object structure services, and standard services use objects and object structures as input and output for the operations they support.
Page 101: Standard Services
Integration Schemas InvokeMXPERSON InvokeMXPERSONResponse PublishMXPERSON QueryMXPERSON QueryMXPERSONResponse SyncMXPERSON UpdateMXPERSON Standard Services Standard services are the services that applications provide for performing specific operations on objects. Each service might have multiple methods that can be exposed as Web services. Standard services are available only for methods that are properly annotated within the service.
Page 102: Object Structure And Enterprise Services
Integration Schemas Standard Service Output The following diagram shows the pochangeStatusResponse (type = pochangeStatusResponseType) output. For this example, the response of the method is the PO object. Object Structure and Enterprise Services The object structure definition contains the content for both object structure and enterprise services.
Page 103 Integration Schemas CreateMXPERSON The following diagram represents the content of the CreateMXPERSON element: Element The CreateMXPERSON element is type CreateMXPERSONType. The CreateMXPERSONType has element MXPERSONSet, which is type MXPERSONSetType. MXPERSONSet is derived from the object structure schema. MXPERSONSetType has elements for all the configured attributes of the PERSON object and elements for the child objects (PHONE, EMAIL, and SMS) that are defined in the object structure.
Page 104 Integration Schemas Create The following diagram represents the content of the CreateMXPERSONResponse MXPERSONResponse element: Element Element CreateMXPERSONResponse is type CreateMXPERSONResponseType. The CreateMXPERSONResponseType has element PERSONMboKeySet, which is type of PERSONMboKeySetType. PERSONMboKeySetType has element PERSON, which is type PERSONKeyType. The PERSONKeyType contains only the PERSONID attribute of the PERSON object (the Primary Key of the PERSON).
Page 105 Integration Schemas DeleteMXPERSON The following diagram represents the content of the DeleteMXPERSON element: Element Element DeleteMXPERSON is type DeleteMXPERSONType. The DeleteMXPERSONType has element MXPERSONDelete, which is type MXPERSONDeleteType. MXPERSONDeleteType has elements for all the configured attributes of the PERSON object. Delete supports only the top object of the object structure (PERSON).
Page 106 Integration Schemas PublishMXPERSON The following diagram represents the content of the PublishMXPERSON element: Element Element PublishMXPERSON is type PublishMXPERSONType. The PublishMXPERSONType has element MXPERSONSet, which is type MXPERSONSetType. MXPERSONSet is derived from the Object Structure Schema. MXPERSONSetType has elements for all the configured attributes of the PERSON object and elements for the child objects ((PHONE, EMAIL, and SMS) defined in the object structure.
Page 107 Integration Schemas QueryMXPERSON The following diagram represents the content of the QueryMXPERSON element: Element The QueryMXPERSON element is type QueryMXPERSONType. QueryMXPERSONType has element MXPERSONQuery, which is type MXPERSONQueryType. MXPERSONQueryType has elements for all the configured attributes of the PERSON object. Query supports only querying against the top object of the object structure (PERSON).
Page 108 QueryMXPERSONRespo The following diagram represents the content of the QueryMXPERSONResponse nse Element element: Element QueryMXPERSONResponse is type QueryMXPERSONResponseType. The QueryMXPERSONResponseType has element MXPERSONSet, which is type MXPERSONSetType. MXPERSONSetType has elements for all the configured attributes of the PERSON object and elements for child objects defined in the object structure (PHONE, EMAIL, and SMS).
Page 109: Chapter 6: Interface Tables
A single external system can transfer outbound data by using either XML messages, interface table flat messages, or both. You can assign an endpoint value to an external system at the publish channel level. © Copyright IBM Corp. 2007, 2008...
Page 110: Location Of Interface Tables
Location of Interface Tables Location of Interface Tables The endpoint definition for an external system or a publish channel points to the database where its interface tables are stored. The database can be a local database or a remote database. The predefined interface table endpoint (MXIFACETABLE) points to the local database, and you can add endpoints for remote databases.
Page 111: Creation Of Interface Tables
Creation of Interface Tables The sequence of TRANSID identifies the sequence in which records are processed by the integration framework. For example, when employees and their phone numbers are entered into the system, the TRANSID values for the PO record must be lower than the TRANSID values for the PO receipt records that reference that The primary difference between the MXIN_INTER_TRANS and MXOUT_INTER_TRANS queue tables is the direction of the interface table...
Page 112: Regeneration Of Interface Tables
Regeneration of Interface Tables Regeneration of Interface Tables When columns are added or deleted from the system database tables, you must regenerate all local and remote interface tables that are associated with those object structures. You regenerate interface tables by using the Create Interface Tables option on the Select Action menu in the External Systems application.
Page 113: Key Columns
Format of Interface Tables Format of Interface Tables The format of an interface table is the same as the format of the corresponding object structure. The interface table includes the persistent and nonpersistent columns that are included in the object structure. The interface table excludes the columns that are excluded from the object structure.
Page 114: Restricted Columns
Format of Interface Tables Restricted Columns The HASLD field, which is an internal system column, is excluded from all object structures. Do not include this column in any object structure that is associated with an interface table. The LANGCODE field is also excluded from the predefined object structures.
Page 115 Format of Interface Tables For example, assume that you create a purchase order with one line item. This transaction uses the predefined MXPOInterface, and it increments the TRANSID value that is associated with the MXOUT_INTER_TRANS queue table to 1065. The transaction produces the following records: One entry in the MXOUT_INTER_TRANS queue table, with the IFACENAME value equal to the MXPOInterface value, and the TRANSID value equal to 1065.
Page 116: Transseq Column
Format of Interface Tables The data in the MXOUT_INTER_TRANS queue table directs the external system to process the interface table records in the following sequence. Sequence Interface Table Identifier (TRANSID) of Record in Interface Table MXPR_IFACE 1001 MXITEM_IFACE 1002 MXINVENTORY_IFACE 1003 MXITEM_IFACE 1004...
Page 117: Extsysname Column
Format of Interface Tables For example, if a purchase order has three line items, that transaction might produce the following records: One entry in the MXOUT_INTER_TRANS queue table, with the IFACENAME value equal to the MXPOInterface value, and the TRANSID value equal to 1065.
Page 118: Importmessage Column
Format of Interface Tables The system populates the ACTION column in the outbound messages. If the external system does not populate the column in the inbound messages, the integration framework tries to retrieve and replace the corresponding database record. If the record does not exist, the integration framework tries to add it to the database.
Page 119: Interface Table Polling
Interface Table Polling Interface Table Polling A predefined cron task, IFACETABLECONSUMER, polls the MXIN_INTER_TRANS queue table and uses the IFACENAME, EXTSYSNAME, and TRANSID values in the queue table to place the corresponding interface table records into the appropriate inbound JMS queue. Then, individual records in the JMS queue are processed.
Page 120: Configuring External Systems
Configuring External Systems Configuring External Systems To use interface tables, you must create the tables and configure the IFACETABLECONSUMER cron task. Overall Processing To configure the external systems to perform general interface queue table and interface table processing: Define procedures to restore the backups of the interface tables. Create interface tables in the user interface.
Page 121 Configuring External Systems Outbound Processing To configure the external system to perform outbound interface queue table and inbound interface table processing: Set up a process to retrieve interface table transactions by using the MXOUT_INTER_TRANS queue table. You can use a polling program, a trigger, or any other mechanism.
Page 122 Configuring External Systems Integration Guide...
Page 123: Chapter 7: Message Tracking
When you use the Message Tracking application, you can determine which messages are flagged with an error. You then can select a failed message and go to the Message Reprocessing application to take appropriate action to correct erroneous data. © Copyright IBM Corp. 2007, 2008...
Page 124: Message Details
Message Details Message Details When you enable message tracking, the integration framework writes all processed messages to the MAXINTMSGTRK table. The system assigns a status to each message which represents its current position in the queue-based processing cycle. Individual message events are displayed in the Message Details table window.
Page 125: Message Tracking Configuration
XML message. To guarantee uniqueness in the messages that are tracked, the integration framework assigns an external message identifier. The system stores the external message identifier as the EXTMSGIDFIELDDATA attribute in the MAXINTMSGTRK table. © Copyright IBM Corp. 2007, 2008...
Page 126: Multi-Noun Message And External Message Id
Message Tracking Configuration To find all messages for the MXPERSONInterface enterprise service, create the following fully qualified XPATH expression as the External Message ID: /{http://www.ibm.com/maximo}SyncMXPERSON/@messageID Multi-noun Message and External Message ID When a multi-noun inbound message is received, the integration framework uses the enterprise service External Message ID XPATH to identify the message.
Page 127: Message Statuses
The Message Tracking application tracks and displays inbound and outbound queue-based transaction processing events. Transaction processing events trigger the system to update the MAXINTMSGTRK table. The following message table attributes are updated according to event type: STATUS STATUDATETIME ERRORMSGR © Copyright IBM Corp. 2007, 2008...
Page 128: Tracked Inbound And Outbound Events
Message Events Tracked Inbound and Outbound Events The following inbound and outbound events update the MAXINTMSGTRK table: Event Details Message is written to queue A record is created in the message tracking table when the integration framework first writes the message to the queue. When the message is successfully written to the queue, the message record status is set to RECEIVED.
Page 129: Chapter 8: Error Management
You can view, correct, cancel, and reprocess the erroneous messages. Error messages can be managed without the need to access error files on the application server. © Copyright IBM Corp. 2007, 2008...
Page 130: Queue Error Management
Sends a notification to a specified e-mail account, informing the recipient that an error occurred. On an IBM WebSphere Application Server environment, the integration framework sends an additional e-mail message to the specified e-mail account each time that you successfully restart your application server.
Page 131: Interface Table Error Management
Interface Table Error Management Interface Table Error Management Errors can occur in the following two stages when inbound interface tables are processed: Writing data from the interface table to the queue Processing data from the queue into the integration framework The integration framework does not apply any business rules to the inbound interface table records as it writes them to the inbound JMS queue.
Page 132: Error Management Configuration
Error Management Configuration Error Management Configuration Error management requires the configuration of the following properties before use. System Properties Configuration The following error management properties are configurable in the System Properties application. mxe.int.adminfromemail This property specifies the from address that appears in error notifications that are submitted by the integration framework, for example, MXINTADM@ZZZ.com.
Page 133: External Systems Configuration Properties
Error Management Configuration External Systems Configuration Properties The following error management properties are configurable in the Add/Modify Queues action in the External Systems application: Maximum Try Count This property specifies the number of times that the system tries to reprocess an error.
Page 134: Error Notification
Error Notification Error Notification When an inbound or outbound transaction results in an error in a queue, the application sends an e-mail notification to the system administrator only if no other errors are awaiting correction in the same queue. The notification informs the system administrator that the queue contains one or more transactions with errors.
Page 135: Message Reprocessing
Message Reprocessing Message Reprocessing When you use the Message Reprocessing application, you can manage and view integration messages that are flagged with an error. You can view the error XML file without accessing the integration server error files. Failed messages can be managed in the following ways in the Message Reprocessing application: Change the message statuses to stop message processing or to reprocess a message...
Page 136: Error Correction
<ERROR> <ERRORMESSAGE>Error occurred while processing PO (Object Structure number 1). Error is:[system:unknownerror] An unknown error has occurred. Please contact your system administrator for assistance. null</ERRORMESSAGE> <ER> <SyncMXPO xmlns="http://www.ibm.com/maximo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDateTime="2007-05-22T14:04:03-04:00" transLanguage="EN" baseLanguage="EN" messageID="11798570432187483" maximoVersion="7 1 Harrier 038a HARRIER-042" event="1" messageid="11798570432652428">...
Page 137: Process Message
Message Reprocessing HARRIER-042" event="1" messageid="11798570432652428"> <MXPOSet> <PO action="Update"> </PO> </MXPOSet> </SyncMXPO> </IR> </ERROR> Process Message After you complete your error XML changes in the Error Data window, you can resubmit the message. The application then starts reprocessing the message. The following actions are performed when the message is successfully processed: The error file is deleted The record in the MAXINTERRORMSG table is deleted The DELETEFLAG, CHANGEBY, and CHANGEDATE attributes in the...
Page 138: Message Deletion
Common Causes of Errors Message Deletion You can choose to delete a message from a queue. After you delete a message, the system cannot reprocess it. When the system deletes the message, the record is deleted from the MAXINTERRORMSG and MAXINTERROR tables. The application refreshes the result set and omits the deleted message listing on the main tab of the Message Reprocessing application.
Page 139: Error Research
Common Causes of Errors Error Type Description Actions Communication error Caused by communication problems with the Restore communication with the external system from system failures or external system. network issues. Message error Caused by erroneous message data values. Change the transaction status to HOLD.
Page 140 MXPERUSERInterface publish channel, the system generates a MX_MXPERUSERInterface file. The file contains the following original outbound message content. <?xml version="1.0" encoding="UTF-8" ?> <PublishMXPERUSER creationDateTime="2007-12-04T13:21:03-05:00" transLanguage="EN" baseLanguage="EN" messageID="11967924643281249" maximoVersion="7 1 082 V7100-001" event="0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/maximo"> <MXPERUSERSet> <PERSON> <ACCEPTINGWFMAIL>0</ACCEPTINGWFMAIL> <ADDRESSLINE1>760 Unity Blvd.</ADDRESSLINE1> <ADDRESSLINE2 /> <ADDRESSLINE3 /> <BILLTOADDRESS />...
Page 141: Non-Queue Error Management
Non-queue Error Management Non-queue Error Management Synchronous integration scenarios require continuous communication between the system and external applications. These synchronous scenarios do not require a messaging queue mechanism. Non-queue error management is necessary when an error occurs when a message is being processed by the integration framework or by the system.
Page 142 Non-queue Error Management Integration Guide...
Page 143: Chapter 9: Basic Configuration
You can either work with pre- existing integration components, or user-defined components to meet your business needs. Before you start the basic configuration, create and configure the Java Message service (JMS) queues on your application server. © Copyright IBM Corp. 2007, 2008...
Page 144: Predefined Components And Queues
Predefined Components and Queues Predefined Components and Queues The following integration components are predefined: An external system (EXTSYS1) An adapter (MAXIMO) Object structures Enterprise services Publish channels Endpoints In addition, the following JMS queues are defined: Inbound sequential (sqin) Inbound continuous (cqin) Outbound sequential (sqout) Error continuous (cqinerr) You can use the predefined queues for development and production.
Page 145: Integration Framework Administration
Integration Framework Administration Integration Framework Administration The integration framework specifies the following system properties, some of which have default values that you should consider updating: System user name Global directory Update SENDERSYSID setting Administrator e-mail address Sender e-mail address The following table describes the framework properties. You can update the following properties in the System Properties application.
Page 146: Jms Queues
JMS Queues Property Description mxe.int.resolveschema A true property value indicates the service schema does not have any references to other schema documents; all schema dependencies are resolved for service schemas. The default value is 0. mxe.int.wsdlincludesschema When you set this property value to true, the Web Service Definition Language (WSDL) files contain the complete service schema definition.
Page 147: Queue Properties
JMS Queues Queue Properties The maximum try count property represents the number of times the system retries to process a failed message before sending an e-mail notification. The maximum try count default value is 5; the integration framework retries a failed message five times.
Page 148: Xmlfileconsumer Cron Task Processing Properties
JMS Queues Parameter Description ENTERPRISESERVICE A required parameter value that identifies the enterprise service name that the cron task uses to process all files that are located in the source directory. FILENAME An optional parameter value that determines whether the cron task data load process selects source files based on its file name.
Page 149: Flatfileconsumer Cron Task Parameters
JMS Queues committed to the queue. Index files are available in the RECOVERY folder which is created in the cron task source directory. The XMLFILECONSUMER cron task uses the index file name to identify the file that was processed before the server or queue problem was encountered. The cron task continues to process the XML file starting at the last successfully committed noun in the index file.
Page 150: Integration Components
Integration Components File split - Multi-noun files that are processed by the FLATFILECONSUMER cron task are split before they are written to the queue. The cron task identifies if the file that is loaded is a multi-noun XML file. If the XML file is a multi-noun file, the integration framework uses the enterprise service key columns to identify where the file split occurs.
Page 151: Endpoints
Integration Components Use the Select Action menu in the External Systems application to perform the following configuration activities: Configure external system integration controls and assign system-level default values. Create external system interface tables. Create and configure a queue. Endpoints Your outbound transactions (publish channels or invocation channels) for your business processes need endpoint values.
Page 152: Configuring Publish Channels
The XPATH expression indicates where the integration framework splits the multi-noun messages with an XML definition. For example, the following XPATH expression shows a Split Tag field value: {http://www.ibm.com/xmlns/prod/tivoli/swkb}SoftwareCatalog/ Products/Product The bracketed content represents the namespace value. You must provide the namespace value for all tags that are assigned a namespace.
Page 153: Configuring Invocation Channels
Integration Components Configure the publish channel integration controls and assign the default values. Generate the schema files to describe the publish channel. Enable and disable the listener for the outbound integration events Publish channel configuration is required if you are working with external system and queue-based integration scenarios.
Page 154 Integration Components Integration Guide...
Page 155 Chapter 16: Integration Framework Customization with Java and XSL Chapter 17: Integration Component Additions and Modifications Chapter 18: Integration Queries Chapter 19: Integration Web Services Chapter 20: Multiple Language Support Chapter 21: Integration Modules Chapter 22: Launch-in-Context Feature © Copyright IBM Corp. 2007, 2008...
Page 157: Chapter 10: Endpoints And Handlers
(for a publish channel message only) and override values for the configured endpoint properties. The handler then sends the data to the destination that is specified by the endpoint with which the handler is associated. © Copyright IBM Corp. 2007, 2008...
Page 158: Configuring Endpoints
Endpoints Endpoints An endpoint represents an application component to which the system delivers outbound transactions. The following table lists the system available endpoints. Endpoint Handler Description MXFLATFILE FLATFILE Writes flat files to a specified directory location. MXIFACETABLE IFACETABLE Writes outbound transactions to local interface tables.
Page 159: Handlers
The CONTEXTFACTORY uses the following property when the target client runs on an IBM WebSphere Application Server: com.ibm.websphere.naming.WsnInitialContextFactory EJBEXIT Property This optional property is used for customization. This property specifies the fully qualified name of a custom Java class that implements the EJBExit interface.
Page 160 The following required property specifies the name by which the enterprise bean client is registered in the application server Java Naming and Directory Interface (JNDI) tree. Server File name Property ibm-ejb-jar-bnd.xml <ejbBindings xmi:id="Session_enterpriseservice_Bnd" WebSphere jndiName="ejb/maximo/remote/enterpriseservice"> Application Server <enterpriseBean xmi:type="ejb:Session" href="META-INF/ejb- jar.xml#Session_enterpriseservice"/>...
Page 161: Flatfile Handler
Handlers The following example is an IBM WebSphere Application Server provider URL. corbaloc:iiop:hostname:iiopport If the handler and the target enterprise bean are running on the same application server instance, do not specify this property because it defaults to the local server URL.
Page 162: Flat File Formatting
Handlers Flat File Formatting If the data in the flat file contains the flat file delimiter character, the data adds the text qualifier, which is " (quotation marks). If the data contains quotation marks, the handler escapes the quotation marks. You cannot use quotation marks as the delimiter character.
Page 163 Handlers HTTPEXIT Property This optional property is used for customization. This property specifies the fully qualified name of a Java class that interprets the HTTP response. This property also helps implement the code that is required for an external system to interpret the HTTP response.
Page 164: Ifacetable Handler
Handlers getHeaderProperties() This method has the following signature: public Map String, String getHeaderProperties(Map String,? metaData, byte[] data, Map String,MaxEndPointPropInfo httpInfo) This method returns a map of the HTTP header properties for the request. The default implementation returns a null value unless a header property map is associated with the metadata map that has the HEADERPROPS key.
Page 165: Jms Handler
Handlers A value of 0 (false) indicates that the interface tables are available in the local system database in the system schema. You do not have to enter any other handler properties. For the predefined MAXIFACETABLE handler, the value of this property is 0.
Page 166 The messaging system represents a queue or topic that is available on the local application server, a remote application server, or a remote dedicated queuing system such as IBM WebSphere MQ. To use this handler, enable the messaging systems by using JMS.
Page 167: Webservice Handler
Handlers JMSEXIT Property This optional property is used for customization. It specifies the fully qualified name of a Java class that runs the JMSExit interface. The Java class must implement the getMessageProperties() method that is defined in the JMSExit interface. You can use this option change or add properties in the JMS message.
Page 168: Xmlfile Handler
Handlers HTTPVERSION Property This optional property specifies the version of the HTTP protocol for Web service invocations. The valid values are HTTP/1.0 and HTTP/1.1. If you do not provide a value, the system uses the default value, HTTP/1.1. HTTPCONNTIMEOUT This optional property specifies the connection timeout value in milliseconds. The Property default value for this property is 60000 milliseconds.
Page 169: Cmdline Handler
Handlers For example, the file name MX_MXASSETInterface_10971102668641398.xml indicates that the file was generated from a system to send data to the external system EXTSYS1. The file name also indicates that the file contains the MXASSETInterface publish channel. CMDLINE Handler The CMDLINE handler is a handler that takes a command and an endpoint as input.
Page 170: Writing Custom Handlers
Writing Custom Handlers The following tags are available: CLWORKINGDIR – A directory to change ( ) to on the remote system before the command is run. CLSSETUPCMD – A setup command to be run before the main command. Use this tag for any environmental setup that must occur on the remote system before the main command is issued.
Page 171 Writing Custom Handlers The following method sends data to the specified endpoint. Metadata provides information about the external system and the interface. Data is the XML data. DestinationMap specifies the endpoint. sendData(Map metaData, byte[] data, Map destinationMap) The handler class displays the properties for which you must specify values. The FTPHandler.java file in the psdi.iface.samples directory contains an example of the handler.
Page 172 Writing Custom Handlers Integration Guide...
Page 173: Chapter 11: Advanced Interface Table Polling
If you send inbound messages through the continuous Java Message Service (JMS) queue and do not require messages to be maintained in first-in-first-out sequence, you can improve the performance of interface table polling. © Copyright IBM Corp. 2007, 2008...
Page 174: Cron Tasks
Cron Tasks Cron Tasks The interface table polling process uses a single default cron task called IFACETABLECONSUMER. This cron task reads all messages from all interface tables for all external systems that write to the tables. Configuring Cron Tasks For improved performance on single-server and multi-server environments, you can configure multithreaded interface table polling by defining multiple instances of the IFACETABLECONSUMER cron task with different property values.
Page 175: Queue Tables
Queue Tables To list multiple interface names in the ENTERPRISESERVICE property: Set ENTERPRISESERVICE=MXPOInterface|MXPRInterface|… Requirements for configuring multiple instances of the cron task: The selectors must be mutually exclusive, so messages are not processed multiple times. The selectors must retrieve all the enterprise service transactions that you use, so no messages are left unprocessed.
Page 176 Queue Tables Integration Guide...
Page 177: Chapter 12: Jms Queue Configuration
Your JMS queue implementation can operate on a single application server or across a cluster of application servers. There are three default message queues: One outbound sequential queue and two inbound queues One sequential One continuous © Copyright IBM Corp. 2007, 2008...
Page 178: Creating And Configuring A Queue
Creating and Configuring a Queue Creating and Configuring a Queue You can use separate queues, one for each external system that you use. Queues can be configured for use with publish channels and enterprise services that integrate with one or more external systems. Queue creation and configuration involves multiple steps.
Page 179: Sequential Queues
Sequential Queues Configure your external system and enterprise services to use the queues. To enable message processing, you must configure the consumers value of the message queue. The system processes the messages after they are written to the queue. Sequential Queues The sequential queue is a JMS queue with a system cron task as a consumer.
Page 180: Enabling Message Beans
To enable the message beans, uncomment the following lines in the ejb-jar.xml file which is located in the ...\applications\maximo\mboejb\ejbmodule\META- INF\ folder. The code changes apply to both IBM WebSphere Application Server and WebLogic Server environments. <!-- MEA ejb for MDB <message-driven id="MessageDriven_JMSContQueueProcessor_1">...
Page 181: Continuous Queue Performance
Continuous Queue <max-beans-in-free-pool>3</max-beans-in-free-pool> </pool> <destination-jndi-name>jms/maximo/int/queues/cqin</ destination-jndi-name> <connection-factory-jndi-name>jms/maximo/int/cf/intcf</ connection-factory-jndi-name> </message-driven-descriptor> <transaction-descriptor> <trans-timeout-seconds>600</trans-timeout-seconds> </transaction-descriptor> <jndi-name>JMSContQueueProcessor-1</jndi-name> </weblogic-enterprise-bean> --> Continuous Queue Performance You can improve performance by increasing the number of message-driven beans for a particular queue and by introducing additional application servers in a cluster.
Page 182: Weblogic Server
Continuous Queue Select intjmsact. Specify a value in the Maximum Concurrent End Points field. WebLogic Server By default, the WebLogic Server is configured to have three message-driven beans. Use the values shown in bold to configure the number of message-driven beans in the weblogic-ejb-jar.xml file: <!-- MEA MDB <weblogic-enterprise-bean>...
Page 183: Continuous Queue Errors
Continuous Queue Continuous Queue Errors You can use different application server configurations to manage error messages. When you are loading a large volume of messages, you can encounter a large number of errors. The continuous queue continues to reprocess the messages at the top of the queue that are in error instead of new messages that are being added to the queue.
Page 184: Weblogic Server
<method> <ejb-name>JMSContQueueProcessor-2</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Required</trans-attribute> </container-transaction> --> You also need to uncomment the following code in the ibm-ejb-jar-bnd.xmi to enable the message-driven beans on the error queue. <!-- MEA MDB for error queue <ejbBindings xmi:type="ejbbnd:MessageDrivenBeanBinding" xmi:id="MessageDrivenBeanBinding_1" activationSpecJndiName="intjmsacterr"> <enterpriseBean xmi:type="ejb:MessageDriven" href="META-INF/ ejb-jar.xml#MessageDriven_JMSContQueueProcessor_2"/>...
Page 185: Queue Message Format
Continuous Queue For example, when you set the batch size property to -1 (unlimited), and the redelivery delay property to 30 seconds (30,000 milliseconds), new messages can be processed in the queue. Processing continues even when a large number of errors are being reprocessed.
Page 186: Message Body
Queue Selectors Properties Description compressed Indicates whether the message is compressed. Values can be true or false; the default value is false. The standard Java Inflater and Deflater APIs (java.util.zip) are used for compression. uncompressed_length Stores the original message payload size before compression.
Page 187: Queue Utilities
Queue Utilities Applying selectors splits a queue into smaller queues, each of which contains a subset of data that each cron task or message-driven bean uses. An error in one subset of the data does not stop processing in the others in a sequential queue. While selectors provide flexibility in separating the processing of transactions, they impair the performance of poll processing.
Page 188: Ibm Websphere Mq
IBM WebSphere MQ You can use IBM WebSphere MQ as a standard for your queuing activities. The integration framework supports WebSphere MQ Version 6. Before you use the WebSphere MQ for any queuing activities, you must familiarize yourself with WebSphere MQ configurations and implementations.
Page 189: Configuring The Integration Queues And Websphere Mq Provider
IBM WebSphere MQ Configuring the Integration Queues and WebSphere MQ Provider You can replace the integration framework queues with the WebSphere MQ queues. The queue setup is supported when you configure the WebSphere Application Server and the integration framework queue definitions.
Page 190 IBM WebSphere MQ Integration Guide...
Page 191: Chapter 13: Security
Security can be set at a user level; user identification and password authentication is necessary for queue access. Security can also be set at a component level, which controls access to component or method calls. © Copyright IBM Corp. 2007, 2008...
Page 192: Integration Queue
Integration Queue Integration Queue The Java Message Service (JMS) queues that are used by integration processing support basic J2EE security (user ID and password-based authentication and authorization). You can prevent unauthorized access to the queue by assigning a user ID and password to the Java Naming and Directory Interface (JNDI) Name, even if the JNDI name of the queue is known.
Page 193: Enterprise Bean Access
Enterprise Bean Access Under the <assembly-descriptor> section in the ejb-jar.xml file, add the following elements shown in bold text: <assembly-descriptor> <security-role> <role-name>maximouser</role-name> </security-role> <container-transaction> <method> <ejb-name>JMSContQueueProcessor-1</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Required</trans-attribute> </container-transaction> </assembly-descriptor> Enterprise Bean Access The integration gateway implements an Enterprise JavaBean (EJB) as the entry point for receiving data from an external system.
Page 194 Enterprise Bean Access <ejb-class>psdi.iface.gateway.MEAGatewayBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> env-entry> <env-entry-name>ALLOWDFLTLOGIN</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>1</env-entry-value> </env-entry> <security-role-ref> <description> Application Users </description> <role-name>maximouser</role-name> <role-link>maximouser</role-link> </security-role-ref> </session> <session id="Session_mosservice"> <ejb-name>mosservice</ejb-name> <home>psdi.iface.mos.MOSServiceHome</home> <remote>psdi.iface.mos.MOSServiceRemote</remote> <local-home>psdi.iface.mos.MOSServiceHomeLocal</local-home> <local>psdi.iface.mos.MOSServiceLocal</local> <ejb-class>psdi.iface.mos.MOSServiceBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> <env-entry> <env-entry-name>ALLOWDFLTLOGIN</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>1</env-entry-value> </env-entry> <security-role-ref> <description> Application Users </description> <role-name>maximouser</role-name>...
Page 195: Http Servlet
HTTP Servlet Client programs call the secure version of the enterprise bean methods for each service type: Enterprise Service: secureProcessExtnernalDataAsync(..) , secureProcessExtnernalDataSync(..) Object Structure Service: secureProcessMOS(..) Standard Service: secureAction(..) To create a secure context for invoking the enterprise bean, do either one of the following procedures: Add the following sample code to the client code: Properties env = new Properties();...
Page 196 HTTP Servlet blocks, one for each type of service: enterprise service, object structure service, and standard service. The <web-resource-name> to service mapping is: <web-resource-name> Service Enterprise Service Servlet Enterprise Service App Service Servlet Standard Service Object Structure Service Servlet Object Structure Service The following integration servlet code samples have the security constraint comment sections removed for each service type.
Page 197: Securing Web Services
Web Services <web-resource-name>Object Structure Service Servlet</web- resource-name> <description>Object Structure Service Servlet (HTTP POST) accessible by authorized users</description> <url-pattern>/os/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <description>Roles that have access to Object Structure Service Servlet (HTTP POST)</description> <role-name>maximouser</role-name> </auth-constraint> <user-data-constraint> <description>data transmission gaurantee</description> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint>...
Page 198: Remote Integration Apis (Micservice)
Remote Integration APIs (MicService) Use the following the security-constraint block for a Web service servlet. <security-constraint> <web-resource-collection> <web-resource-name>Integration Web Services</web- resource-name> <description>Integration Web Services accessible by authorized users</description> <url-pattern>/services/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <description>Roles that have access to Integration Web Services</description>...
Page 199: Interface Table Security
Interface Table Security processObjectStructure(..) routeData(..) To run these methods, the caller must retrieve a valid UserInfo object and pass it to the method to gain access to the secure layer. A UserInfo object is a serialized object that contains user details (user, password, locale, language, and time zone information).
Page 200 Object-Level Authorization For example, you can assign the status option to the changeStatus method of the PO standard service. To run the standard service by using HTTP, enterprise bean, or SOAP, you need authorization to the STATUS option. Standard service authorization does not support the use of a condition that you associate with the signature option.
Page 201: Chapter 14: Cluster Configuration
When you implement a cluster, you can use multiple servers simultaneously to process inbound messages. These messages are processed in the continuous queues by using message-driven beans (MDBs). Cluster configurations facilitate the processing of messages in large volumes. © Copyright IBM Corp. 2007, 2008...
Page 202: Configuring The Cron Task
Configuring the Cron Task Configuring the Cron Task The interface table cron task, the data import cron task, and the Java Message Service (JMS) queue cron task are cluster-aware functions. By default, the cron task framework runs a task on a randomly chosen server. If you want to configure your cron task to run on a specific application server within your cluster, configure the cron task as shown in the following example.
Page 203: Jms Queues
JMS Queues JMS Queues In a cluster configuration, the JMS queues are associated with one member of the server cluster. Access to the queues is provided by the Java Naming and Directory Interface (JNDI) service. The JDNI service is available across all the members on the cluster as shown in the following diagram.
Page 204: Websphere Application Server Continuous Queue Cluster
JMS Queues WebSphere Application Server Continuous Queue Cluster The following diagram shows one example of a cluster configuration on the IBM WebSphere Application Server. The diagram is an example of a continuous queue integration bus configuration in a cluster of three application servers. To gain the benefit of multi-server processing within a cluster, each member of the cluster needs to be configured with its own message engine.
Page 205 JMS Queues Integration cron tasks deliver enterprise service messages from flat or XML files and interface tables. The cron task places messages into the queue store on the server where the cron task is running, which limits the processing to a single server.
Page 206: Websphere Application Server Sequential Queue Cluster
JMS Queues WebSphere Application Server Sequential Queue Cluster The following diagram shows one example of a cluster configuration on the WebSphere Application Server. The sequential queue receives JMS producer messages and processes the JMS consumer messages. A sequential queue integration bus cluster consists of three application servers and one message engine on a single application server.
Page 207: Weblogic Server Continuous Queue Cluster
JMS Queues Unlike the continuous queue, there is no multi-threading of messages. A cluster implementation does not significantly impact the processing performance of messages that are processed through the sequential queue. WebLogic Server Continuous Queue Cluster The following diagram shows one example of a cluster configuration on the WebLogic Server.
Page 208: Weblogic Server Sequential Queue Cluster
JMS Queues After messages are in the queue, all application servers can simultaneously pull messages from the queue and process them into the system. Message-driven beans must be enabled on each application server in the cluster. WebLogic Server Sequential Queue Cluster The following diagram shows one example of a cluster configuration on the WebLogic Server.
Page 209: Dedicated Message Processing Servers
Dedicated Message Processing Servers run on any server in the cluster. Once messages are in the queue, the application server that is running the JMS consumer cron task processes messages in a sequential order. Unlike the continuous queue, there is no multi-threading of messages by design. A cluster implementation does not significantly impact the processing performance of messages that process through the sequential queue.
Page 210: Enterprise Beans
Inbound Message Receipt The noted components are standard J2EE components which are deployed as part of the application EAR file. All these components are cluster-aware. Enterprise Beans With a single server, the provider URL for accessing the JNDI tree is the single server URL.
Page 211 Inbound Message Receipt The following properties must point to the cluster URL: mxe.int.webappurl Integration Web Application URL mxe.int.uddiinurl Integration UDDI Registry Inquiry URL Integration UDDI Registry Publish URL mxe.int.uddipuburl The URL to access a Web service is http://hostname:port/meaweb/services/web service name where the meaweb value represents the mxe.int.webappurl system property value.
Page 212 Inbound Message Receipt Integration Guide...
Page 213: Chapter 15: Integration Framework Customization With Processing Rules
Processing rules can access and evaluate the values in XML and object fields, object sets, and integration and system controls. Processing rules also can change the values in XML and object fields, or stop or skip processing all or part of a message. © Copyright IBM Corp. 2007, 2008...
Page 214: Objects And Records
Objects and Records Objects and Records An object structure consists of one or more records that correspond to system objects. When an object is created, the object fields are populated from the corresponding record fields before standard application processing is applied. During outbound processing, the original object is populated with the record fields from the corresponding fields.
Page 215: Processing Rule Definitions
Processing Rule Definitions Processing Rule Definitions A processing rule performs an action on a field in a record or object, or on the record or object itself. After you select the applicable service or channel, the application displays the records that comprise the corresponding object structure. Select the record on which the processing rule applies.
Page 216: Field Transformation Actions
Processing Rule Definitions SKIP action The skip action bypasses a message that meets the specified criteria. The inbound message is not processed and the outbound message is not sent to an external system. Skip processing does not generate an error, but the system log file is updated with the rule that caused the skip action.
Page 217 Processing Rule Definitions The following field transformation actions manipulate data fields within a message. SET action The set action writes a value to a specified data field. When you define the rule, you specify the data to be set and the source of the new value. Indicate whether the rule always writes the new value to the target field or writes the new value only when the field is null (the default action).
Page 218: Processing Sequence
Processing Rule Definitions source field, one or more target fields, and how the rule processor identifies segments of the source field. The fields can have the following sources: A field in the selected record or object An integration control that contains the delimiter that separates the segments in the source field The source and target fields must exist in the same object.
Page 219: Conditions And Evaluations
Conditions and Evaluations Conditions and Evaluations Processing rules are applied conditionally. Any conditions must be met before the processing or action that is specified in the rule can be performed. Conditions can involve one or more of the following evaluations or comparisons: XML field data Object field Object set...
Page 220: Field To Evaluate
Conditions and Evaluations Because enterprise service processing rules are applied before objects are built, the processing rules cannot evaluate object fields or object sets. You can use the following combinations of categories, processing direction (outbound or inbound), and record types (record or object) in your evaluations. Direction of Processing Rule XML Field Object...
Page 221: When To Evaluate The Field
Conditions and Evaluations Type of Evaluation Description ISNOTNULL The specified field contains a value. NONE This option is available only if the When to Evaluate field is configured as Changed or Not Changed. If NONE is selected, no further evaluation is necessary.
Page 222 Conditions and Evaluations The following table lists the possible types of comparison fields that you can use in the field comparisons. Comparison of an alphanumeric source field is case sensitive. Field Integration control Compare the value in the specified field with the values in a list or value integration control.
Page 223: Integration Controls
Integration Controls Integration Controls Integration controls give you the ability to configure the behavior of any enterprise service or publish channel according to the requirements of individual organizations and sites. Processing rules and Java classes can access integration controls for evaluation purposes. Integration controls are defined at the system level.
Page 224: Control Types
Integration Controls Control Types You can create four types of integration controls to meet your business needs. Boolean Controls A boolean integration control specifies a value of 0 (false) or 1 (true). List Controls A list integration control contains a list of values. You can enter multiple values for the control and optionally assign a system domain to the control.
Page 225: New Control Creations
Integration Controls Multiplication Control A multiplication control can update the company in every organization in the system database. For example, use a multiplication control to update the company in every organization within the system. Value updates occur when the system receives company data using an enterprise service. New Control Creations Modifying control values at the external system level is generally sufficient to customize predefined enterprise service or publish channel processing.
Page 226 Integration Controls Integration Guide...
Page 227: Chapter 16: Integration Framework Customization With Java And Xsl
® ® You can download sample Java classes or XSL files from the IBM Tivoli Open Process Automation Library (OPAL). After changing the Java class files, rebuild and redeploy the application EAR file.
Page 228: Outbound Customization
Outbound Customization Outbound Customization The integration framework processes outbound messages by using either a publish channel or invocation channel. Publish channels and invocation channels use placeholders, or user exits, in the outbound processing flows. Publish Channel The integration framework processes asynchronous outbound messages by using publish channels.
Page 229: Processing Rules
Outbound Customization The primary difference between an invocation channel and a publish channel is that application code invokes the invocation channel, while an event or a data export initiates a publish channel. Additionally, the synchronous processing of an invocation channel can return a response and update the system business objects. For invocations, you can customize an invocation channel in the following ways: In the following Java exits: First user exit (user exit preprocessing)
Page 230: Java Exits
Outbound Customization Java Exits The following figure illustrates the hierarchy of standard Java exit classes for outbound processing. These Java classes are available to both the publish channel and the invocation channel. The hierarchy illustration does not apply to processing rules, XSL, and handler exits.
Page 231: Processing Class
Outbound Customization Change system data by changing the IR record to be sent to the external system Stop the message from being saved in the database by throwing a system exception. The entire message is rolled back, including any changes you make in the application that initiated the event. Stop the message from being sent to the external system by throwing a SKIP_TRANSACTION exception Log the transaction...
Page 232: Xsl Mapping
Outbound Customization The following method can perform the noted processes: Validate data Change data by changing the ER record to be sent to the external system Map additional data from the IR to the ER Stop the transaction from being saved in database by throwing a system exception Stop the message from being sent to the external system by throwing a SKIP_TRANSACTION exception...
Page 233 Outbound Customization The HTTP Processing You can use an HTTP exit placeholder for customization when sending Exit Class transactions from the system to an external system using HTTP. This exit class is optional and is called as part of the response from the HTTP call. The following figure shows the HTTP processing exit class that the system runs when a response is returned to the HTTP Post from an external system.
Page 234: The Enterprise Bean Processing Exit Class
Outbound Customization The Enterprise Bean Processing Exit Class You can use an exit placeholder for class customization when transactions are sent to an external system using an enterprise bean. This exit class is optional and is called before the enterprise bean is called. The following figure shows the various enterprise bean processing exit classes the system uses when sending transactions to an external system.
Page 235: The Java Message Service Processing Exit Class
Outbound Customization The Java Message Service Processing Exit Class You can use an exit placeholder for customization when sending transactions from the system to an external system using Java Message Service (JMS). This exit class is optional and is called before the JMS is called. The following figure shows the JMS processing exit class the system uses when sending transactions to an external system.
Page 236 Outbound Customization public void responseOk(org.w3c.dom.Document response) throws MXException responseOk() method is called after a successful invocation of the external Web service. public void responseError(Exception e) throws MXException If an error was encountered during the Web service invocation, the responseError() method is called with the originating exception as a parameter.
Page 237: Inbound Customization
Inbound Customization Inbound Customization The integration framework processes inbound messages by using enterprise services. Enterprise services provide placeholders, or user exits, in the inbound processing flows for customization. You can customize an enterprise service in the following ways: In an interface table user exit In the following Java exits: First user exit (user exit preprocessing) Enterprise service processing class...
Page 238 Inbound Customization The interface table polling program is run by using the system cron task manager. The cron task, IFACETABLECONSUMER, has an optional property called EXITCLASS, where you can place the fully qualified name of a Java exit class. The Java data structure list represents the record from the interface tables, where the first element is always the action of the message.
Page 239: Java Exits
Inbound Customization Log the transaction You identify this class in the Cron Task Setup application in the Configuration module. Java Exits The following figure illustrates the hierarchy of standard Java exit classes for inbound processing. These Java classes are available to the enterprise service. The hierarchy illustration does not apply to processing rules, XSL, or interface table exits.
Page 240: Enterprise Service Processing Class
Inbound Customization Stop further processing of the transaction by throwing an exception In this case, the transaction remains in the queue to be retried. Stop the message from being sent to the external system by throwing a skip_transaction exception In this case, the message is not saved in the system; the message is removed from the queue.
Page 241: Xsl Mapping
Inbound Customization The following method can perform the noted processes: Validate data Change external data by changing IR record to be saved in the system Map additional data from the ER to the IR Stop further processing of the transaction throwing an exception In this case, the transaction remains in the queue to be retried.
Page 242: Object Structure And Object Processing Rules
Inbound Customization Object Structure and Object Processing Rules For information about the processing rules engine, see Chapter 15, "Integration Framework Customization with Processing Rules," on page 199. Business Object User Exit Processing The Java user exits provide an exit point that runs before the objects that are created from the object structure XML are saved in the system.
Page 243: Chapter 17: Integration Component Additions And Modifications
The copy of an integration component becomes a user-defined entity, and modification restrictions that apply to the predefined component do not apply to the copy. The original version of the component is unchanged. © Copyright IBM Corp. 2007, 2008...
Page 244: Object Structure Creations
Object Structure Creations Object Structure Creations The integration framework provides predefined object structures for enterprise services, publish channels, and invocation channels across multiple functional areas. The functional areas include purchasing, work management, and inventory. You can create an object structure, an enterprise service, and a publish channel to support the exchange of data to and from the integration framework.
Page 245: Alternate Keys
Object Structure Creations Repeat the preceding steps for the remaining required objects. Indicate the relationship between those two objects. Define PERSON as the parent to EMAIL and as the parent to SMS. Alternate Keys An inbound message normally uses the primary key of an object to look up and process records in the system.
Page 246: Interface Table And Flat File Considerations
Predefined Object Structure Modifications By default, nonpersistent columns are excluded in the object when the object structure is created. If you modify the object structure, you can include new nonpersistent columns to the object definition in the object structure. Interface Table and Flat File Considerations If you use the object structure in interface tables or flat files, check whether duplicate column names exist in the object structure.
Page 247: Predefined Endpoint Modifications
Predefined Endpoint Modifications You can modify a user-defined handler. You cannot modify or delete a predefined handler. You can delete a handler only if you do not associate it with an endpoint for an external system. Predefined Endpoint Modifications You can change the property values of an endpoint to meet your individual business needs.
Page 248: Object Structure Services
Adapter, Service, and Channel Creations Processing Rules The integration framework applies any specified processing rules to objects, before it saves the objects. Use object structure processing rules to set or evaluate XML fields. You can manipulate key data before the object is created. You can also use processing rules to access and retrieve pertinent data from objects that you do not include in the object structure.
Page 249: Channel Creations
Adapter, Service, and Channel Creations Channel Creations After determining which adapter to use, you can create new channels for the predefined and user-defined adapters. The channels that you create determine how the adapter processes outbound integration messages. Publish Channels You can create publish channels in the Publish Channels application. When you trigger publish channel processing, the integration framework message data moves into the outbound queue.
Page 250: Predefined Service And Channel Modifications
Predefined Service and Channel Modifications All request and response processing classes and user exits have access to the invocation channel request and response objects by using the IntegrationContext.getCurrentContext() API. Endpoint The endpoint definition identifies how an invocation channel routes outbound data to a specific location.
Page 251: Queues
Predefined External System Modifications Queues A new external system can use the predefined Java Message Service (JMS) queues or queues that you create. Assign at least one inbound or outbound queue to the external system. Working with Enterprise Services To work with the enterprise service that the external system uses: Indicate whether the service processes through the sequential or continuous JMS queue.
Page 252 Predefined External System Modifications Integration Guide...
Page 253: Chapter 18: Integration Queries
Support for XML queries is based on the system Query By Example (QBE) capability. XML-based queries provide the same query support that is provided in the applications except for attribute searches that are available in some system applications. © Copyright IBM Corp. 2007, 2008...
Page 254: Query Services
Query Services Query Services Object structure services and enterprise services support query operations. An external source can use a service to run a query and to retrieve data from a system. In both cases, the object structure schema defines the XML content for the query request and the query response.
Page 255 Query Services The following table lists the attributes that can apply specifically to the root element of a query, a response to a query, or both. All attributes in this table are optional. Attribute Description Type Applicable to uniqueResult Specifies whether the query expects Boolean Query one record or multiple records in a...
Page 256 For example, the response to this query request returns records 11 through 20 of the query result set by virtue of setting the rstart value to 11 and the maxItems value to 10. <max:QueryMXINVBAL xmlns:max="http://www.ibm.com/maximo" creationDateTime="2008-09-28T21:49:45" baseLanguage="EN" transLanguage="EN" messageID="12345" maximoVersion="7.1."...
Page 257: Query Operator
Query Services Query Operator The QueryOperatorType data type supports the use of different operators. Your query request XML can use the different operators to filter the data that is returned to the querying external source. QueryMXPERSON The following graphic represents the content of the QueryMXPERSON element: Element The QueryMXPERSON element is type QueryMXPERSONType.
Page 258 Query Services rsStart – When this value is set to 11 on the query, all the records in the result set are returned starting with record 11. The query result skips records 1 - 10. When the attribute is not defined, the records are returned starting with record 1 in the result set.
Page 259: Object Structure Element
Object Structure Element The Query Response element uses the following additional attributes: rsStart – This value contains the value set on the query request. If the value is not defined on the request, the default response value is 1. rsCount – This value contains the number of records that are returned in the query response.
Page 260: Field Selection
Object Structure Element For example, to find all employees that have an ACTIVE status, format the query as follows: <QueryMXPERSON> <MXPERSONQuery> <PERSON> <STATUS operator ="=">ACTIVE</STATUS> </PERSON> </MXPERSONQuery> </QueryMXPERSON> Field Selection A field-based query compares the value in a database field with the value in the XML field of the query request.
Page 261: Range Selection
Object Structure Element The following query searches for the inventory balances where the bin number is not null. <QueryMXINVBAL> <MXINVBALQuery> <INVBALANCES> <BINNUM operator =”!="></BINNUM> </INVBALANCES > </MXINVBALQuery> </QueryMXINVBAL> The following query searches for the inventory balances where the bin number is null.
Page 262: Web Service Queries
A successful response to a query that is run in a Web service returns the query result set. If the result set is empty (it contains no records), the XML that is returned in the SOAP body contains the following empty mxpersonset tag. <max:QueryMXPERSONResponse xmlns:max="http://www.ibm.com/maximo" creationDateTime="2008-09-28T21:49:45" baseLanguage="EN" transLanguage="EN" messageID="12345" maximoVersion="7.1"...
Page 263 Web Service Queries Integration Queries...
Page 264 Web Service Queries Integration Guide...
Page 265: Chapter 19: Integration Web Services
When XML schema files are generated, they contain the content of each service and a Web Service Definition Language (WSDL) file to describe the service. The system uses Apache Axis 2.0 as the Web service engine. © Copyright IBM Corp. 2007, 2008...
Page 266: Enterprise Web Services
Object Structure Web Services Object Structure Web Services External applications can use Web services to query or send messages to the integration framework. The object structure service contains the logic for integration message processing. You can create an object structure Web service from a predefined or a user- defined object structure.
Page 267: Web Service Deployment Actions
Standard Web Services Can use a Java Message Service (JMS) queue (asynchronous process) or bypass the JMS queue (synchronous process). Enterprise Web services that are processed in a JMS queue do not support the Query operation and do not provide any response content to the caller. Enterprise Web services that are configured with the Query or Create operations provide XML content in the service response.
Page 268: Xml Schema Generation
XML Schema Generation XML Schema Generation The generated schema files are stored in a folder called schema, which is in the location that you specify in the mxe.int.globaldir system property. This folder contains the following subfolders: Common/COMMON/META Common/COMMON/MOS Common/COMMON/MBO SERVICE If you set the mxe.int.resolveschema includes global property in the System...
Page 269: Web Service Definition Language Generation
Web Service Definition Language Generation web service name is the name of the object structure schema you are retrieving with an .xsd file extension. Web Service Definition Language Generation The Web Service Definition Language file is generated during the deployment of a Web service.
Page 270: Uddi Registration
You can invoke integration Web services by using Dynamic Invocation Interface (DII) that uses the JAX-RPC API. You can also generate client stub programs by using a Web services tool of your choice, such as IBM WebSphere Application ® Server or Microsoft .NET Framework.
Page 271 Integration Web Service Invocations For all operations, except for the Query and Create operations, the SOAP body returns empty: <?xml version="1.0" encoding="UTF-8"?> <max:SyncPERSONResponse xmlns:max="http://www.ibm.com/ maximo" creationDateTime="2008-09-28T21:49:45" baseLanguage="string" transLanguage="string" messageID="string" maximoVersion="string" /> The Query operation returns the response content according to the object structure definition.
Page 272 Integration Web Service Invocations Integration Guide...
Page 273: Chapter 20: Multiple Language Support
If your system uses a language that differs from the base language, you can enable the integration framework to send and receive non-base language data to and from external systems. © Copyright IBM Corp. 2007, 2008...
Page 274: Default Processing For Translatable Columns
Default Processing for Translatable Columns Default Processing for Translatable Columns When you log in, you can choose a language code other than the base language for the system. In any application, you can then enter language-specific values for columns that are designated as translatable. By default, outbound transactions contain the applicable column values in the language that is associated with the login session.
Page 275: Multilanguage Attributes
Multilanguage Attributes Multilanguage Attributes Service or channel root elements use the following attributes to manage multilanguage processing: The baseLanguage Attribute The baseLanguage attribute identifies the base language of the system or application that generates outbound XML. For inbound transactions (input XML), this attribute is not validated.
Page 276 Multilanguage Attributes Integration Guide...
Page 277: Chapter 21: Integration Modules
An integration module provides a mechanism for a process management product, such as Change or Release, to invoke an external operational management product, such as IBM Tivoli Provisioning Manager. You can configure an integration module to automate logical management operations, such as software deployment, by using an operational management product.
Page 278: Integration Module Components
Discovery, or an asset management database. First load your operational management product and configuration item data into the discovery engine using the bulk loader interface. The discovery engine combines data from multiple ® ® sources into one data model. You can use the IBM Tivoli Integration Composer Integration Guide...
Page 279: Logical Management Operations
Name - The name of the action (for example, Get Deployment Status) Namespace - The unique qualifier (for example, com.ibm.tivoli.deployment) Invocation pattern: Synchronous - The process management product issues a request and the integration module returns the results of the operation immediately.
Page 280: Integration Module Prerequisites
Integration Module Prerequisites Business object attributes - The specific attributes of the objects that are needed either for input or output and their data types. Input objects and input object attributes identify the data that the process management product passes to the integration module. If the logical management operation is configured with input attributes and does not contain an input object, the process management product can pass any business object that has the required input attributes.
Page 281: Logical Management Operation Enablement
Integration Module Implementation Properties Operational management product and integration module associations are created when the OMPPRODUCTNAME and OMPVERSION values are added to the integration module. If multiple versions of the operational management product are used with the integration module, use a null value for the OMPVERSION.
Page 282: Integration Module Tasks
Integration Module Implementation Properties Name Description ENDPOINTPROP A map of String.psdi.iface.mic.MaxEndPointPropInfo properties that override the endpoint properties. USERNAME The user name that the integration framework uses to communicate with the endpoint. PASSWORD The password for USERNAME. Integration Module Tasks Java-based integration modules are responsible for populating the logical management operation response object or response object set with the results of the operation.
Page 283: Java Class And Invocation Channel Usage
Integration Module Implementation Properties and PASSWORD properties that are returned from the credential mapper can also override the endpoint properties. Integration module endpoint properties are overwritten by the endpoint properties that are passed by the process management product. For example, the USERNAME and PASSWORD properties.
Page 284 Integration Module Implementation Properties Can be used by different applications while using different business objects. Can be designed to make multiple external invocations. Can use different communication protocols for different logical management operations and operational management products. Supports the use of another thread to accommodate a long-running service.
Page 285: Java Class Implementation
Integration Module Implementation Properties Implementing an integration module by using an invocation channel has the following disadvantages: Requires more registration and configuration of system artifacts, even when the invocation is simple. Multiple applications cannot use the integration module with different business objects.
Page 286: Invocation Channel Implementation
Integration Module Implementation Properties management operation is being called. At run time, the integration module retrieves the LMONAME and LMONAMESPACE properties from the metaData input map: import psdi.iface.omp.IMConstants; String lmoName = metaData.get(IMConstants.LMONAME); String lmoNamespace = metaData.get(IMConstants.LMONAMESPACE); The integration module can retrieve logical management operation data from the source object.
Page 287: Integration Module Invocation
Integration Module Invocation When you override these methods, you can perform additional integration module processing. The properties that are passed to the invocation channel are available to the processing classes. The following outbound processing class code shows you how to retrieve the operational management product globally unique identifier when you run an invocation channel: import psdi.server.MXServer;...
Page 288: Step 1: Identify The Logical Management Operation
Integration Module Invocation Identify the operational management product and integration module. Invoke the integration module. Process the integration module response. Step 1: Identify the Logical Management Operation The process management product provides processes to run logical management operations. The logical management operation runs a process, such as software deployment, on a configuration item by using an operational management product.
Page 289: Step 3: Invoke The Integration Module
Integration Module Invocation Utility Method Function psdi.iface.app.im.MaxIMSetRemote Retrieves the list of the integration modules getIMListForOMP(String ompGuid) that implement at least one logical management operation on the operational management product. Collection getIMListForOMPAndLMO(String ompGUID, Retrieves the list of integration modules that String lmoName, String lmoNamespace) implement the logical management operation on the specified operational management product.
Page 290: Invoke Method
Integration Module Invocation The property IMConstants.ENDPOINTNAME contains the name of the endpoint that is associated with in the operational management product, integration module, and logical management operation relationship. In most cases, the endpoint property is the value that the process management product passes to the integration module. However, in unusual cases, the action class overwrites the configured endpoint.
Page 291: Operational Management Product Service Method
Integration Module Invocation The action class passes the following properties when it calls one of the invoke methods on the instantiated service invoker. Property Description metaData The property map that the get service invoker utility method returns. Source object and object set The object with the input attributes that are defined on the logical management operation.
Page 292: Get Service Invoker Utility Methods
Integration Module Invocation Get Service Invoker Utility Methods The operational management product service provides the following getServiceInvoker utility methods to retrieve an instance of an integration module for a logical management operation and an operational management product. Utility Method Function Map<String, Object>...
Page 293 Integration Module Invocation Integration Modules...
Page 294 Integration Module Invocation Integration Guide...
Page 295: Chapter 22: Launch-In-Context Feature
You can configure a console URL for any application with a Web-based console, such as the IBM Tivoli Provisioning Manager or the IBM Tivoli Configuration Manager. Additionally, you can configure console URLs for consoles that use Java™ Web Start, such as Tivoli Application Dependency Discovery Manager.
Page 296: External Application Preparations
External Application Preparations External Application Preparations Most external applications have a Web-based console that you can launch from a URL in a Web browser. The Launch-in-context feature supports the Web application (Servlet or JSP), portal, and Java WebStart console types. To perform a navigation, the external application console must support the land- in-context capability.
Page 297 Defining Launch Entries For example, the following URL is a URL for the Person application that uses the PERSONNAME attribute. https://extsyshost:9045/tcWebUI/interaction- handler?actionId=viewPerson&Person={PERSONNAME} You can also use an attribute from an object that is related to the main business object by specifying the relationship name and the attribute name {relationshipname.attributename} The following URL includes a city attribute from an address.
Page 298: Operational Management Product-Specific Properties
Defining Launch Entries Operational Management Product-specific Properties When you define launch entries, you enter these property values for the associated operational management product: Specific to operational management product launches: Name and version of the operational management product. When you associate an operational management product to a launch entry, the framework searches for the product name on the operational management product servers in the database that manages the configuration item.
Page 299: Associating The Launch Entry With A Signature Option
Associating the Launch Entry with a Signature Option Associating the Launch Entry with a Signature Option Before you add a launch point to an application, you must associate the launch entry record with a signature option. To associate the launch entry with a signature option: Open the Application Designer application.
Page 300: Associating A Signature Option With A Push Button
Associating a Signature Option with a Push Button In the Position field, enter a number to specify the relative position of the select menu item. In the Tabs field, select the MAIN value when the launch URL has substitution variables in it, otherwise select the ALL value. Optional: Enter values in the following fields: Header Description Tabs...
Page 301: Associating A Condition With A Signature Option
Associating a Condition with a Signature Option management product that is configured on the launch entry does not manage the configuration item. This condition applies to launch entries that you associate with a configuration item object or actual configuration item object. You can configure a condition to use the pre-existing condition class.
Page 302 Associating a Condition with a Signature Option Integration Guide...
Page 303: Format Of Collaboration Switches
The process control ID identifies a business process in a system application, such as the validation of an invoice match, the creation of a blanket PO release, and the update of a physical inventory count. © Copyright IBM Corp. 2007, 2008...
Page 304: System Id 1 And System Id
Default Collaboration Switches The following table shows the prefix of the process control ID and indicates the application to which it applies. Prefix of Process Control ID Corresponding Application Invoice Item Inventory Labor Purchase order Purchase requisition Work order For example, the IVRC, IVRCY, and IVWO collaboration switches are all related to inventory processing.
Page 305: Collaboration Switch Retrieval
Collaboration Switch Retrieval The default switches use various combinations of the following values in the System ID 1 and System ID 2 fields: System ID Value Meaning THISMX The system identified in MAXVARS.MXSYSID The collaboration switches do not use the actual value in MXSYSID.
Page 306: View Collaboration Switches
View Collaboration Switches If the record exists, the system uses the record process control value to determine whether or not to bypass system processing. If the record exists, ignore the remaining steps. If the record does not exist, the system modifies the key as follows: If System ID 1 now equals THISMX and System ID 2 does not equal THISMX, the system uses EXT as the System ID 2 value.
Page 307: Collaboration Switch Modification
Collaboration Switch Modification Collaboration Switch Modification Authorized users can use any database tool to modify the process control value of a collaboration switch. Do not change the value of PCID, OWNER1SYSID, or OWNER2SYSID on existing collaboration switches. To change the process control value in a collaboration switch, use the following SQL statement: update mxcollab set pcvalue...
Page 308: Modifying The Mxcollab Table
Collaboration Switch Additions Before you modify the MXCOLLAB table to reflect these conditions, the INV collaboration switches to have the following values: Process Control ID System ID 1 System ID 2 Process Control Value THISMX THISMX Modifying the MXCOLLAB Table To modify the MAXCOLLAB table: Change the value of the INV/ EXT/ THISMX collaboration switches to 1 to bypass normal update processing.
Page 309 Collaboration Switch Additions After you perform this procedure, the INV collaboration switches will have the following values. Process Control ID System ID 1 System ID 2 Process Control Value THISMX THISMX THISMX For example, when you set the value of the ISUIN integration control to 1, the issue transactions are accepted from an external system.
Page 310: Inventory Collaboration Switches
Inventory Collaboration Switches Inventory Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 Update inventory. Update inventory. INVTRANS or INVENTORY MATUSETRANS Used when creating issues, returns, or Do not update inventory. miscellaneous receipts or adjustments.
Page 311 Inventory Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 INVTR Update the From storeroom on a transfer or Update INVBALANCES in the From MATRECTRANS LOCATIONS the receipt of internal PO. storeroom.
Page 312: Invoice Collaboration Switches
Invoice Collaboration Switches Invoice Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 IVILC Update inventory last cost. Update inventory last cost. INVOICE INVENTORY Used when approving invoices. Do not update inventory last cost. IVINV Update inventory average cost.
Page 313 Invoice Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 IVRCY Create service receipts for invoice lines with a Generate a service receipt for the invoice INVOICE PO reference and RECEIPTREQD = N. line.
Page 314: Labor Transaction Collaboration Switches
Labor Transaction Collaboration Switches Labor Transaction Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 LTSRC Generate service receipts for POs. Allow setting value of LABTRANS LABTRANS.GENAPPRSERVRECEIPT to Y; Used when creating labor transactions or configurable in the Application Setup.
Page 315 Purchase Order Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 POIVM Create inventory vendor information for Update or create INVVENDOR record. ITEM of inventory. POLINE Do not create INVVENDOR record. Used when approving POs.
Page 316: Purchase Requisition Collaboration Switches
Purchase Requisition Collaboration Switches Purchase Requisition Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 PRDEL Delete PRs. Do not delete PR. “THISMX” Used when deleting PRs. Use only when Delete the PR and PRLINES;...
Page 317 Purchase Requisition Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 PRPAB Do not allow unreferenced external purchase If PRLINE.AGREEMENTPONUM is not in “EXT” agreements / blankets. PO, error. Normally this Used when adding or updating PR lines and If PRLINE.AGREEMENTPONUM is not in would be from...
Page 318: Receipt Collaboration Switches
Receipt Collaboration Switches Receipt Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 Enter PO receipts. Allow receiving against the PO. MATRECTRANS Used when creating receipts. Do not allow receiving against the PO. SERVRECTRANS RCILC Update inventory last cost.
Page 319: Work Order Collaboration Switches
Work Order Collaboration Switches Work Order Collaboration Switches Process Description Value and Action Derivation of Derivation of Control ID System ID 1 System ID 2 WORES Process material reservations. Generate inventory reservation. WORKORDER INVENTORY Used when changing the status of a work Do not generate inventory reservation.
Page 320 Work Order Collaboration Switches Integration Guide...
Page 321: Notices
Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead.
Page 322 IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created...
Page 323 Trademarks The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: developerWorks Everyplace ibm.com Lotus Maximo Notes QuickPlace Tivoli WebSphere Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
Page 324 Integration Guide...
Page 325: Index
FLATFILECONSUMER parameters 135 prerequisite activities 130 FLATFILECONSUMER processing properties 135 system properties 131 IFACETABLECONSUMER 105 boolean controls 210 selectors 160 business object user exit processing XMLFILECONSUMER parameters 133 customization 228 XMLFILECONSUMER processing properties 134 © Copyright IBM Corp. 2007, 2008...
Page 326 Index cross-reference controls 210 enterprise services (continued) customization processing rules 234 business object user exit processing 228 error management conditions, evaluations 205 configuration 118 EJB handler 220 error causes 124 handlers 218 interface table 117 HTTP handler 219 non-queue 127 inbound processing 223 notification 120 interface tables 223...
Page 327 Index HTTP handler (continued) integration queue HTTPEXIT property 149 definition 178 HTTPMETHOD property 150 J2EE restrictions 178 READTIMEOUT property 150 integration schemas 77 URL property 150 key fields 77 USERNAME, PASSWORD property 150 metadata schema 79 HTTP servlet namespace property 78 definition 181 object schemas 84 securing 181...
Page 328 Index JMS handler (continued) DESINTATIONTYPE property 152 DESTJNDINAME property 152 ISCOMPRESS property 152 message details JMSEXIT property 153 message tracking 110 PROVIDERUSER, PROVIDERPASSWORD property 153 message events 113 PROVIDEURL property 153 inbound and outbound 114 USERNAME, PASSWORD property 153 message processing JMS queues SKIP action 202 asynchronous inbound, cron task 133...
Page 329 Index object structures (continued) create 230 data exchange 8 enterprise service 233 receipt collaboration switches 304 flat files 232 restrictions interface table 232 adapters 236 nonpersistent fields 231 changed attribute 68 persistent fields 231 deletequeue utility 173 required fields 231 FLATFILE handler 147 required objects 230 HASDL column 100...
Page 330 Index object structure services (continued) web services (continued) object structure processing class 42 UDDI registration 256 process initiation 41 web service definition language generation 255 standard services 44 XML schema generation 254 object processing 45 WebLogic process initiation 44 continuous queue cluster 193 synchronous outbound processing message beans 168 integration modules 60...

This manual is also suitable for:

Maximo asset management 7.1 Tivoli asset management for it 7.1 Tivoli change and configuration management database 7.1.1 Tivoli service request manager 7.1

IBM BJ0NJML - Service And Asset Management Integration Manual

Chapter 1: What Is the Integration Framework

Chapter 2: Integration Framework Architecture

Chapter 3: Inbound Integration Processing

Chapter 4: Outbound Integration Processing

Chapter 5: Integration XML and Schemas

Chapter 6: Interface Tables

Chapter 7: Message Tracking

Chapter 8: Error Management

Chapter 9: Basic Configuration

Chapter 10: Endpoints and Handlers

Chapter 11: Advanced Interface Table Polling

Chapter 12: JMS Queue Configuration

Chapter 13: Security

Chapter 14: Cluster Configuration

Chapter 15: Integration Framework Customization with Processing Rules

Quick Links

Related Manuals for IBM BJ0NJML - Service And Asset Management

Summary of Contents for IBM BJ0NJML - Service And Asset Management