# Understanding the Event, Master Data, and Data Exchange Services

# Data Exchange Service

The primary function of the Data Exchange Service is to configure query subscriptions and send query results formatted in XML to trading partners via HTTP, JMS, and AS2.

The Data Exchange Service provides several access points to the Event Repository, allowing the user to perform queries on these events:

- The Query Subscription Administration Console configures the Data Exchange Service to create queries and periodically deliver query results to designated receivers (HTTP, JMS, and AS2). The Console can also test queries before subscribing, displaying user-readable events in XML format.
- A SOAP Web service allows programmatic queries. This SOAP service is based on the technically complete, but not formally ratified as of October 2006, EPCglobal EPC Information Services (EPCIS) Version 1.0 Specification.EPCglobal EPCIS 1.0 Working Draft.

The following sections provide information about query parameters and data security:

- SimpleEventQuery
- Data Security

Figure 5-1 shows the components in the Data Exchange Service.

Figure 5-1 Data Exchange Service

## SimpleEventQuery

A SimpleEventQuery filters the Event Repository by various criteria based on the fields in the events. This type of query is the one configured through the Query Subscription Administration Console and available programmatically through a SOAP service.

A query is defined by a set of query parameters, each of which has a name and a value. For each parameter, Table 5-1 provides a description and the following information:

- Console Name is the name used by the Query Subscription Administration Console for the parameter. (The Console uses identical or similar names for parameters, often grouping similar parameters under a single heading.) Some parameters are only available via the SOAP service.
- SOAP Name is the parameter name in a SOAP query definition object (see Capture and Query APIs).
- Value Type is the data type of the parameter's value to include in a SOAP query definition object (seeQuery Interface Parameters and Data Types).

Table 5-1 SimpleEventQuery Parameter Name/Value Pairs
Parameter | Description
--- | ---
Console Name: Event Type SOAP Name: `eventType` Value Type: List of String | The result will only include events whose type matches one of the types specified in the parameter value. Each element of the parameter value may be one of the following strings: `ObjectEvent` `AggregationEvent` `QuantityEvent` `TransactionEvent` An element of the parameter value may also be the name of an extension event type. If omitted, all event types will be considered for inclusion in the result.
Console Name: After Event Time SOAP Name: `GE_eventTime` Value Type: Time | Only events with `eventTime` greater than or equal to the specified value will be included in the result. If omitted, events are included regardless of their `eventTime` (unless constrained by the `LT_eventTime` parameter).
Console Name: Before Event Time SOAP Name: `LT_eventTime` Value Type: Time | Only events with `eventTime` less than the specified value will be included in the result. If omitted, events are included regardless of their `eventTime` (unless constrained by the `GE_eventTime` parameter).
Console Name: After Record Time SOAP Name: `GE_recordTime` Value Type: Time | Only events with `recordTime` greater than or equal to the specified value will be returned. If omitted, events are included regardless of their `recordTime`, other than the following limitation: The first time a query is executed for a subscription, the only events considered are those whose `recordTime` field is greater than or equal to `initialRecordTime` specified when the subscription was created. For each execution of the query following the first execution, the only events considered are those whose `recordTime` field is greater than or equal to the time when the query was last executed.
Console Name: Before Record Time SOAP Name: `LT_recordTime` Value Type: Time | Only events with `recordTime` less than the specified value will be returned. If omitted, events are included regardless of their `recordTime` unless constrained by the `GE_recordTime` parameter or the limitation based on event record time; See `GE_recordTime`.
Console Name: Action SOAP Name: `EQ_action` Value Type: List of String | The result will only include events that (a) have an `action` field; and where (b) the value of the `action` field matches one of the specified values: `ADD`, `OBSERVE`, or `DELETE`. If omitted, events are included regardless of their `action` field.
Console Name: Business Step SOAP Name: `EQ_bizStep` Value Type: List of String | The result will only include events that (a) have a non-null `bizStep` field; and where (b) the value of the `bizStep` field matches one of the specified values. If omitted, events are returned regardless of the value of the `bizStep` field or whether the `bizStep` field exists at all.
Console Name: Disposition SOAP Name: `EQ_disposition` Value Type: List of String | Analogous to the `EQ_bizStep` parameter, but for the `disposition` field.
Console Name: Read Point SOAP Name: `EQ_readPoint` Value Type: List of String | The result will only include events that (a) have a non-null `readPoint` field; and where (b) the value of the `readPoint` field matches one of the specified values. If this parameter and `WD_readPoint` are both omitted, events are returned regardless of the value of the `readPoint` field or whether the `readPoint` field exists at all.
Console Name: Read Point SOAP Name: `WD_readPoint` Value Type: List of String | WD is an abbreviation for with descendants. If specified, the result will only include events that (a) have a non-null `readPoint` field; and where (b) the value of the `readPoint` field matches one of the specified values, or is a direct or indirect descendant of one of the specified values. If this parameter and `EQ_readPoint` and `readPoint` are omitted, events are returned regardless of the value of the `readPoint` field or whether the `readPoint` field exists at all.
Console Name: Business Location SOAP Name: `EQ_bizLocation` Value Type: List of String | Analogous to the `EQ_readPoint` parameter, but for the `bizLocation` field.
Console Name: Business Location SOAP Name: `WD_bizLocation` Value Type: List of String | Analogous to the `WD_readPoint` parameter, but for the `bizLocation` field.
Console Name: Business Transaction SOAP Name: `EQ_bizTransaction_type` Value Type: List of String | This is not a single parameter, but a family of parameters. If a parameter of this form is specified, the result will only include events that (a) include a `bizTransactionList`; (b) where the business transaction list includes an entry whose type subfield is equal to type extracted from the name of this parameter; and (c) where the `bizTransaction` subfield of that entry is equal to one of the values specified in this parameter.
Console Name: EPC Matches One of the Patterns SOAP Name: `MATCH_epc` Value Type: List of String | The result will only include events that (a) have an `epc` field (that is, `ObjectEvents` or extension event type that extend `ObjectEvent`); and where (b) the `epc` field matches one of the EPC patterns specified in this parameter. Each element of the parameter list is a pure identity pattern. If this parameter is omitted, events are included regardless of their `epc` field of whether the `epc` field exists.
Console Name: Parent ID Matches One of the Patterns SOAP Name: `Match_parentID` Value Type: List of String Required: No | Analogous to `MATCH_epc`, but applies to the `parentID` field of `AggregationEvent` and the `parentID` field of `TransactionEvent.`
Console Name: Child EPC matches one of the Patterns SOAP Name: `MATCH_childEPC` Value Type: List of String | Analogous to `MATCH_epc`, but applies to the `childEPCs` field of an `AggregationEvent`. An event is a candidate for inclusion if any of the elements of its `childEPCs` match any of the patterns specified in this parameter.
Console Name: EPC Class Matches One of the Patterns SOAP Name: `MATCH_epcClass` Value Type: List of String | Analogous to `MATCH_epc`, but applies to the `epcClass` field of a `QuantityEvent.`
Console Name: Quantity SOAP Name: `EQ_Quantity` Value Type: Int | The result will only include events that (a) have a `quantity` field (that is, a `QuantityEvent`); and where (b) the `quantity` field is equal to the specified parameter.
Console Name: Quantity SOAP Name: `GT_Quantity` Value Type: Int | Analogous to `EQ_quantity`, but includes events whose `quantity` field is greater than the specified parameter
Console Name: Quantity SOAP Name: `GE_Quantity` Value Type: Int | Analogous to `EQ_quantity`, but includes events whose `quantity` field is greater than or equal to the specified parameter.
Console Name: Quantity SOAP Name: `LT_Quantity` Value Type: Int | Analogous to `EQ_quantity`, but includes events whose `quantity` field is less than the specified parameter.
Console Name: Quantity SOAP Name: `LE_Quantity` Value Type: Int | Analogous to `EQ_quantity`, but includes events whose `quantity` field is less than or equal to the specified parameter
Console Name: (SOAP only) SOAP Name: `EQ_``fieldname` Value Type: List of String | This is not a single parameter, but a family of parameters. If a parameter of this form is specified, the result will only include events that (a) have a field named `fieldname` whose type is either String or a master data type; and where (b) the value of that field matches one of the values specified in this parameter. A `fieldname` is the fully qualified name of an extension field. The name of an extension field is an XML QName; that is, a pair consisting of an XML namespace URI and a name. The name of the corresponding query parameter is constructed by concatenating the following: the string `EQ_`, the namespace URI for the extension field, a pound sign (#), and the name of the extension field.
Console Name: (SOAP only) SOAP Name: `EQ_``fieldname` Value Type: Int, Float, Time | Analogous to `EQ_``fieldname`, but may be applied to a field of type Int, Float, or Time. The result will include events that (a) have a field named `fieldname`; and where (b) the type of the field matches the type of this parameter (Int, Float, or Time); and where (c) the value of the field is equal to the specified value.
Console Name: (SOAP only) SOAP Name: `GT_``fieldname` Value Type: Int, Float, Time | Analogous to `EQ_``fieldname`, but may be applied to a field of type Int, Float, or Time. The result will include events that (a) have a field named `fieldname`; and where (b) the type of the field matches the type of this parameter (Int, Float, or Time); and where (c) the value of the field is greater than the specified value.
Console Name: (SOAP only) SOAP Name: `GE_``fieldname` Value Type: Int, Float, Time | Analogous to `GT_``fieldname`.
Console Name: (SOAP only) SOAP Name: `LT_``fieldname` Value Type: Int, Float, Time | Analogous to `GT_``fieldname`.
Console Name: (SOAP only) SOAP Name: `LE_``fieldname` Value Type: Int, Float, Time | Analogous to `GT_``fieldname`.
Console Name: (SOAP only) SOAP Name: `EXISTS_``fieldname` Value Type: Void | Analogous to `EQ_``fieldname`, but may be applied to a field of any type (including complex types). The result will include events that have a non-empty field named `fieldname`. Note that the value for this query parameter is ignored.
Console Name: (SOAP only) SOAP Name: HASATTR_`fieldname` Value Type: | This is not a single parameter, but a family of parameters. If a parameter of this form is specified, the result will only include events that (a) have a field named `fieldname` whose type is a master data type; and (b) where the value of that field is a master data entry for which master data is available; and (c) the master data has a non-null attribute whose name matches one of the values specified in this parameter. A `fieldname` is the fully qualified name of a field. For a standard field, this is simply the field name; for example, `bizLocation`. For an extension field. The name of an extension field is an XML QName; that is, a pair consisting of an XML namespace URI and a name. The name of the corresponding query parameter is constructed by concatenating the following: the string `HASATTR_`, the namespace URI for the extension field, a pound sign (#), and the name of the extension field.
Console Name: Field with Attribute SOAP Name: `EQATTR_``fieldname``_``attrname` Value Type: List of String | This is not a single parameter, but a family of parameters. If a parameter of this form is specified, the result will only include events that (a) have a field named `fieldname` whose type is a master data type; and (b) where the value of that field is a master data entry for which master data is available; and (c) the master data has a non-null attribute named `attrname`; and (d) where the value of that attribute matches one of the values specified in this parameter. A fieldname is constructed using the same rules as `HASATTR_``fieldname`.
Console Name: Order By SOAP Name: `orderBy` Value Type: String | Names a single field that will be used to order the results. The `orderDirection` field specifies whether the ordering is in ascending sequence or descending sequence. The value of this parameter MUST be one of: `eventTime`, `recordTime`, `quantity`, or the fully qualified name of an extension field whose type is Int, Float, Time, or String. A fully qualified `fieldname` is constructed as for the `EQ_fieldname` parameter. If omitted, defaults to `eventTime`.
Console Name: Order Direction SOAP Name: `orderDirection` Value Type: String | If specified and `orderBy` is also specified, specifies whether the results are ordered in ascending or descending sequence according to the key specified by `orderBy`. The value of this parameter MUST be one of `ASC` (for ascending order) or `DESC` (for descending order). If omitted, defaults to `DESC`.
Console Name: Event Count Limit SOAP Name: `eventCountLimit` Value Type: Int | Results will only include the first N events that match the other criteria, where N is the value of this parameter. The ordering specified by the `orderBy` and `orderDirection` parameters determine the meaning of "first" for this purpose. If omitted, all events matching the specified criteria will be included in the results. This parameter differs from `maxEventCount` in that this parameter limits the amount of data returned, whereas `maxEventCount` causes an exception to be thrown if the limit is exceeded.
Console Name: Max Event Count SOAP Name: `maxEventCount` Value Type: Int | At most this many events will be included in the query result. If the query would otherwise return more than this number of events, a `QueryTooLargeException` is raised instead of a normal query result. If this parameter is omitted, any number of events may be included in the query result. Note, however, that the EPCIS implementation is free to raise a `QueryTooLargeException` regardless of the setting of this parameter. The value for `MaxEventCount` is configurable via an `<env-entry>` element in: `BEA_HOME/user_projects/applications/``your-domain``/epcis-lib.ear/epcis-ejb.jar/META-INF/ejb-jar.xml` The element is: `<env-entry> <env-entry-name>` `maxEPCISEventRecords` `</env-entry-name> <env-entry-type> java.lang.String </env-entry-type> <env-entry-value>``1000``</env-entry-value> </env-entry>`

## Data Security

A user who has one of the roles that provides the ability to create subscriptions (`Administrator`, `epcis_admin`, or `rfid_admin`) is allowed full access to all events in the Event Repository. For this reason, if you have security concerns about access to event data, BEA recommends that only trusted users be given the right to access the Query Subscription Administration Console or the SOAP service, and that query subscriptions are carefully crafted to expose only the desired data to business partners.