Provision external material API for NextGen

Recieve Material Supply Confirmation: Functional Overview

NextGen exposes an internal API endpoint designed to receive provisioning data from external systems (e.g., SAP) for materials associated with a Procurement Request (PR). This integration allows the external system to communicate the delivery confirmation of materials related to a specific reservation, updating both quantities and serial numbers seamlessly.

Payload Structure & Receiving Workflow

The external system (SAP) calls the integration layer using a specific JSON payload to communicate the delivery.

Example Payload:

JSON

{
  "externalSystemCode": "SAP",
  "reservationId": "8be4df61-93ca-11d2-aa0d-00e098032b8c",
  "materials": [
    {
      "quantity": 100.45,
      "sequenceNumber": "2357717"
    },
    {
      "serialNumber":  ["26EL001", "26EL002", "26EL003"],
      "sequenceNumber": "2357718"
    }
  ]
}

Key Mapping:

• reservationId: Maps to the PR Item UUID (reservationId = item.uuid).

• sequenceNumber: Maps to the PR Item's External Code (item.externalCode = material.sequenceNumber).

Processing Logic & Integration Workflow

When the payload is received, the integration layer triggers a set of private APIs to process the data logically.

1. Initial Validation (PR Header & Item Existence)

• The system searches for all PR items related to the provided reservationId.

  • Failure: If no items exist, the process errors out.

• Unique Header Check: The system verifies that all found items are linked to a single, unique PR header.

  • Failure: If the items are linked to more than one PR header, the process errors out.

2. Position (Material) Processing & Validation

The system iterates through each material listed in the payload request:

• It attempts to match the payload's sequenceNumber with an existing PR Item's externalCode.

  • Failure: If no match is found, the system flags an error for that line item.

• Serial-Managed Materials: If the payload contains an array of serialNumbers:

  • The system checks the inventory for each serial number to ensure uniqueness.

  • If the serial exists: The specific serial code is discarded/ignored, and the loop continues to the next serial.

  • If the serial is new: The system creates a new serialized material record and explicitly links it to the PR item.

  • The PR Item's deliveredQuantity is updated to equal the total number of successfully inserted serialized materials (which could be 0).

• Non-Serial-Managed Materials: If serialNumber is null/empty:

  • The PR Item's deliveredQuantity is updated directly to the quantity value provided in the payload.

3. Unreceived Materials Handling

• After processing the payload, the system iterates through all PR items tied to the reservationId that were not included in the external payload.

• For these items, the deliveredQuantity is explicitly set to 0.

Status Transitions (Post-Processing)

Once all line items are processed and updated via the batch patch API, the system automatically triggers a status recalculation for both the positions and the overall PR header.

Position Status Updates

Based on the deliveredQuantity, the PR Position status updates to:

• Not Delivered: If deliveredQuantity = 0.

• Partially Delivered: If 0 < deliveredQuantity < requestedQuantity.

• Fully Delivered: If deliveredQuantity $\ge$ requestedQuantity.

Header Status Update

The PR header status recalculation is triggered only after all line items have been successfully processed and updated.

Error Handling Rules

• Storage: Only the first error encountered per line item is stored in the log.

• Continuation: Processing continues for other line items even if one fails (e.g., if a serial number exists and is ignored, the valid serials are still processed, and the quantity is updated accordingly).