Meta-object attributes configuration

The connector for FIX Protocol can get processing information from two kinds of meta-objects:

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

Static meta-object

The FIX Protocol static meta-object 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.

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.

Table 12 describes the meta-object properties.

Table 12. Static meta-object properties

Property name Description
CollaborationName
 
The CollaborationName must be specified in the application specific text of the attribute for the business object-verb combination. For example, if a user expects to handle synchronous requests for the business object Customer with the Create verb, the static metadata object must contain an attribute named Customer_Create. The Customer_Create attribute must contain application specific text that includes a name-value pair. For example, CollaborationName=MyCustomerProcessingCollab. See the Application-specific text section for syntax details. Failure to do this results in run-time errors when the connector attempts to synchronously process a request involving the Customer business object.
Note:
This property is only available for synchronous requests.
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.
DataHandlerConfigMO
 
Meta-object passed to data handler to provide configuration information. If specified in the static meta-object, this property overrides 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. 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.
DoNotReportBusObj
 
Optionally, the user can include the DoNotReportBusObj property. By setting this property to true, all PAN report messages issued will have a blank message body. This is recommended when a requestor wants to confirm that a request has been successfully processed and does not need notification of changes to the business object. This does not effect NAN reports. If this property is not found in the static meta-object, the connector will default it to false and populate the message report with the business object.
Note:
This property is only available for synchronous requests.
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. This feature is not used by the adapter for the FIX protocol.
InputQueue The InputQueue property in the connector-specific properties defines which queues the adapter polls. This is the only property that the adapter uses to determine which queues to poll. In the static MO, the InputQueue property and the InputFormat property can serve as criteria for the adapter to map a given message to a specific business object. This feature is not used by the adapter for the FIX protocol.
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.
ResponseTimeout
 
Indicates the length of time in milliseconds to wait before timing out when waiting for a response. The connector returns SUCCESS immediately without waiting for a response if this is left undefined or with a value less than zero. A ResponseTimeout defined in a dynamic child meta-object overrides the value defined in the static meta-object.
TimeoutFatal
 
If this property is defined and has a value of True, the connector returns APP_RESPONSE_TIMEOUT when a response is not received within the time specified by ResponseTimeout. All other threads waiting for response messages immediately return APP_RESPONSE_TIMEOUT to the integration broker. This causes the integration broker to terminate the connector. A TimeoutFatal defined in a dynamic child meta-object overrides the value defined in the static meta-object.

Table 13. Sample default static meta-object structure for Customer_Create

Attribute name App-Text
Customer_Create
 
DataEncoding=Text:UnicodeLittle;
  
 OutputFormat=CUST_OUT;
  
 OutputQueue=QueueA;
  
 ResponseTimeout=10000;
  
 TimeoutFatal=False
 

Application-specific text

The application-specific text 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 = Fix_Create
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputQueue=//queue.manager/CompReceipts;
    DataHandlerClassName=com.crossworlds.
 DataHandlers.fix.disposition_notification;DataHandlerMimeType=message/
 disposition_notification
 IsRequiredServerBound = false
 [End]
 

Overloading input formats

When retrieving a message, the connector normally matches the input format to one specific business object and verb combination. The connector then passes the business object name and the contents of the message to the data handler. This allows the data handler to verify that the message contents correspond to the business object that the user expects.

If, however, the same input format is defined for more than one business object, the connector is unable to determine which business object the data represents before passing it to the data handler. In such cases, the connector passes the message contents only to the data handler and then looks up conversion properties based on the business object that is generated. Accordingly, the data handler must determine the business object based on the message content alone.

If the verb on the generated business object is not set, the connector searches for conversion properties defined for this business object with any verb. If only one set of conversion properties is found, the connector assigns the specified verb. If more properties are found, the connector fails the message because it is unable to distinguish among the verbs.

A sample meta-object

The static meta-object shown below configures the connector to convert Customer business objects using verbs Create, Update, Delete, and Retrieve. Note that attribute Default is defined in the meta-object. The connector uses the conversion properties of this attribute:

OutputQueue=CustomerQueue1;ResponseTimeout=5000;TimeoutFatal=true
 

as default values for all other conversion properties. Thus, unless specified otherwise by an attribute or overridden by a dynamic child meta-object value, the connector issues all business objects to queue CustomerQueue1 and then waits for a response message. If a response does not arrive within 5000 milliseconds, the connector terminates immediately.

Customer object with Verb Create

Attribute Customer_Create indicates to the connector that any messages of format NEW should be converted to a business object of type Customer with the verb Create. Since an output format is not defined, the connector will send messages representing this object-verb combination using the format defined for input (in this case NEW).

Customer object with Verbs Update and Delete

Input format MODIFY is overloaded--defined for both business object Customer with verb Update and business object Customer with verb Delete. In order to successfully process retrieved messages of this format, the business object name and possibly the verb should be contained in the message content for the data handler to identify (see Overloading input formats). For Request processing operations, the connector sends messages for either verb using the input format MODIFY since an output format is not defined.

Customer object with Verb Retrieve

Attribute Customer_Retrieve specifies that business objects of type Customer with verb Retrieve should be sent as messages with format Retrieve. Note that the default response time has been overridden so that the connector waits up 10000 milliseconds before timing out (it will still terminate if a response is not received).

[ReposCopy]
 Version = 3.1.0
 Repositories = 1cHyILNuPTc=
 [End]
 [BusinessObjectDefinition]
 Name = Sample_MO
 Version = 1.0.0
  
 [Attribute]
 Name = Default
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = OutputQueue=CustomerQueue1;ResponseTimeout=5000;TimeoutFatal=true
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Customer_Create
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=NEW
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Customer_Update
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=MODIFY
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Customer_Delete
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = InputFormat=MODIFY
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Customer_Retrieve
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo = OutputFormat=RETRIEVE;ResponseTimeout=10000
 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 meta-object

If it is difficult or unfeasible to specify the necessary metadata through a static meta-object, the connector can optionally accept metadata specified at run-time for each business object instance.

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.

Since dynamic child meta object properties override those found in static meta-objects, if you specify a dynamic child meta-object, you need not include a connector property that specifies the static meta-object. Accordingly, you can use a dynamic child meta-object independently of the static meta-object and vice-versa.

Table 13 and Table 14 show sample static and dynamic child meta-objects, respectively, for business object Customer_Create. Note that the application-specific text consists of semi-colon delimited name-value pairs.

Table 14. Dynamic child meta-object structure for Customer_Create

Attribute name Value
DataEncoding
 
Text:UnicodeLittle
 
DataHandlerMimeType1
 
fix
 
OutputFormat
 
CUST_OUT
 
OutputQueue
 
QueueA
 
ResponseTimeout
 
10000
 
TimeoutFatal
 
False
 
  1. Assumes that DataHandlerConfigMO has been specified in either the connector configuration properties or the static meta-object.

The connector checks the application-specific text 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 the integration broker 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.

Table 15 shows how a dynamic child meta-object might be structured for polling.

Table 15. JMS dynamic child meta-object structure for polling

Attribute name Sample value
InputFormat
 
CUST_IN
 
InputQueue
 
MYInputQueue
 
OutputFormat
 
CxIgnore
 
OutputQueue
 
CxIgnore
 
ResponseTimeout
 
CxIgnore
 
TimeoutFatal
 
CxIgnore
 

As shown in Table 15, 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:

Sample dynamic child meta-object

[BusinessObjectDefinition]
 Name = MO_Sample_Config
 Version = 1.0.0
  
 [Attribute]
 Name = OutputFormat
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 DefaultValue = CUST
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = OutputQueue
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = OUT
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = ResponseTimeout
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = -1
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = TimeoutFatal
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 DefaultValue = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = InputFormat
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = InputQueue
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 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]
 [BusinessObjectDefinition]
 Name = Customer
 Version = 1.0.0
 AppSpecificInfo = cw_mo_conn=MyConfig
  
 [Attribute]
 Name = FirstName
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = LastName
 Type = String
 MaxLength = 1
 IsKey = true
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = Telephone
 Type = String
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 IsRequiredServerBound = false
 [End]
 [Attribute]
 Name = MyConfig
 Type = MO_Sample_Config
 ContainedObjectVersion = 1.0.0
 Relationship = Containment
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 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]
 

Copyright IBM Corp. 1997, 2003