Skip to main content

Serial numbers

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.

Services​

Use the following services to manage your serial numbers:

With the following main properties:

  • Name - has to be unique unique
  • Description
  • 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:

  • GetSerialNumberRegistrationReasons
  • CreateSerialNumberRegistrationReason
  • UpdateSerialNumberRegistrationReason

All are translatable through entity translations.

Events​

The event export Target SerialNumber has the following event Types:

  • Used
  • Verification_requested
  • verified

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.

Verification​

The verification flow allows for denial and reason specification. These are the following:

  • Status / StatusID - which can be either:
    • Rejected(-1);
    • Pending (0);
    • Verified (1).
  • Reason / ReasonID - which is managed through the above mentioned SerialNumberRegistrationReason services

You can see this in action in the following sample of the (optional) VerificationEndpoint in a JSON response body;

{
  "StatusID": -1,
  "Reason": "SerialUnknown"
}

Checkout option​

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.

  1. Configure your event exports middleware to listen to the mentioned events.
  2. The event contains a SerialNumberRegistrationID and additional data; you can use this for validation.
  3. 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.

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.

Scripting​

You can use a script to finetune whether the serial number needs to be validated/verified or not based on the object in question (order line or repair for example).

For more information, please see SerialNumberValidation extension point.