[CHANGE REQUEST] journal entries: add url for downloading documents and remove rentalStartMileage and other dublicated fields

[matt-wirtz]

API Version

1.5

Summary

Some integrations require the MP to be able to provide billing documents to the user. This can be implemented by providing an URL where the MP can download the billing document as PDF. Currently a link to such PDF can not be provided in the journal entry object.

The journal entries have data fields that seem to make no sense or are duplicated with the leg info.

• rentalStartMileage: the mileage at the start of the rental.
  • this is the absolute mileage of the vehicle? Seems only valid for cars since they have an odometer that could be read off.
  • this is not even part of the leg object
  • are there TOs who record this and expose this info
  • what is the purpose? Do users want to know after their ride what the odometer was at trip start?
• comment:
  • what would be expected here?
  • the leg object does not have a comment field
  • only the legEvent, notification and supportRequest objects have comments.
  • is this rather meant as a description of the journal entry, like a summary? And therefore has nothing to do with the other "comments" fields?
• distance & distanceType: the traveled distance. Only if applicable.
  • is already provided in the leg object (v1.5)
  • was this de-normalized to ease implementation?
• usedTime: the time in seconds that the asset is used. Only if applicable.
  • is already provided in the legProgress (v1.5) object / operationParameter (v2.0) object
  • was this de-normalized to ease implementation?

Expected Behavior

Current Behavior

Possible Solution

Add journal entry object to hold the URL that directs to a billing document.

Remove rentalStartMileage, comment, distance, distanceType and usedTime.

[edwinvandenbelt]

Hey Matthias! Maybe to clarify some things: the journal-entry is also used to underpin the payment: it contains data to reproduce the final price. This explains the last 2 issues. And, the journal-entries are also there for 'custom' payments as well, like fines etc. Therefore, we cannot do without the comments field, although renaming for v2.0 to 'description' would be appropriate.

Secondly, referring to a billing document removes the advantage of standardisation... It could be an addition, but in most cases, a single journal-entry is only a part of a complete bill. The rentalStartMileage, that's a good one. We've added it in v1.2.2, (#393) on user request (MP).

[matt-wirtz]

Hi Edwin! I understand the need to underpin each journal entry with enough information so that one can check if everything was correctly calculated.
But in my understanding if it's a trip related journal entry the booked trip (leg) is the most relevant information. And that is already linked with journalId. The leg object should hold all information necessary to check the calculated price.
Currently a distance and rental time information is provided in the journal entry directly. But what if the asset type is necessary to recompute the price. Or there are different time prices over the day and it's necessary to know at which time of the day the rental took place. So to really be able to check if the price is correct there is more needed as provided right now in the journal entry.

Regarding the URL linking to a billing document: I don't understand why that would prevent the TOMP specification to become a standard. Because I mentioned that the billing document could be provided as PDF? Is the PDF standard the culprit?
You are right, a bill might be comprised out of one or more journal-entries. That is already reflected by the invoiceId. Could be the same for the URL.

Regarding the rentalStartMileage. In the issue #393 there are no explanations given what this is needed for. Du you remember any conversation related to this? Thx,