📦 🔄 Shipment Data Intake Workflow

[coderbyheart]

Why we need this feature

There is a lot of communication happening between Distribute Aid (DA) and Aid Groups (AG) to provide the necessary information for these three lifecycle events of a shipment

1. gauge whether an AG has the necessary means to put together a shipment and that this shipment is worth undertaking (DA needs to ensure that our funds for shipping aid are used to their best impact). This is the form currently used to collect the necessary data.
2. provide the necessary details about the contents of the shipment before it can be picked up
3. provide updates on the progress of the shipment while it is underway

Right now it is a big effort to keep everyone in the loop and make sure everyone has the right, and up to date, information. This is a big challenge because all communication happens in different WhatsApp groups.

Bets

We assume that this situation can be greatly improved by:

• providing a centralized location to collect and present shipment information
• allow AGs to subscribe to shipment updates and receive automated notifications as soon something changes

This will allow DA to point AGs to Toolbox as a single point of entry where they can always find the latest information about their shipments.

Doing so will remove the need for DA to monitor WhatsApp channels and respond to questions. Instead AGs can rely on finding the latest information about a specific shipment on Toolbox.

Experiment

As discussed in this recorded session here is what should go in the first experiment to validate the bet outlined above:

The main purpose is to have the Aid Group confirm that the shipment does not contain dangerous goods.

1. Distribute Aid can create new shipments for an Aid Group

Feature: Create shipment entry

    As a Distribute Aid administrator
    I can create a new shipment for an Aid Organization
    so all information can be collected in one place.

Rule: New shipments have the status "draft"

Scenario: Create new shipment

    Given an Aid Group "ACME" exists
    And I have selected the "ACME" Aid Group ID in "aidGroupId"
    When I set the GQL variable "aidGroupId" to "{aidGroupId}"
    And I set the GQL variable "name" to "Example Shipment"
    And I execute this GQL query
    """
    mutation createShipment($aidGroupId: ID!, $name: String!) {
        createShipment(aidGroupId: $aidGroupId, name: $name)
    }
    """
    Then the GQL query result should not contain errors
    And I store the GQL operation result as "shipmentId"

Scenario: Fetch created shipment

    When I set the GQL variable "shipmentId" to "{shipmentId}"
    And I execute this GQL query
    """
    query GetShipment($shipmentId: ID!) {
        shipments(
            filter: { id: $shipmentId }
        ) {
            edges {
                title
                status
                version
            }
        }
    }
    """
    Then the GQL query result should not contain errors
    And "shipments[0].edges.title" of the GQL query result should equal "Example Shipment"
    And "shipments[0].edges.status" of the GQL query result should equal "draft"
    And "shipments[0].edges.version" of the GQL query result should equal 1

UI mockup

2. Aid Group confirms that the shipment does not contain dangerous data

Feature: Provide necessary data

    As an Aid Group member
    I can provide the necessary data for a shipment
    so that Distribute Aid can decide whether they will ship it

Rule: Aid Groups must provide whether a shipment contains dangerous goods

Scenario: List shipments for my group

    When I execute this GQL query
    """
    query GetAllShipments {
        shipments {
            edges {
                id
                title
                status
                version
                dangerousGoods
            }
        }
    }
    """
    Then the GQL query result should not contain errors
    And "shipments[0].edges.title" of the GQL query result should equal "Example Shipment"
    And "shipments[0].edges.status" of the GQL query result should equal "draft"
    And "shipments[0].edges.dangerousGoods" of the GQL query result should be undefined
    And "shipments[0].edges.version" of the GQL query result should equal 1
    And I store "shipments[0].edges.id" of the GQL operation result as "shipmentId"

Scenario: Specify that the shipment does not contain dangerous goods

    This will also notifiy Distribute Aid

    When I set the GQL variable "shipmentId" to "{shipmentId}"
    And I set the GQL variable "shipmentVersion" to 1
    And I execute this GQL query
    """
    mutation Updateshipment($shipmentId: ID!, $shipmentVersion: Int!) {
        updateShipment(shipmentId: $shipmentId, shipmentVersion: $shipmentVersion, dangerousGoods: false)
    }
    """
    Then the GQL query result should not contain errors
    And Distribute Aid Administrators should receive this email notification
    """
    Subject: [#{shipmentId}] Update for the ACME shipment "Example Shipment"

    The shipment information was updated by ACME.

    - Contains dangerous goods: no
    - Status: Draft -> Review pending

    https://toolbox.distributeaid.org/shipment/{shipmentId}
    """

Scenario: Fetch updated shipment

    When I set the GQL variable "shipmentId" to "{shipmentId}"
    And I execute this GQL query
    """
    query GetShipment($shipmentId: ID!) {
        shipments(
            filter: { id: $shipmentId }
        ) {
            edges {
                status
                version
                dangerousGoods
            }
        }
    }
    """
    Then the GQL query result should not contain errors
    And "shipments[0].edges.status" of the GQL query result should equal "review_pending"
    And "shipments[0].edges.dangerousGoods" of the GQL query result should be true
    And "shipments[0].edges.version" of the GQL query result should equal 2

UI mockup

3. Distribute Aid accepts shipment

Feature: Distribute Aid accepts shipment

    As a Distribute Aid Administrator
    I can accept a shipment
    so that we can start the planning

Rule: Shipments must be accepted in order to be eligible for shipping

Scenario: Fetch shipment

    When I set the GQL variable "shipmentId" to "{shipmentId}"
    And I execute this GQL query
    """
    query GetShipment($shipmentId: ID!) {
        shipments(
            filter: { id: $shipmentId }
        ) {
            edges {
                status
                version
                dangerousGoods
            }
        }
    }
    """
    Then the GQL query result should not contain errors
    And "shipments[0].edges.status" of the GQL query result should equal "review_pending"
    And "shipments[0].edges.dangerousGoods" of the GQL query result should be true
    And "shipments[0].edges.version" of the GQL query result should equal 2

Scenario: Accept shipment

    This will also notify the Aid Group

    When I set the GQL variable "shipmentId" to "{shipmentId}"
    And I set the GQL variable "shipmentVersion" to 2
    And I execute this GQL query
    """
    mutation Updateshipment($shipmentId: ID!, $shipmentVersion: Int!) {
        updateShipment(shipmentId: $shipmentId, shipmentVersion: $shipmentVersion, status: "planning")
    }
    """
    Then the GQL query result should not contain errors
    And "ACME" Aid Group Members should receive this email notification
    """
    Subject: [#{shipmentId}] Update for the ACME shipment "Example Shipment"

    The shipment information was updated by Distribute Aid.

    - Status: Review pending -> Planning

    https://toolbox.distributeaid.org/shipment/{shipmentId}
    """

UI mockup

[pedro-gutierrez]

As far as the GraphQL API for shipments is concerned, we have types, queries and mutations already in place. Please have a look at this ticket: https://github.com/distributeaid/toolbox/issues/26. You can also play with the same api at https://toolbox-staging-distributeaid.cloud.okteto.net/api/graphiql:

[coderbyheart]

@pedro-gutierrez looking at the schema these are the changes needed to implement the proposed features:

Shipment

• add dangerousGoods: Boolean
• add aidGroup: Group! (to determine which Aid Group Members can edit the shipment)
• add status: ShipmentStatus! (make enum)
• add mutations for these values (must respect status, group membership, DA admin status)
• add history relation to fetch changes to this shipment

Group

• add members: [Member!]

I understand that we don't have a user concept right now in Toolbox and this needs to be solved first.

[pedro-gutierrez]

As far as dangerousGoods and the status field, those can be easily added. I'll plan a ticket for this for the upcoming sprint. However the aidGroup property is not 100% clear to me. A shipment is already implicitly linked to two different groups, the pickup group (via the shipment's pickup address) and the delivery group (via the shipment's delivery address). I think both the aidGroup and the members field in a Group are maybe part of the bigger discussion around authentication and authorisation, where we should define a general model for permissions and group memberships in the toolbox (some ideas drafted in #18).

[coderbyheart]

Maybe a better name would be shippingAidGroup instead of just aidGroup to leave other relations open. Only the shipping aid group should be allowed to provide whether a shipment contains dangerous goods or not. The receiving group should not be able to set this property.

[coderbyheart]

It turns out that #49 is not needed but is actually closely related to this issue: we need to implement the "DA Quote Request" form which is used today to collect the necessary information for a shipment.

[coderbyheart]

I am busy this week with moving, so my plan is to rework the process outlined above to include this form. I think it is valuable to implement this form fully, because the MVP already exists (it's the Google Form).

[coderbyheart]

I've started to create JSON schemas for the data collected in the forms: https://github.com/distributeaid/schemas/blob/saga/schemas/quote-request.schema.json

[coderbyheart]

It turns out that this intake form is not used after all anymore.