Windward's Bring Your Own Data (BYOD) empowers you to seamlessly integrate your unique shipment-related data directly into our platform.

This powerful feature allows you to:

1. Complement existing data: Enhance our rich dataset with your own valuable information from sources like internal systems, sensors, and third-party providers.
2. Fill critical gaps: Achieve a complete and accurate view of your shipments by addressing any missing information.
3. Unlock deeper insights: Gain unprecedented visibility into your operations by analyzing your data alongside Windward's comprehensive intelligence.
4. Optimize workflows: Streamline processes and improve decision-making with enriched data and enhanced operational insights.

Foundational Principles

This section highlights critical points to keep in mind while uploading data:

Strict Validation Rules: Ensuring Data Accuracy

• All data is validated against DCSA standards, including UN/LOCODEs and standardized ENUMs, to ensure accuracy and consistency.
• If any record fails validation, the entire payload is rejected to avoid inconsistencies or partial ingestion that could disrupt workflows and insights.
• This approach ensures all ingested data is fully compliant and ready for accurate processing and calculations.

Unified Submission

• Each new payload replaces only previously uploaded BYOD data for a shipment, leaving data from other sources (e.g., carriers, Windward) unaffected.
• Each new payload replaces previously uploaded BYOD data, ensuring the most current and complete set of events is always available. This best practice helps maintain data consistency and prevents outdated or fragmented records.
• Customers are required to submit a full set of events for a shipment with each payload to maintain accuracy and consistency across the system.

Current Scope

• The feature currently supports only land events occurring after the discharge at Port of Discharge (POD) event, prioritizing workflows like detention and demurrage (DnD) calculations.
• This focused scope ensures clarity and simplifies the initial implementation while delivering immediate value for post-POD operations.
• Future updates will expand the scope to include pre-POD and maritime events, providing a full lifecycle view of shipments.
• By following these guidelines, you can ensure smooth data submission and processing.

Prerequisites

1. API Access: Ensure you have valid API credentials (API key or token). Contact your solution architect POC if credentials are missing.
2. Endpoint URL: GQL Endpoint: https://graphql.wnwd.com
3. GraphQL Client: Use a GraphQL client (like Postman, Insomnia, or Apollo) or integrate the API into your custom application.

---

Data Processing Flow

Required Data Fields

Here are the required fields for data ingestion:

Mutation Example

Below is an example GraphQL mutation for uploading event data:

mutation PushShipmentEvents($events: [PushShipmentEventsInput]) {
  pushShipmentEvents(events: $events) {
    trackedShipmentId
    eventType
    eventDatetimeLocal
    eventLocation
    shipmentLocationTypeCode
    facilityTypeCode
    transportModeCode
    eventClassifierCode
    emptyIndicatorCode
  }
}

Example Payloads

Valid Payload:

{
  "events": {
    "eventType": "EQUIPMENT",
    "eventClassifierCode": "ACT",
    "eventDatetimeLocal": "2024-12-01T10:00:00",
    "trackedShipmentId": "abc123",
    "eventLocation":  "SGSIN",
    "facilityTypeCode": "DEPO",
    "emptyIndicatorCode": "LADEN",
    "equipmentEventType": "DISC",
    "shipmentLocationTypeCode":"POD",
    "transportModeCode": 1
  }
}

Erroneous Payload (Missing Values):

{
  "events":  {

        "trackedShipmentId": null,
        "eventType": "EQUIPMENT",
        "equipmentEventType": "GTOT",
        "facilityTypeCode": "POTE",
        "transportModeCode": 1,
        "eventClassifierCode": "ACT",
        "eventDateTimeLocal": "2024-08-06T00:00:00",
        "eventLocation": "GBLGP"
    }

}

Error Response:

{
  "errors": [
    {
      "message": "Missing trackedShipmentId",
      "field": "trackedShipmentId"
    }
  ]
}

Validation Rules

1. Mandatory Fields:
   • Ensure all required fields (eventType, eventClassifierCode, eventDateTime, trackedShipmentId, etc.) are included.
2. Field Consistency:
   • Conditional fields like emptyIndicatorCode and equipmentEventType are required based on eventType.
3. UN/LOCODE Validation:
   • The eventLocation.unLocode must comply with UN/LOCODE standards.
4. Payload Rejection:
   • If any record in the payload is invalid, the entire payload will be rejected.

Response Format

When data is submitted via the BYOD API, a JSON response will indicate the submission status and provide a summary of processed records.

Response Fields

• status: Submission result ("success" or "failed").
• errors: List of issues for rejected records (optional).
• summary: Record breakdown:
  • totalRecords: Total records submitted.
  • validRecords: Successfully validated and ingested records.
  • erroneousRecords: Records that failed validation.

Successful Submission

{
  "status": "success",
  "summary": {
    "totalRecords": 100,
    "validRecords": 100,
    "erroneousRecords": 0
  }
}

Failed Submission

{
  "status": "failed",
  "summary": {
    "totalRecords": 100,
    "validRecords": 85,
    "erroneousRecords": 15
  },
  "errors": [
    {
      "recordId": "12345",
      "field": "eventDateTime",
      "error": "Invalid date format"
    }
  ]
}

📘

Support

For further assistance, contact your Solution Architect POC or refer to the API documentation at https://developer.windward.ai/

.