IBM BJ0NJML - Service And Asset Management Integration Manual Download

Page: 264 / 330

Web Service Queries

250

Integration Guide

Summary of Contents for BJ0NJML - Service And Asset Management

Page 1: ...Integration Guide 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 ...

Page 2: ...iguration Management Database and to all subsequent releases and modifications until otherwise indicated in new editions Copyright International Business Machines Corporation 2007 2008 All rights reserved US Government Users Restricted Rights Use duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp Note Before using this information and the product it supports read the i...

Page 3: ...s 14 Operational Management Products 15 Integration Framework for User Interface Integration 15 Launch Entries 15 Land in Context 16 Chapter 3 Inbound Integration Processing 19 Asynchronous Inbound Integration Processing 20 Enterprise Services 20 Inbound Integration Process Initiation 21 Messages in the Inbound Queues 21 Inbound Queue Message Retrieval 24 Object Structure Identification 24 User Ex...

Page 4: ...Outbound Integration Processing 47 Asynchronous Outbound Integration Processing 48 Publish Channels 48 Outbound Integration Process Initiation 49 Object Structure Identification 50 Object Structure Processing Rules 50 Object Structure Multiplication 51 User Exit Preprocessing 52 Publish Channel Class Processing 52 User Exit Postprocessing 53 XSL Map 54 Send the Publish Channel Data to the External...

Page 5: ...ration 82 Schema Content 82 Object Schemas 84 Schema Name 84 Schema Generation 85 Schema Content 85 Service Level Schemas 86 Schema Name 86 Schema Generation 86 Service Level Schema Elements 86 Standard Services 87 Object Structure and Enterprise Services 88 Object Structure and Enterprise Services Schema Content 88 Chapter 6 Interface Tables 95 Location of Interface Tables 96 Names of Interface T...

Page 6: ...118 System Properties Configuration 118 External Systems Configuration Properties 119 Error Notification 120 Message Reprocessing 121 Message Statuses 121 Error Correction 122 Error Details 122 Process Message 123 Save Message 123 Cancel Message 123 Message Deletion 124 Critical Errors 124 Common Causes of Errors 124 Error Research 125 Non queue Error Management 127 Chapter 9 Basic Configuration 1...

Page 7: ... 160 Configuring Cron Tasks 160 Selectors 160 Defining Selectors 160 Queue Tables 161 Chapter 12 JMS Queue Configuration 163 Creating and Configuring a Queue 164 Sequential Queues 165 Continuous Queue 165 Enabling Message Beans 166 Continuous Queue Performance 167 Configuring Message Beans 167 WebSphere Application Server 167 WebLogic Server 168 Message Caching 168 Continuous Queue Errors 169 WebS...

Page 8: ...egration Web Services 196 Chapter 15 Integration Framework Customization with Processing Rules 199 Objects and Records 200 Object Rule Definitions 200 Processing Rule Definitions 201 Processing Rule Initiation 201 Processing Rule Action 201 Message Processing Actions 201 Field Transformation Actions 202 Processing Sequence 204 Conditions and Evaluations 205 Condition Specifications 205 Evaluation ...

Page 9: ...ations 232 Predefined Object Structure Modifications 232 Endpoint Creations 232 Predefined Endpoint Modifications 233 Adapter Service and Channel Creations 233 Adapters 233 Services 233 Enterprise Services 233 Object Structure Services 234 Standard Services 234 Web Services 234 Channel Creations 235 Publish Channels 235 Invocation Channels 235 Predefined Service and Channel Modifications 236 Creat...

Page 10: ...9 Java Class Implementation 271 Invocation Channel Implementation 272 Java Methods for Inbound and Outbound Processing 272 Integration Module Invocation 273 Step 1 Identify the Logical Management Operation 274 Step 2 Identify the Operational Management Product and Integration Module 274 Service Utility Methods 274 Step 3 Invoke the Integration Module 275 getServiceInvoker Property Map 275 Invoke M...

Page 11: ...ation Switch Additions 293 Modifying the MXCOLLAB Table 294 Inventory Collaboration Switches 296 Invoice Collaboration Switches 298 Labor Transaction Collaboration Switches 300 Purchase Order Collaboration Switches 300 Purchase Requisition Collaboration Switches 302 Receipt Collaboration Switches 304 Work Order Collaboration Switches 305 Notices 307 Index 311 ...

Page 12: ...xii Integration Guide ...

Page 13: ...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 T Developers T Implementation analysts T Support personnel T System administrators ...

Page 14: ...xiv Integration Guide ...

Page 15: ...tion 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 Using the Integration Framework I ...

Page 16: ......

Page 17: ... of predefined content by using a processing rule engine Java and Extensible Stylesheet Language Transformations XSLT T Support for multiple communication modes including Web services HTTP Java Message Service JMS messaging Database interface tables XML and flat files T Event based batch program initiated and user initiated processing of outbound and inbound messages T Data load and performance sc...

Page 18: ... including Web Service Definition Language WSDL T 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 Each adapter can have its own interface and delivery mode Predefined adapters for Oracle and SAP are available as add ons ...

Page 19: ...ay 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 Integration Framework Architecture 2 ...

Page 20: ...pplications The integration framework provides the following capabilities T Build transform and customize message content T Send and receive messages using multiple protocols including Web services Hypertext Transfer Protocol HTTP Java Message Service JMS T Exchange data synchronously and asynchronously T Exchange event based messages T Import and export messages in batch mode The following integr...

Page 21: ...tion module uses to invoke the operational management product The integration module can map the service response so that it is returned to the process management product The service response then can be processed in multiple ways The service can open a response in a user interface application or save the response data to the application database You use the integration framework to integrate oper...

Page 22: ...cation Land in Context Integration Framework for Data Exchange The integration framework consists of individual data exchange components and features Object Structures An object structure is the common data layer that the integration framework uses for all outbound and inbound application data processing An object structure consists of one or more business objects that make up the content of an XM...

Page 23: ...system then moves the message through multiple processing layers before placing the message into a queue and releasing the initiator of the transaction The publish channel can use the following processing layers T Processing rules The integration framework provides a rule engine where you can filter and transform the XML message You can implement rules in the Publish Channel application T User exi...

Page 24: ...then moves through multiple processing layers before calling the external service The invocation channel can use the following processing layers T User exit Represents a Java class that you can use to filter data transform data and implement business logic You can use this class as part of an installation customization T Data processing class Represents a Java class that you can use to filter tran...

Page 25: ...Represents a Java class that you can use to filter transform data and implement business logic You can use this class as part of an installation customization T Data processing class Represents a Java class that you can use to filter transform data and implement business logic Adapters for Oracle and SAP provide processing classes to support integration to these products T XSL Map Represents an XS...

Page 26: ...can be updated for each deployed service The integration framework supports the following Web services T Object structure Web service Object structure Web services are created from an object structure and do not provide a processing layer which is available to enterprise services An object structure Web service supports five operations create delete query sync and update T Enterprise Web service E...

Page 27: ...ct structures have one or more business objects and contain the relationships that are needed between business objects T Corresponding enterprise services and publish channels for the predefined object structures T One external system that is configured to use all the predefined enterprise services and publish channels T Eight predefined handlers that support different communication protocols such...

Page 28: ...l management product definitions act as the interface between the process management product and the integration module The logical management operation allows the integration module and the process management product to be designed and implemented independent of each other A logical management product created by an integration module would identify the actions that the integration module supports...

Page 29: ...nagement product definitions are registered in the system and can be loaded from the discovery engine using the Integration Composer You can also load operational management product definitions by using the features of the integration framework such as object structure services The operational management product definitions include properties of the operational management product such as a host na...

Page 30: ...t 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 application user interface and to pass context information as part of the URL str...

Page 31: ...Integration Framework for User Interface Integration Integration Framework Architecture 17 ...

Page 32: ...Integration Framework for User Interface Integration 18 Integration Guide ...

Page 33: ...JMS queues JMS queues can process messages in order of priority or in a multi threaded manner Synchronous messages are not processed through the JMS queues A direct connection is established between the integration framework and the external application The integration framework returns a response to the external application that confirms success or failure of the processed message The integration...

Page 34: ...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 Query type enterprise services cannot be processed asynchronously in the integration framework Enterprise Services The following diagram gives an overview of the asy...

Page 35: ...are written according to the Sun Microsystems Inc J2EE client specification You can use the following code to invoke the Enterprise JavaBean to process the enterprise service message asynchronously public byte processExternalDataAsync byte extData String serviceName String sender Method Availability XML that uses the integration framework that uses HTTP Post Enterprise JavaBean EJB Invocation Web ...

Page 36: ...terprise Services tab in the External Systems application 4 If the verification is successful the integration framework identifies the inbound JMS queue that is assigned to the selected enterprise service and external system TIP To find the location of that queue go to the System tab in the External Systems application 5 The integration framework writes the message to the inbound queue If the mess...

Page 37: ... the database The preview data process checks that the data structure of the selected file complies with the integration XML or flat file definitions Interface Tables The following steps describe the initiation of inbound processing that uses interface tables 1 The external system writes message data to the appropriate interface tables It also updates the MXIN_INTER_TRANS queue table with informat...

Page 38: ... queue the continuous queue or a combination of the two The sequential queue processes messages on a strict first in first out basis The continuous queue supports multi threaded processing of messages When an error occurs in the sequential queue the application sends an e mail message to the system administrator The sequential queue also flags the message as an error and continues to reprocess the...

Page 39: ...prise Services application Look for the processing order field on the Object Structure Sub Records table window The Enterprise Service main object structure is always processed after all the additional object structures If the integration framework creates copies of the enterprise service message the remaining inbound processing actions apply to each copy of the enterprise service Output The outpu...

Page 40: ...Configuration and Enterprise Service Response Configuration table windows for processing class values Output The following table shows the possible enterprise service class processing outcomes Condition Output No user exit class exists The unchanged enterprise service The user exit class skips the record due to non applicable data None processing ends and the message is deleted from the queue If t...

Page 41: ...user exit object processing methods Output The following table shows the possible user exit postprocessing outcomes XSL Map Summary The integration framework applies any mapping to the enterprise service to convert it to an object structure format The MAXIMO adapter does not provide predefined XSL maps TIP To see if an XSL map exists for an enterprise service go to the Enterprise Service tab in th...

Page 42: ... a duplicated object structure because of an error in the data apply the stop action to all of the object structures that are created every copy of the original object structure TIP To see if a cross reference control exists go to the Enterprise Service tab in the Enterprise Services application The following steps describe the steps the integration framework takes when it multiplies an object str...

Page 43: ...this activity is the objects Object Processing Rules Summary The integration framework applies processing rules to the objects that it builds before saving the objects You can use object processing rules to manipulate data in the object before the objects are saved You can also use processing rules to access and retrieve pertinent data from objects that you do not include in the object structure T...

Page 44: ...sing 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 The processing rules stop the record None processing ends and the message in error remains in the queue The processing rules complete successfully The updated ob...

Page 45: ...ystem and standard system processing is applied The integration framework treats a single message from the inbound queue as a single system transaction All objects that a message creates must be successfully processed before the database commit transaction can occur An error in any one of the multiple object structures causes the entire transaction to fail Condition Output No user exit processing ...

Page 46: ... service processing activities Not every activity applies to every inbound message Inbound Integration Process Initiation Summary An enterprise service can use HTTP Post Enterprise JavaBean invocation and Web service invocation methods for enterprise service synchronous message responses and receipts HTTP Post and Enterprise Beans The following steps describe the initiation of inbound processing i...

Page 47: ...n framework notifies the sender of the error and does not process the message TIP To see if an external system is enabled go to the System tab in the External Systems application To see if an enterprise service is valid and enabled go to the Enterprise Services tab in the External Systems application Object Structure Identification Summary The integration framework identifies the object structures...

Page 48: ...vice You can use a preprocessing method to manipulate the enterprise service before any predefined processing takes place The predefined services do not provide any user exit classes TIP To see if preprocessing customization exists go to the Enterprise Service tab in the Enterprise Services application If the Enterprise Service Configuration and Enterprise Service Response Configuration table wind...

Page 49: ... 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 Both the object structure and the enterprise service are available for your use The MAXIMO adapter does not provide predefined user...

Page 50: ...ate a copy of the object structure for each applicable organization or site For example you want to insert a vendor from an external system into the system under multiple organizations You can insert a vendor once and apply a cross reference control The system creates a copy of each vendor for each applicable organization The MAXIMO adapter does not provide any predefined cross reference controls ...

Page 51: ...anization or site that is specified in the cross reference control Object Structure Processing Rules Summary The integration framework applies any 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 You can ma...

Page 52: ...ervices application Output The following table shows the possible object rule processing outcomes Object Structure Processing Class Summary The integration framework applies any predefined logic to the object structure Output The following table shows the possible object structure processing outcomes Condition Output No object processing rules exist The object The processing rules skip the record ...

Page 53: ...cessfully processed before the database commit transaction can occur An error in any one of the multiple object structures causes the entire transaction to fail Enterprise Service Response Processing A synchronous enterprise service provides a response to the invoking application The service indicates whether the message was processed successfully For the query and create operations XML content is...

Page 54: ...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 Enterprise Service Web Services You can access enterprise services by using HTTP or an enterprise bean You can deploy enterprise services as Web services External applications can use Web services to query or to send messages to the integration f...

Page 55: ...amework 1 A servlet enables the external systems to post messages to the system You can use the following URL to post the transactions to object structure services that process synchronously hostname port meaweb os osname osname is the name of the object structure 2 J2EE clients can invoke Enterprise JavaBeans that are written according to the Sun Microsystems Inc J2EE client specification To invo...

Page 56: ...ure name and operation from the root element in the inbound XML transaction The integration framework inbound integration can process numbers that are represented in standard or scientific notation 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 Structure Processing Class ...

Page 57: ...plied 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 You can deploy object structure services as Web services External applications can use Web services to query or to send messages to the integration framework ...

Page 58: ...stems to post transactions to the system You can use the following URL to post the transactions to standard services that process synchronously hostname port meaweb ss maximo service name maximo service name is the name of the application service 2 J2EE clients can invoke Enterprise JavaBeans that are written according to the Sun Microsystems Inc J2EE client specification To invoke the Enterprise ...

Page 59: ...IntialContext object The context derives the provider URL and the context factory from the environment Object Processing Summary The objects are passed to the system and standard system processing is applied Standard Web Services You can access standard services by using HTTP or an enterprise bean You can deploy standard services as Web services External applications can use Web services to query ...

Page 60: ...Synchronous Inbound Integration Processing 46 Integration Guide ...

Page 61: ...he Java Message Service JMS queue JMS queues can process messages in the queues in either first in order of sequence or in a multi threaded manner 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 fa...

Page 62: ...annels and external systems must be defined T The external systems must be configured with an endpoint T The following entities must be enabled External systems Applicable publish channels Applicable event listeners The cron task that polls the outbound queue Publish Channels The following diagram illustrates an overview of the asynchronous publish channel processing activities Not every activity ...

Page 63: ...step is the only step in the outbound integration process that is visible to you 2 The primary object that is associated with the transaction identifies the related publish channel that has the event listener enabled The outbound integration process is initiated for all publish channels with enabled listeners TIP To see if the event listener is enabled for a particular publish channel see the Enab...

Page 64: ...ime 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 Rules also can change in an object structure Yo...

Page 65: ...www w3 org 2001 XMLSchema instance xmlns http www ibm com maximo ObjectStructureNameSet ObjectName ObjectName ObjectStructureNameSet PublishChannelName The actions listed in each stage apply to each copy of the object structure that is created for a specific external system and publish channel combination The skip action applies only to the copy of the object structure when the outbound processing...

Page 66: ...ation framework applies predefined publish channel processing logic in the processing class to the object structure A publish channel processing class typically implements additional processing logic and converts data from an object structure format to a publish channel format The MAXIMO adapter does not provide any predefined publish channel processing classes The XML format for the publish chann...

Page 67: ...ostprocessing method The same processing class contains the user exit preprocessing and user exit postprocessing methods Output The following table shows the possible user exit postprocessing 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 processing en...

Page 68: ...he integration framework writes and sends the publish channel data to the external system 1 The integration framework writes the XML message to the outbound queue specified for the external system TIP To see which outbound queue an external system uses go to the System tab in the External Systems application 2 The cron task that polls the outbound queue picks up the message 3 The cron task passes ...

Page 69: ...egration 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: ...ion Summary The integration framework performs the following activities when it builds a request object structure from the objects 1 The request object structure that is associated with each invocation channel is determined 2 The request object structure identifies its component objects 3 The integration framework constructs the request object structure from the objects 4 The integration framework...

Page 71: ...outcomes Request User Exit Preprocessing Summary The integration framework applies custom request processing logic in the user exit class to the invocation channel This option is typically used to customize a predefined invocation channel before invocation channel request processing takes place Both the input object structure and the invocation channel that are created from that object structure a...

Page 72: ...le By default numbers greater than seven digits use a scientific notation Send the Invocation Channel Data to the Endpoint Summary The integration framework writes the invocation channel data to the location that you specify on the endpoint The endpoint determines the data transport mechanism of an invocation channel 1 The integration framework writes the XML message to the endpoint location TIP T...

Page 73: ...following table shows the possible response class processing outcomes Response User Exit Preprocessing Summary The integration framework applies custom response processing logic in the user exit class to the invocation channel This option is typically used to customize a predefined invocation channel before invocation channel response processing takes place Both the invocation channel and the resp...

Page 74: ...table window for a response XSL map Output The output of this activity must be an XML message in an invocation channel format Object Processing Summary The objects are build from response object structure data and are passed to the system where standard system processing is applied The system must successfully process all the objects that are created from the response object structure that is crea...

Page 75: ...uctures elements and attributes for 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 Integration XML and Schemas 5 ...

Page 76: ... object structure syncMXPERSON root element MXPERSON object structure element PERSON object element PHONE object element PHONE object element EMAIL object element EMAIL object element SMS object element SMS object element PERSON MXPERSON syncMXPERSON Integration XML Content The content of any XML document is based on the associated object structure and the operation that the channel or service per...

Page 77: ...bute Description Type Applicable to baselanguage Base language in which the content values are supplied string All input and output operations creationDateTime Date and time the content was generated dateTime All input and output operations maximoVersion A concatenated string that identifies the major version minor version build and database build The system generates this value for all published ...

Page 78: ...y can return multiple records this attribute limits the number of records to be returned at one time If this attribute is not specified the response contains the entire result set positiveInteger Queries input rsStart The first record in the response In queries Use with maxItems to specify the first record to be returned in a response If rsStart is not specified the response starts with the first ...

Page 79: ...cord in the result set and includes the number of records specified by the rsCount attribute integer Responses output rsCount The number of records returned in the message If the original query specifies a maxItems value the rsStart value for the subsequent request for additional records is rsStart rsCount 1 integer Responses output rsTotal The total number of records in the result set If the quer...

Page 80: ...Version 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 creationDateTime 2008 09 28T21 49 45 baseLanguage EN transLanguage EN messageID 11876346770938768 maximoVersion 7 1 Harrier 060 HARRIER 066 rsStart 100 rsCou...

Page 81: ...art of the key of both the PERSON and PHONE objects but in the MXPERSON object structure it appears only in the PERSON object Attribute Description Type Applicable to action The value is derived from action attribute of the primary object within the message For outbound messages this attribute is for informational purposes only For inbound messages the processing logic uses this value only for the...

Page 82: ...es An outbound XML contains the changed attribute only when the transaction meets all the following conditions T An outbound event based transaction creates the message T The action attribute on the primary object is Change or Replace T The object structure uses the same parent child object relationship as the corresponding application For example the MXPERSON object structure and the Person appli...

Page 83: ... system can provide the individual components as in the following example GLDEBITACCT GLCOMP glorder 0 6400 GLCOMP GLCOMP glorder 1 2 GLCOMP GLCOMP glorder 2 10 GLCOMP GLDEBITACCT In this case the system validates the components and uses the segment delimiter defined in the GLCONFIGURE table to recreate the account number T The external system can provide the entire account number separated by the...

Page 84: ...zdG8 PASSWORD MAXUSER PERSON MXPERUSER The action Attribute The action attribute is an optional attribute that applies to the content of primary and child objects in an object structure It specifies the type of processing that the receiving system is to perform on the XML message This attribute applies to inbound XML documents that perform data synchronization operation sync It also applies to pub...

Page 85: ...T action Add NAME SMITH NAME TITLE MANAGER TITLE COMPCONTACT COMPCONTACT action Change NAME JONES NAME TITLE ENGINEER TITLE COMPCONTACT COMPANIES MXVENDOR Add action An add action indicates that the corresponding data is added to a database For inbound transactions an error occurs if the data exists The add action on a primary object extends to its child objects so it is not necessary to specify t...

Page 86: ... the primary object in an XML message indicates that the message contains a complete set of objects that represent the net result of additions changes and deletions to the object structure These objects replace the existing database records and any database record that is not referenced in the XML message is deleted For outbound processing the system always uses the replace action not the change a...

Page 87: ...itself sending an inbound vendor record with the action value equal to null results in the deletion of contact information in the database However sending a vendor record with the action value equal to AddChange results in the update of vendor information the contact information remains Default action attributes The system processes the message in the following ways when an inbound XML message doe...

Page 88: ...O 101 due to the changes in its child POLINE and POCOST records T A change action on POLINE 1 due to changes in its child PCOST records T A change action on the POCOST 2 record within POLINE 1 due to changes in that record T A delete action on the POCOST 3 record within POLINE 2 T A change action on the POLINE 2 record due to changes in that record T A delete action on the POLINE 3 record which de...

Page 89: ...any the add change action Valid action attribute combinations The following table shows the combinations of action attributes you can include on primary and child records Find the action attribute for the parent record in the column on the left then read across the table to find out if the action attribute for the child is valid Child Record Add Delete Change Replace AddChange No Value Remarks Pri...

Page 90: ... the system does not decrypt the received data Character encoding The integration XML uses UTF 8 encoding If an inbound transaction specifies any other encoding the entire message must use that encoding If an error is encountered during the processing of an inbound transaction that uses encoding other than UTF 8 the entire error XML that is written is encoded as UTF 8 xml version 1 0 encoding ISO ...

Page 91: ...an object structure as input or output T Standard services process an object MboSet MboList or specific individual typed parameters as input or output The input and output types for all services except standard services are reusable as they are based on the object structure for the service Key Fields The generated schemas identify the key fields within a service or channel from the object structur...

Page 92: ...ntains the core reusable types that the system uses to build all the other schemas Generating a Schema Whenever you change an object structure or the data dictionary you must regenerate the affected schemas The following changes also warrant a regeneration of the schema T Making a database field required or optional T Changing the data type of a database field T Adding or removing fields from the ...

Page 93: ...ttribute groups T Content types T Query data types T Supporting data types Attribute Groups The following table lists attributes by group Group Subdirectory Description Metadata schema common meta Metadata schema file MXMeta xsd Object Structure schema common mos Object structure schema files Object schema common mbo Object schema files Service schema service Service level schema files for enterpr...

Page 94: ...s software version MXBooleanType Extension of integer changed MXDateTimeType Extension of dateTime changed MXDomainType Extension of string identifies the corresponding Maxvalue for a domain value changed maxvalue MXDoubleType Extension of double changed MXFloatType Extension of float changed MXGLAccountType Complex type with 2 values VALUE and GLCOMP identifies individual GL components and their ...

Page 95: ...ension of string operator Type Description Restricted Values BooleanType Indicates whether the result of a logical test is true or false T 0 false T 1 true ChangeIndicatorType Indicates whether a field has a new value Applies only to object structures generated by an event 1 true EventType Indicates whether a published object structure is the result of an event If the value is 1 the published stru...

Page 96: ...ect action menu in the Object Structures application T The enterprise service schema where the object structure is referenced by the service T The publish channel schema where the object structure is referenced by the channel All object structure schemas include the MXMeta xsd schema file The generated schemas are under the schema common mos directory Schema Content An object is configured only on...

Page 97: ...N object name which has type MXPERSON_PERSONType T Complex type MXPERSON_PERSONType has elements for all the configured attributes of the PERSON object and elements for the child objects in the object structure PHONE EMAIL and SMS T Additional objects in the schema have a corresponding complex type like MXPERSON_PERSONType that defines the PERSON object The following example shows the structure of...

Page 98: ... number exists in the child PHONE object Object delete content You can use delete elements only within the context of service level schemas The following content format is in the object delete element T Element MXPERSONDelete is type MXPERSONDeleteType T Complex type MXPERSONDeleteType has elements for all the configured attributes of the PERSON object The following differences exist between the c...

Page 99: ...element PERSONMboKey PERSONMboKeyType This type contains a single instance of the PERSON element that is PERSONKeyType The PERSONKeyType contains the attribute that is the primary key of the PERSON object PERSONID If multiple attributes make up the primary key of an object objectKeyType contains the attributes that make up the primary key This element is included in the response to a Create operat...

Page 100: ...schemas is application service name Service for example PERSONService xsd The naming convention for service level schemas is object structure Service for example MXPERSONService xsd Schema Generation Predefined service schema files are not provided When you deploy a service a service schema file is generated for the associated object structure if one does not exist already The following conditions...

Page 101: ...e methods that can be exposed as Web services Standard services are available only for methods that are properly annotated within the service The service schemas that are generated for standard services are used only by the corresponding actions Service schemas that are generated for objects and object structures are potentially reusable across different services Standard service input The followi...

Page 102: ...eated for a specific operation Therefore multiple enterprise services must be created to support multiple operations even though they reference the same object structure and thus use the same schema Two operations Add and Query support an output type The output for the Add operation is a set of keys corresponding to the object that was added and the output for the query operation is a result set o...

Page 103: ...et is derived from the object structure schema T 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 The definitions of the following elements and types are comparable to the CreateMXPERSON element and type Element Type UpdateMXPERSON UpdateMXPERSONType SyncMXPERSON SyncM...

Page 104: ...element T Element CreateMXPERSONResponse is type CreateMXPERSONResponseType T The CreateMXPERSONResponseType has element PERSONMboKeySet which is type of PERSONMboKeySetType T PERSONMboKeySetType has element PERSON which is type PERSONKeyType T The PERSONKeyType contains only the PERSONID attribute of the PERSON object the Primary Key of the PERSON ...

Page 105: ...f the DeleteMXPERSON element T Element DeleteMXPERSON is type DeleteMXPERSONType T The DeleteMXPERSONType has element MXPERSONDelete which is type MXPERSONDeleteType T 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: ...e has element MXPERSONSet which is type MXPERSONSetType MXPERSONSet is derived from the Object Structure Schema T 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 The Publish element is like the Create element but it uses the additional attribute event which is defined in the P...

Page 107: ...yMXPERSONType T QueryMXPERSONType has element MXPERSONQuery which is type MXPERSONQueryType T 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 The Query element uses the additional attributes uniqueResults maxItems and rsStart which are defined in the QueryContentGroup ...

Page 108: ...SONSetType T 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 T Although the QueryMXPERSON element restricts querying to the top object of the object structure PERSON its response can contain the child objects PHONE EMAIL and SMS The Query Response element uses the additional attri...

Page 109: ...el Invocation channels object structure services standard services and query operations do not support interface tables Data synchronization messages can be exchanged by using interface tables Interface tables do not support the Query and Invoke operations A single external system can transfer outbound data by using either XML messages interface table flat messages or both You can assign an endpoi...

Page 110: ...fferent object structure must use different interface table names Interface Queue Tables The interface queue tables identify the sequence in which a receiving system should process the records in the respective interface tables Two queue tables exist one for inbound transactions and the other for outbound transactions Some transactions depend on the successful processing of a previous transaction ...

Page 111: ...isplays a list of interface tables based on the uniqueness of the interface table name and its corresponding endpoint You can create interface tables for enterprise services and publish channels when the associated object structures are marked as flat supported The Support Flat Structure check box must be selected on the object structure The alias conflict must also be resolved before an interface...

Page 112: ...rresponding inbound transaction is ready to process or the inbound transaction is in error The interface table creation process does not check for records in the MXOUT_INTER_TRANS queue table Deletion of Interface Tables and Records When one or more related inbound transaction records are successfully processed in an interface table the corresponding record is deleted from the MXIN_INTER_TRANS que...

Page 113: ...t object and a child object a duplicate column name error occurs when the interface table or a flat file record is generated To resolve the duplicate column name problem change the system alias for duplicate column names Every system database column can have an alias alternate name When an alias exists the system uses the alias when interface tables and flat files are generated Change the alias to...

Page 114: ...bound transactions For inbound transactions the external system must populate the column with the enterprise service name or the publish channel name that corresponds to the row that is inserted into an interface table TRANSID Column The TRANSID column in an interface queue table is a sequential number that uniquely identifies an integration transaction The TRANSID and the interface table name ide...

Page 115: ...ndary sequence number If a transaction writes to multiple interface tables the interface queue table contains a separate record with a unique TRANSID value for each interface table Each interface queue table maintains its own TRANSID counter The outbound TRANSID value is initialized when the interface queue table records are generated You must create and maintain the TRANSID counters that populate...

Page 116: ...ing sequence TRANSSEQ Column When multiple records in an interface table share the same TRANSID value the TRANSSEQ column provides a secondary sequence number that indicates the sequence in which those records should be processed Sequence Interface Table Identifier TRANSID of Record in Interface Table 1 MXPR_IFACE 1001 2 MXITEM_IFACE 1002 3 MXINVENTORY_IFACE 1003 4 MXITEM_IFACE 1004 Sequence Inter...

Page 117: ...Column The following table shows the ACTION column values in an interface queue table and the corresponding action that is applied to the interface table Value of EXTSYSNAME Direction of Transaction The external system that is the destination of the transaction Outbound The value of a valid and enabled external system that is defined in the integration framework Inbound Value in ACTION Column Inte...

Page 118: ...n the language that the TRANSLANGUAGE value defines MESSAGEID Column The MESSAGEID column is a unique identifier that the system assigns to every outbound transaction IFACETBNAME Column The IFACETBNAME column is the name of the interface table that corresponds to the IFACENAME column This column applies to outbound transactions only Long Description Columns in Oracle Databases Long description col...

Page 119: ... program as the system does for inbound transactions triggers or any other mechanism The cron task has the following configurable parameters All parameters are optional Parameter Description EXITCLASS Java exit class that enables the manipulation of data before it is written to an inbound queue ENDPPOINT Endpoint that is associated with the interface table The default value is the predefined endpo...

Page 120: ...e an interface table record and populate it with the following information The transaction data The incremented TRANSID value If multiple records exist for the same interface table the incremented TRANSSEQ value b Create an MXIN_INTER_TRANS queue record with the following information The same TRANSID value that is contained the interface table record The name of the enterprise service that corresp...

Page 121: ...e in the TRANSID sequence b Enable each record in the MXOUT_INTER_TRANS queue table Access the interface table that you just identified and retrieve the first record in which the TRANSID value matches the TRANSID value in the current MXOUT_INTER_TRANS queue record If the interface table contains multiple records with the same TRANSID value retrieve and process them in TRANSSEQ sequence Process dat...

Page 122: ...Configuring External Systems 108 Integration Guide ...

Page 123: ...d publish channel messages The Message Tracking application works with the Message Reprocessing application 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 Message Tracking 7 ...

Page 124: ...e message For inbound messages the system assigns an MXJMS default value For outbound messages the system assigns the name of the endpoint that is used in message processing T Operation The processing operation the system applies to the tracked message SYNC UPDATE QUERY DELETE CREATE and PUBLISH T System Name of the external system that is associated with either the enterprise service or publish c...

Page 125: ...essage ID and search ID values are registered as a comma separated list of values Database field lengths are applicable to external ID and search ID fields If necessary you can adjust the length of these fields in the Database Configuration application External Message ID In the Message Tracking application you can use the External Message ID attribute to locate specific messages The syntax that y...

Page 126: ... noun searches The system stores the search identifier in the SEARCHFIELDDATA field in the MAXINTMSGTRK table To find all messages for the MXPERSONInterface enterprise service create the following fully qualified XPATH expression as the Search ID http www ibm com maximo SyncMXPERSON http www ibm com maximo MXPERSONSet http www ibm com maximo PERSON http www ibm com maximo PERSONID Multi noun Messa...

Page 127: ...tatuses Message Events 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 T STATUS T STATUDATETIME T ERRORMSGR Status Description ERROR Message processing failed due to validatio...

Page 128: ...ling the cause of failure Error in message processing The existing record in the message tracking table When the system encounters a processing error it updates the message record status to ERROR If you resend your message and a processing error occurs again the system maintains the ERROR message status End of queue processing The following transaction processing events update the existing record ...

Page 129: ...messages are stored in a queue from which they are retrieved for dispatch to an external system Queue error management is initiated when an error condition is identified The error identification occurs when a message is processing in an outbound or inbound queue You can view correct cancel and reprocess the erroneous messages Error messages can be managed without the need to access error files on ...

Page 130: ...ocessed until the message in error is resolved As a result only one error at a time can exist in a sequential queue The continuous queue processes messages in a multi threaded mode When an error occurs in the continuous queue the error management mechanism is initiated and the message is flagged as having an error The integration framework continues to process subsequent messages in the queue As a...

Page 131: ...e MXIN_INTER_TRANS queue table For the first error in the MXIN_INTER_TRANS queue table the system sends an e mail notification to the administrator e mail address that is specified in the System Properties application After the cron task processes subsequent records in the MXIN_INTER_TRANS queue table it switches to an idle state When processing resumes the cron task tries to process the records i...

Page 132: ...elimited with a comma You can optionally use the e mail address property at the queue level to override the administrator address Use this option to specify different e mail addresses for each queue If you do not configure an e mail address property no e mail notification is sent when queue processing errors occur T mxe int globaldir This property specifies the root folder under which all integrat...

Page 133: ...transaction After the first unsuccessful attempt to process the transaction the system administrator receives a notification and a message is written to an error file This value is typically set to 0 for outbound queues For the WebSphere Application Server valid values are any numbers that are equal to or greater than zero T E Mail Address This optional property can be specified if you want e mail...

Page 134: ...r whether the system is running in a clustered or non clustered environment For example assume that the continuous inbound queue contains ten messages The system successfully processes the first four and then encounters an error in the fifth Depending on the value of the Maximum Try Count property the message might be tried one or more times An e mail notification is sent to the system administrat...

Page 135: ...en correct the erroneous data If you have not enabled message tracking you can go to the Message Reprocessing application to check for transaction errors Message Statuses You use the Change Status action in the Message Reprocessing application to change the status of a message The system designates a status to each message to indicate whether it is ready for processing A message can have a status ...

Page 136: ...d during enterprise service and user exit processing The IR element is provided for information only and any change to the IR is ignored when the message is reprocessed The following code is an example of an error message that contains both the ER and IR elements xml version 1 0 encoding UTF 8 ERROR ERRORMESSAGE Error occurred while processing PO Object Structure number 1 Error is system unknowner...

Page 137: ...listing on the main tab of the Message Reprocessing application The following actions are performed when message is not successfully processed T The MAXINTERRORMSG table is updated with the new error description T The CHANGEBY and CHANGEDATE attributes in the MAXINTERROR table are updated T An error message is created The application refreshes the result set and displays the new error for the unsu...

Page 138: ...om an outbound queue are related to the problematic delivery of a message to the endpoint that is specified for the external system Typical problems are disruptions of the communication link between the system and the external application or database table space or file space issues in the external application To resolve an outbound error you typically do not need to modify the XML message Errors ...

Page 139: ...in a sequential queue inbound or outbound processing of the queue stops until the error is resolved One XML file exists in the error folder for the queue When an error occurs in a continuous queue processing of the queue continues and additional errors can occur before the initial error is resolved Multiple XML files exist in the Message Reprocessing application No ER and IR Elements in the Error ...

Page 140: ...ce 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 ...

Page 141: ...g processed by the integration framework or by the system Instead of relying on an error queue the integration framework responds synchronously to the caller of the process with an error message When the system encounters a processing error the calling application must receive the response correct the error and retry the transaction You can use the system log as an aid in troubleshooting your sync...

Page 142: ...Non queue Error Management 128 Integration Guide ...

Page 143: ...ation involves working with predefined components administration and queue properties 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 Basic Configuration 9 ...

Page 144: ...ng JMS queues are defined T Inbound sequential sqin T Inbound continuous cqin T Outbound sequential sqout T Error continuous cqinerr You can use the predefined queues for development and production Prerequisite Activities Before you can process integration framework transactions create the following components T The object structures that you use T The publish channels and endpoints to which the s...

Page 145: ...e application server default directory If you specify an alternate location the location must be accessible from all system application servers mxe int expupdatesender Specifies whether the integration framework writes the system identifier the value of MAXVARS MXSYSID to the SENDERSYSID field when it generates an outbound transaction from the Data Export feature The default value is 0 mxe int adm...

Page 146: ...int wsdlincludesschema When you set this property value to true the Web Service Definition Language WSDL files contain the complete service schema definition The mxe in resolveschema property must also be set to true mxe int wsdlnamespace Specifies the Web Service Definition Language target namespace for Web services mxe int xmlnamespace Specifies the namespace for all the XML documents mail smtp ...

Page 147: ...y Cron Task for the Sequential Queues The default settings direct the JMSQSEQCONSUMER cron task to poll the outbound queue sqout and the sequential inbound queue sqin every 30 seconds You must activate the applicable instances of the cron task SEQQIN SEQQOUT to avoid having the unprocessed inbound and outbound messages remain in the queues If you do not use one or both of these queues do not activ...

Page 148: ... integration framework uses the split tag value and XML schema when default schema is not being used to identify the node in which the file split occurs T Queue processing The XMLIN cron task identifies the queue in which the XML file is loaded The location is based on the queue continuous or sequential specified at the external system and enterprise service level The cron task creates an index fi...

Page 149: ...rt of flat file definition FLATFILECONSUMER Cron Task Processing Properties Keep in mind the following cron task processing properties for inbound messages T File processing order The order in which files are loaded on to the server that is determined by the XML file time stamp The cron task user exit class can be used to overwrite the inbound message processing logic Parameter Description SOURCED...

Page 150: ... is created in the cron task source directory The FLATFILECONSUMER 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 Errors that are identified after a message is successfully written to an inbound queue must ...

Page 151: ...uration activities 1 Create an object structure 2 Add the system objects to the object structure 3 Assign the processing classes inbound or outbound to the object structure 4 Specify whether the object structure supports a flat file representation 5 Restrict object structure supported operations to QUERY Use the Select Action menu in the Object Structures application to perform the following confi...

Page 152: ...space In the example the software catalog tag has an assigned namespace value Use the Select Action menu in the Enterprise Services application to perform the following configuration activities 1 Create the integration controls 2 Configure the enterprise service integration controls and assign default values 3 Generate the schema files to describe the enterprise service Enterprise service configur...

Page 153: ...you are working with external system and queue based integration scenarios Configuring Invocation Channels Use the Invocation Channels tab in the Invocation Channels application to perform the following configuration activities 1 Create an invocation channel 2 Identify the object structures for request and response processing 3 Assign an endpoint 4 Assign the processing classes Use the Select Acti...

Page 154: ...Integration Components 140 Integration Guide ...

Page 155: ...ation Chapter 15 Integration Framework Customization with Processing Rules 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 Advanced Topics II ...

Page 156: ......

Page 157: ...sary data to identify the specifics of communications with the destination such as a URL The outbound queue cron task process or invocation channel invokes the handler and passes the message body and the metadata properties to it The handler uses the metadata properties to determine the external system for a publish channel message only and override values for the configured endpoint properties Th...

Page 158: ... for those properties Use the predefined handlers or create new ones to enable additional physical entities such as FTP servers For more information and detailed instructions for adding or modifying endpoints refer to the online help in the End Points application Endpoint Handler Description MXFLATFILE FLATFILE Writes flat files to a specified directory location MXIFACETABLE IFACETABLE Writes outb...

Page 159: ...perty specifies a J2EE context factory class name The documentation for your application server contains the name of the default context factory to use 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 spec...

Page 160: ...he class in the Java package structure applications maximo businessobjects classes folder T Modify the mboweb webmodule META INF MANIFEST MF class path to include the package structure T Rebuild the application EAR file and include the EJBExit class file JNDINAME Property The following required property specifies the name by which the enterprise bean client is registered in the application server ...

Page 161: ... channels The object structure that you associate with a publish channel must be marked as flat supported Resolve all object structure alias conflicts and format the XML message according to the system schema to write the message to a flat file Flat File Naming Convention File names require the following format externalsystemname_publishchannelname_uniqueidentifier DAT T externalsystemname is the ...

Page 162: ...T PAYMENTTERMS 1071 Rotating Custom Item No 71 1000 A0001 The following example data uses a comma as a delimiter The INVOICEDESC data Rotating Custom Item No 71 contains the delimiter character and double quotation marks When the flat file is written the INVOICEDESC value appears in the code EXTSYS1 MXINVOICEInterface Add INVOICENUM INVOICEDESC PONUM VENDOR CONTACT PAYMENTTERMS 1071 Rotating Custo...

Page 163: ...e of valid codes values 200 through 299 If the response code falls outside that range the system assumes that the message was not delivered to the external system An exception occurs and the message remains in the queue If you need additional processing for a specific implementation extend the default implementation and override the processResponseData method As an alternative you can implement th...

Page 164: ...This optional property specifies the read timeout value in milliseconds URL Property This optional property specifies a valid URL to which XML data can be posted or where an HTTP GET operation can be performed USERNAME and PASSWORD Properties If the URL requests basic authentication these properties specify the required values Both values are MIME encoded and are passed to the URL IFACETABLE Handl...

Page 165: ...LIN The example contains the location port number and database name USERNAME and PASSWORD Properties If access to the database instance requires a user name and password these properties specify those values These properties apply only when the value of ISREMOTE is 1 JMS Handler The Java Messaging Service JMS handler is a Java component that consists of several properties The handler delivers XML ...

Page 166: ...e JNDI tree CONTEXTFACTORY Property This property specifies the initial context factory class name The property is not required when the JMS handler is communicating with a JMS provider that shares the same initial context factory as the application server of the handler When the handler and the JMS provider share a WebSphere Application Server they share the initial context factory class The cont...

Page 167: ... InitialContext object PROVIDERUSER and PROVIDERPASWORD Properties These properties are used for the JMS provider authentication The properties map to the connectionFactory createConnection provideruser providerpassword API in JMS WEBSERVICE Handler The WEBSERVICE handler is a Java component that consists of several properties The handler invokes a specified Web service with system data as a SOAP ...

Page 168: ...thod is called after a successful invocation of the external Web service public void responseError Exception e throws MXException If an error occurs when the Web service is called the responseError method is called with the originating exception as a parameter The default implementation of the WSExit interface is psdi iface router DefaultWSExit XMLFILE Handler The XMLFILE handler is a Java compone...

Page 169: ...er configuration the endpoint has at the time of the system invocation The CMDLINE handler has the following properties T CMDTIMEOUT The timeout value for command execution T CONNTIMEOUT The timeout value for the connection T USERNAME The user name for the connection T PASSWORD The password for corresponding user name T HOST The host name of target where command is run T PORTNO The port number of ...

Page 170: ... A CLSUBn tag must correspond to each substitution position in the CLCMDPATTERN tag The return byte array representation of an XML document contains the results of the command The XML document contains tags that correspond to the return value STDOUT and STDERR The following tags are available T CLRETURNCODE The return code from the remote command T CLRESPONSEOUT The data that is returned by the re...

Page 171: ...mation about the external system and the interface T Data is the XML data T 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 158 Integration Guide ...

Page 173: ...ation of the interface table polling process to improve its performance when reading data from interface tables 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 Advanced Interface Table Polling 11 ...

Page 174: ...ance1 1 When you implement multiple cron tasks you also must implement mutually exclusive selectors to avoid processing a message more than once For more information about cron tasks refer to the System Administrator Guide and the online help for the Cron Task Setup application Selectors You use a selector to add a WHERE clause to a cron task If you define multiple instances of the cron task you m...

Page 175: ...he corresponding data in the interface tables You can improve performance by setting up multiple queue tables For example you can write each interface to a separate queue table and define separate cron tasks to process the queue tables independently of one another You also can set up separate queue tables for each external system and within each queue table define selectors for each interface Depe...

Page 176: ...Queue Tables 162 Integration Guide ...

Page 177: ...he queue When the system sends publish channel messages the message is written to a JMS queue The message is then sent to an external system Messages remain in an outbound queue until they are successfully processed or deleted from the queue Your JMS queue implementation can operate on a single application server or across a cluster of application servers There are three default message queues T O...

Page 178: ... that you must configure when you do not to use the default queues and do not use a provided application server Provider URL A value that you must configure when you do not to use the default queues and do not use a provided application server User ID The user ID that you configure when the queue is secured on the application server Password The password that is configured when the queue is secure...

Page 179: ...sk one that polls the inbound queue and one that polls the outbound queue The following table describes the cron task parameters that you can configure Continuous Queue The continuous queue is a JMS queue with a message driven bean MDB as a consumer By default this queue is configured for enterprise services only The queue does not process messages in first in first out sequence as the sequential ...

Page 180: ...ntry name MESSAGEPROCESSOR env entry name env entry type java lang String env entry type env entry value psdi iface jms QueueToMaximoProcessor env entry value env entry message driven MEA ejb for MDB container transaction method ejb name JMSContQueueProcessor 1 ejb name method name method name method trans attribute Required trans attribute container transaction Uncomment the following lines in th...

Page 181: ...ame item number If an inventory message for Item A is processed before the item message that adds Item A to the system is processed the inventory message produces an error because Item A does not exist Processing continues with the next message Eventually the item message for Item A is processed and Item A is added to the system The failed message can then be successfully processed In this case th...

Page 182: ... number of message driven beans until you are satisfied with the processing performance of the messages in the continuous queue The number of message driven beans and the volume of messages processing in a queue can use enough system resources to affect your application users If you continue to increase the amount of message driven beans this change may have little or no impact on message processi...

Page 183: ...he message when the number of retries set in the maximum failed deliveries parameter is met The continuous queue then processes new queue messages Configuring the Error Queue To configure an error queue 1 Configure an error queue destination within the same bus member where the continuous queue resides 2 Configure the continuous queue destination definition to have an exception destination The exc...

Page 184: ...ame 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 MessageDrive...

Page 185: ...ueue you must uncomment entries for the error queue in the ejb jar xml and weblogic ejb jar xml files Queue Message Format Messages that are loaded into the JMS queues by the integration framework have defined components and formats Message Header The header can contain the following standard JMS header values Message Properties The properties contain the following mix of properties from the JMS p...

Page 186: ...ompression This value must comply with the schema type int xsd int and is present only when the compressed property is set to true MSG_TRK_ENABLED Internal value MSG_OP_MODE The endpoint name for the outbound messages fixed string MXJMS for inbound messages MSG_TRK_STORE_MSG Internal value MSG_TRK_EXTSYS External system name for outbound and inbound messages Msgkeyval A field name message key sear...

Page 187: ...tor SENDER EXTSYS1 AND INTERFACE IN MXPOInterface MXPRInterface message selector If two external systems send data to an inbound sequential queue an error in any record stops the processing of all transactions in that queue to maintain a first in first out processing order Create multiple instances of a cron task each with a selector that processes a different external system to prevent an error i...

Page 188: ...in following ways 1 Create an WebSphere MQ provider on the WebSphere Application Server and configure an integration endpoint to point to the message queue MQ provider by using T The destination JNDI name DESTJNDINAME T The connection factory JNDI name CONFACTORYJNDINAME 2 Configure the endpoint to point to the WebSphere MQ by using T The destination JNDI name DESTJNDINAME T The connection factory...

Page 189: ...reate the JMS queue by defining an alternate provider to replace the default provider 2 Create a proxy queue on the WebSphere Application Server by using the WebSphere MQ provider that points to your message queue MQ server queue 3 In the Add Modify Queues dialog box in the External Systems application add values to the Queue JNDI name and Connection Factory fields to point to the proxy queue and ...

Page 190: ...IBM WebSphere MQ 176 Integration Guide ...

Page 191: ...of system components You can enable security as needed based on your implementation 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 Security 13 ...

Page 192: ... the queue enter the same user ID and password in the Add Modify Queues dialog box in the External Systems application You access this dialog from the Select Action menu For the continuous queue update the message driven bean the consumer of the continuous queue deployment descriptors as follows to access a secured queue 1 Under the enterprise beans section in the ejb jar xml file add the followin...

Page 193: ...nable the security for each enterprise bean in the deployment descriptors 1 Change the ALLOWDFLTLOGIN value to 0 false to force system authentication Under the enterprise beans section of the ejb jar xml file three integration EJBs enterprise service object structure service and standard service are deployed with a default value of 1 no authentication The ejg name to service mapping is The followi...

Page 194: ... 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_actionservice ejb name actionservice ejb name home psdi iface action ...

Page 195: ...nformation through the D parameters in the bat sh script that launches the client Djava naming security principal username Djava naming security credentials password The SSL version of Internet Inter ORB Protocol performs data encryption in the provider URL while the system communicates with the enterprise bean HTTP Servlet The HTTP servlet is a J2EE component that handles inbound HTTP posts to th...

Page 196: ...uth constraint user data constraint description data transmission gaurantee description transport guarantee NONE transport guarantee user data constraint security constraint security constraint web resource collection web resource name App Service Servlet web resource name description App Service Servlet HTTP POST accessible by authorized users description url pattern ss url pattern http method GE...

Page 197: ...ser description role name maximouser role name security role In addition change the following web xml value for useAppServerSecurity from 0 to 1 in the web xml description Indicates whether to use Application Server security or not description env entry name useAppServerSecurity env entry name env entry type java lang String env entry type env entry value 0 env entry value env entry You can secure...

Page 198: ...straint security constraint 2 For Web service invocation ensure that the client program uses the following user name and password calls in the JAX RPC Call object call setProperty Call USERNAME_PROPERTY username call setProperty Call PASSWORD_PROPERTY password You can securely deploy a Web service by using SSL HTTPS Set up the SSL in the application server with the appropriate digital certificates...

Page 199: ...that implements the interface table handler Outbound Router Handler Security The outbound router handlers have support for authorization and confidentiality The enterprise bean HTTP JMS Web service and interface table handlers have support for security Object Level Authorization The system provides object level authorization based on the security configuration set within the system If an object or...

Page 200: ...eStatus 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 Any condition that you assign is ignored ...

Page 201: ...ation of the continuous queue can handle your message volume If a single server does not meet your needs add central processing units hardware and a cluster configuration to improve message processing performance 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 MD...

Page 202: ...n task instance is instance1 1 In the Cron Task Setup application set the TARGETENABLED property for instance1 to 1 2 In the application server1 setup set the D crontaskname instance1 to 1 and restart the server In this configuration example the task is not pushed to another server if the targeted server stops To replace a stopped server set the D crontaskname instance1 value to 1 then restart the...

Page 203: ... cluster members to produce messages into the queue Additionally messages are read by a single threaded cron task to support first in first out processing The continuous queue is multi threaded on the consumer side The queue supports message processing in high volumes In this queue the message processing order is not considered Enterprise service messages that use the sequential queue are processe...

Page 204: ...ster needs to be configured with its own message engine The processing occurs when the integration framework receives enterprise service messages by using the HTTP EJB Enterprise JavaBeans and SOAP actions The load balancer directs the enterprise service messages to an application server which then places the message into the continuous queue Each application server in the cluster places messages ...

Page 205: ... data You can use the External System Interface and Queue table properties to select data T Import XML file data Enable multiple instances of the XML file import cron task to different servers and use the cron task properties to select different files to import Use the source directory and file name properties to select the import files T Import flat file data Enable multiple instances of the flat...

Page 206: ...plication servers and one message engine on a single application server ATTENTION Do not implement the sequential queue on the continuous queue integration bus When you use the continuous queue integration bus for sequential queue implementations messages may be unprocessed or may be processed out of order The load balancer directs the application server to drop enterprise service messages into th...

Page 207: ...e example three application servers exist in the clustered environment The continuous JMS queue is pinned to one member of the cluster The processing occurs when the integration framework receives enterprise service messages by using HTTP enterprise beans and SOAP actions The load balancer directs the application server to drop enterprise service messages into the continuous queue Each member of t...

Page 208: ...mer messages In the example three application servers exist in the clustered environment The sequential JMS queue is pinned to one member of the cluster The processing occurs when the integration framework receives enterprise service messages by using HTTP enterprise beans and SOAP actions The load balancer directs the application server to drop enterprise service messages into the sequential queu...

Page 209: ...luster that is dedicated to processing inbound messages deploy a separate application EAR file and the target enabled cron tasks for polling the inbound queues interface table and inbound file processing to the server cluster If applicable configure the message driven beans to pull data from the inbound continuous queue You can run other background processing cron tasks on this server cluster You ...

Page 210: ...l members of the cluster With a single server the URL is the HTTP and HTTPS URL of that server With a cluster the URL is the HTTP and HTTPS URL of the load balancer for the cluster A separate servlet is deployed for each type of service object structure enterprise and standard service The URL formats for each service are shown in the following table The meaweb value represents the mxe int webappur...

Page 211: ... Web Application URL mxe int webappurl T Integration UDDI Registry Inquiry URL mxe int uddiinurl T 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 198 Integration Guide ...

Page 213: ...und messages of an enterprise service You cannot use processing rules in invocation channels object structure services or standard services 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 Integration Fr...

Page 214: ...ssing you can apply processing rules to object structure records only T For inbound processing you can apply processing rules to object structure records or objects If an inbound rule changes the key field value of an object apply rules to the object structure record If an inbound rule does not evaluate or manipulate an object or object set apply rules to the object structure record If an inbound ...

Page 215: ...top action on the PERSON object Specify that the rule that is to be applied when the primary PERSON object is updated This rule performs the stop action if a user changes any attribute on a person record When an outbound message is generated using the Data Export feature or by a programmatic call to the publish channel all enabled processing rules are run regardless of the action settings The syst...

Page 216: ...u use the skip action For example if a processing rule with a stop action applies to a publish channel that is generated by the Data Export feature the stop action is treated as a skip action If the stop action evaluates as true the message is skipped SKIPCHILDREN action The skip children action is available only for outbound messages in a publish channel Apply the processing rule on the record or...

Page 217: ...ace the SITEID value in a publish channel with an external PLANTID value and to replace the external PLANTID value in an enterprise service with a SITEID value you can use a single cross reference control COMBINE action The combine action concatenates values from multiple source fields into a single target field When you define the rule you identify the target field and the source fields You also ...

Page 218: ...e field length sequence and values that you specify For example target field A with a character length of 6 holds positions 1 6 of the source field Target field B with a character length of 3 holds positions 7 9 of the source field Variable length Data Segments If the length of the source field segments is variable but the source field contains a distinct delimiter that identifies the segments use...

Page 219: ...alse If every evaluation within a condition is true the condition is true If any evaluation within the condition is false the condition is false If a processing rule contains multiple conditions only one condition must be true for the action that is associated with the processing rule Evaluation Category Specifications Before you define the specifics of an evaluation select the type of data that m...

Page 220: ... evaluations that you can use Direction of Processing Rule XML Field Evaluation Object Field Evaluation Object Set Evaluation Control Evaluation Outbound Available Available Available Available Inbound record Available Not available Not available Available Inbound Object Available Available Available Available Type of Evaluation Description EQUALS The value in the specified field is equal to the v...

Page 221: ...ng rule uses one of the first eight evaluation types it must specify the field comparison field with which it is making the comparison The user interface displays subsets depending on the type of evaluation XML field object field object set or control 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 Chan...

Page 222: ...r the database all decimal fields must use a period as the decimal placeholder Numbers to the left of the placeholder are not formatted This format applies to inbound and outbound data For example 1 738 593 64 must be in the following format 1738593 64 Example A processing rule compares the value of the POLIN1 field with the value SPARE If the evaluation type is EQUALS and the two values are the s...

Page 223: ...ists among these levels because organizations are defined for a system and sites are defined within organizations Accordingly an integration control can be configured to override values at any of the following levels Data that is processed by enterprise services or publish channels that use a control with an organization or site override must be at the organization or site level Control Value Desc...

Page 224: ...to a system value You can optionally assign a system domain to a cross reference control If a domain is specified any system value that is specified for the control is validated against that domain If a domain is not assigned there is no validation of the values that are entered Cross reference controls must have a one to one mapping between the system value and the external system value If two sy...

Page 225: ...enerally sufficient to customize predefined enterprise service or publish channel processing If new business rules are implemented or a new publish channel and enterprise service is implemented a new control might be needed Use the following guidelines when you create new controls T Control names must unique T To use the controls as part of a processing rule and to set a value at the external syst...

Page 226: ...Integration Controls 212 Integration Guide ...

Page 227: ...ne or more of these placeholders or user exits for your customizations 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 You can reference the XSL file in the application EAR file or in a directory path in your file system Integration Framework Customization wi...

Page 228: ...preprocessing Processing class Second user exit user exit postprocessing T With XSL mapping T In a handler exit The following diagram shows the flow of a message that uses a publish channel The process flow starts from the object structure to the endpoint The endpoint delivers the message to its destination Invocation Channel The customization of an invocation channel is comparable to the publish ...

Page 229: ...cessing T With XSL mapping T In a handler exit For responses you can customize an invocation channel in the following ways T In the following Java exits First user exit user exit preprocessing Publish channel processing class Second user exit user exit postprocessing T With XSL mapping The following diagram illustrates the flow of a message that uses an invocation channel The process flow starts f...

Page 230: ...e Java exit cannot update the values of the business object You can access a business object that is not part of the publish channel object structure by using any relationship from an object available in the exit You can also instantiate a new object from the database as needed You can use either option to retrieve additional data from the system You then can map the data to the outbound XML messa...

Page 231: ...tprocessing or after exit class If you create a publish channel use the following method to customize the publish channel processing class public StructureData setDataOut StructureData sData The following method can perform the noted processes T Validate data T Change system data by changing the IR record to be sent to the external system T Stop the transaction from being saved in the database by ...

Page 232: ... Channel tab in the Publish Channels application The XSL file can be part of the EAR file and must reside in the businessobjects classes folder structure You also can define the XSL file on a publish channel by using a directory file path that is not part of the EAR file Register the XSL file mapping in the following manner when the XSL file mapping xsl resides in the businessobejcts classes psd i...

Page 233: ...emented in the HTTP exit class If the publish channel message is not accepted the code must raise an exception The message in the outbound queue is marked in error and is not removed from the queue If the message is accepted the message is removed from the outbound queue If the invocation channel message fails the exception is returned to the invoker of the channel and the invoker handles the exce...

Page 234: ...ature in the form of an array of Java classes The following method can perform the noted processes T Create an array of parameter values that correspond with the signature of the external enterprise bean method to be called public Object getObjectParams byte data String interfaceName String destinationName The parameters of the enterprise beans are returned in the form of an array of Java Objects ...

Page 235: ...ied name of the Java class in the JMSEXIT property of the endpoint that implements the JMS handler The Web Service Processing Exit Class You can use an exit placeholder for customization when sending transactions from the system to an external system using a Web service This exit class is optional and is called before the Web service is invoked The following figure shows the Web service processing...

Page 236: ...throws MXException The getOneWayWsInfo method returns a Boolean value that specifies whether the Web service being invoked is one way public String getSoapAction Map metaData String endpointURL String serviceName String interfaceName String targetNameSpace String soapAction throws MXException The getSoapAction method returns the SOAPAction HTTP header to be used while invoking the Web service You ...

Page 237: ...object user exit The following diagram shows the flow of a message that uses an enterprise service The process flow starts at the receipt of a message that uses one of multiple protocols supported by the framework through to the setting of the data in the object structure and system business objects The enterprise services that use XML can bypass the JMS queue Interface Table User Exit The externa...

Page 238: ...after the data is pulled from the interface table and before the data is inserted into one of the inbound queues public void afterCommit long transid String extSys String ifaceName Connection conn This method is called after the data has been inserted to an inbound queue and deleted from the interface queue table and the database commit is done public void afterRollback long transid String extSys ...

Page 239: ...ou can instantiate a new object from the database to perform lookups or gather additional system information as part of your custom logic User Exit Preprocessing The user exit class consists of two methods one exit runs before and one exit runs after the enterprise service processing class If you have an ERP adapter that provides a processing class your user exit logic can be implemented to run be...

Page 240: ...e processing class by using the following method public StructureData setDataIn StructureData sData This method can perform the following processes T Validate data T Change external data by changing the ER record before it is mapped to the IR record and saved in the system T Stop further processing of the transaction throwing an exception In this case the transaction remains in the queue to be ret...

Page 241: ...ceholder to implement an XSL file and to manipulate the data to be set to the object structure after the Java exit processing is completed The XSL file is always called with the XML message that is output from the Java exit processing You identify the XSL file on the Enterprise Service tab in the Enterprise Services application The XSL file can be a part of the EAR and must be under the businessob...

Page 242: ...ainst the objects that are created in the system by using the following method public void setUserMboIn MboRemote mbo The object parameter is a reference to a primary object in the object structure This method is called once for the primary object For an XML transaction with multiple nouns the object exit is called once for each noun The method can perform the noted processes T Validate data T Sto...

Page 243: ...ined components Duplicating an integration component and modifying the copy has several advantages 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 Integration Component Additions and Modifications 17 ...

Page 244: ...ition object structure MXPERSON After you use the person application you determine that the data that you need resides in the following tables PERSON PHONE EMAIL SMS The tables have the same name as the corresponding objects Include the PERSON PHONE EMAIL and SMS objects in the object structure that you create The resulting enterprise service and publish channel contain the data fields in those ob...

Page 245: ...ue instead of the primary key to access the object Required Fields The integration framework and the external system exchange a subset of the data columns in the objects within the object structure Subject to certain restrictions you can add nonpersistent object structure columns and exclude persistent object structure columns Persistent Fields By default the system includes in object structures a...

Page 246: ...te a user defined object structure and deleting objects from the copy Object Columns You can include and exclude persistent and nonpersistent columns within the scope of the standard validations Outbound messages include the columns for objects that you add to an object structure Test inbound messages to ensure that the added object columns are processed successfully If the object columns are not ...

Page 247: ...ocesses inbound integration messages Enterprise Services The enterprise service specifies the type of operation that the service supports Processing rules change data in the enterprise service before objects are created You can change data without having to use Java class files Object Structures The object structure provides the XML message content for enterprise service data processing Operation ...

Page 248: ...structure service processing Object Structure Processing You can provide customized inbound and outbound processing logic in the inbound processing and an outbound definition classes Object structure services require XML messages that comply with the object structure XML schema definition Standard Services You can use standard services to expose system application service methods for invocation by...

Page 249: ...rols globally and associate them to a publish channel You can use integration controls to control the behavior of processing logic in a Java class or in a processing rule Control values are used in publish channel implementations to meet your business requirements Interface Tables If necessary you can change the interface table name for the service or channel Invocation Channels You can create an ...

Page 250: ...e class by using the integration context You must set the context API to IntegrationContext getCurrentContext setProperty MetaDataPropert ies ENDPOINT endpointname Predefined Service and Channel Modifications Rather than create a service or channel you can duplicate predefined services and channels and then modify the duplicate record You can work with the service configurations to redefine the fo...

Page 251: ...The attribute defines the processing that the object must perform Working with Publish Channels To work with the publish channel the external system uses 1 Decide whether the channels run through the Data Export feature or an event based message data is updated by a system application You export data by using the Data Export button on the Publish Channels tab 2 Enable the publish channel for outbo...

Page 252: ...Predefined External System Modifications 238 Integration Guide ...

Page 253: ... a response to the query You can execute a query by using HTTP Java Remote Method Invocation RMI or a Simple Object Access Protocol SOAP request in a Web service 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 applicati...

Page 254: ...ject Structures application to create additional object structures which provide support for the Query operation Creating an Enterprise Service Query To create an enterprise service query 1 If one does not exist create an object structure containing the objects that the query needs to access 2 Define an enterprise service that implements the previously created object structure 3 Specify Query as t...

Page 255: ...r Query rsStart In the query request Use with maxItems to specify the first record to be returned in a response If maxItems equals 10 and rsStart is not specified the response returns results 0 through 9 To receive results 10 through 19 resend the query with rsStart equals 10 If rsStart is not specified the response starts with the first record in the result set If the number of records in the que...

Page 256: ...otal of 35 rows as noted by rsTotal but only rows 11 through 20 are returned max QueryMXINVBALResponse xmlns max http www ibm com maximo creationDateTime 2008 09 28T21 49 45 baseLanguage EN transLanguage EN messageID 12345 maximoVersion 7 1 rsStart 11 rsCount 10 rsTotal 35 max MXINVBALSet max MXINVBALSet rsCount The number of records that are returned in the message rsCount does not reflect any ro...

Page 257: ...or all the configured attributes of the PERSON object and all of its child objects EMAIL PHONE and SMS The QueryMXPERSON operation element uses the following additional attributes T uniqueResults Is a Boolean value that when set to 1 True directs the query to return a single and unique record when the value is set to 1 True If more than one record is found an error is returned When the attribute i...

Page 258: ...der that it was retrieved by the database T operandMode This value has two valid values AND and OR The system uses this value when one or more fields is used for evaluation in a query execution When you use the AND value all field evaluations must be true When you use the OR value only one of the field evaluations must be true When the attribute is not defined the default value is AND QueryMXPERSO...

Page 259: ... of a query request contains the selection criteria for the query A query can select records based on a single value or a range of values The integration framework supports the use of query operators such as or Selection criteria applies only to attributes of objects in the top two levels of the object structure However the response includes data from all the objects in the object structure Field ...

Page 260: ...The following query searches for employees where PERSONID is equal to ATI and STATUS is equal to ACTIVE QueryMXPERSON MXPERSONQuery PERSON PERSONID operator ATI PERSONID STATUS operator ACTIVE STATUS PERSON MXPERSONQuery QueryMXPERSON The operandMode attribute of the MXPERSONQuery element defines the statement that is run with an AND or an OR condition between the field evaluations The default con...

Page 261: ...r INACTIVE QueryMXPERSON MXPERSONQuery PERSON STATUS ACTIVE INACTIVE STATUS PERSON MXPERSONQuery QueryMXPERSON The following query searches for the employees where the Person ID starts with the letter A QueryMXPERSON MXPERSONQuery PERSON PERSONID operator SW A PERSONID PERSON MXPERSONQuery QueryMXPERSON The following query searches for the employees where the Person ID ends with the letter Z Query...

Page 262: ... You must configure enterprise Web services to bypass the JMS queues 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 baseLa...

Page 263: ...Web Service Queries Integration Queries 249 ...

Page 264: ...Web Service Queries 250 Integration Guide ...

Page 265: ...terprise services as Web services The system Web services are document literal style Web services that comply with the Web Services Interoperability Organization WS I Basic Profile 1 1 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 Integrat...

Page 266: ...operation T Provide a response for the Query operation in the object structure XML schema format Enterprise Web Services You can create an enterprise Web service from a predefined or a user defined enterprise service Enterprise Web services differ from object structure Web services in that the enterprise Web service supports additional exit processing business rules and transformations not availab...

Page 267: ... input and output parameters for the standard Web service Web Service Deployment Actions You deploy a Web service through the Deploy Web Service action When you deploy a Web service the following events occur T Schemas are generated and regenerated for existing service schemas T The Web Services Description Language file is generated for the service interface T The Web service is deployed for the ...

Page 268: ...structs The XML schema folders contain the following files There is an external folder in the schema folder If you want to use an external service to deploy an enterprise service as a Web service place the service schema files in the external folder You can view the generated schema files using the following URLs T hostname port meaweb is the value of the Integration Web Application URL property T...

Page 269: ... literal as mandated by Web Services Interoperability Organization WS I Basic Profile 1 1 The Web Service Definition Language also specifies the URL on which to invoke the Web service A client program needs the schema definitions and Web Service Definition Language to generate client stubs The client program uses a programming language for example Java or C to invoke the Web service You can access...

Page 270: ...iles The WebSphere Application Server provides the tool WSDL2Java When a Web service is invoked the response is synchronous A successful response returns an HTTP response code of 200 By default SOAP faults that are returned do not contain the server side stack trace as it represents a potential security risk However you can change this function by changing the following parameter value in the axis...

Page 271: ...sLanguage string messageID string maximoVersion string The Query operation returns the response content according to the object structure definition xml version 1 0 encoding UTF 8 max CreateMXPERSONResponse xmlns max http www ibm com maximo creationDateTime 2008 09 28T21 49 45 baseLanguage string transLanguage string messageID string maximoVersion string max PERSONMboKeySet max PERSON The Create o...

Page 272: ...Integration Web Service Invocations 258 Integration Guide ...

Page 273: ...ervices can include these translated columns A single system database can contain data in multiple languages You specify the base language when you install the application 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 Multiple Language Support 20 ...

Page 274: ... table called L_tablename for example ITEM and L_ITEM The L_tablename table stores the non base language values for every translated column except the long description Long descriptions in all languages are in the LONGDESCRIPTION table To include translated values in the output XML include the L_tablename and LONGDESCRIPTION objects in the applicable object structures Provide the base language val...

Page 275: ...lidated The languageEnabled Attribute Output XML includes the attribute on every translatable column as shown in the following example DESCRIPTION langenabled 1 Item 1 description DESCRIPTION The transLanguage Attribute The attribute identifies the language in which the values for applicable multilanguage fields are specified If this attribute is missing or does not contain a value all data is ass...

Page 276: ...Multilanguage Attributes 262 Integration Guide ...

Page 277: ...or by using the Tivoli Provisioning Manager You can download integration modules from the Tivol Open Process Automation Library OPAL Use the process solution installer to load integration modules into the integration framework If you are familiar with the programming interface for the operational management product you can create integration modules when one does not exist A process management pro...

Page 278: ...ntegration module Operational Management Products An operational management product such as Tivoli Provisioning Manager automates system processes such as software deployment Operational management product services are run on assets such as servers The assets are referred to as configuration items Multiple instances of operational management products can exist in a production environment More than...

Page 279: ...owing properties T Name The name of the action for example Get Deployment Status T Namespace The unique qualifier for example com ibm tivoli deployment T Invocation pattern Synchronous The process management product issues a request and the integration module returns the results of the operation immediately Asynchronous one way The process management product issues a request and no response is ret...

Page 280: ...nt product must be enabled Logical Management Operation Associations Typically there is a one to one communication between a logical management operation and an operational management product function However a single logical management operation invocation can cause the integration module to invoke an operational management product multiple times An integration module that uses an invocation chan...

Page 281: ...perties The following properties are necessary to implement an integration module Integration Module Parameters The integration framework provides integration module input parameters Parameters include source and response objects and object sets and endpoint names These parameters are passed when you run an integration module as a Java class or as an invocation channel The following table lists th...

Page 282: ...If applicable handle the operational management product response T If applicable populate the response object or response object set with the return data T Return processing information back to the caller Integration Modules and Endpoints The integration framework provides endpoints that facilitate the invocation of an external service such as an operational management product service An integrati...

Page 283: ...use one of the available handler protocols An alternative solution is to write a custom handler that supports the operational management product service protocol Configure a different endpoint for each operational management product to establish individual protocols for each product The handler that you define for the endpoint must match the handler that you configure for the integration module Co...

Page 284: ... transactions T The integration framework handles the conversion of objects to XML and XML to objects T Can be configured to use processing classes user exits and XSL mapping for inbound and outbound transactions T The integration framework performs endpoint invocation T Can be invoked directly without an association to an integration module or a logical management operation T A simple integration...

Page 285: ...ss integration modules must implement the Java interface psdi iface mic ServiceInvoker The service invoker Java interface is included in the businessobjects jar file Include the integration module Java class in the system class path at run time The service invoker Java interface has variations of the following method signature public byte invoke Map String Object metaData MboRemote sourceMbo MboRe...

Page 286: ...e integration module behavior but you must clearly define the expected behavior in the logical management operation description Invocation Channel Implementation Invocation channels use object structures in its implementations to expand the message data content The object structure uses the object that the process management product passes as the source object to build an entire record that can co...

Page 287: ...an configure the XSL mapping layer to do XML mapping or data transformation If the object structure that you need for your integration module invocation does not exist you can create an object structure in the Object Structures application You also can use XML with the MXINTOBJECT object structure to create object structures as part of the installation process For more information and detailed ins...

Page 288: ...talled An integration module record identifies which logical management operations are supported on an operational management product When the integration modules configuration items and operational management products are registered the process management product Java class performs a lookup The Java class determines which integration modules that it invokes based on the configuration items that ...

Page 289: ...ion on the operational management product Collection getIMListForOMPAndLMO String ompGUID String lmoName String lmoNamespace Retrieves the list of integration modules that implement the logical management operation on the specified operational management product Returns a collection of psdi iface omp OmpImLmoRelInfo objects Collection getIMListForOMPAndLMO String ompHostname String ompProductname ...

Page 290: ...ker utility method The action class provides the logical management operation response object to the integration module when necessary The logical management operation response object requires attributes The action class must ensure that the response object has the logical management operation attributes The attributes can be persistent or nonpersistent The response object typically contains the s...

Page 291: ... that manage the specified actual configuration item public Collection Map getServiceInvokerListForCIAndLMO String actCIGUID String lmoName String lmoNamespace UserInfo userInfo Each operational management product that has a relationship with the specified actual configuration item returns the preferred integration module for the logical management operation Property Description metaData The prope...

Page 292: ...fo ompImLmoRelInfo psdi security UserInfo userInfo Retrieves the service invoker for the specified integration module logical management operation and operational management product Map String Object getServiceInvoker psdi iface app im OmpImLmoRelRemote ompImLmoRelRemote psdi security UserInfo userInfo Retrieves the service invoker for the specified integration module logical management operation ...

Page 293: ...Integration Module Invocation Integration Modules 279 ...

Page 294: ...Integration Module Invocation 280 Integration Guide ...

Page 295: ...ication 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 You cannot use a launch entry to open applications that are not enabled for the Web You can configure a launch point from any system application L...

Page 296: ...tion users are authenticated and directed to the external console Otherwise the external console opens a login panel to authenticate the application user Defining Launch Entries To make a launch entry available to the system applications 1 Define the properties of the launch entry 2 Create a user interface control also known as a launch point that is tied to the registered launch entry Available c...

Page 297: ...dow value identifies whether the window that you want to open the external application in T Launch entry business objects The business objects that you assign restrict the launch entry usage to applications that support these objects The restriction applies when you associate a launch entry to a user interface control A launch entry can support single or multiple business objects No restrictions a...

Page 298: ...u are viewing If you are viewing the configuration item business object the globally unique identifier GUID attribute is used instead Operational management product source token The source token is an attribute of the configuration item and operational management product server relationship The operational management product console accepts the source token as the configuration item identifier Whe...

Page 299: ...e Associate to Launch Entry To Enable The Launch in Context radio button 7 In the Launch Entry Name field specify a name for the launch entry 8 Click OK to return to the Application Designer application Associating a Signature Option with a User Interface Control or a Toolbar Menu Item When you associate the signature option with a user interface control you are linking the launch entry with a lau...

Page 300: ... button you are linking the launch entry with a push button To associate a signature option with a push button 1 In the Application Designer application on the toolbar click Control Palette 2 Drag the Pushbutton control onto the application work area 3 Click the push button control to open the Control Properties dialog window 4 In the Label field type the name that you want to appear on the button...

Page 301: ...de a launch point based on set group access privileges If you use a Java condition class you must change the condition EXPRESSION attribute to the name of the launch entry The Java class can identify which launch entry is executed The expression attribute value must be an exact match to the name of the launch entry values are case sensitive Associating a Condition with a Signature Option After you...

Page 302: ...Associating a Condition with a Signature Option 288 Integration Guide ...

Page 303: ...oceed as per standard system functionality Format of Collaboration Switches Collaboration switches provide a flexible user defined way to control the processing of some inbound transactions by letting the system bypass the default processing for certain types of transactions The collaboration switches reside in the system MXCOLLAB table Each collaboration switch contains four elements three of whi...

Page 304: ... being referenced or updated Process Control Value The process control value specifies whether the system business components should bypass default processing for the type of transaction indicated by the process control ID System ID 1 and the System ID 2 The process control value can be 0 false or 1 true and can have the following meanings Default Collaboration Switches The system creates three de...

Page 305: ...m that owns the PR 2 If the value in System ID 1 is now blank null or equal to the value in the MXSYSID row of the system MAXVARS table the system uses THISMX for System ID 1 3 If the value in System ID 2 is now blank null or is equal to the value in the MXSYSID row of the system MAXVARS table and the process control ID is not PRPAB the sytem uses THISMX for System ID 2 4 If the process control ID...

Page 306: ...em ID 1 and System ID 2 10 The system finds the record with the modified key in the MXCOLLAB table This record always exists because every process control value has a default collaboration switch with both system IDs equal to EXT 11 The system uses the record process control value to determine whether or not to bypass system processing View Collaboration Switches You can use any database tool to d...

Page 307: ...aboration switches to the MXCOLLAB table New switches must use an existing process control ID but they can use new system IDs Only the default collaboration switches can use the values THISMX and EXT in the system ID fields To add a collaboration switch use the following SQL statement insert into mxcollab pcid owner1sysid owner2sysid pcvalue values PCID OWNER1SYSID OWNER2SYSID PCVALUE For example ...

Page 308: ... collaboration switch INV ORC THISMX to the MXCOLLAB table The single SQL statement following step 5 performs the processing for steps 3 4 and 5 4 Set the new collaboration switch process control value to 0 This value directs the system to perform the normal balance and cost updates when it receives issues from Oracle Financials 5 Set the OWNERSYSID attribute on the inbound transaction to the syst...

Page 309: ...nventory Process Control ID INV that is issued in the external system System ID 1 EXT and owned by the system System ID 2 THISMX If the value of the INV EXT THISMX collaboration switch were 0 the inventory balance and cost values are updated This is the default processing If the value of the INV EXT THISMX collaboration switch were 1 the default processing is bypassed The inventory balance and cos...

Page 310: ...y without any validations and delete INVBALANCES record for the item THISMX INVENTORY INVISS Enter item issues Used when issuing material 0 1 Allow material issues for the inventory Do not allow material issues for the inventory MATUSETRANS INVENTORY INVISSR Enter item issue returns Used when returning material 0 1 Allow material returns Do not allow issue returns for the material MATUSETRANS INVE...

Page 311: ...dor for internal PO ITMDEL Delete items Used when deleting items that this system does not own Attenion If value is 1 the item will still exist on related open PRs POs RFQs work orders and so on This might result in problems receiving approving these lines 0 1 Delete item if it passes normal system validations Delete item without any validation Also delete INVENTORY INVBALANCES and INVVENDOR recor...

Page 312: ... to 1 0 1 Validate match Do not validate any match provided THISMX INVOICE IVPO Update POs and receipts Used when approving invoices 0 1 Update PO status and receipts Do not update PO status or receipts INVOICE PO IVPRO Check and prorate differences between invoice headers and lines Used when approving invoices 0 1 Prorate the difference between the header and the line total Do not prorate the dif...

Page 313: ... line INVOICE PO IVTOL Perform invoice tolerance checking validation Used when approving invoices 0 1 Perform all tolerance checks on invoice Do not perform tolerance checks on invoice THISMX INVOICE IVVLC Update vendor last cost Used when approving invoices 0 1 Update vendor last cost Do not update vendor last cost INVOICE INVVENDOR IVWO Update work orders Used when approving invoice 0 1 Update w...

Page 314: ...e and Action Derivation of System ID 1 Derivation of System ID 2 PODEL Delete POs Used when deleting POs Use only when deleting then subsequently re adding a PO due to changes in the PO If any PRLINES contain a reference to the PO clear them If necessary reopen the PR When the PO is re added the PRLINEs will be established again 0 1 Do not delete PO Delete PO and PRLINEs do not delete POSTATUS THI...

Page 315: ... for blanket POs Used when approving PR and the PR lines contain a blanket references and when a release is created directly from a PO without a PR 0 1 Generate PO release If PRLINE AGREEMENTPONUM not in PO do not generate PO release Do not regenerate PO releases PR PO of the blanket PORES Process material reservations Used when changing the status of internal POs 0 1 Generate inventory reservatio...

Page 316: ... are maintained in an external system Items are in ITEM master in the system storeroom is defined as a LOCATION INVENTORY is not defined for item storeroom combination because it is not owned by the system The owner of the PR is the MXSYSID of the system that creates the PR Validation occurs when an item storeroom INVENTORY is validated on the PRLINE The OWNERSYSID of the storeroom is compared wit...

Page 317: ...ting PR lines and changing the status of PRs 0 1 If PRLINE AGREEMENTPONUM is not in PO error If PRLINE AGREEMENTPONUM is not in PO ignore error PR EXT Normally this would be from PO of the blanket but in this case the blanket PO does not exist Process Control ID Description Value and Action Derivation of System ID 1 Derivation of System ID 2 ...

Page 318: ...RECTRANS INVENTORY RCIV Generate invoices for PO receipts Used when approving receipts 0 1 Generate invoice if value of PayOnReceipt is set Do not generate invoice even if value of PayOnReceipt is set MATRECTRANS or SERVRECTRANS PO RCPO Update external PO Used when approving receipt 0 1 Update PO Do not update PO MATRECTRANS or SERVRECTRANS PO RCR Enter PO receipt return Used when creating receipt...

Page 319: ... Description Value and Action Derivation of System ID 1 Derivation of System ID 2 WORES Process material reservations Used when changing the status of a work order Inventory must exist in this system 0 1 Generate inventory reservation Do not generate inventory reservation WORKORDER INVENTORY ...

Page 320: ...Work Order Collaboration Switches 306 Integration Guide ...

Page 321: ...lectual Property Department in your country or send inquiries in writing to IBM World Trade Asia Corporation Licensing 2 31 Roppongi 3 chome Minato ku Tokyo 106 0032 Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY...

Page 322: ...alent agreement between us Information concerning non IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non IBM products Questions on the capabilities of non IBM products should be addressed to t...

Page 323: ...e trademarks of Sun Microsystems Inc in the United States other countries or both Linux is a registered trademark of Linus Torvalds in the United States other countries or both Intel Intel logo Intel Inside Intel Inside logo Intel Centrino Intel Centrino logo Celeron Intel Xeon Intel SpeedStep Itanium and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in t...

Page 324: ...310 Integration Guide ...

Page 325: ...es 130 system properties 131 boolean controls 210 business object user exit processing customization 228 C channels create 235 invocation 235 modifying 236 publish 235 cluster configuration cron task 188 global directory 195 inbound message receipt 195 enterprise beans 196 HTTP servlet 196 web services 196 JMS queues 189 message processing servers 195 WebLogic continuous queue 193 WebLogic sequent...

Page 326: ... services configuring 137 data exchange 11 integration controls 234 interface tables 234 object structure 233 operation type 233 processing 233 enterprise services continued processing rules 234 error management configuration 118 error causes 124 interface table 117 non queue 127 notification 120 research 125 error management configuration external system properties 119 system properties 118 exter...

Page 327: ...ions 266 operational management product integration 14 operational management product service method 277 parameters 267 prerequisites 266 service utility method 274 tasks 268 integration queue definition 178 J2EE restrictions 178 integration schemas 77 key fields 77 metadata schema 79 namespace property 78 object schemas 84 object structure schemas 82 schema directory and files 79 schema generatio...

Page 328: ...ion 265 enablement 267 integration 14 integration module associations 266 long description column interface table 104 M message details message tracking 110 message events 113 inbound and outbound 114 message processing SKIP action 202 SKIPCHILDREN action 202 SKIPRECORD action 202 STOP action 202 message reprocessing critical errors 124 error correction 122 error details 122 message deletion 124 s...

Page 329: ...e service create 240 operator 243 root element 240 queue selectors 172 queue utilities 173 R receipt collaboration switches 304 restrictions adapters 236 changed attribute 68 deletequeue utility 173 FLATFILE handler 147 150 HASDL column 100 interface tables 98 predefined components 130 S schemas XML directories 79 search ID message tracking 112 security enterprise bean access 179 HTTP servlet 181 ...

Page 330: ...ata exchange 12 deployment actions 253 enterprise 234 invocations 256 object structure 234 queries 248 securing 183 standard 234 253 web services continued UDDI registration 256 web service definition language generation 255 XML schema generation 254 WebLogic continuous queue cluster 193 message beans 168 sequential cluster queue 194 WEBSERVICE handler definition 153 HTTPCONNTIMEOUT property 154 H...

Search results

Summary of Contents for BJ0NJML - Service And Asset Management

Reviews:

Related manuals for BJ0NJML - Service And Asset Management

Brands by name

Popular brands

IBM BJ0NJML - Service And Asset Management, Integration Manual

Search results

Summary of Contents for BJ0NJML - Service And Asset Management

Reviews:

Related manuals for BJ0NJML - Service And Asset Management

Brands by name

Popular brands