Is the /capture/{captureID} end point as defined really useful?

[domguinard]

Currently /capture/{captureID} returns the URIs of all created events for a capture job:

[
  [
    "/eventTypes/ObjectEvent/events/oa123",
    "/eventTypes/ObjectEvent/events/oa345"
  ]
]

We do not think this really makes sense. The feedback from our implementation team is that they expected this endpoint to return a status of the capture job as well as errors that occurred vs actual events created which we concur with.

One key point which is unclear to us (when reading 1.2) is what the expected behaviour on errors should be. If an event is not processed correctly should the server:

1. Continue processing other events
2. Roll back all the already processed events and return an error

If 2 then we would like to propose the following response:

{
 state: 'running' | 'done' | 'failed'
 error: {
  "type": "...",
  "title": "A server-side error occurred",
  ...
   }
}

if 1 then we would like to propose the following response:

{
 state: 'running' | 'done' | 'failed',
 errors: [ <errors> ],
 errorFile: URI
}

with one of errors or errorFile being mandatory.

[mgh128]

Hi Dom,

Thanks for raising this issue. These points will need to be clear in the draft spec if they're currently unclear. I'd assumed that if an error occurs, then the capture operation fails atomically and all events from that capture are rolled back, as if the capture had not been attempted. I don't know if everyone else in the group agrees with that approach.

My recollection about the behaviour returning a list of event URLs for that capture was that if the capturing application had not populated the eventID field, then the repository would calculate and set an eventID field for each event captured and return those in an ordered list (matching the sequence of events in the capture operation) back to the capturing application, as a receipt of successful capture and informing the capturing application of the eventIDs / eventURLs that had been set.

[domguinard]

Thanks Mark, this is what we feared the expected behavior was: roll back on any error. Roll backs are very complex operations as you definitely know, in particular in modern event streams based systems where a lot of things will happen on an event (and not simply a write to a DB). For us a better approach would be to log errors and proceed with the events that can be recorded. However hearing the opinion of the group on that would be valuable indeed. Nevertheless I would suggest modifying the response of the /capture/{captureID} endpoint to reflect the status of the capture job. This, for the use cases we have with our customers, is a lot more valuable information than returning a list of created events.

[RalphTro]

Dear Dom and Mark, Here is how it was designed some time ago in our traceability solution: capture operations are handled through a web service which captures ALL EPCIS events that are OK from a technical and content-related point of view. For those messages as part of a given capture request (e.g. one out of twenty EPCIS events) that could not be not captured (e.g. due to missing authorisation), the response message indicates which specific events the EPCIS capture application rejected, along with an appropriate error reason code. So, there is no roll-back in our case. This approach worked best for the customer's needs. Hope this helps in finding a solution to this subject.

[joelvogt]

Header: GS1-Capture-Behaviour: rollback | proceed. Default is rollback { running: true|false, success: true|false, errors: [ ], errorFile: URI }

[domguinard]

Should it be GS1-Capture-Error-Behaviour to depict that it is the behaviour. Also: are we using the US or British spelling in GS1 standards?

[mgh128]

GS1 uses British English spelling in its standards, so Behaviour - not Behavior . I agree that GS1-Capture-Error-Behaviour is better as a name for this header, because it's about behaviour when there is an error in the capture process.