Subscriptions

Subscriptions

Subscriptions are a way to perform predefined queries at regular interval, or when a trigger is manually registered by a user. Subscription can be created using the query interface. Examples can be found in the Postman and SoapUI collections.

Subscription Destination

The data matching the subscription query are delivered by HTTP(s) calls. It is possible to specify a HTTP Basic authentication to be used to call the destination endpoint.

Subscription delivery results are stored in the SQL table subscriptions.trigger for debug/audit, and a reason is included if the delivery failed.

Subscription Trigger

There are two ways for the subscriptions to be triggered and delivered to destination: scheduled or custom triggered.

Scheduled delivery

Scheduled subscription are created with specifying the schedule field in the subscription request sent to the EPCIS server.

FasTnT EPCIS repository will always try to serve the subscription delivery at the closest time possible from the subscription schedule. However, if there are many subscriptions on the same repository, delay might appear in the deliveries.

The delivery time is computed from the subscription "schedule" field, the implementation details can be found in the FasTnT.Domain.Services.Subscriptions.SubscriptionScheduleclass (GetNextOccurence method).

Example of a schedule field from a subscription request:

<controls>
   <schedule>
      <second>0</second>
      <minute>0</minute>
   </schedule>
   <reportIfEmpty>true</reportIfEmpty>
</controls>

This query will be executed once per hour at the top of the hour. See the section 8.2.5.3 of the EPCIS 1.2 specification for more example/details on the schedule controls.

Triggered delivery

The EPCIS 1.2 specification also contains another way to execute the subscription delivery, by specifying a "trigger" value.

If the trigger field is specified instead of the schedule one, then the subscription will only be delivered when the specified trigger is manually called. The endpoint to call a trigger is:

GET {BaseUrl}/v1_2/Subscription/Trigger/{triggerName}.

Subscription result

A subscription can send multiple responses, depending on the result of the internal query that is performed. The response can be a QueryResults if the query succeeded, or a QueryTooLargeException or ImplementationException results in case of failure.

Examples of the Query Result and exceptional results can be found in the Postman collection examples.

Implementation

The default implementation of the subscription is a BackgroundService running aside the API. With this implementation, multiple-instance deployment is not recommended as the same subscription can then be triggered and delivered multiple times.

For multiple-instance deployment, it is recommended to extract the subscription process in a separate application that will run independently from the API.