Add new property for AddOns #224
Assignees
Comments
|
This is really great! A couple of modelling notes:
So for example, something like this perhaps: "beta:addOn": [
{
"@type": "Product",
"@id": "https://padel4all.com/openactive/add-ons/de505ce7-351f-4f8f-90c4-29887947a603",
"name": "Adult Racket Hire",
"beta:availableQuantity": {
"@type": "QuantitiveValue",
"minValue": 0,
"maxValue": 4
},
"ageRange": {
"@type": "QuantitativeValue",
"minValue": 16
},
"offers": [
{
"@id": "https://padel4all.com/openactive/add-ons/de505ce7-351f-4f8f-90c4-29887947a603#/offers/1",
"@type": "Offer",
"price": 1.5,
"priceCurrency": "GBP"
}
]
}
] |
|
Great suggestions, all makes a lot of sense! I thought we should get this sorted out in preparation before tackling the slightly more complicated booking system. I also think we should specify what to do in the case of free addons, for example if Junior racket hire was free but adult was not. Would it be reasonable just to have the |
|
Great plan - and yes Might be worth thinking about booking at the same time in case it affects the model? If this was to be added to beta, would be good to ensure that it had that broader compatibility? |
|
I'm thinking for adding to the booking OrderItem in this format: |
|
So they're dependents of the OrderItem? If so I wonder if it might be worth thinking about the expected behaviour for e.g. cancellation and replacement - do the addOns get immediately cancelled along with their parent OrderItem? Perhaps there's a more generic structure that can be used here so that interaction with OrderItems can be homogeneous, so something roughly like this: |
|
I think it makes sense for them to be dependents of the OrderItem. For two main reasons, firstly if you're hiring equipment it makes sense for that to be at a specific time and duration. Secondly, if you're purchasing equipment it's important for the Venue to know when that particular item has to be in stock, and when you're expecting it. Consider the example of racket hire, if you're cancelling that opportunity it no longer makes sense to hire the rackets. |
|
After further discussion it's agreed that they should be flat, as in Nick's example above. This is so that we can still handle the OrderItem cancellation/modification flows such as for standard OrderItems. |
|
Also do we also need a In fact, looking at the modelling again, perhaps we should model this as a more generic C1, C2, B request {
"@type": "OrderItem",
"orderedItem": "https://example.com/api/openactive/add-on/4",
"acceptedOffer": "https://example.com/api/openactive/add-on/4#/offers/1",
"beta:parentOrderItem": {
"@type": "OrderItem",
"position": 1
},
"position": 4
},C1, C2 response: {
"@type": "OrderItem",
"orderedItem": {...},
"acceptedOffer": {...},
"beta:parentOrderItem": {
"@type": "OrderItem",
"position": 1
},
"position": 4
},P response: {
"@type": "OrderItem",
"orderedItem": {...},
"acceptedOffer": {...},
"beta:parentOrderItem": {
"@type": "OrderItem",
"@id": "https://example.com/api/openbooking/orders/63cc36f8-e755-4445-99b6-739ff03f3c77#/orderedItems/1994",
"position": 1
},
"position": 4
},At B response: {
"@type": "OrderItem",
"orderedItem": {...},
"acceptedOffer": {...},
"beta:parentOrderItem": {
"@type": "OrderItem",
"@id": "https://example.com/api/openbooking/orders/63cc36f8-e755-4445-99b6-739ff03f3c77#/orderedItems/1994"
}
}, |
|
Yes I think that's a sensible suggestion, and nicely abstracts it for future additions |
|
@nathansalter areas to address from our call just now:
Note when referencing items across Orders we'd probably need a different request and potentially more detail in the Orders feed to allow the Broker to dereference the Order (as the URI scheme of the OrderItem is known only to the booking system) e.g. as below: Request: {
"@type": "OrderItem",
"orderedItem": "https://example.com/api/openactive/add-on/4",
"acceptedOffer": "https://example.com/api/openactive/add-on/4#/offers/1",
"beta:parentOrderItem": {
"@type": "OrderItem",
"@id": "https://example.com/api/openbooking/orders/63cc36f8-e755-4445-99b6-739ff03f3c77#/orderedItems/1994"
},
"position": 4
},Response / Orders Feed contents {
"@type": "OrderItem",
"orderedItem": "https://example.com/api/openactive/add-on/4",
"acceptedOffer": "https://example.com/api/openactive/add-on/4#/offers/1",
"beta:parentOrderItem": {
"@type": "OrderItem",
"@id": "https://example.com/api/openbooking/orders/63cc36f8-e755-4445-99b6-739ff03f3c77#/orderedItems/1994"
"beta:order": {
"@type": "Order",
"@id": "https://example.com/api/openbooking/orders/63cc36f8-e755-4445-99b6-739ff03f3c77"
"identifier": "63cc36f8-e755-4445-99b6-739ff03f3c77"
}
},
"position": 4
}, |
|
I've also transferred this to Open Booking API, as the functionality around the modelling may be as important to reach consensus on as the modelling itself? It appears that the modelling exists here for the purposes of facilitating booking functionality rather than purely to publish open data? |
Add OnsAddOns in Availability feedsCollating this all into a single issue, we have stage 1 with adding this into the IndividualFacilityUse feeds Objects in the AddOns in Booking FlowAnd Stage 2 adding this into the booking APIs:
In the image above, it indicates how the structure of the order items is assumed to be. Although it's possible that you can have a deeper structure than a single AddOn, currently brokers SHOULD only use a single level of nesting to help implementation from the booking system side. The standard booking api can be updated to the following: C1 RequestC1 ResponseNote how the C2 RequestIn this request we have transparently removed the original third order item and replaced it with an identical replacement. This is to show how the booking system must take the given OrderItems and remove existing ones from its original booking model where they are replaced. This is indicated by any order item with a Requests at P and B will be identical when referring to AddOns. Appendices:R.Appendix ACancelling an AddOn. As described in Open Booking API 8.2, simply removing the AddOn from the next request will remove it from the Order: To cancel an AddOn after B, simply use the same request as defined in the booking spec However, if you try to cancel an OrderItem which has children, Brokers MUST cancel all Order Items: As opposed to: Which the Booking System MUST return this error: R.Appendix BAddOns MAY be modified before B using replacement as defined above. However after B, AddOns MUST NOT increase in quantity for that Order. If more AddOns are required, the Broker will need to create a new Order. AddOns however can reduce in quantity, as this can fit nicely with the cancellation flow: |
|
If helpful, some of my notes from the W3C call 27/04/2022 (there were other actions recorded too not captured here):
It might be useful to also - in future - consider deposits for rackets etc (e.g. via partial refunds) It would also be helpful to have a data dump from Playfinder for the shape of Add-ons |
|
Finally gone through this again, and revised with the comments from the discussions made. We're going to be continuing on with implementing this, so I'll update here with any issues we face during execution. Add OnsAddOns in Availability feedsFacility Use FeedsObjects in the You MAY also specify Brokers SHOULD offer these at checkout for the customer to optionally Session Series FeedsAddOns in Booking FlowAnd Stage 2 adding this into the booking APIs:
In the image above, it indicates how the structure of the order items is The standard booking api can be updated to the following: C1 RequestC1 ResponseC2 RequestIn this request we have transparently removed the original third order item and replaced it with an identical replacement. This is to show how the booking system must take the given OrderItems and remove existing ones from its original booking model where they are replaced. This is indicated by any order item with a Requests at P and B will be identical when referring to AddOns. Appendices:Appendix ACancelling an AddOn. As described in Open Booking API 8.2, simply removing the AddOn from the next request will remove it from the Order: To cancel an AddOn after B, simply use the same request as defined However, if you try to cancel an OrderItem which has children, Brokers As opposed to: To which the Booking System MUST return this error: Order Items cannot be created without a parent: To which the Booking System MUST return this error: Appendix BAddOns MAY be modified before B using replacement as defined above. Appendix COrder Items cannot be forced to create a recursive tree: To which the Booking System MUST return this error: Order Items cannot be created at multiple levels of inheritance. This is To which the Booking System MUST return this error: Appendix DIf the AddOn has a stock level which can run out, when running C1 or |
github-project-automation
bot
moved this from 👀 In review
to 🆕 ODI Questions / New
in OpenActive Infrastructure
nickevansuk
moved this from 🆕 ODI Questions / New
to 👀 In review
in OpenActive Infrastructure
14 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Proposer
Playfinder/Bookteq
Use Case
When pulling a list of FacilityUses, I want to be able to view what additional paid facilities this has. Examples include racket hire, floodlight hire, tennis balls and other sports equipment.
Why is this not covered by existing properties?
An
Offeris described as:This is currently too restrictive to allow other types of Offers to be purchased by the Customer.
Please provide a link to example data
The Bookteq widget on Padel4all (https://play.padel4all.com/dashboard/book user account required) has options for hiring equipment.
Proposal
The
FacilityUseandIndividualFacilityUsemodels should have an extrabeta:addOnsproperty which contains an array of Offer modelsExample
The text was updated successfully, but these errors were encountered: