WebSphere Sensor Events 6.2 Feature Pack 1 ASN Persistence RUC update 1.0 Overview 2.0 Included in this package 3.0 Deploying the ASN Persistence RUC 4.0 Customizing 5.0 Using the component 1.0 OVERVIEW ------------ This README provides information about the Feature Pack Cumulative APAR available in this package. WebSphere Sensor Events 6.2 Feature Pack 1 includes an ASN Persistence RUC and pluggable ASN Parser that adds the following functions for ASN to WebSphere Sensor Events: – Parse an ASN into a standard Java structure. – Collect hierarchy-dependent properties from ASN. – Collect data via RUC queries for every contained EPC. – Publish collected props and data to WebSphere Business Events for validation against flexible rules. – If valid, persist the ASN as pedigree events to EPCIS. This fix must be installed on an IBM WebSphere Sensor Events server 6.2 that has Feature Pack 1 installed. 2.0 INCLUDED IN THIS PACKAGE --------------------------------- The following reported program defects are fixed in this update: List of APARs included: APAR Number Description IC66134 ASN Persistence RUC and metadata for EPCIS events. IC65034 ASN Persistence RUC updates. IC66576 Update to EPCConnector to support alternate namespaces and multiple values for required items. n/a Fix to correctly extract the parent from the result of the Inference RUC getParent query before sending the tag information for validation. n/a Updates to the ASN Parser to use UTF-8 encoding and optional parsing techniques. 3.0 DEPLOYING THE ASN PERSISTENCE RUC ------------------------------------- This section contains the following subsections: 3.1 Removing an existing ASN Persistence RUC 3.2 Locating the ASN Parser and ASN Persistence RUC EAR files 3.3 Pre-configuring the ASN Persistence RUC 3.4 Installing the EAR files 3.1 Removing an existing ASN Persistence RUC If you had previously deployed the ASN Persistence RUC install, you must remove it before deploying this updated version. 1. Remove the WebSphere Sensor Events Agent. a. In WebSphere Sensor Events Admininstration console, click on Agent Configuration. b. Check the box next to ASNPersistenceAgent. c. Click the Delete Selected Agents button. 2. Remove the WebSphere Sensor Events Locations. a. In WebSphere Sensor Events Admin, click on Locations. b. Expand ASNPERSISTENCE. c. For all three contained ASNPERSISTENCE_RUC_x locations, click the link, click Delete, and then click OK. d. For the remaining container ASNPERSISTENCE location, click the link, click Delete, and then click OK. 4. Uninstall the following EARs a. ibmruc_ASNParserBackend_ear b. ibmruc_ASNPersistence_ear 3.2 Locating the ASN Parser and ASN Persistence RUC EAR files Prerequisite: Feature Pack 1 must be installed on WebSphere Sensor Events 6.2 The ASN Parser and RUC are NOT deployed automatically when the Feature Pack is installed. 1. Download the Feature Pack update file (IC66600.zip). 2. Create a folder named maintenance in the WebSphere Sensor Events server C:\Program Files\IBM\RFID directory. 3. Extract the files from the IC66600.zip file to the C:\Program Files\IBM\RFID\maintenance directory. The .zip file contains these files: IC66600\ibmruc_ASNParserBackend_ear.ear IC66600\ibmruc_ASNPersistence_ear.ear IC66600\IC66600-readme.html IC66600\WebSphere_Sensor_Events.IC66600.fxtag 4. Note the location of the following EAR files: – ibmruc_ASNParserBackend_ear.ear (Parser Backend) – ibmruc_ASNPersistence_ear.ear (RUC) 5. Copy the WebSphere_Sensor_Events.IC66600.fxtag file to the C:\Program Files\IBM\RFID\properties\version directory. 3.3 Pre-configuring the ASN Persistence RUC 1. Extract the cfg folder from the ibmruc_ASNPersistence_ear.ear file. 2. Create the JMS Activation Specification. In the WebSphere Application Server Administration console, create a new Activation Spec using the values provided in the CreateActivationSpec.txt file. 3. Create the RUC Task Agent. In the WebSphere Sensor Events Administration console, import the CreateRUCAgent.xml configuration file. 4. Create the event source locations. In the WebSphere Sensor Events Administration console, import the CreateEventSourceLocations.xml configuration file. 5. Load the WebSphere Business Events (WebSphere Business Events) rules. Note: This is not required if WebSphere Business Events validation is disabled. Open the WebSphere Business Events project XML using either WebSphere Business Events Design Data or WebSphere Business Events Design. See “4.0 Customizing” for more information. 3.4 Installing the EAR files Install the two EAR files using the WebSphere Application Server administrative console. Start the two EAR files and verify that they are started. If they are started a green arrow is displayed next to the filename. 4.0 Customizing ---------------- This section contains the following subsections: 4.1 ASNPersistenceAgent (RUC) properties 4.2 Fields sent to WebSphere Business Events for validation 4.3 Defining Validation Rules for the ASN Persistence RUC 4.4 Deploying WebSphere Business Events rules 4.5 Customizing the ASN Parser 4.1 ASNPersistenceAgent (RUC) properties The following properties are customizable for ASNPersistenceAgent (RUC). • Target Backend is the default ASN Parser Backend. – ruc.targetBackend = ruc.custom – ruc.targetBackendJNDI = • Enable queries to collect data. – doLocate, doInfo, doInference, doMasterData (boolean) • Enable publish to WebSphere Business Events for validation against rules. – doWBE (boolean) • Enable generation and publishing of EPCIS pedigree events. – doCommission, doObserve, doAggregate (boolean) • responseTime – The time (in milliseconds) that the ASN Persistence RUC should wait, after publishing the EPC validation events to WebSphere Business Events, before forcing a final decision on the ASN. • statusTopic – The topic on which the ASN Persistence RUC should publish a message announcing the final decision state of the ASN. • Possible states are PERSISTED, REJECTED, EXPIRED, or SYSTEMFAILURE. • masterdata.category.value – Category used for Master Data query if doMasterData = true • masterdata.key.property – A property used to lookup its value in ASN pack properties, which will be used as the key for Master Data query if doMasterData = true ASNPersistenceAgent (RUC) properties. • COMM_SOURCE_ID (default L1001) – Event sourceId used by RUC when creating a Commission event, must correspond to real WebSphere Sensor Events location. Use this value when setting static location metadata for EPCIS events. • OBS_SOURCE_ID (default L1002) – Event sourceId used by RUC when creating an Observe event, must correspond to real WebSphere Sensor Events location. Use this value when setting static location metadata for EPCIS events. • AGG_SOURCE_ID (default L1003) – Event sourceId used by RUC when creating an Aggregate event, must correspond to real WebSphere Sensor Events location. Use this value when setting static location metadata for EPCIS events. 4.2 Fields sent to WebSphere Business Events for validation The following fields are used when validating the WebSphere Business Events. • ASN properties All props discovered at this level and previously, based on depth-first iteration. • ASN hierarchy data ASN_ID, PACK_TYPE, TAG, ASN_PARENTID • If doLocate All props returned from Locating RUC. • If doInference INFERRED_PARENTID if a parent WebSphere Application Server successfully inferred. • If doInfo All props returned from Info RUC. • If doMasterData All props returned from Info RUC getMasterData query (see Agent properties to control master data query parameters). 4.3 Defining Validation Rules for the ASN Persistence RUC 1. Using WebSphere Business Events Design Data, review the predefined input properties for events. a. Expand the Touchpoint. b. Note the predefined properties ASN_ID, and so on. 2. Review the predefined action. Note: BMSE_JMSResponse has been changed for this RUC to publish a message to the bus: - On topic : default/asnpersistence/add - With fields: ASN_ID as passed, isValidToPersist = true 3. Make any required changes such as adding new input properties or defining new actions to the Design Data. 4. Using WebSphere Business Events Design, review the predefined validation filter. 5. Make any required changes such as adding new filter conditions or triggering new actions to the Design. 6. Deploy the updated rules. See "4.4 Deploying WebSphere Business Events rules". 4.4 Deploying WebSphere Business Events rules 1. Deploy the new rules into into Repository. a. From either WebSphere Business Events Design or Design Data, click Tools > Repository. b. Authenticate to the Repository. c. Add in new rules, or check in updated rules. 2. Reload WebSphere Business Events runtime from Repository. a. In the browser, log into WebSphere Business Events web application. b. Select Console. c. Click the Refresh from Repository icon. 4.5 Customizing the ASN Parser The ASN Parser is considered a backend for the ASN Persistence RUC. The contract between the parser and the RUC is the ASNParserBackendInterface. The ASNParserBackendInterface is defined in ibmruc_ASNParserBackend_ejbClient.jar file using the single method: public PackageLevel parseASN(String asnURL) throws the ASNParserException ====================================================================================================================== 5.0 Using the component This section contains the following subsections: 5.1 Calling the ASN Persistence RUC 5.2 Handling results and exceptions 5.3 Asynchronous result messages 5.4 Exceptions caused by WebSphere Business Events callbacks 5.5 Currently supported ASN fields 5.6 ASN property names and ASN containing data element 5.7 Optional ASN Parser techniques 5.1 Calling the ASN Persistence RUC The the ASN Persistence RUC can be called using either the SLSB, WS, or MDB interface. The following calls are available in the ASN Persistence RUC. • persistASN ( String asnURL ) The only method that callers call directly. It passes a URL to the ASN file on the local file system. The RUC parses, collects information, validates, and persists to EPCIS. • addTagStatus This is a callback method from WebSphere Business Events that checks if a single tag is valid or invalid. If all tags from the ASN are reported as valid, addTagStatus triggers a call to persistProcessedASN. • stopTagStatus This is a callback method from WebSphere Business Events that checks if an entire ASN is valid or invalid. If the ASN is valid, stopTagStatus triggers a call to persistProcessedASN. • persistProcessedASN Performs the generation and publishing of EPCIS pedigree events. • handleTimer (String asnId) This is a Timer handler method that is called automatically when time expires. It can also be called manually as a RUC method. 5.2 Handling results and exceptions Calls to the persistASN return synchronously while background validation and processing continues. If ASN is not parsable, ASNParserException returns. If doWBE=true and ASN contains duplicate tags the DuplicateTagInASNException occurs. Otherwise the asnId (used as key across WebSphere Business Events, callbacks and timer events) is returned. Asynchronous result messages indicate the success or failure of validation and processing. They are published on configurable topic and give the validation status for a certain ASN (by ID and URL). The following table shows both the synchronous and asynchronous messages for specific ASN inputs. Input ASN Agent Props Synchronous Response Asynchronous Response ASN file path cannot be loaded Any ReusableComponent Exception wrapping IOException None ASN loaded, but fails in ASNParser Any ASNParser Exception None ASN contains duplicate tags doWBE = true DuplicateTagInASN Exception None Well-formed ASN passes WebSphere Business Events validation for all tags Any Success (asnId) ISensorEvent with status PERSISTED Well-formed ASN but WebSphere Business Events sends rejection callback doWBE = true Success (asnId) ISensorEvent with status REJECTED Well-formed ASN but WebSphere Business Events does not send a valid callback for all tags before timer doWBE = true Success (asnId) ISensorEvent with status EXPIRED ASN includes a level with multiple tags, and that Multiple Aggregation Parent Exception level has children doAggregate = true Success (asnId) causes ISensorEvent with status SYSTEMFAILURE 5.3 Asynchronous result messages The ISensorEvents is published on the topic given by the Agent property “statusTopic” and includes these fields in the payload: ASN_ID ASN_URL VALID_STATUS with the following possible values: PERSISTED REJECTED EXPIRED SYSTEMFAILURE 5.4 Exceptions caused by WebSphere Business Events callbacks When WebSphere Business Events calls back to the RUC with a tag or ASN validation status, this updates the status in an internal valid tag list for this asnId, but may trigger a ReusableComponentException if: • Unexpected ASN ID: failed to locate internal valid tag list for this asnId. • Expired ASN ID: ASN has already completed processing (will also print the status of the ASN). • Unexpected tag: failed to locate tag in valid tag list for this asnId. 5.5 Currently supported ASN fields The following information is supported in ASN fields: • The entire hierarchical structure of the ASN. • Serial IDs (EPCs) and quantities at each level. If a tag is in the recognized standard format (that is, tag URN or EPCGlobal TDS 1.4), it is converted to URN PureID form. If the tag format is not recognized, it is passed back unchanged to caller. • ASN ID The ASN ID is a combination of interchange control number and interchange sender ID. • Identification code (ship to, ship from). • Original purchase order and invoice numbers. • Properties throughout the hierarchy which include product/service ID (NDC number, lot number) and expiration date. 5.6 ASN property names and ASN containing data element ASN PROPERTY ASN CONTAINING DATA ELEMENT expirationDate HL Pack/Item Level -> DTM02 (when DTM01 = 208 or 036) invoiceNumber HL Order Level -> REF02 lotNumber HL Pack/Item Level -> LIN05 or LIN07 (when LIN04 or LIN06 = LT) ndcNumber HL Pack/Item Level -> LIN03 purchaseOrderNumber HL Order Level -> PRF01 shipFromCodes HL Shipment Level -> N104 (when N101 = SF) shipToCodes HL Shipment Level -> N104 (when N101 = ST) quantity HL Item Level -> SLN04 5.7 ASN Parser can be configured via ASN Persistence Agent properties to change the technique used to parse the ASN: • The parser can be configured to be more lenient when dealing with spurious carriage return or line feed characters introduced by text editors. • Configurable via the com.ibm.rfid.asn.hdma.parser.lenient ASN Persistence Agent property of type boolean. • The default value is false. • The parser can be configured with the desired strategy for handling orphaned package levels. An orphaned package level is one whose HL (hierarchical level) segment has a value for the Parent ID data segment that points to a non-existing parent. • Configurable via the com.ibm.rfid.asn.hdma.parser.strategy.orphan ASN Persistence Agent propertiy of type String with one of the following values.     IGNORE (orphaned package level will simply be discarded)     REJECT (entire ASN will be rejected and an exception logged)     ROOT (orphaned packaged level will be attached to the root package level of the current ship notice being processed)     PREDECESSOR (orphaned package level will be attached as a child of the immediately preceding package level) •The default value is IGNORE.