louisaxel-ambroise/epcis

GS1 EPCIS repository written in .NET Core. Supports v1.2 and v2.0 of the specification.

FasTnT EPCIS repository

FasTnT EPCIS is a lightweight GS1 EPCIS 1.2 and 2.0 repository written in C# using .NET8 and backed with EntityFramework Core.

The repository fully supports the following databases:

• SqlServer (provider: SqlServer)
• PostGreSQL (provider: Postgres)
• Sqlite (provider: Sqlite)

Environments and Testing

There is a sandbox available if you want to quickly test this EPCIS repository capabilities.

A Postman team is also available that contains collections for both XML/SOAP and JSON endpoints. Alternatively, a SoapUI project can be found in the source code that contains queries for the v1.2 implementation.

Setup

1. Download the source code: $ git clone https://www.github.com/louisaxel-ambroise/epcis && cd epcis
2. Apply database migrations: $ dotnet ef database update --project src/FasTnT.Host --connection "Data Source=fastnt.db;" -- --FasTnT.Database.Provider "Sqlite"
3. Start the repository: $ dotnet run --project src\FasTnT.Host\FasTnT.Host.csproj --urls "http://localhost:5102/" --connectionStrings:FasTnT.Database "Data Source=fastnt.db;" --FasTnT.Database.Provider "Sqlite"

That's it! You have a properly working EPCIS repository using Sqlite as storage.

You can replace the Connection String and Database Provider with the values that suits better your needs (Sqlite, SqlServer or PostGreSQL).

You can also setup FasTnT EPCIS using the Docker image or in Azure very easily. Check the wiki for more details.

HTTP Endpoints

The API is secured using HTTP Basic auth by default. The users are not stored in the database, but a hash of the authorization value is stored alongside the request. By default the events and masterdata returned in a query are restricted to the ones captured with the same authorization header.

EPCIS 1.2 endpoints:

FasT&T provides a full implementation of the EPCIS 1.2 specification. The endpoints are:

• Capture: POST /v1_2/Capture
• Queries : POST /v1_2/Query.svc

Capture endpoint only supports requests with content-type: application/xml or content-type: text/xml header and XML payload.

Queries endpoint supports SOAP requests on endpoint /v1_2/Query.svc.

See the wiki for more details.

Implemented Features

This is the list of implemented 1.2 features in the repository:

• Capture
  • Events
  • Capture Master Data (CBV)
• Queries:
  • GetVendorVersion
  • GetStandardVersion
  • GetQueryNames
  • GetSubsciptionIDs
  • Poll
    • SimpleEventQuery
    • SimpleMasterDataQuery
• Query Callback:
  • CallbackResults
  • CallbackQueryTooLargeException
  • CallbackImplementationException
• Subscriptions:
  • Subscribe to an EPCIS request
  • Unsubscribe from EPCIS repository
  • Trigger subscriptions that register to specific trigger name
  • Execute subscription based on schedule

EPCIS 2.0 endpoints:

The repository also implements the EPCIS 2.0 specification. The endpoints are:

• Capture: POST /v2_0/Capture
• Query : GET /v2_0/events

Capture endpoint supports requests with both content-type: application/xml or content-type: application/json headers and payload.

Queries endpoint supports HTTP requests and supports both accept: application/json and accept: application/xml headers.

The subscriptions will always receive the results in JSON format.

The OpenApi definition of the EPCIS 2.0 endpoints is available at the URL /v2_0/openapi.json. See the wiki for more details.

Implemented Features

This is the list of implemented 2.0 features in the repository:

• Capture
  • Capture list of Events
  • Capture a single Event
  • Capture CBV masterdata
• Queries:
  • List events
  • Event pagination
  • Create/Delete a named query
  • Execute a named query
• Subscriptions:
  • Subscribe to an EPCIS request (webhook)
  • Subscribe to an EPCIS request (websocket)
• Discovery endpoints
  • EventType discovery endpoint
  • EPCs discovery endpoint
  • Business Steps discovery endpoint
  • Business Locations discovery endpoint
  • Read Points discovery endpoint
  • Dispositions discovery endpoint

Restrictions

• Only rollback value is accepted for GS1-Capture-Error-Behaviour header
• Only Never_Translates value is accepted for GS1-EPC-Format header
• Requests are captured synchronously in the repository

Authors

External contributions on this EPCIS repository are welcome from anyone. This project was created an is primarily maintained by Louis-Axel Ambroise.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details

Contact: [email protected]

epcis's Issues

XMLMasterdataParser for v2_0

Discussed in #252

^{Originally posted by jamiedeignan2 November 11, 2022}
Any thoughts about adding an XMLMasterDataParser for the v2_0 capture endpoint? From my testing it appears any cbv data included in a post to that endpoint is just quietly dropped right now.

QueryParameter.FieldName 'System.IndexOutOfRangeException'

Hello,

Really great work on this EPCIS 1.x - 2.0 project! We are looking into using this project as our EPCIS repository.

So far I have added our own security model (role based) and swagger to your code, and I am hosting on IIS. All quite straightforward.
The SOAP XML 1.2 interfaces seem to work quite well in PostMan (Query, Capture and Subscriptions tested).

However, when performing queries in the REST-JSON interface (EPCIS 2.0) I get 'System.IndexOutOfRangeException' on parameters like GE_errorDeclarationTime. Looking a the code for the FieldName extension of QueryParameter this seems logical:

public static string FieldName(this QueryParameter parameter) => parameter.Name.Split('_')[1].Split('#')[1];

'GE_errorDeclarationTime' contains no '#' so this has to fail ...

This seems to occur for any LT_ or GE_ query parameter.
The same parameters do work in SOAP-XML (which does not use the same methods, right?).

Is this a bug or am I missing something?

Cheers
Yves

SqlException on V1_2/Capture Endpoint (Capture Masterdata)

Environment

• Database Provider: SqlServer
• Runtime: .net8

Issue

When interacting with the V1_2/Capture endpoint there appears to be a SqlException getting triggered with the Masterdata XML example (from the Postman Sandbox). Upon dumping the contents of the SaveChangesAsync() call embedded in the StoreAsync(Request request, CancellationToken cancellationToken) : CaptureHandler.cs method, SQL Profiler showed us that it's attempting to insert this query.

INSERT INTO [Cbv].[MasterDataChildren] 
([ChildrenId], [MasterDataId], [MasterDataRequestId], [MasterDataType], [MasterdataId], [MasterdataType])
VALUES 
(@p104, @p105, @p106, @p107, @p108, @p109),
(@p110, @p111, @p112, @p113, @p114, @p115),
(@p116, @p117, @p118, @p119, @p120, @p121);

The insert manages to have values for the first three properties of the insert statement, but the latter two do not - instead defaulting to null. From looking around I was not able to find a relationship linking the MasterdataId and MasterdataType properties to the MasterDataChildren table. Those appear to only be properties referenced within the MasterDataAttribute table. I did notice that the MasterDataChildren has a link to MasterData which contains a list of MasterDataAttribute's, potentially creating a link between the two?

All that being said, I was hoping you could provide any insight on how the DbContext is suggesting those two properties - MasterdataId and MasterdataType - belong to the MasterDataChildren type within the insert statement.

Thanks!

Query error when using WD_readpoint

Hello,

been getting an error when a query parameter leads to a readpoint hierarchy query.

The code for this query is 'not translatable' to SQL.

Message=The LINQ expression 'DbSet()
.OrderByDescending(e => e.EventTime)
.Where(e => __Select_0
.Contains(e.Type))
.Where(e => __Select_1
.Contains(e.Action))
.Where(e => __param_Values_2
.Contains(e.BusinessStep))
.Where(e => __param_Values_3
.Contains(e.Disposition))
.Where(e => EF.Property<List>(e, "PersistentDispositions")
.AsQueryable()
.Any(o => (int)o.Type == (int)__type_4 && False || o.Id == __value_5))
.Where(e => EF.Property<List>(e, "PersistentDispositions")
.AsQueryable()
.Any(o0 => (int)o0.Type == (int)__type_6 && False || o0.Id == __value_7))
.Where(e => __param_Values_8
.Contains(e.ReadPoint))
.Where(e => ___context_9.ReadPointHierarchy(e.ReadPoint)
.Any(h => __param_Values_10
.Contains(h.Id)))' could not be translated. Additional information: Translation of method 'FasTnT.Application.Database.EpcisContext.ReadPointHierarchy' failed. If this method can be mapped to your custom function, see https://go.microsoft.com/fwlink/?linkid=2132413 for more information. Either rewrite the query in a form that can be translated, or switch to client evaluation explicitly by inserting a call to 'AsEnumerable', 'AsAsyncEnumerable', 'ToList', or 'ToListAsync'. See https://go.microsoft.com/fwlink/?linkid=2101038 for more information.

Thanks for any help.

Add Logs