IBM BJ0NJML - Service And Asset Management Integration Manual - Processing Sequence

Manual is about: Integration Guide

Summary of 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

    This edition applies to version 7, release 1, modification 0 of ibm maximo asset management, ibm tivoli asset management for it, and ibm tivoli service request manager, and version 7, release 1, modification 1 of ibm tivoli change and configuration management database and to all subsequent releases ...

  • Page 3: Contents

    © copyright ibm corp. 2007, 2008 iii about this publication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Xiii intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 4

    Iv integration guide object structure identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 user exit preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 5

    Contents v the changed attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 the glorder attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 6

    Vi integration guide importmessage column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 translanguage column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....

  • Page 7

    Contents vii configuring object structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 configuring enterprise services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 8

    Viii integration guide securing enterprise bean access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 http servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 9

    Contents ix user exit postprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 xsl mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....

  • Page 10

    X integration guide web service deployment actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 xml schema generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 11

    Contents xi default collaboration switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 collaboration switch retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...

  • Page 12

    Xii integration guide.

  • Page 13: About This Publication

    © copyright ibm corp. 2007, 2008 xiii about this publication this guide describes the integration framework and how to configure, integrate, and create business flows between the system and your framework applications. Intended audience the guide is intended for the following people: t developers t ...

  • Page 14

    Xiv integration guide.

  • Page 15: Using The Integration

    © copyright ibm corp. 2007, 2008 chapter 1: what is the integration framework? Chapter 2: integration framework architecture chapter 3: inbound integration processing chapter 4: outbound integration processing chapter 5: integration xml and schemas chapter 6: interface tables chapter 7: message trac...

  • Page 17: What Is The Integration

    © copyright ibm corp. 2007, 2008 3 the integration framework is a set of applications that help you to integrate the system to your external applications. You also can create business flows between the system and your external applications. Key features of the integration framework the key features ...

  • Page 18

    4 integration guide t dynamic xml schema generation for all integration interfaces. T dynamic generation of web services interoperability (ws-i) compliant web services, including web service definition language (wsdl). T provides the concept of an adapter that is used to group related integration fr...

  • Page 19: Integration Framework

    © copyright ibm corp. 2007, 2008 5 anyone involved in the implementation or day-to-day administration of the integration framework applicationsmust be familiarized with the integration framework architecture. Familiarity with the architectural concepts is essential for using the application and impl...

  • Page 20

    Integration framework overview 6 integration guide integration framework overview the integration framework facilitates bidirectional data exchange between the system and external applications in real time or batch mode. Through the integration framework, you can exchange data synchronously and asyn...

  • Page 21

    Integration framework overview integration framework architecture 7 operational management product integration operational management product integration facilitates the automation of information technology services, such as software deployment. A process management product calls an integration modu...

  • Page 22: Object Structures

    Integration framework for data exchange 8 integration guide integration framework for ui integration the integration framework provides a mechanism for you to navigate from a system application user interface to an external application user interface. You can define the context to facilitate the nav...

  • Page 23: Publish Channels

    Integration framework for data exchange integration framework architecture 9 the object structure is the building block of the integration framework that lets framework applications to perform the following functions: t publish and query application data t add, update, and delete application data t ...

  • Page 24: Invocation Channels

    Integration framework for data exchange 10 integration guide invocation channels the service oriented architecture (soa) enables the use of external services to process data from multiple sources. Invocation channels support a generic service-oriented architecture capability by enabling the system t...

  • Page 25: Enterprise Services

    Integration framework for data exchange integration framework architecture 11 invocation channel can be configured to ignore the response that is returned from the external service and return no data to the caller of the channel. Enterprise services the enterprise service is a pipeline for querying ...

  • Page 26: Web Services

    Integration framework for data exchange 12 integration guide to create an external system, you specify an endpoint, the queues, and the integration control values in the external system application. You can also define the following properties on the external system: t the endpoint that identifies h...

  • Page 27: Content

    Integration framework for operational management product integration integration framework architecture 13 data import and data export with the integration framework, you can load data from either flat files, such as comma separated, or xml files. You can initiate the data load through an applicatio...

  • Page 28: Action

    Integration framework for operational management product integration 14 integration guide operations and integration modules. The process management product provides an action class that initiates the call to an integration module, and subsequently the operational management product. The process man...

  • Page 29: Launch Entries

    Integration framework for user interface integration integration framework architecture 15 when invoked by a process management product, the integration module uses data that is passed by the process management product to assist in the invocation of the operational management product service. The in...

  • Page 30: Land In Context

    Integration framework for user interface integration integration framework architecture 16 the classification value of current data being processed in the user interface) t operational management product-specific features including the automatic substitution of operational management product host na...

  • 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: Inbound Integration

    © copyright ibm corp. 2007, 2008 19 data that the integration framework receives from an external application is identified as inbound data. The integration framework can facilitate inbound data exchange asynchronously or synchronously. Asynchronous messages are processed through the java message se...

  • Page 34: Enterprise Services

    Asynchronous inbound integration processing 20 integration guide asynchronous inbound integration processing the following prerequisites apply to asynchronous inbound processing: t all applicable object structures, services, and external systems must be defined. T the following entities must be enab...

  • Page 35

    Asynchronous inbound integration processing inbound integration processing 21 inbound integration process initiation summary an external system can use the following methods to send asynchronous messages to the system: messages in the inbound queues http post and enterprise beans the following steps...

  • Page 36

    Asynchronous inbound integration processing 22 integration guide a client can use the java naming and directory interface (jndi) name of the enterprise javabean (ejb/maximo/remote/enterpriseservice) to look up the enterprise javabean reference and to invoke the method. The client also needs the foll...

  • Page 37

    Asynchronous inbound integration processing inbound integration processing 23 if the verification fails, the integration framework issues an error and does not process the message. 2 if the verification is successful, the integration framework identifies the inbound jms queue that is assigned to the...

  • Page 38

    Asynchronous inbound integration processing 24 integration guide data import cron task the following steps describe the initiation of inbound processing that uses a data import cron task. 1 the xmlfileconsumer cron task or the flatfileconsumer cron task regularly polls the source directory that is s...

  • Page 39

    Asynchronous inbound integration processing inbound integration processing 25 the following framework activities identify the object structures that are associated with the message: 1 the integration framework retrieves the record from the inbound queue. 2 the integration framework identifies the en...

  • Page 40

    Asynchronous inbound integration processing 26 integration guide output the following table shows the possible user exit preprocessing outcomes. Enterprise service class processing summary the maximo adapter does not provide any predefined enterprise service processing classes. It implements all int...

  • Page 41

    Asynchronous inbound integration processing inbound integration processing 27 user exit postprocessing summary the integration framework applies predefined processing logic in the user exit class to the output from the preceding activity. A user exit processing class typically customizes the object ...

  • Page 42

    Asynchronous inbound integration processing 28 integration guide output the following table shows the possible xsl map processing outcomes. Object structure multiplication summary if the transaction applies to multiple organizations or sites, the integration framework creates a copy of the object st...

  • Page 43

    Asynchronous inbound integration processing inbound integration processing 29 object structure processing rules summary the integration framework applies processing rules to the object structures before it builds the objects. Object structure processing rules define conditions under which the system...

  • Page 44

    Asynchronous inbound integration processing 30 integration guide 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 t...

  • Page 45

    Asynchronous inbound integration processing inbound integration processing 31 the same processing class contains the enterprise service user exit preprocessing, enterprise service user exit postprocessing, and user exit object processing methods. Output the following table shows the possible user ex...

  • Page 46: Enterprise Services

    Synchronous inbound integration processing 32 integration guide synchronous inbound integration processing enterprise services that support query and create operations, return xml content as part of the synchronous response. The response processing layer supports java and xsl customization, but the ...

  • Page 47

    Synchronous inbound integration processing inbound integration processing 33 2 you can use the following code to invoke the enterprise javabean to process the enterprise service message synchronously: public byte{} processexternaldatasync(byte[] extdata, string servicename, string sender) a client c...

  • Page 48

    Synchronous inbound integration processing 34 integration guide the integration framework inbound integration can process numbers in either standard or scientific notation. T ip to see the processing sequence of multiple object structures associated with an enterprise service, go to the add/modify a...

  • Page 49

    Synchronous inbound integration processing inbound integration processing 35 enterprise service class processing summary the integration framework applies predefined enterprise service processing logic in the processing class to the enterprise service. The maximo adapter does not provide any predefi...

  • Page 50

    Synchronous inbound integration processing 36 integration guide 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 object structure format. The maximo adapter does n...

  • Page 51

    Synchronous inbound integration processing inbound integration processing 37 in the data, apply the stop action to all of the object structures that are created (every copy of the original object structure). T ip to see if a cross-reference control exists, go to the enterprise service tab in the ent...

  • Page 52

    Synchronous inbound integration processing 38 integration guide object creation summary the integration framework builds the objects by using the information in the object structure. Output the output of this activity is the objects. Object processing rules summary if specified, the integration fram...

  • Page 53

    Synchronous inbound integration processing inbound integration processing 39 user exit object processing summary the integration framework applies any final custom logic to the object. T ip to see if object processing customization exists, go to the enterprise service tab in the enterprise services ...

  • Page 54

    Synchronous inbound integration processing 40 integration guide for the create operation, the keys of the primary object of the object structure are returned. The entire object structure is returned based on the results of the query operation. When you use an enterprise service you can implement cus...

  • Page 55: Object Structure Services

    Synchronous inbound integration processing inbound integration processing 41 object structure services the following diagram illustrates an overview of the synchronous object structure service processing activities. Inbound integration process initiation summary an object structure service can use h...

  • Page 56

    Synchronous inbound integration processing 42 integration guide access to the home and remote class files access to the j2ee jar files for the server the url of the server that hosts the enterprise javabean the context factory class name the client code must instantiate the default intialcontext obj...

  • Page 57

    Synchronous inbound integration processing inbound integration processing 43 object processing summary the objects are passed to the system, and standard system processing is applied. If the system identifies an error in processing, it sends the object structure to the caller of the service. Object ...

  • Page 58: Standard Services

    Synchronous inbound integration processing 44 integration guide standard services the following diagram illustrates an overview of the synchronous standard service processing activities. Inbound integration process initiation summary a standard service can be accessed by using an http post, an enter...

  • Page 59: Standard Web Services

    Synchronous inbound integration processing inbound integration processing 45 access to the j2ee jar files for the server the url of the server that hosts the enterprise javabean the context factory class name the client code must run the default intialcontext object. The context derives the provider...

  • Page 60

    Synchronous inbound integration processing 46 integration guide.

  • Page 61: Outbound Integration

    © copyright ibm corp. 2007, 2008 47 data that the integration framework sends to an external application is outbound data. The integration framework can facilitate outbound data exchange asynchronously or synchronously. Asynchronous messages are processed through the java message service (jms) queue...

  • Page 62: Publish Channels

    Asynchronous outbound integration processing 48 integration guide asynchronous outbound integration processing the following prerequisites apply to all asynchronous outbound integrations: t all applicable object structures, publish channels, and external systems must be defined. T the external syste...

  • Page 63

    Asynchronous outbound integration processing outbound integration processing 49 outbound integration process initiation summary you initiate the outbound integration process by using event-based activities or by using the data export feature that you access in the external systems application. Event...

  • Page 64

    Asynchronous outbound integration processing 50 integration guide object structure identification summary the integration framework builds an object structure from the objects. 1 the object structure that is associated with each publish channel is determined. 2 the object structure identifies its co...

  • Page 65

    Asynchronous outbound integration processing outbound integration processing 51 output the following table shows the possible object structure processing outcomes. Object structure multiplication summary if the publish channel is associated with multiple external systems, the integration framework c...

  • Page 66

    Asynchronous outbound integration processing 52 integration guide user exit preprocessing summary the integration framework applies the custom processing logic in the user exit class to the object structure. You can use a preprocessing method in a user exit class to manipulate the object structure b...

  • Page 67

    Asynchronous outbound integration processing outbound integration processing 53 output the following table shows the possible publish channel class processing outcomes. User exit postprocessing summary the integration framework applies custom processing logic in the user exit class to the publish ch...

  • Page 68

    Asynchronous outbound integration processing 54 integration guide xsl map summary the integration framework applies any custom mapping to the publish channel. Xsl mapping lets you map user-defined publish channels or customize the mapping done by predefined publish channel processing classes. Both t...

  • Page 69: Invocation Channels

    Synchronous outbound integration processing outbound integration processing 55 synchronous outbound integration processing as a prerequisite, you must define all applicable object structures and endpoints on the invocation channel. Invocation channels the following diagram illustrates an overview of...

  • Page 70

    Synchronous outbound integration processing 56 integration guide outbound integration process initiation summary a service oriented architecture (soa) environment enables the use of external services for the purposes of data processing from multiple data sources. Invocation channels support this gen...

  • Page 71

    Synchronous outbound integration processing outbound integration processing 57 request class processing summary the integration framework applies predefined invocation channel request class processing logic in the processing class to the request object structure. An invocation channel request proces...

  • Page 72

    Synchronous outbound integration processing 58 integration guide output the following table shows the possible request user exit preprocessing outcomes. Request xsl map summary the integration framework applies any custom request mapping to the invocation channel. You can use xsl mapping to map user...

  • Page 73

    Synchronous outbound integration processing outbound integration processing 59 response class processing summary the integration framework applies predefined invocation channel response class processing logic in the processing class to the response object structure. An invocation channel response pr...

  • Page 74

    Synchronous outbound integration processing 60 integration guide output the following table shows the possible response user exit preprocessing outcomes. Response xsl mapping summary the integration framework applies any custom response mapping to the invocation channel. You can use xsl mapping to m...

  • Page 75: Integration Xml and

    © copyright ibm corp. 2007, 2008 61 the integration framework creates various structures, 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 servi...

  • Page 76: Integration Xml Structure

    Integration xml structure 62 integration guide integration xml structure the standard format for all integration xml messages that are exchanged through the integration framework is an object structure within a root element. Standard services do not support the use of object structures. For example,...

  • Page 77: Root Element

    Integration xml content integration xml and schemas 63 the following operations are available. T create t delete t invoke t publish t query t sync t update root element the root element of an xml message contains one or more object structures. The name of the root element is the concatenation of the...

  • Page 78

    Integration xml content 64 integration guide event the origin of an outbound xml message. Valid values are: 0 (false)—generated by the data export feature. 1 (true)—generated by an outbound integration event listener (that is, data entry in an application). Eventtype all output operations uniqueresu...

  • Page 79

    Integration xml content integration xml and schemas 65 rsstart in responses to queries: this value matches the rsstart value in the corresponding query. If the corresponding query contains a maxitems value, the rsstart value in requests for additional records is rsstart + rscount + 1. If this attrib...

  • Page 80

    Integration xml content 66 integration guide the following examples illustrate a root element with attributes. Creationdatetime="2008-09-28t21:49:45" baselanguage="en" translanguage="en" messageid="11876346770938768" maximoversion=" 7 1 harrier 060 harrier-066" uniqueresult="0" maxitems="201" rsstar...

  • Page 81: Object Structure Element

    Object structure element integration xml and schemas 67 object structure element every xml document contains one or more object structure elements. The following table lists the attributes that can apply to the object structure element. All attributes in this table are optional. The following exampl...

  • Page 82: Field Attributes

    Object structure element 68 integration guide field attributes the following attributes apply at the field level on outbound xml messages: t changed t glorder t langenabled t maxvalue t maxencrypted these attributes apply to messages that are generated by an outbound integration event. The changed a...

  • Page 83

    Object structure element integration xml and schemas 69 in outbound xml the value of a gl type field, including delimiters, appears in the value child element within the field. The outbound xml also places the gl type field components, based on the database definition of the components, in the glcom...

  • Page 84

    Object structure element 70 integration guide the maxvalue attribute fields that are associated with a synonym type domain can specify the corresponding maxvalue. This value is available for customization or exit processing. It is informational only and is not used for processing. 560-00 tubing, cop...

  • Page 85

    Object structure element integration xml and schemas 71 the change, replace, and addchange actions differ in the information that they include in the xml message and the processing that they require of the receiving system. An action attribute at the primary object level specifies the overall proces...

  • Page 86

    Object structure element 72 integration guide object. If the parent object does not exist in the database, no error is reported to the sending system. Update actions the change and replace actions indicate that the existing database records are updated. The addchange action can result in an update w...

  • Page 87

    Object structure element integration xml and schemas 73 addchange action the addchange action is like the replace action, except that any existing child record that is not specified in the message is not deleted. An addchange action on the primary object adds the primary record and all the sub-recor...

  • Page 88

    Object structure element 74 integration guide t deletion of poline3 and, by default, its child pocost records records accompanying the change action in the diagram, thepo with the action value equal to change or addchange has records that accompany a change action on the primary po object. For the s...

  • Page 89

    Object structure element integration xml and schemas 75 for the sample po, the sending system sends the following records. Some may contain updated information; some may contain the same data that are in the database. T the po header t poline 1 and pocost lines 1 and 2 t poline 2 and pocost lines 1 ...

  • Page 90: Additional Considerations

    Object structure element 76 integration guide additional considerations boolean columns in inbound transactions, a tag that represents a boolean field must contain a value of 0 (false) or 1 (true). If the tag does not contain a 0 or a 1, the object generates an error. If the xml does not include a t...

  • Page 91: Viewing Xml

    Integration schemas integration xml and schemas 77 viewing xml to view xml, select the generate schema/view xml action from the select action menu in the following applications: t enterprise services t invocation channels t object structures t publish channels you also can view xml on the web servic...

  • Page 92: Xml Validation

    Integration schemas 78 integration guide xml validation outbound and inbound xml transactions are not validated against the corresponding xml schema. Integration business rules apply to inbound data regardless of schema validation. Namespace property to change the name of the xml name space, update ...

  • Page 93: Schema Directory and Files

    Integration schemas integration xml and schemas 79 schema directory and files the generated schema files are in the subdirectories in the schema directory on the server. Metadata schema the mxmeta.Xsd file contains the core reusable types that the system uses to build all other schemas. The system r...

  • Page 94

    Integration schemas 80 integration guide content, query data, and supporting data types the following tables list the content, query data, and supporting data types. Querycontentgroup t maxitems t rsstart t uniqueresult the root element of all query input schema types. Responsecontentgroup t rscount...

  • Page 95

    Integration schemas integration xml and schemas 81 type description attribute mxbooleanquerytype extension of integer operator mxdatetimequerytype extension of datetime operator mxdomainquerytype extension of string operator maxvalue mxdoublequerytype extension of double operator mxfloatquerytype ex...

  • Page 96: Object Structure Schemas

    Integration schemas 82 integration guide object structure schemas object structure schemas define the content of an object structure. Each object structure has a distinct schema that includes all the configured persistent and nonpersistent fields that are defined for each object in the structure. Ob...

  • Page 97

    Integration schemas integration xml and schemas 83 these elements are referenced in service level schemas and only the mxperson and mxpersonset can be outside the context of a service level schema. For example, internal applications such as deployment manager use schemas comparable to mxperson and m...

  • Page 98: Object Schemas

    Integration schemas 84 integration guide object query content you can use query elements only within the context of a service level schema. The following content format is in the object query element: t element mxpersonquery is type mxpersonquerytype. T complex type mxpersonquerytype has elements fo...

  • Page 99

    Integration schemas integration xml and schemas 85 schema generation the system generates the files when you generate the following components: t object structure schema that contains the object t object structure service or enterprise service schema where the object structure referenced by the serv...

  • Page 100: Service Level Schemas

    Integration schemas 86 integration guide service level schemas service level schemas apply to enterprise services, object structure services, and standard services. The same schema describes enterprise services and object structure services. A different schema describes standard services. Enterprise...

  • Page 101

    Integration schemas integration xml and schemas 87 t invokemxperson t invokemxpersonresponse t publishmxperson t querymxperson t querymxpersonresponse t syncmxperson t updatemxperson standard services standard services are the services that applications provide for performing specific operations on ...

  • Page 102

    Integration schemas 88 integration guide standard service output the following diagram shows the pochangestatusresponse (type = pochangestatusresponsetype) output. For this example, the response of the method is the po object. Object structure and enterprise services the object structure definition ...

  • Page 103

    Integration schemas integration xml and schemas 89 createmxperson element the following diagramrepresents the content of the createmxperson element: t the createmxperson element is type createmxpersontype. T the createmxpersontype has element mxpersonset, which is type mxpersonsettype. Mxpersonset i...

  • Page 104

    Integration schemas 90 integration guide create mxpersonresponse element the following diagram represents the content of the createmxpersonresponse element: t element createmxpersonresponse is type createmxpersonresponsetype. T the createmxpersonresponsetype has element personmbokeyset, which is typ...

  • Page 105

    Integration schemas integration xml and schemas 91 deletemxperson element the following diagram represents the content of the deletemxperson element: t element deletemxperson is type deletemxpersontype. T the deletemxpersontype has element mxpersondelete, which is type mxpersondeletetype. T mxperson...

  • Page 106

    Integration schemas 92 integration guide publishmxperson element the following diagram represents the content of the publishmxperson element: t element publishmxperson is type publishmxpersontype. T the publishmxpersontype has element mxpersonset, which is type mxpersonsettype. Mxpersonset is derive...

  • Page 107

    Integration schemas integration xml and schemas 93 querymxperson element the following diagram represents the content of the querymxperson element: t the querymxperson element is type querymxpersontype. T querymxpersontype has element mxpersonquery, which is type mxpersonquerytype. T mxpersonqueryty...

  • Page 108

    94 integration guide querymxpersonrespo nse element the following diagram represents the content of the querymxpersonresponse element: t element querymxpersonresponse is type querymxpersonresponsetype. T the querymxpersonresponsetype has element mxpersonset, which is type mxpersonsettype. T mxperson...

  • Page 109: Interface Tables

    © copyright ibm corp. 2007, 2008 95 ‘ interface tables are an option for integration with systems that use database tables to exchange data. Interface tables are generated based on the definition of the object structure that is associated with an enterprise service or publish channel. Invocation cha...

  • Page 110: Location of Interface Tables

    Location of interface tables 96 integration guide location of interface tables the endpoint definition for an external system or a publish channel points to the database where its interface tables are stored. The database can be a local database or a remote database. The predefined interface table e...

  • Page 111: Creation of Interface Tables

    Creation of interface tables interface tables 97 the sequence of transid identifies the sequence in which records are processed by the integration framework. For example, when employees and their phone numbers are entered into the system, the transid values for the po record must be lower than the t...

  • Page 112

    Regeneration of interface tables 98 integration guide regeneration of interface tables when columns are added or deleted from the system database tables, you must regenerate all local and remote interface tables that are associated with those object structures. You regenerate interface tables by usi...

  • Page 113: Format of Interface Tables

    Format of interface tables interface tables 99 format of interface tables the format of an interface table is the same as the format of the corresponding object structure. The interface table includes the persistent and nonpersistent columns that are included in the object structure. The interface t...

  • Page 114: Restricted Columns

    Format of interface tables 100 integration guide restricted columns the hasld field, which is an internal system column, is excluded from all object structures. Do not include this column in any object structure that is associated with an interface table. The langcode field is also excluded from the...

  • Page 115

    Format of interface tables interface tables 101 for example, assume that you create a purchase order with one line item. This transaction uses the predefined mxpointerface, and it increments the transid value that is associated with the mxout_inter_trans queue table to 1065. The transaction produces...

  • Page 116

    Format of interface tables 102 integration guide the data in the mxout_inter_trans queue table directs the external system to process the interface table records in the following sequence. The data in the mxin_inter_trans queue table directs the integration framework to process the interface table r...

  • Page 117

    Format of interface tables interface tables 103 for example, if a purchase order has three line items, that transaction might produce the following records: t one entry in the mxout_inter_trans queue table, with the ifacename value equal to the mxpointerface value, and the transid value equal to 106...

  • Page 118

    Format of interface tables 104 integration guide the system populates the action column in the outbound messages. If the external system does not populate the column in the inbound messages, the integration framework tries to retrieve and replace the corresponding database record. If the record does...

  • Page 119: Interface Table Polling

    Interface table polling interface tables 105 interface table polling a predefined cron task, ifacetableconsumer, polls the mxin_inter_trans queue table and uses the ifacename, extsysname, and transid values in the queue table to place the corresponding interface table records into the appropriate in...

  • Page 120: Configuring External Systems

    Configuring external systems 106 integration guide configuring external systems to use interface tables, you must create the tables and configure the ifacetableconsumer cron task. Overall processing to configure the external systems to perform general interface queue table and interface table proces...

  • Page 121

    Configuring external systems interface tables 107 outbound processing to configure the external system to perform outbound interface queue table and inbound interface table processing: 1 set up a process to retrieve interface table transactions by using the mxout_inter_trans queue table. You can use...

  • Page 122

    Configuring external systems 108 integration guide.

  • Page 123: Message Tracking

    © copyright ibm corp. 2007, 2008 109 the message tracking application tracks and displays the processing history of queue-based enterprise service messages, and queue-based publish channel messages. The message tracking application works with the message reprocessing application. When you use the me...

  • Page 124: Message Details

    Message details 110 integration guide message details when you enable message tracking, the integration framework writes all processed messages to the maxintmsgtrk table. The system assigns a status to each message which represents its current position in the queue-based processing cycle. Individual...

  • Page 125: External Message Id

    Message tracking configuration © copyright ibm corp. 2007, 2008 111 the following attributes have dynamic values that change based on the transaction events. Message tracking configuration you can maintain a record of processing actions for messages that are sent through publish channels or that are...

  • Page 126: Search Id

    Message tracking configuration 112 integration guide to find all messages for the mxpersoninterface enterprise service, create the following fully qualified xpath expression as the external message id: /{http://www.Ibm.Com/maximo}syncmxperson/@messageid multi-noun message and external message id whe...

  • Page 127: Message Statuses

    Message statuses © copyright ibm corp. 2007, 2008 113 message statuses every inbound and outbound queue-based message that is registered in the message tracking application has a status value that indicates its position in the transaction processing cycle. The message tracking status indicates wheth...

  • Page 128

    Message events 114 integration guide tracked inbound and outbound events the following inbound and outbound events update the maxintmsgtrk table: event details message is written to queue a record is created in the message tracking table when the integration framework first writes the message to the...

  • Page 129: Error Management

    © copyright ibm corp. 2007, 2008 115 the integration framework uses java message service (jms) queues as a staging mechanism. Inbound messages from external systems are first stored in a queue, and then retrieved for processing. Similarly, outbound messages are stored in a queue, from which they are...

  • Page 130: Queue Error Management

    Queue error management 116 integration guide queue error management outbound processing errors can occur as the message is sent from the queue to the external system. These errors are typically caused by a communication failure between the queue and external system, or a problem with database config...

  • Page 131

    Interface table error management error management 117 interface table error management errors can occur in the following two stages when inbound interface tables are processed: t writing data from the interface table to the queue t processing data from the queue into the integration framework the in...

  • Page 132

    Error management configuration 118 integration guide error management configuration error management requires the configuration of the following properties before use. System properties configuration the following error management properties are configurable in the system properties application. T m...

  • Page 133

    Error management configuration error management 119 external systems configuration properties the following error management properties are configurable in the add/modify queues action in the external systems application: t maximum try count this property specifies the number of times that the syste...

  • Page 134: Error Notification

    Error notification 120 integration guide error notification when an inbound or outbound transaction results in an error in a queue, the application sends an e-mail notification to the system administrator only if no other errors are awaiting correction in the same queue. The notification informs the...

  • Page 135: Message Reprocessing

    Message reprocessing error management 121 message reprocessing when you use the message reprocessing application, you can manage and view integration messages that are flagged with an error. You can view the error xml file without accessing the integration server error files. Failed messages can be ...

  • Page 136: Error Correction

    Message reprocessing 122 integration guide error correction you can view message details and change error message contents in the message details dialog box in the message reprocessing application. You can choose to process, save, or cancel your xml changes. You can edit only the messages that are i...

  • Page 137

    Message reprocessing error management 123 harrier-042" event="1" messageid="11798570432652428"> . . . Process message after you complete your error xml changes in the error data window, you can resubmit the message. The application then starts reprocessing the message. The following actions are perf...

  • Page 138: Message Deletion

    Common causes of errors 124 integration guide message deletion you can choose to delete a message from a queue. After you delete a message, the system cannot reprocess it. When the system deletes the message, the record is deleted from the maxinterrormsg and maxinterror tables. The application refre...

  • Page 139: Error Research

    Common causes of errors error management 125 error research when you receive an error notification, look at the xml file in the message reprocessing application. Depending on the type of queue (sequential or continuous) and the number of messages in the queue, zero, one, or multiple error xml files ...

  • Page 140

    Common causes of errors 126 integration guide because the error is a major exception, the integration framework cannot retry the xml file. To correct the error you must remove the incorrect data from the source xml file. You then must delete the error record by changing its message status to delete....

  • Page 141: Non-Queue Error Management

    Non-queue error management error management 127 non-queue error management synchronous integration scenarios require continuous communication between the system and external applications. These synchronous scenarios do not require a messaging queue mechanism. Non-queue error management is necessary ...

  • Page 142

    Non-queue error management 128 integration guide.

  • Page 143: Basic Configuration

    © copyright ibm corp. 2007, 2008 129 you must complete several configuration activities before you perform basic integration processing. Basic configuration involves working with predefined components, administration, and queue properties. You can either work with pre- existing integration component...

  • Page 144: Prerequisite Activities

    Predefined components and queues 130 integration guide predefined components and queues the following integration components are predefined: t an external system (extsys1) t an adapter (maximo) t object structures t enterprise services t publish channels t endpoints in addition, the following jms qu...

  • Page 145

    Integration framework administration basic configuration 131 integration framework administration the integration framework specifies the following system properties, some of which have default values that you should consider updating: t system user name t global directory t update sendersysid setti...

  • Page 146: Jms Queues

    Jms queues 132 integration guide jms queues the following predefined jms queues are provided by the system. Ensure that the jms queues are configured so that inbound and outbound message processing is successful. Configuring jms queues configure jms queues when you are working with the integration p...

  • Page 147: Queue Properties

    Jms queues basic configuration 133 queue properties the maximum try count property represents the number of times the system retries to process a failed message before sending an e-mail notification. The maximum try count default value is 5; the integration framework retries a failed message five ti...

  • Page 148

    Jms queues 134 integration guide all xml files that are available in the source directory are associated with a specific external system – enterprise service when you add a value to the externalsystem, sourcedirectory, and the enterpriseservice parameters. These xml files also are loaded into the in...

  • Page 149

    Jms queues basic configuration 135 committed to the queue. Index files are available in the recovery folder which is created in the cron task source directory. The xmlfileconsumer cron task uses the index file name to identify the file that was processed before the server or queue problem was encoun...

  • Page 150: Integration Components

    Integration components 136 integration guide t file split - multi-noun files that are processed by the flatfileconsumer cron task are split before they are written to the queue. The cron task identifies if the file that is loaded is a multi-noun xml file. If the xml file is a multi-noun file, the in...

  • Page 151: Endpoints

    Integration components basic configuration 137 use the select action menu in the external systems application to perform the following configuration activities: 1 configure external system integration controls and assign system-level default values. 2 create external system interface tables. 3 creat...

  • Page 152: Configuring Publish Channels

    Integration components 138 integration guide 6 identify whether you are using an external schema. 7 assign a split tag that you use to process multi-noun messages. 8 assign the processing classes (request or response). 9 create the processing rules. A fully qualified xpath expression must be provide...

  • Page 153

    Integration components basic configuration 139 2 configure the publish channel integration controls and assign the default values. 3 generate the schema files to describe the publish channel. 4 enable and disable the listener for the outbound integration events publish channel configuration is requi...

  • Page 154

    Integration components 140 integration guide.

  • Page 155: Advanced Topics

    © copyright ibm corp. 2007, 2008 chapter 10: endpoints and handlers chapter 11: advanced interface table polling chapter 12: jms queue configuration chapter 13: security chapter 14: cluster configuration chapter 15: integration framework customization with processing rules chapter 16: integration fr...

  • Page 157: Endpoints and Handlers

    © copyright ibm corp. 2007, 2008 143 endpoints and their handlers facilitate the routing of outbound messages from the outbound java message service (jms) queue to its destination. Endpoints also route outbound data from an invocation channel directly to its destination. The endpoint and handler com...

  • Page 158: Endpoints

    Endpoints 144 integration guide endpoints an endpoint represents an application component to which the system delivers outbound transactions. The following table lists the system available endpoints. Configuring endpoints perform the following steps to configure an endpoint: t define the handler t d...

  • Page 159: Handlers

    Handlers endpoints and handlers 145 handlers a handler specifies how to route outbound data to a specific endpoint location, in a specific format. Enterprise bean handler the enterprise javabean (ejb) handler is a java component that consists of enterprise bean clients. The handler publishes a set o...

  • Page 160

    Handlers 146 integration guide the responseok() method is called after a successful enterprise bean invocation. Public void responseerror(exception e) throws mxexception the responseerror() method is called with the originating exception as a parameter if an error is encountered during enterprise be...

  • Page 161: Flatfile Handler

    Handlers endpoints and handlers 147 the following example is an ibm websphere application server provider url. Corbaloc:iiop:hostname:iiopport if the handler and the target enterprise bean are running on the same application server instance, do not specify this property because it defaults to the lo...

  • Page 162: Http Handler

    Handlers 148 integration guide flat file formatting if the data in the flat file contains the flat file delimiter character, the data adds the text qualifier, which is " (quotation marks). If the data contains quotation marks, the handler escapes the quotation marks. You cannot use quotation marks a...

  • Page 163

    Handlers endpoints and handlers 149 httpexit property this optional property is used for customization. This property specifies the fully qualified name of a java class that interprets the http response. This property also helps implement the code that is required for an external system to interpret...

  • Page 164: Ifacetable Handler

    Handlers 150 integration guide t getheaderproperties() this method has the following signature: public map string, string getheaderproperties(map string,? Metadata, byte[] data, map string,maxendpointpropinfo httpinfo) this method returns a map of the http header properties for the request. The defa...

  • Page 165: Jms Handler

    Handlers endpoints and handlers 151 a value of 0 (false) indicates that the interface tables are available in the local system database in the system schema. You do not have to enter any other handler properties. For the predefined maxifacetable handler, the value of this property is 0. A value of 1...

  • Page 166

    Handlers 152 integration guide the messaging system represents a queue or topic that is available on the local application server, a remote application server, or a remote dedicated queuing system such as ibm websphere mq. To use this handler, enable the messaging systems by using jms. The messaging...

  • Page 167: Webservice Handler

    Handlers endpoints and handlers 153 jmsexit property this optional property is used for customization. It specifies the fully qualified name of a java class that runs the jmsexit interface. The java class must implement the getmessageproperties() method that is defined in the jmsexit interface. You ...

  • Page 168: Xmlfile Handler

    Handlers 154 integration guide httpversion property this optional property specifies the version of the http protocol for web service invocations. The valid values are http/1.0 and http/1.1. If you do not provide a value, the system uses the default value, http/1.1. Httpconntimeout property this opt...

  • Page 169: Cmdline Handler

    Handlers endpoints and handlers 155 for example, the file name mx_mxassetinterface_10971102668641398.Xml indicates that the file was generated from a system to send data to the external system extsys1. The file name also indicates that the file contains the mxassetinterface publish channel. Cmdline ...

  • Page 170: Writing Custom Handlers

    Writing custom handlers 156 integration guide the following tags are available: t clworkingdir – a directory to change ( cd ) to on the remote system before the command is run. T clssetupcmd – a setup command to be run before the main command. Use this tag for any environmental setup that must occur...

  • Page 171

    Writing custom handlers endpoints and handlers 157 the following method sends data to the specified endpoint. T metadata provides information about the external system and the interface. T data is the xml data. T destinationmap specifies the endpoint. Senddata(map metadata, byte[] data, map destinat...

  • Page 172

    Writing custom handlers 158 integration guide.

  • Page 173: Advanced Interface

    © copyright ibm corp. 2007, 2008 159 the system provides the option of using interface tables to exchange data with external systems. You can perform advanced configuration of the interface table polling process to improve its performance when reading data from interface tables. If you send inbound ...

  • Page 174: Cron Tasks

    Cron tasks 160 integration guide cron tasks the interface table polling process uses a single default cron task called ifacetableconsumer. This cron task reads all messages from all interface tables for all external systems that write to the tables. Configuring cron tasks for improved performance on...

  • Page 176

    Queue tables 162 integration guide.

  • Page 177: Jms Queue

    © copyright ibm corp. 2007, 2008 163 you can use java message service (jms) queues to exchange data with an external system. When an enterprise service message is received, it writes the message to a jms queue. Messages remain in an inbound queue until they are successfully processed into the system...

  • Page 178

    Creating and configuring a queue 164 integration guide creating and configuring a queue you can use separate queues, one for each external system that you use. Queues can be configured for use with publish channels and enterprise services that integrate with one or more external systems. Queue creat...

  • Page 179: Sequential Queues

    Sequential queues jms queue configuration 165 3 configure your external system and enterprise services to use the queues. 4 to enable message processing, you must configure the consumers value of the message queue. The system processes the messages after they are written to the queue. Sequential que...

  • Page 180: Enabling Message Beans

    Continuous queue 166 integration guide when message processing results in an error, the system generates an error file, then continues processing subsequent messages in the queue. There is one default continuous queue to process inbound messages. Enabling message beans to enable the message beans, u...

  • Page 181: Continuous Queue Performance

    Continuous queue jms queue configuration 167 3 jms/maximo/int/queues/cqin destination-jndi-name> jms/maximo/int/cf/intcf connection-factory-jndi-name> 600 jmscontqueueprocessor-1 --> continuous queue performance you can improve performance by increasing the number of message-driven beans for a parti...

  • Page 182: Message Caching

    Continuous queue 168 integration guide 2 select intjmsact. 3 specify a value in the maximum concurrent end points field. Weblogic server by default, the weblogic server is configured to have three message-driven beans. Use the values shown in bold to configure the number of message-driven beans in t...

  • Page 183: Continuous Queue Errors

    Continuous queue jms queue configuration 169 continuous queue errors you can use different application server configurations to manage error messages. When you are loading a large volume of messages, you can encounter a large number of errors. The continuous queue continues to reprocess the messages...

  • Page 184

    Continuous queue 170 integration guide to enable the message-driven beans on the error queue, uncomment the values shown in bold in the ejb-jar.Xml file and set the mdbdelay value. You also need to uncomment the following code in the ibm-ejb-jar-bnd.Xmi to enable the message-driven beans on the erro...

  • Page 185: Queue Message Format

    Continuous queue jms queue configuration 171 for example, when you set the batch size property to -1 (unlimited), and the redelivery delay property to 30 seconds (30,000 milliseconds), new messages can be processed in the queue. Processing continues even when a large number of errors are being repro...

  • Page 186: Queue Selectors

    Queue selectors 172 integration guide message body the message body contains the xml message that is processed into the system or sent to the external system. Queue selectors selectors act as where clauses in the jms queue consumer. Selectors can be applied to message headers and properties in eithe...

  • Page 187: Queue Utilities

    Queue utilities jms queue configuration 173 applying selectors splits a queue into smaller queues, each of which contains a subset of data that each cron task or message-driven bean uses. An error in one subset of the data does not stop processing in the others in a sequential queue. While selectors...

  • Page 188: Ibm Websphere Mq

    Ibm websphere mq 174 integration guide the following property values are required utility values. Ibm websphere mq you can use ibm websphere mq as a standard for your queuing activities. The integration framework supports websphere mq version 6. Before you use the websphere mq for any queuing activi...

  • Page 189

    Ibm websphere mq jms queue configuration 175 configuring the integration queues and websphere mq provider you can replace the integration framework queues with the websphere mq queues. The queue setup is supported when you configure the websphere application server and the integration framework queu...

  • Page 190

    Ibm websphere mq 176 integration guide.

  • Page 191: Security

    © copyright ibm corp. 2007, 2008 177 some security mechanisms are provided to prevent the unauthorized use 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 queu...

  • Page 192: Integration Queue

    Integration queue 178 integration guide integration queue the java message service (jms) queues that are used by integration processing support basic j2ee security (user id and password-based authentication and authorization). You can prevent unauthorized access to the queue by assigning a user id a...

  • Page 193: Enterprise Bean Access

    Enterprise bean access security 179 2 under the section in the ejb-jar.Xml file, add the following elements shown in bold text: maximouser jmscontqueueprocessor-1 * required enterprise bean access the integration gateway implements an enterprise javabean (ejb) as the entry point for receiving data f...

  • Page 194

    Enterprise bean access 180 integration guide psdi.Iface.Gateway.Meagatewaybean stateless container env-entry> allowdfltlogin java.Lang.String 1 application users maximouser maximouser mosservice psdi.Iface.Mos.Mosservicehome psdi.Iface.Mos.Mosserviceremote psdi.Iface.Mos.Mosservicehomelocal psdi.Ifa...

  • Page 195: Http Servlet

    Http servlet security 181 client programs call the secure version of the enterprise bean methods for each service type: t enterprise service: secureprocessextnernaldataasync(..) , secureprocessextnernaldatasync(..) t object structure service: secureprocessmos(..) t standard service: secureaction(..)...

  • Page 196

    Http servlet 182 integration guide blocks, one for each type of service: enterprise service, object structure service, and standard service. The to service mapping is: the following integration servlet code samples have the security constraint comment sections removed for each service type..

  • Page 197: Web Services

    Web services security 183 object structure service servlet resource-name> object structure service servlet (http post) accessible by authorized users /os/* get post roles that have access to object structure service servlet (http post) maximouser data transmission gaurantee none --> the preceding se...

  • Page 198

    Remote integration apis (micservice) 184 integration guide 1 use the following the security-constraint block for a web service servlet. Integration web services resource-name> integration web services accessible by authorized users /services/* get post roles that have access to integration web servi...

  • Page 199: Interface Table Security

    Interface table security security 185 t processobjectstructure(..) t routedata(..) to run these methods, the caller must retrieve a valid userinfo object and pass it to the method to gain access to the secure layer. A userinfo object is a serialized object that contains user details (user, password,...

  • Page 200

    Object-level authorization 186 integration guide for example, you can assign the status option to the changestatus method of the po standard service. To run the standard service by using http, enterprise bean, or soap, you need authorization to the status option. Standard service authorization does ...

  • Page 201: Cluster Configuration

    © copyright ibm corp. 2007, 2008 187 the system can be implemented within a cluster of application servers, and integration services can run across the cluster. You can implement a cluster of application servers based on the size of your system implementation. First, determine whether a single serve...

  • Page 202: Configuring The Cron Task

    Configuring the cron task 188 integration guide configuring the cron task the interface table cron task, the data import cron task, and the java message service (jms) queue cron task are cluster-aware functions. By default, the cron task framework runs a task on a randomly chosen server. If you want...

  • Page 203: Jms Queues

    Jms queues cluster configuration 189 jms queues in a cluster configuration, the jms queues are associated with one member of the server cluster. Access to the queues is provided by the java naming and directory interface (jndi) service. The jdni service is available across all the members on the clu...

  • Page 204

    Jms queues 190 integration guide websphere application server continuous queue cluster the following diagram shows one example of a cluster configuration on the ibm websphere application server. The diagram is an example of a continuous queue integration bus configuration in a cluster of three appli...

  • Page 205

    Jms queues cluster configuration 191 integration cron tasks deliver enterprise service messages from flat or xml files and interface tables. The cron task places messages into the queue store on the server where the cron task is running, which limits the processing to a single server. To configure i...

  • Page 206

    Jms queues 192 integration guide websphere application server sequential queue cluster the following diagram shows one example of a cluster configuration on the websphere application server. The sequential queue receives jms producer messages and processes the jms consumer messages. A sequential que...

  • Page 207

    Jms queues cluster configuration 193 unlike the continuous queue, there is no multi-threading of messages. A cluster implementation does not significantly impact the processing performance of messages that are processed through the sequential queue. Weblogic server continuous queue cluster the follo...

  • Page 208

    Jms queues 194 integration guide after messages are in the queue, all application servers can simultaneously pull messages from the queue and process them into the system. Message-driven beans must be enabled on each application server in the cluster. Weblogic server sequential queue cluster the fol...

  • Page 209: Server Cluster Configuration

    Dedicated message processing servers cluster configuration 195 run on any server in the cluster. Once messages are in the queue, the application server that is running the jms consumer cron task processes messages in a sequential order. Unlike the continuous queue, there is no multi-threading of mes...

  • Page 210: Enterprise Beans

    Inbound message receipt 196 integration guide the noted components are standard j2ee components which are deployed as part of the application ear file. All these components are cluster-aware. Enterprise beans with a single server, the provider url for accessing the jndi tree is the single server url...

  • Page 211

    Inbound message receipt cluster configuration 197 the following properties must point to the cluster url: t integration 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 s...

  • Page 212

    Inbound message receipt 198 integration guide.

  • Page 213: Integration Framework

    © copyright ibm corp. 2007, 2008 199 you can use processing rules to change the behavior of predefined integration processing without having to write java classes. You can implement processing rules on outbound messages of a publish channel or inbound messages of an enterprise service. You cannot us...

  • Page 214: Objects and Records

    Objects and records 200 integration guide objects and records an object structure consists of one or more records that correspond to system objects. When an object is created, the object fields are populated from the corresponding record fields before standard application processing is applied. Duri...

  • Page 215: Processing Rule Definitions

    Processing rule definitions integration framework customization with processing rules 201 processing rule definitions a processing rule performs an action on a field in a record or object, or on the record or object itself. After you select the applicable service or channel, the application displays...

  • Page 216

    Processing rule definitions 202 integration guide skip action the skip action bypasses a message that meets the specified criteria. The inbound message is not processed and the outbound message is not sent to an external system. Skip processing does not generate an error, but the system log file is ...

  • Page 217

    Processing rule definitions integration framework customization with processing rules 203 the following field transformation actions manipulate data fields within a message. Set action the set action writes a value to a specified data field. When you define the rule, you specify the data to be set a...

  • Page 218: Processing Sequence

    Processing rule definitions 204 integration guide source field, one or more target fields, and how the rule processor identifies segments of the source field. The fields can have the following sources: t a field in the selected record or object t an integration control that contains the delimiter th...

  • Page 219: Conditions and Evaluations

    Conditions and evaluations integration framework customization with processing rules 205 conditions and evaluations processing rules are applied conditionally. Any conditions must be met before the processing or action that is specified in the rule can be performed. Conditions can involve one or mor...

  • Page 220: Field to Evaluate

    Conditions and evaluations 206 integration guide because enterprise service processing rules are applied before objects are built, the processing rules cannot evaluate object fields or object sets. You can use the following combinations of categories, processing direction (outbound or inbound), and ...

  • Page 221: When to Evaluate The Field

    Conditions and evaluations integration framework customization with processing rules 207 when to evaluate the field for xml field and object field evaluations, the processing rule first determines whether it evaluates the specified data. The system evaluates the data by checking the evaluate when fi...

  • Page 222

    Conditions and evaluations 208 integration guide the following table lists the possible types of comparison fields that you can use in the field comparisons. Comparison of an alphanumeric source field is case sensitive. Field use integration control compare the value in the specified field with the ...

  • Page 223: Integration Controls

    Integration controls integration framework customization with processing rules 209 integration controls integration controls give you the ability to configure the behavior of any enterprise service or publish channel according to the requirements of individual organizations and sites. Processing rul...

  • Page 224: Control Types

    Integration controls 210 integration guide control types you can create four types of integration controls to meet your business needs. Boolean controls a boolean integration control specifies a value of 0 (false) or 1 (true). List controls a list integration control contains a list of values. You c...

  • Page 225: New Control Creations

    Integration controls integration framework customization with processing rules 211 multiplication control a multiplication control can update the company in every organization in the system database. For example, use a multiplication control to update the company in every organization within the sys...

  • Page 226

    Integration controls 212 integration guide.

  • Page 227: Integration Framework

    © copyright ibm corp. 2007, 2008 213 the integration framework provides multiple placeholders within the transaction flow to customize transactions by using java programs and xsl. Based on your requirements, you can use one or more of these placeholders, or user exits, for your customizations. You c...

  • Page 228: Outbound Customization

    Outbound customization 214 integration guide outbound customization the integration framework processes outbound messages by using either a publish channel or invocation channel. Publish channels and invocation channels use placeholders, or user exits, in the outbound processing flows. Publish chann...

  • Page 229

    Outbound customization integration framework customization with java and xsl 215 the primary difference between an invocation channel and a publish channel is that application code invokes the invocation channel, while an event or a data export initiates a publish channel. Additionally, the synchron...

  • Page 230

    Outbound customization 216 integration guide java exits the following figure illustrates the hierarchy of standard java exit classes for outbound processing. These java classes are available to both the publish channel and the invocation channel. The hierarchy illustration does not apply to processi...

  • Page 231

    Outbound customization integration framework customization with java and xsl 217 t change system data by changing the ir record to be sent to the external system t stop the message from being saved in the database by throwing a system exception. The entire message is rolled back, including any chang...

  • Page 232

    Outbound customization 218 integration guide the following method can perform the noted processes: t validate data t change data by changing the er record to be sent to the external system t map additional data from the ir to the er t stop the transaction from being saved in database by throwing a s...

  • Page 233

    Outbound customization integration framework customization with java and xsl 219 the http processing exit class you can use an http exit placeholder for customization when sending transactions from the system to an external system using http. This exit class is optional and is called as part of the ...

  • Page 234

    Outbound customization 220 integration guide the enterprise bean processing exit class you can use an exit placeholder for class customization when transactions are sent to an external system using an enterprise bean. This exit class is optional and is called before the enterprise bean is called. Th...

  • Page 235

    Outbound customization integration framework customization with java and xsl 221 the java message service processing exit class you can use an exit placeholder for customization when sending transactions from the system to an external system using java message service (jms). This exit class is optio...

  • Page 236

    Outbound customization 222 integration guide public void responseok(org.W3c.Dom.Document response) throws mxexception the responseok() method is called after a successful invocation of the external web service. Public void responseerror(exception e) throws mxexception if an error was encountered dur...

  • Page 237: Inbound Customization

    Inbound customization integration framework customization with java and xsl 223 inbound customization the integration framework processes inbound messages by using enterprise services. Enterprise services provide placeholders, or user exits, in the inbound processing flows for customization. You can...

  • Page 238

    Inbound customization 224 integration guide the interface table polling program is run by using the system cron task manager. The cron task, ifacetableconsumer, has an optional property called exitclass, where you can place the fully qualified name of a java exit class. The java data structure list ...

  • Page 239: User Exit Preprocessing

    Inbound customization integration framework customization with java and xsl 225 t log the transaction you identify this class in the cron task setup application in the configuration module. Java exits the following figure illustrates the hierarchy of standard java exit classes for inbound processing...

  • Page 240: User Exit Postprocessing

    Inbound customization 226 integration guide t stop further processing of the transaction by throwing an exception in this case, the transaction remains in the queue to be retried. T stop the message from being sent to the external system by throwing a skip_transaction exception in this case, the mes...

  • Page 241: Xsl Mapping

    Inbound customization integration framework customization with java and xsl 227 the following method can perform the noted processes: t validate data t change external data by changing ir record to be saved in the system t map additional data from the er to the ir t stop further processing of the tr...

  • Page 242

    Inbound customization 228 integration guide object structure and object processing rules for information about the processing rules engine, see chapter 15, "integration framework customization with processing rules," on page 199. Business object user exit processing the java user exits provide an ex...

  • Page 243: Integration Component

    © copyright ibm corp. 2007, 2008 229 depending on the scope and requirements of your implementation, you can create new components or copy, modify, or extend the predefined components. Duplicating an integration component and modifying the copy has several advantages. The copy of an integration comp...

  • Page 244: Object Structure Creations

    Object structure creations 230 integration guide object structure creations the integration framework provides predefined object structures for enterprise services, publish channels, and invocation channels across multiple functional areas. The functional areas include purchasing, work management, a...

  • Page 245

    Object structure creations integration component additions and modifications 231 3 repeat the preceding steps for the remaining required objects. Indicate the relationship between those two objects. Define person as the parent to email and as the parent to sms. Alternate keys an inbound message norm...

  • Page 246: Endpoint Creations

    Predefined object structure modifications 232 integration guide by default, nonpersistent columns are excluded in the object when the object structure is created. If you modify the object structure, you can include new nonpersistent columns to the object definition in the object structure. Interface...

  • Page 247: Adapters

    Predefined endpoint modifications integration component additions and modifications 233 you can modify a user-defined handler. You cannot modify or delete a predefined handler. You can delete a handler only if you do not associate it with an endpoint for an external system. Predefined endpoint modif...

  • Page 248

    Adapter, service, and channel creations 234 integration guide processing rules the integration framework applies any specified processing rules to objects, before it saves the objects. Use object structure processing rules to set or evaluate xml fields. You can manipulate key data before the object ...

  • Page 249: Channel Creations

    Adapter, service, and channel creations integration component additions and modifications 235 channel creations after determining which adapter to use, you can create new channels for the predefined and user-defined adapters. The channels that you create determine how the adapter processes outbound ...

  • Page 250: Creating An External System

    Predefined service and channel modifications 236 integration guide all request and response processing classes and user exits have access to the invocation channel request and response objects by using the integrationcontext.Getcurrentcontext() api. Endpoint the endpoint definition identifies how an...

  • Page 251: Queues

    Predefined external system modifications integration component additions and modifications 237 queues a new external system can use the predefined java message service (jms) queues or queues that you create. Assign at least one inbound or outbound queue to the external system. Working with enterpris...

  • Page 252

    Predefined external system modifications 238 integration guide.

  • Page 253: Integration Queries

    © copyright ibm corp. 2007, 2008 239 the integration framework supports external system queries. The external system sends an xml message to query the integration framework and the integration framework returns an xml message as a response to the query. You can execute a query by using http, java™ r...

  • Page 254: Query Services

    Query services 240 integration guide query services object structure services and enterprise services support query operations. An external source can use a service to run a query and to retrieve data from a system. In both cases, the object structure schema defines the xml content for the query req...

  • Page 255

    Query services integration queries 241 the following table lists the attributes that can apply specifically to the root element of a query, a response to a query, or both. All attributes in this table are optional. Attribute description type applicable to uniqueresult specifies whether the query exp...

  • Page 256

    Query services 242 integration guide for example, the response to this query request returns records 11 through 20 of the query result set by virtue of setting the rstart value to 11 and the maxitems value to 10. Creationdatetime="2008-09-28t21:49:45" baselanguage="en" translanguage="en" messageid="...

  • Page 257: Query Operator

    Query services integration queries 243 query operator the queryoperatortype data type supports the use of different operators. Your query request xml can use the different operators to filter the data that is returned to the querying external source. Querymxperson element the following graphic repre...

  • Page 258

    Query services 244 integration guide t rsstart – when this value is set to 11 on the query, all the records in the result set are returned starting with record 11. The query result skips records 1 - 10. When the attribute is not defined, the records are returned starting with record 1 in the result ...

  • Page 259: Object Structure Element

    Object structure element integration queries 245 the query response element uses the following additional attributes: t rsstart – this value contains the value set on the query request. If the value is not defined on the request, the default response value is 1. T rscount – this value contains the n...

  • Page 260: Field Selection

    Object structure element 246 integration guide for example, to find all employees that have an active status, format the query as follows: active field selection a field-based query compares the value in a database field with the value in the xml field of the query request. For example, the followin...

  • Page 261: Range Selection

    Object structure element integration queries 247 the following query searches for the inventory balances where the bin number is not null. The following query searches for the inventory balances where the bin number is null. Null the following query uses the equivalent of a sql in clause to search f...

  • Page 262: Web Service Queries

    Web service queries 248 integration guide for example, the following query searches for the purchase orders where department is greater than 1000. 1000 the following query searches for person records where personid is greater than 1000 and less than 20000. The query uses two instances of a single fi...

  • Page 263

    Web service queries integration queries 249.

  • Page 264

    Web service queries 250 integration guide.

  • Page 265: Integration Web

    © copyright ibm corp. 2007, 2008 251 external applications can use web services to query or to send transactions to the system in the integration framework. You can deploy standard services, object structure services, and enterprise services as web services. The system web services are document-lite...

  • Page 266: Enterprise Web Services

    Object structure web services 252 integration guide object structure web services external applications can use web services to query or send messages to the integration framework. The object structure service contains the logic for integration message processing. You can create an object structure ...

  • Page 267: Standard Web Services

    Standard web services integration web services 253 t can use a java message service (jms) queue (asynchronous process) or bypass the jms queue (synchronous process). Enterprise web services that are processed in a jms queue do not support the query operation and do not provide any response content t...

  • Page 268: Xml Schema Generation

    Xml schema generation 254 integration guide xml schema generation the generated schema files are stored in a folder called schema, which is in the location that you specify in the mxe.Int.Globaldir system property. This folder contains the following subfolders: t common/common/meta t common/common/m...

  • Page 269

    Web service definition language generation integration web services 255 t web service name is the name of the object structure schema you are retrieving with an .Xsd file extension. Web service definition language generation the web service definition language file is generated during the deployment...

  • Page 270: Uddi Registration

    Uddi registration 256 integration guide uddi registration you can register deployed web services in a uddi registry by configuring the following global properties in the system properties application: if you specify values for the uddi registry publish url and inquiry url properties, the system regi...

  • Page 271

    Integration web service invocations integration web services 257 for all operations, except for the query and create operations, the soap body returns empty: maximo" creationdatetime="2008-09-28t21:49:45" baselanguage="string" translanguage="string" messageid="string" maximoversion="string" /> the q...

  • Page 272

    Integration web service invocations 258 integration guide.

  • Page 273: Multiple Language

    © copyright ibm corp. 2007, 2008 259 your system database can contain some elements, such as descriptions and long descriptions, in multiple languages. Publish channels and enterprise services can include these translated columns. A single system database can contain data in multiple languages. You ...

  • Page 274: Language Tables

    Default processing for translatable columns 260 integration guide default processing for translatable columns when you log in, you can choose a language code other than the base language for the system. In any application, you can then enter language-specific values for columns that are designated a...

  • Page 275: Multilanguage Attributes

    Multilanguage attributes multiple language support 261 multilanguage attributes service or channel root elements use the following attributes to manage multilanguage processing: the baselanguage attribute the baselanguage attribute identifies the base language of the system or application that gener...

  • Page 276

    Multilanguage attributes 262 integration guide.

  • Page 277: Integration Modules

    © copyright ibm corp. 2007, 2008 263 an integration module provides a mechanism for a process management product, such as change or release, to invoke an external operational management product, such as ibm tivoli provisioning manager. You can configure an integration module to automate logical mana...

  • Page 278

    Integration module components 264 integration guide integration module components an integration module is composed of defined integration framework components. You can configure the integration module to be implemented as a java class or as an invocation channel. When you install the integration mo...

  • Page 279

    Integration module components integration modules 265 to move data from the discovery engine into the database. You can also load this data by using the services configured in the integration framework. Logical management operations logical management operations identify the actions that integration...

  • Page 280

    Integration module prerequisites 266 integration guide t business object attributes - the specific attributes of the objects that are needed either for input or output and their data types. Input objects and input object attributes identify the data that the process management product passes to the ...

  • Page 281

    Integration module implementation properties integration modules 267 operational management product and integration module associations are created when the ompproductname and ompversion values are added to the integration module. If multiple versions of the operational management product are used w...

  • Page 282

    Integration module implementation properties 268 integration guide integration module tasks java-based integration modules are responsible for populating the logical management operation response object or response object set with the results of the operation. For invocation channels, you can specif...

  • Page 283

    Integration module implementation properties integration modules 269 and password properties that are returned from the credential mapper can also override the endpoint properties. Integration module endpoint properties are overwritten by the endpoint properties that are passed by the process manage...

  • Page 284

    Integration module implementation properties 270 integration guide t can be used by different applications while using different business objects. T can be designed to make multiple external invocations. T can use different communication protocols for different logical management operations and oper...

  • Page 285

    Integration module implementation properties integration modules 271 implementing an integration module by using an invocation channel has the following disadvantages: t requires more registration and configuration of system artifacts, even when the invocation is simple. T multiple applications cann...

  • Page 286

    Integration module implementation properties 272 integration guide management operation is being called. At run time, the integration module retrieves the lmoname and lmonamespace properties from the metadata input map: import psdi.Iface.Omp.Imconstants; . . . String lmoname = metadata.Get(imconstan...

  • Page 287

    Integration module invocation integration modules 273 when you override these methods, you can perform additional integration module processing. The properties that are passed to the invocation channel are available to the processing classes. The following outbound processing class code shows you ho...

  • Page 288: Integration Module

    Integration module invocation 274 integration guide 2 identify the operational management product and integration module. 3 invoke the integration module. 4 process the integration module response. Step 1: identify the logical management operation the process management product provides processes to...

  • Page 289

    Integration module invocation integration modules 275 step 3: invoke the integration module integration module instances are called service invokers because they implement the java interface psdi.Iface.Mic.Serviceinvoker . Integration modules can be implemented either as java classes or as invocatio...

  • Page 290

    Integration module invocation 276 integration guide the property imconstants.Endpointname contains the name of the endpoint that is associated with in the operational management product, integration module, and logical management operation relationship. In most cases, the endpoint property is the va...

  • Page 291

    Integration module invocation integration modules 277 the action class passes the following properties when it calls one of the invoke methods on the instantiated service invoker. Operational management product service method use the operational management product service method when the action clas...

  • Page 292

    Integration module invocation 278 integration guide get service invoker utility methods the operational management product service provides the following getserviceinvoker utility methods to retrieve an instance of an integration module for a logical management operation and an operational managemen...

  • Page 293

    Integration module invocation integration modules 279.

  • Page 294

    Integration module invocation 280 integration guide.

  • Page 295: Launch-In-Context

    © copyright ibm corp. 2007, 2008 281 the launch-in-context feature opens a console for an external application that takes you directly to information that is relevant to your work within the system. You use the launch in context application to create and update launch entries. A launch entry defines...

  • Page 296: Defining Launch Entries

    External application preparations 282 integration guide external application preparations most external applications have a web-based console that you can launch from a url in a web browser. The launch-in-context feature supports the web application (servlet or jsp), portal, and java webstart consol...

  • Page 297

    Defining launch entries launch-in-context feature 283 for example, the following url is a url for the person application that uses the personname attribute. Https://extsyshost:9045/tcwebui/interaction- handler?Actionid=viewperson&person={personname} you can also use an attribute from an object that ...

  • Page 298

    Defining launch entries 284 integration guide operational management product-specific properties when you define launch entries, you enter these property values for the associated operational management product: t specific to operational management product launches: name and version of the operation...

  • Page 299: Option

    Associating the launch entry with a signature option launch-in-context feature 285 associating the launch entry with a signature option before you add a launch point to an application, you must associate the launch entry record with a signature option. To associate the launch entry with a signature ...

  • Page 300: Signature Option Conditions

    Associating a signature option with a push button 286 integration guide 7 in the position field, enter a number to specify the relative position of the select menu item. 8 in the tabs field, select the main value when the launch url has substitution variables in it, otherwise select the all value. 9...

  • Page 301

    Associating a condition with a signature option launch-in-context feature 287 management product that is configured on the launch entry does not manage the configuration item. This condition applies to launch entries that you associate with a configuration item object or actual configuration item ob...

  • Page 302

    Associating a condition with a signature option 288 integration guide.

  • Page 303: Process Control Id

    © copyright ibm corp. 2007, 2008 289 collaboration switches have been designed from an inbound integration point of view to provide users with a way to better manage data synchronization between the integration framework and external systems using a concept of ownership. These switches provide the a...

  • Page 304: System Id 1 and System Id 2

    Default collaboration switches 290 integration guide the following table shows the prefix of the process control id and indicates the application to which it applies. For example, the ivrc, ivrcy, and ivwo collaboration switches are all related to inventory processing. System id 1 and system id 2 sy...

  • Page 305

    Collaboration switch retrieval 291 the default switches use various combinations of the following values in the system id 1 and system id 2 fields: authorized users can update only the process control value in the default collaboration switches. Deleting a default collaboration switch or modifying a...

  • Page 306: View Collaboration Switches

    View collaboration switches 292 integration guide if the record exists, the system uses the record process control value to determine whether or not to bypass system processing. If the record exists, ignore the remaining steps. 7 if the record does not exist, the system modifies the key as follows: ...

  • Page 307

    Collaboration switch modification 293 collaboration switch modification authorized users can use any database tool to modify the process control value of a collaboration switch. Do not change the value of pcid, owner1sysid, or owner2sysid on existing collaboration switches. To change the process con...

  • Page 308: Modifying The Mxcollab Table

    Collaboration switch additions 294 integration guide before you modify the mxcollab table to reflect these conditions, the inv collaboration switches to have the following values: modifying the mxcollab table to modify the maxcollab table: 1 change the value of the inv/ ext/ thismx collaboration swi...

  • Page 309

    Collaboration switch additions 295 after you perform this procedure, the inv collaboration switches will have the following values. For example, when you set the value of the isuin integration control to 1, the issue transactions are accepted from an external system. The inv collaboration switch con...

  • Page 310

    Inventory collaboration switches 296 integration guide inventory collaboration switches process control id description value and action derivation of system id 1 derivation of system id 2 inv update inventory. Used when creating issues, returns, or miscellaneous receipts or adjustments. Inventory mu...

  • Page 311

    Inventory collaboration switches 297 invtr update the from storeroom on a transfer or the receipt of internal po. Used when creating transfers or creating a receipt for an internal pos. 0 1 update invbalances in the from storeroom. Do not update invbalances in the from storeroom. Matrectrans locatio...

  • Page 312

    Invoice collaboration switches 298 integration guide invoice collaboration switches process control id description value and action derivation of system id 1 derivation of system id 2 ivilc update inventory last cost. Used when approving invoices. 0 1 update inventory last cost. Do not update invent...

  • Page 313

    Invoice collaboration switches 299 ivrcy create service receipts for invoice lines with a po reference and receiptreqd = n. Used when approving invoices containing a line with a po reference, when the corresponding poline is a service and receiptreqd = n. 0 1 generate a service receipt for the invoi...

  • Page 314

    Labor transaction collaboration switches 300 integration guide labor transaction collaboration switches purchase order collaboration switches process control id description value and action derivation of system id 1 derivation of system id 2 ltsrc generate service receipts for pos. Used when creatin...

  • Page 315

    Purchase order collaboration switches 301 poivm create inventory vendor information for inventory. Used when approving pos. 0 1 update or create invvendor record. Do not create invvendor record. Po item of poline popr update status of prs. Used when copying pr lines to pos, creating pos from prs, re...

  • Page 316

    Purchase requisition collaboration switches 302 integration guide purchase requisition collaboration switches process control id description value and action derivation of system id 1 derivation of system id 2 prdel delete prs. Used when deleting prs. Use only when deleting then subsequently re-addi...

  • Page 317

    Purchase requisition collaboration switches 303 prpab do not allow unreferenced external purchase agreements / blankets. Used when adding or updating 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 “ex...

  • Page 318

    Receipt collaboration switches 304 integration guide receipt collaboration switches process control id description value and action derivation of system id 1 derivation of system id 2 rc enter po receipts. Used when creating receipts. 0 1 allow receiving against the po. Do not allow receiving agains...

  • Page 319

    Work order collaboration switches 305 work order collaboration switches process control id 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 gen...

  • Page 320

    Work order collaboration switches 306 integration guide.

  • Page 321: Notices

    © copyright ibm corp. 2007, 2008 307 notices this information was developed for products and services offered in the u.S.A. Ibm may not offer the products, services, or features discussed in this document in other countries. Consult your local ibm representative for information on the products and s...

  • Page 322

    308 integration guide ibm may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independe...

  • Page 323: Trademarks

    309 trademarks the following terms are trademarks of international business machines corporation in the united states, other countries, or both: ibm aix db2 developerworks everyplace ibm.Com lotus maximo notes quickplace tivoli websphere adobe, the adobe logo, postscript, and the postscript logo are...

  • Page 324

    310 integration guide.

  • Page 325: Index

    © copyright ibm corp. 2007, 2008 311 a action 14 action column, interface tables 103 adapters create 233 modifying 236 alias column names 99 apis 184 asynchronous inbound processing enterprise service class processing 26 enterprise services 20 message retrieval 24 object creation 29 object processin...

  • Page 326

    Index 312 integration guide cross-reference controls 210 customization business object user exit processing 228 conditions, evaluations 205 ejb handler 220 handlers 218 http handler 219 inbound processing 223 interface tables 223 object rule 200 objects, records 200 outbound processing 214 processin...

  • Page 327

    Index 313 http handler (continued) httpexit property 149 httpmethod property 150 readtimeout property 150 url property 150 username, password property 150 http servlet definition 181 securing 181 i ifacename column, interface tables 100 ifacetable handler driver property 151 isremote property 150 ur...

  • Page 328

    Index 314 integration guide jms handler (continued) desintationtype property 152 destjndiname property 152 iscompress property 152 jmsexit property 153 provideruser, providerpassword property 153 provideurl property 153 username, password property 153 jms queues asynchronous inbound, cron task 133 c...

  • Page 329

    Index 315 object structures (continued) create 230 data exchange 8 enterprise service 233 flat files 232 interface table 232 nonpersistent fields 231 persistent fields 231 required fields 231 required objects 230 operational management product integration action 14 integration modules 14 logical man...

  • Page 330

    Index 316 integration guide object structure services (continued) object structure processing class 42 process initiation 41 standard services 44 object processing 45 process initiation 44 synchronous outbound processing integration modules 60 invocation channels 55 object processing 60 request clas...