Event Queries
TIX6 provides a flexible way of querying event data. As with all REST endpoints, there is a nodeId parameter that is required when using a user with access to more than one node.
All parameters passed to the REST endpoint must be URL-encoded, so for example date parameters like: '2009-07-25T19:30:00.000+00:00' must escape the '+' character as '%2B', so in the URL the parameter looks like: '2009-07-25T19:30:00.000%2B00:00'.
These queries are provided as SOAP endpoints as well.
GET /event/SimpleEventQuery
This is a rest implementation of the SimpleEventQuery as described in the EPCIS specification.
Parameter | Default | Description |
|---|---|---|
| ObjectEvent, AggregationEvent, TransactionEvent and/or QuantityEvent | |
| Greater than or equal to date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 | |
| Less than date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 | |
| Greater than or equal to date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. | |
| Less than date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 | |
| If specified, 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. The elements of the value of this parameter each must be one of the strings ADD, OBSERVE, or DELETE; if not, the implementation SHALL raise a QueryParameterException. If omitted, events are included regardless of their action field. | |
| If specified, 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 this parameter is omitted, events are returned regardless of the value of the bizStep field or whether the bizStep field exists at all. | |
| Like the EQ_bizStep parameter, but for the disposition field. | |
| 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. 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. | |
| 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. The meaning of “direct or indirect descendant” is specified by master data, as described in Section 6.5. (WD is an abbreviation for “with descendants.”) If this parameter and EQ_readPoint are both omitted, events are returned regardless of the value of the readPoint field or whether the readPoint field exists at all. | |
| Like the EQ_readPoint parameter, but for the bizLocation field. | |
| Like the WD_readPoint parameter, but for the bizLocation field. | |
| 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. | |
| If this parameter is specified, the result will only include events that (a) have an epcList or a childEPCs field (that is, ObjectEvent, AggregationEvent, TransactionEvent or extension event types that extend one of those three); and where (b) one of the EPCs listed in the epcList or childEPCs field (depending on event type) matches one of the EPC patterns or URIs specified in this parameter. Each element of the parameter list may be a pure identity pattern as specified in [TDS1.3], or any other URI. If the element is a pure identity pattern, it is matched against event field values using the procedure for matching identity patterns specified in [TDS1.3, Section 6]. If the element is any other URI, it is matched against event field values by testing string equality. If this parameter is omitted, events are included regardless of their epcList or childEPCs field or whether the epcList or childEPCs field exists. | |
| Like MATCH_epc, but applies to the parentID field of AggregationEvent, the parentID field of TransactionEvent, and extension event types that extend either AggregationEvent or TransactionEvent. Each element of the parameter list may be a pure identity pattern as specified in [TDS1.3], or any other URI. If the element is a pure identity pattern, it is matched against event field values using the procedure for matching identity patterns specified in [TDS1.3, Section 6]. If the element is any other URI, it is matched against event field values by testing string equality. | |
| If this parameter is specified, the result will only include events that (a) have an epcList field, a childEPCs field, or a parentID field (that is, ObjectEvent, AggregationEvent, TransactionEvent or extension event types that extend one of those three); and where (b) the parentID field or one of the EPCs listed in the epcList or childEPCs field (depending on event type) matches one of the EPC patterns or URIs specified in this parameter. Each element of the parameter list may be a pure identity pattern as specified in [TDS1.3], or any other URI. If the element is a pure identity pattern, it is matched against event field values using the procedure for matching identity patterns specified in [TDS1.3,Section 6] If the element is any other URI, it is matched against event field values by testing string equality. | |
| Like MATCH_epc, but applies to the epcClass field of QuantityEvents or extension event types that extend QuantityEvent. The definition of a “match” for the purposes of this query parameter is as follows. Let P be one of the patterns specified in the value for this parameter, and let C be the value of the epcClass field of a QuantityEvent being considered for inclusion in the result. Then the QuantityEvent is included if each component Pi of P matches the corresponding component Ci of C, where “matches” is as defined in [TDS1.3, Section 6]. | |
| If this parameter is specified, the result will only include events that (a) have a quantity field (that is, QuantityEvents or extension event type that extend QuantityEvent); and where (b) the quantity field is equal to the specified parameter. | |
| Like EQ_quantity, but includes events whose quantity field is greater than the specified parameter. | |
| Like EQ_quantity, but includes events whose quantity field is greater than or equal to the specified parameter. | |
| Like EQ_quantity, but includes events whose quantity field is less than the specified parameter. | |
| Like EQ_quantity, but includes events whose quantity field is less than or equal to the specified parameter. | |
| 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 vocabulary type; and where (b) the value of that field matches one of the values specified in this parameter. 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. | |
| EQ_fieldname as described above, 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. Fieldname is constructed as for EQ_fieldname. | |
| Like EQ_fieldname as described above, 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. Fieldname is constructed as for EQ_fieldname. | |
| Analogous to GT_fieldname. | |
| Analogous to GT_fieldname. | |
| Analogous to GT_fieldname. | |
| Like EQ_fieldname as described above, 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. Fieldname is constructed as for EQ_fieldname. Note that the value for this query parameter is ignored. | |
| 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 vocabulary type; and (b) where the value of that field is a vocabulary element 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. Fieldname is the fully qualified name of a field. For a standard field, this is simply the field name; e.g., 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. | |
| 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 vocabulary type; and (b) where the value of that field is a vocabulary element 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. Fieldname is constructed as for HASATTR_fieldname. The implementation MAY raise a QueryParameterException if fieldname or attrname includes an underscore character. | |
| eventTime | If specified, 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. Events included in the result that lack the specified field altogether may occur in any position within the result event list. The value of this parameter SHALL 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. In the case of a field of type String, the ordering SHOULD be in lexicographic order based on the Unicode encoding of the strings, or in some other collating sequence appropriate to the locale. If an event contains several equal fully qualified fieldnames with different values, then the result set will also contain several events. If omitted, it will default to order by eventTime. |
| DESC | 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 SHALL raise a QueryParameterException. If omitted, defaults to DESC. |
| If specified, the 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 and maxEventCount are mutually exclusive; if both are specified, a QueryParameterException SHALL be raised. This parameter may only be used when orderBy is specified; if orderBy is omitted and eventCountLimit is specified, a QueryParameterException SHALL be raised. 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. | |
maxEventCount | If specified, 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 SHALL be raised instead of a normal query result. This parameter and eventCountLimit are mutually exclusive; if both are specified, a QueryParameterException SHALL be raised. 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. |
EPCIS 1.1 update
New parameters supported by TIX 6.1.0, implementing the EPCIS 1.1 standard. Parameter marked with 
are parameter supported in EPCIS 1.0, that has been updated to support EPCIS 1.1.
Parameter | Default | Description |
|---|---|---|
| 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 EQ_source_urn:epcglobal:cbv:sdt:possessing_party=urn:epc:id:sgln:4012345.00001.0 | |
| 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 EQ_destination_urn:epcglobal:cbv:sdt:location=urn:epc:id:sgln:0614141.00777.0 | |
| If this parameter is specified, the result will only include events that: (a) have an If this parameter is omitted, events are included regardless of their MATCH_inputEPC=urn:epc:id:sgtin:4012345.011122.25 | |
| If this parameter is specified, the result will only include events that: (a) have an If this parameter is omitted, events are included regardless of their MATCH_outputEPC=urn:epc:id:sgtin:4000001.065432.99886655 | |
| If this parameter is specified, the result will only include events that: (a) have a The result will also include | |
| If this parameter is specified, the result will only include events that: (a) have an MATCH_inputEPCClass=urn:epc:epcclass:lgtin:4012345.011111.4444 | |
| If this parameter is specified, the result will only include events that: (a) have an MATCH_outputEPCClass=urn:epc:epcclass:lgtin:0614141.077777.987 | |
| If this parameter is specified, the result will only include events that: (a) have a | |
| Analogous to EQ_ILMD_http://ns.example.com/epcis#productionName=X02341 | |
| Analogous to GT_ILMD_http://ns.example.com/epcis#batchNumber=42LT_ILMD_http://ns.example.com/epcis#bestBeforeDateTime=2014-12-10T13:58:56.591-01:00 | |
EQ_transformationID | If this parameter is specified, the result will only include events that (a) Have a transformationID field (that is, TransformationEvents or extension event type that extend TransformationEvent); and where (b) The transformationID field is equal to one of the values specified in this parameter. example EQ_transformationID=urn:transformation:id:sample_a |
GET /event/ExtendedEventQuery
This interface includes all the parameters from SimpleEventQuery but provides some additional parameters.
Parameter | Description |
|---|---|
EXISTS_extension | Similar to the EXISTS_field attribute group, it selects the event that have a specified extension. Specify the namespace and extension name separated by an escaped hash %23. If several extensions are specified events containing any of the extensions will be included in the result. |
| Substring match of EPC. Search for events with the specified substring in an EPC. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| same as SUB_epc but will limit search to parent ids. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| same as SUB_epc but for parentIDs as well. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| substring search for readpoints. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| substring search for bizLocation. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| substring search for bizTransactionId. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| Similar to EQ_bizTransaction_type but with substring matching of the bizTransactionID parameter values. |
| substring search for disposition. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
| substring search for bizStep. An asterisk (*) will be interpreted as a wildcard and can be used to perform prefix (*foo) or suffix queries (*foo) or more complex queries (*foo*bar) |
groupBy | Works together with the aggregate parameter for aggregate queries. Only aggregate queries that result in events are allowed. Legal values are "action", "eventType", "epcClass", "disposition", "readPoint", "bizLocation", "bizStep". |
aggregate | Specifies a field to aggregate on. Currently only MAX and MIN is supported. Example: groupBy=epcClass aggregate=MAX_eventTime will return one event per class with the latest eventTime. Legal aggregation parameters are "eventTime", "recordTime" and "quantity". Note that if multiple events share the same aggregate value and groupBy, they will all appear in the result set. |
extrapolate | Takes any number of extension names, with or without namespace. These extensions will be extrapolated to all returned events, using earlier values associated with the EPC of the events, provided these are events that have been converted into ttData property values. For events referring to multiple EPCs, multiple values of the same extension might occur. In these cases each extension will be fitted with an EPC attribute so that it can be associated to the correct EPC. |
companyPrefix | Parameter for limiting event data on companyPrefix. This is a shorthand and companyPrefix=9999 should be equivalent to: MATCH_anyEPC=urn:gtnet:idpat:gsii:9999.*.* |
orderBy | Same as orderBy in SimpleEventQuery, extended to support order by |
| Specifies how many objects to include on each page. |
| Specifies which page to retrieve. If not specified it returns the first page. Counting from 1 to Integer.MAX_VALUE / pageSize |
ET_duration | Specifies the event time duration. This should be supplied with either GE_eventTime or LT_eventTime but not both. When used events within the supplied time period with respect to either GE_eventTime or LT_eventTime will be returned. When supplied with GE_eventTime then it will be used to resolve the Less than equal date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ. When supplied with LT_eventTime, it will be used to resolve the Greater than or equal to date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ. Supported format:
For example, "P3Y6M4DT12H30M5S" represents a duration of "three years, six months, four days, twelve hours, thirty minutes, and five seconds". P3W represents a period of 3 weeks PT3H2M1S represents a period of three hours, two minutes and one second P1Y represents a period of 1 year. PT2H represents a period of 2 hours. |
EPCIS 1.1 update
New parameters supported by TIX 6.1.0, implementing the EPCIS 1.1 standard, new parameters added to ExtendedEventQuery (not part of EPCIS 1.1)
Parameter | Default | Description |
|---|---|---|
| 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 sourceList; (b) where the source list includes an entry whose type subfield is equal to type extracted from the name of this parameter; and (c) where the source subfield of that entry is equal to one of the values specified in this parameter. example EQ_source_urn:epcglobal:cbv:sdt:possessing_party=4012345.0 | |
| 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 example EQ_destination_urn:epcglobal:cbv:sdt:location=00777.0 | |
SUB_extension | Similar to the SUB_field attribute group, it selects the event that have a specified extension. Specify the namespace and extension name separated by an escaped hash %23. If several extensions are specified events containing any of the extensions will be included in the result. Substring matching will be performed on the specified values. This means that if the parameter values do not include any wildcard character '*' they will be prefixed and suffixed with one. E.g. "test" will become "*test*". |
GET /event/CountEventQuery
Supports all the parameters of SimpleEventQuery and ExtendedEventQuery but only returns the number of events that match the query and would be returned if this was a call to ExtendedEventQuery.
Subscription queries
Subscriptions have all the same parameters as SimpleEventQuery, with some additional parameters for subscription control.
Subscribe
Create a new subscription.
Parameter | Description |
|---|---|
subscriptionId | An arbitrary string that is copied into every response delivered to the specified destination, and otherwise not interpreted by the EPCIS service. The client may use the subscriptionId to identify from which subscription a given result was generated, especially when several subscriptions are made to the same destination. |
queryName | e.g. SimpleEventQuery |
destination | Specifies a destination where results from the query are to be delivered, via the Query Callback Interface. The destination parameter is a URI that both identifies a specific binding of the Query Callback Interface to use and specifies addressing information. |
initialRecordTime | Specifies a time used to constrain what events are considered when processing the query when it is executed for the first time. If omitted, defaults to the time at which the subscription is created. |
reportIfEmpty | If true, a QueryResults instance is always sent to the subscriber when the query is executed. If false, a QueryResults instance is sent to the subscriber only when the results are non-empty. |
second | If present, determines the periodic schedule for query execution. The range for seconds is 0 through 59, inclusive. |
minute | If present, determines the periodic schedule for query execution. The range for minutes is 0 through 59, inclusive. |
hour | If present, determines the periodic schedule for query execution. The range for hours is 0 through 23, inclusive. |
dayOfWeek | If present, determines the periodic schedule for query execution. The range for is 1 through 7, inclusive, denoting Monday through Sunday. |
dayOfMonth | If present, determines the periodic schedule for query execution. The range for day of month is 1 through 31, inclusive. (Values of 29, 30, and 31 will only match during months that have at least that many days.) |
month | If present, determines the periodic schedule for query execution. The range for month is 1 through 12, inclusive. |
allPages | If true, the query result will be paged and each page sent to the destination (instead of throwing a QueryTooLargeException). If false or not present, the query will be run as a single query and if the result is too large then a QueryTooLargeException is thrown. Can only be used with ExtendedEventQuery. |
GET /event/subscription/getSubscriptionIds
Returns the SubscriptionIds of the registered subscriptions of the current user.
Parameter | Description |
|---|---|
queryName | One of SimpleEventQuery or SimpleMasterDataQuery |
GET /event/subscription/getQueryNames
Returns the legal queryNames for the subscriptions. Takes no parameters.
GET /event/ExtendedCountEventQuery
Works like the CountEventQuery but instead groups the results based on the supplied 'Group_By' criteria. The 'Group_By' criteria determines what will and what won't be included in the count. The parameters below are supported by the ExtendCountEventQuery.
Parameter | Description |
|---|---|
nodeId | This is compulsory and denotes the ID of the node whose events are to be counted. |
Group_by | This is compulsory, it denotes the criteria to use for grouping the results of the count. |
GE_eventTime | Greater than or equal to date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 |
LT_eventTime | Less than date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 |
GE_recordTime | Greater than or equal to date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 |
LT_recordTime | Less than or equal date in the format yyyy-MM-dd'T'HH:mm:ss.SSSZ, e.g. 2009-07-25T19:30:00.000+00:00 |