Many Records Strategy (Array)

There use cases, when a client sends many records in a single request.

For example, when a client posts multiple purchase orders as JSON array:

j.PurchaseOrders.GRN.POST.REQ
[
    {
      "extRefId"        : "character",
      "purchaseOrderNo" : "number",
      "qtyReceived"     : "number"
    }
]

[
  { "externalRefId" : "ref01", "purchaseOrderNo" : "PO_01", "qtyReceived" : 2 },
  { "externalRefId" : "ref02", "purchaseOrderNo" : "PO_02", "qtyReceived" : 7 },
  { "externalRefId" : "ref03", "purchaseOrderNo" : "PO_03", "qtyReceived" : 1 }
]

In such case, you must expect that not all purchase orders will be processes properly, for example, when the client wants to update a purchase order which does not exist in the target system.

Imagine, PO_03 is invalid and cannot be processed - updated. How can we inform te client about that problem?

Implementation Pattern

The API Process

The API process represents the deployable component. It does not implement any logic, because we might want to run the logic in a Unit-Test as well.

The split and merge process

  1. One request document that contains an array of items it split into n documents.

  2. The createPurchaseOrder()logic is executed for n documents, and

    1. n Documents of type j.Errors.RES are returned

  3. n Documents are merged into on response document,

    1. using a script to count error and ok records.

The business logic for each purchase order

  1. The business logic for each document is wrapped into a try/catch handler.

    1. Exceptions - per document - are turned into an j.Errors.RES

    2. The [0]tag is used to signal that it is a single record in an array profile (j.Errors.RES)

Validation Pattern

It is good practice to check, before you execute a target system request, whether you have got appropriate data to perform this request. With other words, you will want to validate your data first, using the validation pattern which throws an exception in case of an error.

This is probably my favourite example to demo how exception handling works: the sub-validation-process validates and it recognizes that something's wrong. Easy as that, the process aborts execution to tell its parent: I got an exception and I could not do what you expected.

The sub-process is not interested in exception handling or so, neither does it know that it runs as part of an API request, neither does it know that the request contained many items etc. etc.

See also: Pre-Condition Check

Last updated