The connector for HL7 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.
The 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 HL7_MT502_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.
Table 15 describes the meta-object properties.
Table 15. Static meta-object properties
Property name | Description |
---|---|
CollaborationName | The collaboration name must be specified in the application-specific text
of the attribute for the business object/verb combination. For example,
if you expect to handle synchronous requests for the business object Customer
with the Create verb, the static meta-data object must contain an attribute
named HL7_MTnnn_Verb,
where nnn is the HL7 message type, for example,
HL7_MT502_Create. The HL7_MT502_Create attribute
must contain application-specific text that includes a name-value pair.
For example, CollaborationName=MyCustomerProcessingCollab. See the Application-specific information section for syntax details. Failure to do this
results in runtime errors when the connector attempts to synchronously process
a request involving the Customer business object.
|
DoNotReportBusObj | Optionally, you can include the DoNotReportBusObj
property. By setting this property to true, all PAN report
messages issued have a blank message body. This is recommended when you
want to confirm that a request has been successfully processed but does not
need notification of changes to the business object. This does not
affect NAN reports. If this property is not found in the static
meta-object, the connector defaults to false and populates the
message report with the business object.
|
InputFormat | The input format 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. If this format is not specified for a business object, the connector does not handle subscription deliveries for the given business object. |
OutputFormat | The output format is set on messages created from the given business object. If a value for the OutputFormat property is not specified, the input format is used, if available. An OutputFormat property value defined in a dynamic child meta-object overrides the value defined in the static meta-object. |
InputQueue | The input queue that the connector polls to detect new messages. You can use connector-specific properties to configure multiple InputQueues and optionally map different data handlers to each queue. |
OutputQueue | The output queue is the queue to which messages derived from the given business object are delivered. An OutputQueue property value defined in a dynamic child meta-object overrides the value defined in the static meta-object. |
ResponseTimeout | The length of time in milliseconds to wait for a response before timing out. The connector returns SUCCESS immediately without waiting for a response if this property is undefined or has a value less than zero. A ResponseTimeout property value 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 connection to the connector. A TimeoutFatal property defined in a dynamic child meta-object overrides the value defined in the static meta-object. |
The application-specific information is structured in name-value pair format, separated by semicolons. For example:
InputFormat=ORDER_IN;OutputFormat=ORDER_OUT
You can use application-specific information to map a data handler to an input queue.
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:
For example, the following attribute in a static meta-object associates a data handler with an InputQueue named CompReceipts:
[Attribute] Name = HL7_MT502_Create Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = InputQueue=//queue.manager/CompReceipts; DataHandlerClassName=com.crossworlds. DataHandlers.HL7.disposition_notification; DataHandlerMimeType=message/ disposition_notification IsRequiredServerBound = false [End]
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 cannot 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 static configuration meta-object is specific to MQ connectivity. It provides the following services:
Attribute Name | Type | IsKey | Foreign Key | IsRequired | Cardinality | Max Length | Default | ASI | Comment |
---|---|---|---|---|---|---|---|---|---|
Default | String | Yes | No | Yes | 1 | 1 |
| OutputQueue=queue://crossworlds.queue.manager/MQCONN.OUT | Output queue defnition |
HL7_Message_Create | String | No | No | No | 1 | 7 | Create | InputFormat=MQSTR;OutputFormat=MQSTR |
|
ObjectEventID |
| No |
| No | 1 |
|
|
| Reserved for system use |
The static meta-object shown below configures the connector to convert HL7_MT502 business objects using verbs Create 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.
Attribute HL7_MT502_Create indicates to the connector that any messages of format NEW should be converted to a business object with the verb Create. Because an output format is not defined, the connector sends messages representing this object-verb combination using the format defined for input (in this case NEW).
Attribute HL7_MT502_Retrieve specifies that business objects with verb Retrieve should be sent as messages with format RETRIEVE. Note that the default response time has been overridden so that the connector can wait up 10000 milliseconds before timing out (it still terminates if a response is not received).
[ReposCopy] Version = 3.0.0 Repositories = 1cHyILNuPTc= [End] [BusinessObjectDefinition] Name = Sample_MO Version = 3.0.0 [Attribute] Name = Default Type = String Cardinality = 1 MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false AppSpecificInfo = OutputQueue=queue://crossworlds.queue.manager/MQCONN.OUT;ResponseTimeout=5000;TimeoutFatal=true IsRequiredServerBound = false [End] [Attribute] Name = HL7_MT502_Create Type = String Cardinality = 1 MaxLength = 1 IsKey = false IsForeignKey = false IsRequired = false AppSpecificInfo = InputFormat=NEW IsRequiredServerBound = false [End] [Attribute] Name = HL7_MT502_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 = Retrieve [End] [End]
If it is difficult or unfeasible to specify the necessary meta-data through a static meta-object, the connector can optionally accept meta-data specified at runtime for each business object instance.
The connector recognizes and reads conversion properties from a dynamic meta-object that is 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.
Because 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 either a dynamic child meta-object or a static meta-object, or both.
Table 17 shows sample static meta-object properties for business
object HL7_MT502_Create. Note that the application-specific
text consists of semicolon-delimited name-value pairs
Table 17. Static meta-object structure for HL7_MT502_Create
Attribute name | Application-specific text |
---|---|
HL7_MT502_Create | InputFormat=ORDER_IN;OutputFormat=ORDER_OUT;OutputQueue=QueueA;ResponseTimeout=10000;TimeoutFatal=False |
Table 18 shows a sample dynamic child meta-object for business object
HL7_MT_Create.
Table 18. Dynamic child meta-object Structure for HL7_MT502_Create
Property name | Value |
---|---|
OutputFormat | ORDER_OUT |
OutputQueue | QueueA |
ResponseTimeout | 10000 |
TimeoutFatal | False |
The connector checks the application-specific text of the 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.
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 Table 19 shows how a dynamic child meta-object might be structured
for polling.
Table 19. JMS dynamic child meta-object structure for polling
Property name | Sample value |
---|---|
InputFormat | ORDER_IN |
InputQueue | MYInputQueue |
OutputFormat | CxIgnore |
OutputQueue | CxIgnore |
ResponseTimeout | CxIgnore |
TimeoutFatal | CxIgnore |
As shown in Table 19, you can define an additional property, InputQueue, in a dynamic child meta-object. This property 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:
The following meta-object is used to configure all heathcare data
handlers.
Attribute Name | Type | IsKey | Foreign Key | IsRequired | Cardinality | Max Length | Default | Comment |
---|---|---|---|---|---|---|---|---|
HL7 | MO_DataHandler_HL7 | No |
| No | 1 | N/A |
| Attribute name designates a name for the MIME type of HL7 messages |
DummyKey | String | Yes | No | Yes | 1 | 1 |
|
|
The following meta-object contains configuration properties for the HL7
data handler. BO_Prefix, Default Verb, and ClassName are used in the
invocation of the data handler by the connector.
Attribute Name | Type | IsKey | Foreign Key | IsRequired | Cardinality | Max Length | Default | Comment |
---|---|---|---|---|---|---|---|---|
BOPrefix | String | Yes | No | Yes | 1 | 4 | HL7 | BO's prefix |
Default Verb | String | No | No | No | 1 | 7 | Create | Verb set in BO |
Class Name | String | No | No | No | 1 | 255 | com.bim.adapters.datahandlers.hl7.HL7DataHandle | Java class name of the HL7 data handler |
Representation | String | No | No | No | 1 | 1 | Simplified | Can be on of the following:
"Simplified" or "Native" Simplified signifies the use of a parsing method which provides find object representation to only the message header. Native signifies the user of a parsing method which provides fine object representation to the whole message |
Field delimiter | String | No | No | No | 1 | 1 | | | Default field delimiter for all types |
RepetitionDelimiter | String | No | No | No | 1 | 1 | ~ | Default repetition delimiter for all types |
ComponentDelimiter | String | No | No | No | 1 | 1 | ^ | Default component delimiter for all types |
SubcomponentDelimiter | String | No | No | No | 1 | 1 | & | Default subcomponent delimiter for all types |
MTEventMap | String | No | No | No | 1 | 255 | file=...\Healthcare\dependencies\HL7\BIA_HL7MTEventMap.cfg | This configuration contains a map of (Message type X Event Type)->Message Structure |
I118N | String | No | No | No | 1 | 255 | file=...\Healthcare\dependencies\HL7\BIA_HLI118N.cfg | Specifies the path name of the BIA_HL7I118N.cfg file. This files contains map information on ISO character set, escape secquence and Java name |
DummyKey | String | Yes | No | No | 1 |
|
|
|
[BusinessObjectDefinition] Name = MO_Sample_Config Version = 1.0.0 [Attribute] Name = OutputFormat Type = String MaxLength = 1 IsKey = true IsForeignKey = false IsRequired = false DefaultValue = ORDER 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 = Retrieve [End] [End] [BusinessObjectDefinition] Name = HL7_MT502 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 = Retrieve [End] [End]
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, to control the ReplyToQueue on a per-request basis (rather than using the default ReplyToQueue specified in the adapter properties), and to re-target a message CorrelationID. This section describes these attributes and how they affect event notification and request processing in both synchronous and asynchronous modes.
The following attributes, which reflect JMS and HL7 header properties, are
recognized in the dynamic meta-object.
Table 22. Dynamic meta-object header attributes
Header attribute name | Mode | Corresponding JMS header |
---|---|---|
CorrelationID | Read/Write | JMSCorrelationID |
ReplyToQueue | Read/Write | JMSReplyTo |
DeliveryMode | Read | JMSDeliveryMode |
Priority | Read | JMSPriority |
Destination | Read | JMSDestination |
Expiration | Read | JMSExpiration |
MessageID | Read | JMSMessageID |
Redelivered | Read | JMSRedelivered |
TimeStamp | Read | JMSTimeStamp |
Type | Read | JMSType |
UserID | Read | JMSXUserID |
AppID | Read | JMSXAppID |
DeliveryCount | Read | JMSXDeliveryCount |
GroupID | Read | JMSXGroupID |
GroupSeq | Read | JMSXGroupSeq |
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.
The interpretation and use of these attributes are described in the sections below.
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:
The table below shows application-specific information properties that you
must define for attributes in the JMSProperties object.
Table 23. 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 attribute JMSProperties in the dynamic meta-object and definitions for four properties in the JMS message header: ID, GID, RESPONSE and RESPONSE_PERSIST. The application-specific information of the attributes defines the name and type of each. For example, attribute ID maps to JMS property ID of type String).
Figure 3. JMS properties attribute in a dynamic meta-object
If a dynamic meta-object with header attributes is present in the event business object, the connector performs the following steps (in addition to populating the meta-object with transport-related data):
For synchronous event processing, the adapter posts an event and waits for a response from the integration broker before sending a response message back to the application. Any changes to the business data are reflected in the response message returned. Before posting the event, the adapter populates the dynamic meta-object just as described for asynchronous event notification. The values set in the dynamic meta-object are reflected in the response-issued header as described below (all other read-only header attributes in the dynamic meta-object are ignored.):
If you do not define attribute CorrelationID in the meta-object, the connector handles the CorrelationID automatically.
The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. The connector performs the following steps before sending a request message:
The connector uses the dynamic meta-object, if present, to populate the request message prior to issuing it. If the dynamic meta-object contains header attributes, the connector populates it with corresponding new values found in the response message. The connector performs the following steps (in addition to populating the meta-object with transport-related data) after receiving a response message:
If a JMS property cannot be read from or written to a message, the connector logs an error and the request or event fails. If a user-specified ReplyToQueue does not exist or cannot be accessed, the connector logs an error and the request fails. If a CorrelationID is invalid or cannot be set, the connector logs an error and the request fails. In all cases, the message logged is from the connector message file.