WebSphere brand IBM WebSphere Sensor Events, Version 6.2

EPCIS Connector

The EPCIS Connector Reusable Component converts an ISensorEvent (tag reads, aggregated tag reads, or generic event) into EPCIS XML events. The generated XML is augmented with additional information based on name-value pairs.

EPCIS is a standard for storing and sharing RFID data. Event data is delivered to EPCIS in the form of XML messages that adhere to a schema that is part of the EPCIS standard. The use of EPCIS is especially popular in the pharmaceutical business area, but is applicable to any sensor solution that uses persisted data, such as track and trace or asset monitoring. IBM® has implemented the EPCIS standard in InfoSphere™ Traceability Server.

The generated XML can be:

After the EPCIS Connector creates the EPCIS XML messages, it can submit them to an EPCIS (such InfoSphere Traceability Server) by publishing them to a WebSphere Sensor Events MQ queue that is shared between the systems. The required steps to configure this communication are described in this technote: Configuring WebSphere Sensor Events and InfoSphere Traceability Server to communicate on remote machines

WebSphere Sensor Events configuration

Table 1. EPCIS Connector agent properties
Name Description PID Agent properties
EPCIS Connector Agent RUC EPCIS Connector Agent com.ibm.rfid.epcis.slsb.EPCISConnectorAgent
  • generate.output.failure=rucresponse/epcisconnector/generate/failure
  • generate.output.success=rucresponse/epcisconnector/generate/success
  • include.location.context=false
  • publish.outbound.parameter.key=epcisconnector.action
  • publish.outbound.topic=epcisconnector
  • publish.output.failure=rucresponse/epcisconnector/publish/failure
  • publish.output.success=rucresponse/epcisconnector/publish/success
  • publishoutbound.output.failure=rucresponse/epcisconnector/publishoutbound/failure
  • publishoutbound.output.success=rucresponse/epcisconnector/publishoutbound/success

WebSphere Application Server configuration

See Configuring the messaging interface for the WebSphere Application Server configuration details.

Methods

Using the EPCIS Connector Reusable Component

To invoke the EPCIS Connector Reusable Component using IBM Sensor Events or XML, the payload must include:

Generic payload created from a map can also be used. It must include either of the following:

Note: TAG_KEY_INOUT takes a String value. TAGLIST_KEY_INOUT takes a value of java.util.List populated with Strings.

To publish to Reusable Components MDBs, set the following values for the JMS topic and eventType. For multi-action Reusable Components, the topic is checked in the message selector and in the MDB code.

The JMS topic and eventType for the MDB output from the Reusable Component comes from the agent properties. You can set JMS header properties to be included when publishing an event to the output channel. To add a name and value pair to the JMS header, add any attribute beginning with the name jmsheader. to the payload metadata of the original event. Default output topics for success and failure for each action are shown in Table 1.

Providing event attributes

Required event attributes are provided to the EPCIS Connector in one of two ways:

If the attributes are not in the tag event as payload metadata, the Reusable Component checks the database based on the location that generated the event. The OBJECTINSTANCEMETADATA database table stores the attributes.

At setup time, this database table can be populated directly or through using SQL, as shown in the Example database configuration at the end of this topic. At runtime, the attributes contained in this table can be manipulated using the WebSphere Sensor Events API methods, getLocationMetaData and setLocationMetaData. Running applications should not update the database table using SQL statements directly.

Required event attributes

The EPCIS XML messages, or events, are of one of four types: ObjectEvent, AggregationEvent, TransactionEvent, and QuantityEvent. The EPCIS Connector can generate all four types of events. Each of these events requires special attributes.

Table 2. Attributes for the events
ObjectEvent AggregationEvent TransactionEvent QuantityEvent
  • action
  • bizStep
  • disposition
  • readPoint
  • bizLocation
  • bizTransaction
  • bizTransactionType
  • eventTimeZoneOffset
  • action
  • bizStep
  • disposition
  • readPoint
  • bizLocation
  • bizTransaction
  • bizTransactionType
  • eventTimeZoneOffset
  • action
  • bizStep
  • disposition
  • readPoint
  • bizLocation
  • bizTransaction
  • bizTransactionType
  • eventTimeZoneOffset
  • epcClass
  • quantity
  • bizStep
  • disposition
  • readPoint
  • bizLocation
  • bizTransaction
  • bizTransactionType
  • eventTimeZoneOffset

Adding attributes and elements

You can add information beyond the attributes listed in Table 2 to the EPCIS XML message by using extensions. To add an attribute as an extension to the event, the name of the attribute needs to start with extension., for example extension.expirationDate.

You can also add elements into the main body of the EPCIS XML using the prefix: epcis.

This attribute allows you to insert custom elements into the main body of the XML. For example:

epcis.employeeName = Bob

This insertion results in the generated XML containing the following in the main event body:

<employeeName>Bob</employeeName>

Elements that begin with extension. or epcis. support nesting. For example:

epcis.employee/name = Bob

This insertion results in the generated XML containing the following in the main event body:

<employee><name>Bob</name></employee>

You can also specify an index in the path using square brackets, as in accordance with the XPath syntax.

Any number of attributes are also supported on extension. or epcis., using the XPath syntax.

Special event attributes

In addition to the required attributes and the extension mechanism, there are special attributes that allow you to decide which type of event to create, as well as how to determine the parent tag from a group of tags in an aggregation message.

EVENTTYPE
Set this attribute to choose which of the four types of events to create. The value for EVENTTYPE should be ObjectEvent, AggregationEvent, TransactionEvent, or QuantityEvent. If no EVENTTYPE is specified, the EPCIS Connector defaults to ObjectEvent.
PARENTTAG
This attribute is used in the AggregationEvent and TransactionEvent types to determine which of the tags in a group of tags is the parent. The value can be a specific EPC tag value or a list of EPC tags separated by spaces. If any value is provided, this attribute has priority over the alternative attributes, PARENTTAGTYPE and PARENTTAGFILTER, which will be ignored.

An example of this attribute value is: urn:epc:tag:sgtin-96:3.0614141.100734.1

If you want to specify multiple possible EPC tags that might be the parent, then this attribute value could look like this:

urn:epc:tag:sgtin-96:3.0614141.100734.1 urn:epc:tag:sgtin-96:3.0614141.100734.2 urn:epc:tag:sgtin-96:3.0614141.100734.3

If multiple EPCs from the group of tags match the PARENTTAG list, only the first match from the group is used as the parentID in the generated EPCIS event; however, all matching parent tags are removed from the list of childEPCs in the generated EPCIS event.

PARENTTAGTYPE
This attribute is used in the AggregationEvent and TransactionEvent types to determine which of the tags in a group of tags is the parent. For example, in an aggregated tag read, this value tells the EPCIS Connector the tag type of the pallet. An example of this attribute value is sscc-96.
PARENTTAGFILTER
This attribute identifies the EPC tag filter value of the parent. This value is used in combination with the PARENTTAGTYPE to identify the parent tag from a group. An example of this attribute value is 0.

If multiple EPCs from the group of tags match the PARENTTAGTYPE and PARENTTAGFILTER combination, only the first match from the group is used as the parentID in the generated EPCIS event; however, all matching parent tags are removed from the list of childEPCs in the generated EPCIS event.

ALIAS.alias_name
This attribute allows you to insert a namespace alias into the XML header of the generated EPCIS event. This alias can then be used within the event XML to qualify metadata tags and values that you specify for other attributes. The value of this special attribute must include the full namespace for this alias and should also include the XSD schema file name (including the relative path or URL). These two items should be separated by a space. For example:
ALIAS.hls	=	urn:epcglobal:hls:1 hls.xsd

This special attribute can be added multiple times for different aliases, resulting in multiple namespace aliases in the XML header of the generated EPCIS event.

Example database configuration

The following is an example of the SQL code required to configure the EPCIS Connector to create AggregationEvents from the P2 location:

insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','EVENTTYPE','AggregationEvent','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','PARENTTAGTYPE','sscc-96','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','PARENTTAGFILTER','0','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','action','ADD','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','bizStep','urn:epcglobal:epcis:bizstep:commissioning','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','disposition','urn:epcglobal:epcis:disp:active','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','readPoint','urn:epcglobal:hls:loc:1234567.12345','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','bizLocation','urn:epcglobal:hls:loc:1234567.12345.0001','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','bizTransaction','urn:epcglobal:epcis:trans:1234567','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','bizTransactionType','urn:epcglobal:fmcg:btt:po','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','eventTimeZoneOffset','-5:00','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','extension.batchNo','XYZ123','');
insert into SAGE.OBJECTINSTANCEMETADATA values ('P2','extension.expirationDate','01 Jan 2009','');
commit; 

Logging and exceptions

In addition to the exceptions listed in Troubleshooting the Reusable Components, the following exception can occur with the EPCIS Connector Reusable Component:

When an error is encountered while generating the EPCIS XML, the EPCIS Connector logs the exception and return an empty string. This does not result in anything being published to the MQ queue, or the output channel. If the reusable component is called as an MDB and the generate action is called, the EPCIS Connector publishes on the failure topic. The EPCIS Connector MDB always publishes responses to the success topic for the publish and publishoutbound actions.


Library | Support | Terms of use

(c) Copyright IBM Corporation 2004, 2009. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.