Collaborative logistics tool: call for help to develop API

Dear OFN community,

We want to share the web-app tool RutesCompartides (we have developed in Catalunya, for collaborative logistics) and to ask for your collaboration, as we would like to join efforts to develop an API to connect this tool to the OFN software.

We think it would be great to have these 2 tools working together, so it would be easier to order products through Katuma (in our case, it’s the name of the catalan instance for the OFN software) if it was linked to RutesCompartides (a transport solution), in an easy way for users (just one login).

Rutescompartides.cat is free software; you can find its code here: Komun / RutesCompartides.cat · GitLab

We would also like to develop “rutescompartides.cat/otherPlace” so it’s useful to use this tool in other places apart from Catalunya (so any help for this and translations, will be also very welcome!)

HOW DOES RUTES COMPARTIDES WORK:

If a producer is planning to deliver her products and there’s some spare space in her vehicle, she publishes the «route» (“publicar ruta”) and the date and time of departure. She will also specify the type of vehicle she’s using (if it’s refrigerated, isotherm, freezer or dry).

If another producer needs to send any products to a consumer, she can publish her «order» (“publicar comanda”), a specific date or a maximum date of arrival, and the type of vehicle that her products require (if any).

If the route (“ruta”) and the order (comanda) match in place (or distance, as both producers can specify the amount of Kms they agree to drive from the specific departure or arrival places), time and type of vehicle, both producers will be notified so they will get in contact with the other part, if they agree to do so, to confirm the details of the transport to share the route.

There are some other details (payment methods, communication…) that we are still going to improve in the next couple of months (and we can talk about them), but we would really love to see RutesCOmpartides working together to ease and promote the use of Katuma, so if you also think this tool can help this aim, let’s work together on it!

2 Likes

Hello @lirca and welcome here :slight_smile:

Thank you for your proposal. Just to be sure I’ve understood correctly: you propose to work on a specific integration for RutesCompartides, correct?

FYI OFN has work on a standard for tools dedicated to short food chains: Introduction - DFC standard documentation

Other collaborative logisitics tools have committed in FR and the UK to use the standard in their communication with external tools. That’s why OFN has currently on the roadmap to develop an API compatible with the standard. This work is moving slowly as currently the OFN team only has 2 core developers and they have many other things to do (we hare hiring, if you might be interested :slight_smile: ).

Do you think RutesCompartides would be interested in complying to the standard as well?

Otherwise I’m afraid OFN does not have the capacity to invest in specific integrations at the moment.

You could still go ahead and submit PRs on the ofn repo for this work. But this will require code review and testing from our team. Do you have budget to help fund that part? Same question for the future : if OFN code evolves and there are breaking changes to this integration, do you have budget to maintain it?

I’m pinging other team members to get their opinions too: @delivery

1 Like

Hi @Rachel ,

THank you so much for your quick reply!

Yes, we propose to work on a specific integration for RutesCompartides+OFN.

Regarding your question related to complying to the DFC standard: we checked the link (and some of the appendixes, etc.) to better understand the work you’ve done on this standarization (wow, amazing!) but we couldn’t find if there’s any specific standard/ontology for routes/transport (or any already implemented interface related to routes/transport). Could you please help us find this specific information so we can analyse its implications and think on a better response?

Related to the budget: we’re working in further developments to improve the app (how the routes are appearing on the map; communication; inner payment methods) and maintain it, with the budget we’ve got. We’d love there were some spare funds after finishing these improvements, so we could invest them in the API development, but we don’t think this will happen (Ivan, the dev who has worked on the app development so far, he has already put so much time out from the budget): we could look for this funding in the future, if necessary :wink:

we couldn’t find if there’s any specific standard/ontology for routes/transport

Other route/transport tools have shared they are happy so far with the current version, but that does not mean that there isn’t anything missing! Don’t hesitate to contribute the change you would like to see: the standard is open source and open for contributions!

Dear @Rachel and @delivery

We would like to join efforts to develop an API to connect rutescompartides.cat to the OFN software.

Sorry for repeating some info, but just to be sure we are talking about the same: RutesCompartides is a web-app that we (some producers from Catalunya who are using Katuma) together with Ivan (the dev who joined the project for its technical implementation) and through a grant that we received (from the Catalan Federation of Labour Cooperatives) developed as free software tool, and as free use for everyone (no one has to pay anything to use it), that can already be used by any producer to get in touch with other producers that are driving their products through the same routes.

We wanted to make logistics more efficient. So, instead of 2 producers driving almost the same transport routes for delivering our products, using our 2 different half-empty vehicles, wasting a lot of time-money-effort-CO2, the app helps us share our delivery routes (it’s like a free blablacar or a mobicoop, but for products transport).

We think it would be great to connect this transport app to the OFN software as we could have in one same tool the software to offer our products, to ease the purchase to consumers, to manage stocks, etc. [OFN software] together with the software for transport [rutescompartides, or whatever name it takes in other places where the tool could be used in the future].

If this API can’t be developed now, it’s ok: maybe we don’t have this time/person/money to do it now, but we will love to see this connection implemented in the future and to work together to achieve this goal.

If there are some standards to follow to get this API working in the best way for the OFN community and for further developments, we don’t have any problems: we agree to use them, of course (but we’ll need to find first if there’s any specific standard/ontology for routes/transport, or any implemented interface related to routes/transport, so we don’t work over something that has already been developed by others).

It would be great to know if the other “route/transport tools (that) have shared they are happy so far with the current version”, have already developed an API, so maybe they can help us on the API development for rutescompartides-katuma. It will be great also to wait until we can find a better moment to develop this API, if that moment isn’t now. We’ll be happy and we’ll continue working on improving the tool (social coin inner payment, to show regular routes on the map, etc.) until that moment arrives! =D

1 Like

Uh, that’s exciting. I’m wondering what we would be able to do with Zapier/N8N already. You first need to define which data you need. I would imagine that you need a list of orders with delivery destinations and product dimensions to evaluate how many trucks need to go where. Then we can work out how to get the data to your app. I’m not expecting any data to be sent from your app to OFN. Your app will probably show all the reports and maps needed for delivery.

How great that you find it exciting: thanks @maikel !

Imagine that all the producers that have regular routes (for example: every Monday morning, Producer1 goes from village A to village B to deliver her weekly vegetable boxes for consumer groups) had the routes she does every week already created on the app (on the OFN software, which would be linked to the rutescompartides software). This could be a great start to help other spontaneous orders to be transported through sharing the spare space that these regular routes vehicles may have.

Going on with the previous example: let’s imagine that a consumer group from the same village B would like to order a 25kg lentils bag (that is not a regular weekly order) from Producer2, who lives in a village that is in between village A and village B. This order, created in the OFN software, would create a “Comanda” directly through the Rutescompartides app, so the software would tell Producer1 that there’s a “comanda” from Producer2 that needs to be transported (as in this example), and it would tell Producer2 that there’s a “Ruta” (as in this example) from Producer1 that ‘s matching so if they’d agree, they could share the route. At this moment, Producer1 and Producer2 would get in touch to arrange the details (where exactly and at what time to meet, how to compensate for the time and oil that Producer1 will use, etc.).

If we had this link between the 2 softwares (OFN + rutescompartides) we could be saving so much time, effort, CO2 emissions…by sharing routes between so many producers that are already traveling each week (with spare space in our vehicles) and it could also help us meeting and networking with other producers that need to deliver their products to the same places that we’re already going to (instead of paying for this transport to logistics companies…)

Okay, so you say that you want the order to appear in the app and the route to appear in OFN. I’m wondering about the workflow for the user. For example, OFN could have a report which is downloaded as CSV and then imported into rutescompartides. There it could search for already existing routes.

We could also send out notifications when an order was placed (or at the end of the order cycle) so that the requests appear in the app automatically. I think that the matching of requests and offers should happen in rutescompartides.

Hi @maikel and sorry for the delay in my response (my account got blocked and I just recovered it but couldn’t post with the links related to the info, so I had to remove them… hope the message is understandable anyway!).

To continue with our coversation, I agree that it would be great if both softwares were linked and, at the end of the order cycle (or when an order is placed, for those orders that are to be delivered before the end of an order cycle), OFN would automatically check in Rutes Compartides (as if you were searching in the main home page that exists now in the app) if there’re any routes that are already existing that are matching in time and space (origin and destination).

IF THERE WERE some routes matching, the producer related to this new order would see a message asking if she wants to get redirected into the app RutesCompartides to check the existing matching routes (but before this step, she would be in the normal OFN software and all the communication between OFN-RutesCompartides would hapen automatically, without her noticing, through the API). If she agreed to check this existing route, she could see the details and she would be asked if she wants to send her products through this existing route so it would be also sent a message to the producer who was offering the existing route with spare space on her vehicel (OFN should create a new “comanda” automatically, taking the user-origin-destination-date details from the order placed in OFN, to send this “Comanda” to the producer, so she can decide if she agrees to take it or not). If she also agreed, they would get in touch to arrange the final details (time and exact place of meeting for delivering products to be transported, etc.).

IF THERE WEREN’T any existing routes matching with this new order of products requestes through OFN, the producer would be asked if she wants to create and “publicar ruta” (if she’s going to use her vehicle and offers some spare space for others) or if she prefers to create and “publicar comanda” (if she doesn’t want to drive her products but wants to send them by using the spare space on other producer’s vehicle). Once this happens, then she gets redirected into the app RutesCompartides, but before this step, she would be in the normal OFN software (and all the communication between OFN-RutesCompartides would happen automatically, without her noticing).

Do you think this (or any similar) automatic communication/interaction between OFN-RutesCOmpartides would be desiderable and possible?

It’s possible but I’m not sure about the user experience. This is new functionality to search for routes. And if we do it for one provider, we should be general enough to support others, too. It may be easier to use an OFN report which is imported into RutesCompartides or processed by another app to search for routes.

We provide all reports on the API and we are adding webhook notifications soon. You could write an app that listens to the webhook to know when the order cycle ends. It can then download a report with all orders including destinations and check that against the RutesCompartides API. I think that this will be much easier to maintain and quicker to develop then trying to integrate it into OFN. Our problem is that our code base is huge already and very change takes a long time.

Thanks for your answer, @maikel : great idea!! To download a report with all orders, when the order cycle ends, and check origin and destinations against RutesCompartides API.

In which OFN version are you implementing the webhook notifications? Just wondering if Katuma (local instance for the OFN software here) is on this same version, so we can/can’t work on it.

There’s current work in progress on webhooks when order cycles open: https://github.com/openfoodfoundation/openfoodnetwork/pull/9687

Having a webhook for closing order cycles should be easy but I’m not sure of the road map. @dcook, what’s the current plan with webhooks?

1 Like

This webhook is still in progress, but having discussed last night, It’s not the current priority.
But I hope to be able to pick it back up to finish off sometime in the next month.

1 Like

Dear @dcook and @maikel ,

We are having a meeting soon to discuss the priorities and further developments on the app RutesCompartides and its integration with other tools for last mile bike logistics. I was wondering if there was any progress on the webhook…? as for populated areas placing more orders (like Barcelona) it would be great to integrate managing orders (through Katuma), producers sharing transport from origin to some shared warehouse (through RutesCompartides), and last mile bike delivery (through coopcycle and/or others).

Yes, we have a pull request in review which sends a webhook when an order cycle opens. That should be merged within a week. You need a webhook when the order cycle closes though which would be another little piece of work which needs to be prioritised for your case. @dcook Is this part on the roadmap at all?

The alternative would be set up an N8N integration to notify you when an order cycle closes.

I’m not sure but I don’t think the order cycle closing webhook is on the roadmap yet, although it would make sense to do next. I will ask.

In the meantime, I don’t know if this is helpful but you could consider using the email notifications described here: Order Cycles (for Hubs) - OFN User Guide
It’s intended for notifying suppliers/producers when the order cycle is closed (can be automatic or manual triggered). But you might be able to hook it up via a middleware like N8N or Zapier to achieve what you want.

Hi @lirca

As @maikel and @dcook have mentioned, the job to create an ‘order cycle close’ webhook is likely quite straightforward once the ‘order cycle open’ one is done. However we have a lot of competing priorities in the pipe, including a number of funded features that people have paid to get done that we probably will need to prioritise first.

The product team is meeting next week to do a big review of all the core, desired and funded requests and work out what we are prioritising to get done in 2023. If you would like the ‘order cycle close’ webhook to get a strong showing in this discussion, any $$ contribution you could make would help

ping @Rachel @lin_d_hop