EVA facilitates serial number validation and management by means of several services, accompanied by regex validation to direct which serial numbers are permissible and events to keep track of their use. Once configured, they will be visible throughout the Checkout App, POS, and Admin Suite.
Use the following services to manage your serial numbers:
to list registrations and their outcome for a specific SerialNumber.GetSerialNumberConfigurations to display all available configurations
CreateSerialNumberConfiguration to create new ones
UpdateSerialNumberConfiguration to updates existing ones
With the following main properties:
Name - has to be unique unique
ValidationRegex (optional) - when set, all serial numbers entered for products with this configuration must comply with this regex or be rejected
VerificationRequired (default false) - when true will block the serial number flow until external verification is done
VerificationEndpoint (optional) - only considered when VerificationRequired is true, and when set, we'll pretend to be your middleware and push a serial number event (see Event exports) to this endpoint, and on a 200 OK EVA will verify the serial number for you. Note however the following:this is not our specialty, nor do we aim EVA to be: dedicated middleware is best
we will retry 5 times over a small period of time - after that, it’s on you
Verification and rejection reasons can be managed via the following services:
All are translatable through entity translations.
The event export Target SerialNumber has the following event Types:
All have the following data parameters:
SerialNumberRegistrationID - unique identifier for this registration
SerialNumber - the serial number
SerialNumberHandler - the case where this serial number applies (OrderLine / Repair / UserBoughtProduct)
SerialNumberHandlerID - the case identifier (the ID of the entity, e.g. with handler OrderLine this field is an order line ID)
ProductID - mostly added for convenience
Although there is a serial_number_changed event type on Order, the above events are recommended for use.
The verification flow allows for denial and reason specification. These are the following:
Status / StatusID - which can be either:Rejected(-1);
Reason / ReasonID - which is managed through the above mentioned SerialNumberRegistrationReason
You can see this in action in the following sample of the (optional) VerificationEndpoint in a JSON response body;
The tile for displaying serial number validation is set up in the Checkout options.
Flows in practice
There's two possible flows, in the first one we push our serial number data to your middleware. This is the regular way we handle event exports and the one we recommend. In the second flow you add a specific endpoint in the serial number configuration and we'll pretend to be your middleware - not recommended.
Start off by creating or updating a (Create)SerialNumberConfiguration, as described above, with VerificationRequired set to true.
Create a product (or alter one) that requires a serial number, via ImportProducts
or GenerateProductExcelSample / UploadProductExcel, by setting the RequireSerialNumberForSale property to true and specifying the serial number configuration ID in the SerialNumberConfigurationID property.
Every serial number that is created, either for an order line (sale/return), repair, case related item or user bought product, will trigger an event of target SerialNumbers with type verification_requested.
That's where EVA's contribution should halt and your middleware should take over.
Configure your event exports middleware to listen to the mentioned events.
The event contains a SerialNumberRegistrationID and additional data; you can use this for validation.
Have your middleware call VerifySerialNumber
with the SerialNumberRegistrationID to validate or deny the number.
Depending on the process attached to this serial number, an order can now be shipped; a repair can be picked up, etc.
The not-recommended “we’ll be your middleware” flow
Once again, start off by creating or updating a SerialNumberConfiguration with VerificationRequired set to true, but now also set use the VerificationEndpoint property.
For every serial number that is created, either for an order line (sale/return), repair, case related item or user bought product, we will push the same event data as above, but now to this configured VerificationEndpoint and await the result:
When it replies with a 200 OK, we will verify the order
If the (200 OK) response body can be parsed as a JSON ExternalVerificationResponse (see above), we will set these StatusID / Reason instead
Depending on the process attached to this serial number, an order can now be shipped, repair can be picked up, etc.