Introduction of VerificationRequest #218
Assignees
Labels
Comments
aloccid-iata
added a commit
that referenced
this issue
Mar 7, 2024
|
Text updated on the 26/03 to include more implementation details |
|
Remove FieldVerification as ErrorDetail already contains all the needed information |
|
Error handling basic sequence diagram added |
|
Approved by API working group on the 16/09/2024 |
|
This issue has been added into the documentation and will be sent for approval to the COTB |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Introduction
Presently, the ONE Record standard enables third parties to suggest modifications to specific properties within logistics objects (See Update a Logistics Object). However, there's a gap in the specification when it comes to identifying anomalies or errors within these objects without proposing entirely new values.
To address this issue, we suggest the introduction of a new subclass named VerificationRequest under the ActionRequest. This enhancement would allow any party noticing anomalies or issues within a Logistics Object to request verification without the necessity of proposing alternative values.
The VerificationRequest will inherit all attributes of the ActionRequest and introduce a new attribute named hasVerification.
In addition to the VerificationRequest, we introduce a new entity referred to as Verification, which contains details regarding anomalies detected within a particular Logistics Object.
The Verification Object will have three properties:
- hasError
- hasLogisticsObject
- hasRevision
- notifyRequestStatusChange
The hasLogisticsObject and the hasRevision allows the party to target a specific version of a logistics object while the hasError is an array of Error objects. As in all other Action Requests, notifyRequestStatusChange allows to receive notification on status change.
Each issue or anomaly on a specific logistics object will be incapsulated into a Error object which contains two attributes: HasTitle and HasErrorDetail. Should users need to convey a specific message, indicate a particular property, or transmit an error code, they can utilize the ErrorDetail object for this purpose.
Class Diagram
This class diagram includes the newly defined VerificationRequest with Verification and FieldVerification objects.
classDiagram direction LR class LogisticsObject{ } class Organization{ } class AccessDelegation{ + hasDescription: xsd:string [0..1] + hasPermission[]: Permission [1..*] + isRequestedFor[]: Organization [1..*] + notifyRequestStatusChange: xsd:boolean = FALSE + hasLogisticsObject[]: LogisticsObject [1..*] } AccessDelegation "1" --> "1..*" Permission AccessDelegation "1" --> "1..*" Organization: requestedFor AccessDelegation "1" --> "1..*" LogisticsObject class ActionRequest { <<Abstract>> + hasError[]: Error [*] + isRequestedAt: xsd:dateTime + isRequestedBy: Organization + isRevokedBy: Organization [0..1] + hasRequestStatus: RequestStatus = REQUEST_PENDING + isRevokedAt: xsd:dateTime [0..1] } ActionRequest <|-- AccessDelegationRequest ActionRequest <|-- ChangeRequest ActionRequest <|-- SubscriptionRequest ActionRequest <|-- VerificationRequest ActionRequest "1" --> "0..*" Error ActionRequest "1" --> "1..*" Organization : requestedBy ActionRequest --> RequestStatus ActionRequest "1" --> "1..*" Organization : revokedBy class AccessDelegationRequest{ + hasAccessDelegation: AccessDelegation } AccessDelegationRequest "1" --> "1" AccessDelegation class ChangeRequest{ + hasChange: Change } ChangeRequest "1" --> "1" Change class SubscriptionRequest{ + hasSubscription: Subscription } SubscriptionRequest "1" --> "1" Subscription class VerificationRequest{ + hasVerification: Verification } VerificationRequest"1" --> "1" Verification class Change{ + hasDescription: xsd:string [0..1] + hasOperation[]: Operation [1..*] + hasLogisticsObject: LogisticsObject + hasRevision: xsd:positiveInteger + notifyRequestStatusChange: xsd:boolean = FALSE } Change "1" --> "1" LogisticsObject Change "1" --> "1..*" Operation class Subscription{ + hasContentType[]: xsd:string [*] + hasDescription: xsd:string [0..1] + expiresAt: xsd:dateTime [0..1] + hasSubscriber: Organization + hasTopicType: TopicType + notifyRequestStatusChange: xsd:boolean = FALSE + sendLogisticsObjectBody: xsd:boolean = FALSE + includeSubscriptionEventType[]: SubscriptionEventType [1..*] + hasTopic: xsd:anyURI } Subscription "1" --> "1" Organization: hasSubscriber Subscription --> TopicType Subscription "1" --> "1..*" SubscriptionEventType class Verification{ + hasLogisticsObject: LogisticsObject + hasError[]: Error[1..*] + hasRevision: xsd:positiveInteger + notifyRequestStatusChange: xsd:boolean = FALSE } Verification "1" --> "1" LogisticsObject Verification "1" --> "1..*" Error class RequestStatus{ <<Enumeration>> REQUEST_PENDING REQUEST_ACCEPTED REQUEST_ACKNOWLEDGED REQUEST_REJECTED REQUEST_FAILED REQUEST_REVOKED } class SubscriptionEventType{ <<Enumeration>> LOGISTICS_OBJECT_CREATED LOGISTICS_OBJECT_UPDATED LOGISTICS_EVENT_RECEIVED } style VerificationRequest fill:#9D4141 style Verification fill:#9D4141State Diagram for VerificationRequest:
stateDiagram-v2 direction LR [*] --> REQUEST_PENDING REQUEST_PENDING --> REQUEST_ACKNOWLEDGED: acknowledged by holder REQUEST_PENDING --> REQUEST_REJECTED: rejected by holder REQUEST_PENDING --> REQUEST_REVOKED: revocation requested REQUEST_PENDING --> REQUEST_FAILED: revocation requested REQUEST_REVOKED --> [*] REQUEST_FAILED --> [*] REQUEST_REJECTED --> [*] REQUEST_ACKNOWLEDGED --> [*]Sequence Diagram
The following diagram illustrates a basic data exchange process between a forwarder and a carrier, including error handling using VerificationRequest. The forwarder creates a shipment logistics object and notifies the carrier. Upon receiving the shipment, the carrier identifies any discrepancies in the goods description and reports these issues back to the forwarder using VerificationRequest. The forwarder then acknowledges the VerificationRequest, rectifies the data, and notifies the carrier of the updates.
sequenceDiagram participant Forwarder participant Carrier Forwarder->>Forwarder: Create shipment LogisticsObject on its ONE Record server Forwarder->>Carrier: Notify the shipment creation using notification endpoint Carrier->>Carrier: Review the shipment object and identify issues in goods description Carrier->>Forwarder: Report incorrect data via VerificationRequest Forwarder->>Forwarder: Acknowledge VerificationRequest and rectify the shipment object Forwarder->>Carrier: Notify the update of the shipmentAPI Implementation
EndPoint
Request
The following HTTP header parameters MUST be present in the POST request:
The HTTP request body must contain a valid Verification object in the format as specified by the Content-Type in the header.
Response
A successful request MUST return a ``HTTP/1.1 201 Created` status code and the following HTTP headers parameters MUST be present in the response:
Otherwise, an
Errorobject withErrorDetailas response body MUST be returned with the following HTTP headers:The following HTTP status codes MUST be supported:
JSON Examples:
VerificationRequest Object
Verification Object
ChangeRequest update
In order to link a VerificationRequest with a ChangeRequest we would like to add a new optional parameter in the Change objected :
NOTE: This is an optional change that needs to be discussed.
Audit Trail update
All VerificationRequest objects should be saved into the audit trail together with the changeRequest objects. For this reason the hasChangeRequest in the audit trail should be renamed into hasActionRequest and it should contains both Verification and Change requests.
The text was updated successfully, but these errors were encountered: