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 Apps, and Admin Suite.

Work in progress

The serial numbers feature is a work in progress. While most of the back-end work is finished, front ends are currently not ready yet for any serial number requirements other than 0.

Services​

Use the following services to manage your serial numbers:

Our main service, CreateSerialNumberConfiguration, comes with the following properties:

  • Name - has to be unique
  • Description
  • Requirement - specify for what kind of flow a serial number will be required
    • -1 (None) - the default, which entails a serial number is never required
    • 0 (Sales) - for your day to day sales and returns
    • 1 (OwnershipChange) - sales (including SFS and C&C) and returns + shipments (Interbranch / incoming shipments / RTS)
    • 2 (StockMovements) - sales and returns + shipments (Interbranch / incoming shipments / RTS) + Cycle counts and Full stock counts, basically all stock mutations
  • ValidationRegex (optional) - when set, all serial numbers entered for products with this configuration must comply with this regex or be rejected

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.

The recommended flow comes down to EVA pushing the available serial number data to your middleware.

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.

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.