Configuring connector meta-objects

The connector can recognize and read two kinds of meta-objects:

The attribute values of the dynamic child meta-object duplicate and override those of the static meta-object.

Configuring a static connector meta-object

A static meta-object contains application-specific information that you specify about business objects and how the connector processes them. A static meta-object provides the connector with all the information it needs to process a business object when the connector is started.

After you have created a static meta-object for the connector, make sure the connector subscribes to the static meta-object by specifying the name of the static meta-object in the connector-specific property DataHandlerConfigMO. For more information, see "Connector-specific properties".

The static meta-object for the iSoft connector consists of a list of conversion properties defined for different business objects. To define the conversion properties for a business object, first create a string attribute and name it using the syntax busObj_verb. For example, to define the conversion properties for a Customer object with the verb Create, create an attribute named Customer_Create. In the application-specific text of the attribute, you specify the actual conversion properties.

Additionally, a reserved attribute named Default can be defined in the meta-object. When this attribute is present, its properties act as default values for all business object conversion properties. Never assign default values to the InputFormat or InputQueue properties; the values of these properties are used to match incoming messsages to business objects only.

Note:
If a static meta object is not specified, the connector is unable to map a given message format to a specific business object type during polling. When this is the case, the connector passes the message text to the configured data handler without specifying a business object. If the data handler cannot create a business object based on the text alone, the connector reports an error indicating that this message format is unrecognized.

The table below describes the meta-object properties.
Property name Description
DataEncoding

DataEncoding is the encoding to be used to read and write messages. If this property is not specified in the static meta-object, the connector tries to read the messages without using any specific encoding. DataEncoding defined in a dynamic child meta-object overrides the value defined in the static meta-object. The default value is Text. The format for the value of this attribute is messageType[:enc]. I.e., Text:ISO8859_1, Text:UnicodeLittle, Text, or Binary.This property is related internally to the InputFormat property: specify one and only one DataEncoding per InputFormat.

DataHandlerConfigMO Meta-object passed to data handler to provide configuration information. If specified in the static meta-object, this will override the value specified in the DataHandlerConfigMO connector property. Use this static meta-object property when different data handlers are required for processing different business object types. If defined in a dynamic child meta-object, this property will override the connector property and the static meta-object property. Use the dynamic child meta-object for request processing when the data format may be dependent on the actual business data. The specified business object must be supported by the connector.
DataHandlerMimeType Allows you to request a data handler based on a particular MIME type. If specified in the static meta-object, this will override the value specified in the DataHandlerMimeType connector property. Use this static meta-object property when different data handlers are required for processing different business object types. For example,
If defined in a dynamic child meta-object, this property will override the connector property and the static meta-object property. Use the dynamic child meta-object for request processing when the data format might be dependent on the actual business data. The business object specified in DataHandlerConfigMO should have an attribute that corresponds to the value of this property.
DataHandlerClassName Name of the data handler class to use when converting messages to and from business objects.
InputFormat

The InputFormat is the message format to associate with the given business object. When a message is retrieved and is in this format, it is converted to the given business object if possible. Do not set this property using default conversion properties; its value is used to match incoming messages to business objects that will store message content.

InputQueue The InputQueue is the input queue that the connector will poll to discover new messages received from Peer-to-Peer Agent. Do not set this property using default conversion properties; its value is used to match incoming messages to business objects.
OutputFormat The OutputFormat is set on messages created from the given business object. If the OutputFormat is not specified, the input format is used, if available. An OutputFormat defined in a dynamic child meta-object overrides the value defined in the static meta-object.
OutputQueue The OutputQueue is the output queue to which messages derived from the given business object are delivered. An OutputQueue defined in a dynamic child meta-object overrides the value defined in the static meta-object.

Application-specific information

The application-specific information is structured in name-value pair format, separated by semicolons. For example:

InputFormat=CUST_IN;OutputFormat=CUST_OUT

Mapping data handlers to InputQueues

You can use the InputQueue property in the application-specific information of the static meta-object to associate a data handler with an input queue. This feature is useful when dealing with multiple trading partners who have different formats and conversion requirements. To do so you must:

  1. Use connector-specific properties (see InputQueue) to configure one or more input queues.
  2. For each input queue, specify the queue manager and input queue name as well as data handler class name and mime type in the application-specific information.

For example, the following attribute in a static meta-object associates a data handler with an InputQueue named CompReceipts:

[Attribute]
   Name = Cust_Create
   Type = String
   Cardinality = 1
   MaxLength = 1
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = InputQueue=//queue.manager/
     CompReceipts;DataHandlerClassName=com.crossworlds.
   DataHandlers.MQ.disposition_notification;DataHandlerMimeType=message/
   disposition_notification
   IsRequiredServerBound = false
   [End]
   

A Sample connector meta-object

The static meta-object shown below configures the connector to handle the following:

Notice that in this sample meta-object, no data handler has been specified in the AppSpecificInfo of the attribute for the Sample_ISoft_Order_Create business object or for the Sample_ISoft_Catalog_Create business object. Because this sample meta-object does not contain the configuration values that would specify data handlers for those business objects, the data handler specified in the connector-specific properties will be used for them instead. However, in the attribute for the Sample_ISoft_MDN_Create business object and the Sample_ISoft_Notification_Create business object, this meta-object does provide configuration values in AppSpecificInfo to specify data handlers, and those values override the data handler values specified in the connector-specific properties.

[ReposCopy]
   Version = 3.1.0
   Repositories = 1cHyILNuPTc=
   [End]
   [BusinessObjectDefinition]
   Name = Sample_ISoft_MO_Config
   Version = 1.0.0
    
   [Attribute]
   Name = Default
   Type = String
   Cardinality = 1
   MaxLength = 1
   IsKey = true
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = OutputQueue=queue://isoft.queue.manager/
     COMPA.OUT;DataEncoding=Text
   IsRequiredServerBound = false
   [End]
    
   [Attribute]
   Name = Sample_ISoft_Order_Create
   Type = String
   Cardinality = 1
   MaxLength = 1
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = InputQueue=queue://isoft.queue.manager/
     COMPA.IN
   IsRequiredServerBound = false
   [End]
    
   [Attribute]
   Name = Sample_ISoft_Catalog_Create
   Type = String
   MaxLength = 255
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = OutputFormat=application/xml;
   IsRequiredServerBound = false
   [End]
    
   [Attribute]
   Name = Sample_ISoft_MDN_Create
   Type = String
   MaxLength = 255
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = InputQueue=queue://isoft.queue.manager/
     COMPA.RECEIPTS;
   DataHandlerClassName=com.crossworlds.DataHandlers.message
     .disposition_notification;
   DataHandlerMimeType=message/disposition-notification
   IsRequiredServerBound = false
   [End]
    
   [Attribute]
   Name = Sample_ISoft_Notification_Create
   Type = String
   MaxLength = 255
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   AppSpecificInfo = DataHandlerMimeType=isoftp2p/command;
   InputQueue=queue://isoft.queue.manager/COMPA.NOTICES;
   DataHandlerClassName=com.crossworlds.DataHandlers.isoftp2p.command
   IsRequiredServerBound = false
   [End]
    
   [Attribute]
   Name = ObjectEventId
   Type = String
   MaxLength = 255
   IsKey = false
   IsForeignKey = false
   IsRequired = false
   IsRequiredServerBound = false
   [End]
    
   [Verb]
   Name = Create
   [End]
    
   [Verb]
   Name = Delete
   [End]
    
   [Verb]
   Name = Retrieve
   [End]
    
   [Verb]
   Name = Update
   [End]
   [End]
   

Dynamic child connector meta-object

The connector recognizes and reads conversion properties from a dynamic meta-object added as a child to the top-level business object passed to the connector. The attribute values of the dynamic child meta-object duplicate the conversion properties that you can specify via the static meta-object that is used to configure the connector.

The table below shows a sample dynamic child meta-object for business object Customer_Create. Note that the application-specific information consists of semi-colon delimited name-value pairs.
Attribute name Value
DataEncoding Text:UnicodeLittle
DataHandlerMimeType* text/delimited
OutputFormat CUST_OUT
OutputQueue QueueA
JMSProperties The iSoft Peer-to-Peer Agent sets the AS/2 "to" and "from" names associated with a given message in the MQ RFH2 header of messages it sends to the adapter. In order to have these populated in the business object, the user should define two child attributes in the "JMSProperties" object. The attribute names are insignificant; however the app-specific information of the attributes must contain name-value pairs type=String;name=to and type=String;name=from corresponding to the fields in the MQ RFH2 header that the iSoft Peer-to-Peer Agent populates with the AS/2 "to" and "from" names, respectively.

*Assumes that DataHandlerConfigMO has been specified in either the connector configuration properties or the static meta-object.

The connector checks the application-specific information of top-level business object received to determine whether tag cw_mo_conn specifies a child meta-object. If so, the dynamic child meta-object values override those specified in the static meta-object.

Population of the dynamic child meta-object during polling

In order to provide collaborations with more information regarding messages retrieved during polling, the connector populates specific attributes of the dynamic meta-object, if already defined for the business object created.

The table below shows how a dynamic child meta-object might be structured for polling.
Attribute name Sample value
InputFormat CUST_IN
InputQueue MYInputQueue
OutputFormat CxIgnore
OutputQueue CxIgnore

As shown in the table above, you can define an additional attribute, InputQueue, in a dynamic child meta-object. This attribute contains the name of the queue from which a given message has been retrieved. If this property is not defined in the child meta-object, it will not be populated.

Example scenario:

JMS headers, WebSphere MQ message properties, and dynamic child meta-object attributes

You can add attributes to a dynamic meta-object to gain more information about, and more control over, the message transport. Adding such attributes allows you to modify JMS properties and to re-target a message CorrelationID. This section describes these attributes and how they affect event notification and request processing.

The following attributes, which reflect JMS and WebSphere MQ header properties, are recognized in the dynamic meta-object.

Table 1. Dynamic Meta-Object Header Attributes
Header attribute name Mode
CorrelationID
   
Read/Write
DeliveryMode
   
Read/Write
Priority
   
Read/Write
Destination
   
Read
Expiration
   
Read
MessageID
   
Read
Redelivered
   
Read
TimeStamp
   
Read
Type
   
Read
UserID
   
Read
AppID
   
Read
DeliveryCount
   
Read
JMSProperties
   
Read/Write

Read-only attributes are read from a message header during event notification and written to the dynamic meta-object. These properties also populate the dynamic MO when a response message is issued during request processing. Read/write attributes are set on message headers created during request processing. During event notification, read/write attributes are read from message headers to populate the dynamic meta-object.

For example, if attribute DeliveryMode is present in the dynamic meta-object, the adapter updates this attribute with the value of the JMSDeliveryMode header field of the message. If DeliveryMode is not specified in the MO, then the JMS provider establishes the persistence setting.

Note:
If attribute DeliveryMode is set to 2 in an asynchronous request, the message is sent persistently. If DeliveryMode is set to 1, the message is not sent persistently. Any other value may fail the connector.

The interpretation and use of these attributes are described in the sections below.

Note:
None of the above attributes are required. You may add any attributes to the dynamic meta-object that relate to your business process.

JMS properties

Unlike other attributes in the dynamic meta-object, JMSProperties must define a single-cardinality child object. Every attribute in this child object must define a single property to be read/written in the variable portion of the JMS message header as follows:

  1. The name of the attribute has no semantic value.
  2. The type of the attribute should always be String regardless of the JMS property type.
  3. The application-specific information of the attribute must contain two name-value pairs defining the name and format of the JMS message property to which the attribute maps.
  4. Values specified in the JMSProperty attribute are mapped to the MQ RHF2 message header, which can be used to exchange trading partner information and the iSoft Peer-to-Peer Agent.

The table below shows application-specific information properties that you must define for attributes in the JMSProperties object.

Table 2. Application-Specific Information for JMS Property Attributes
Name Possible values Comments
Name Any valid JMS property name This is the name of the JMS property. Some vendors reserve certain properties to provide extended functionality. In general, users should not define custom properties that begin with JMS unless they are seeking access to these vendor-specific features.
Type String, Int, Boolean, Float, Double, Long, Short This is the type of the JMS property. The JMS API provides a number of methods for setting values in the JMS Message: setIntProperty, setLongProperty, setStringProperty, etc. The type of the JMS property specified here dictates which of these methods is used for setting the property value in the message.

The figure below shows the attribute JMSProperties in the dynamic meta-object and definitions for two properties in the MQ RFH2 header. These properties map to the MQ RFH2 fields "to" and "from" which the iSoft Peer-to-Peer Agent recognizes as containing trading partner information. Currently, the iSoft Peer-to-Peer Agent only recognizes these two fields in the MQ RFH2 header. In the future, if the iSoft Peer-to-Peer Agent is enhanced to recognized additional fields, they can be defined here in the JMSProperties object.

Figure 3. JMSProperties attribute in a dynamic meta-object


Copyright IBM Corp. 1997, 2003