KDE PIM/KDE Itinerary

From KDE Community Wiki

KDE Itinerary

What is KDE Itinerary?

KDE Itinerary is a digital travel assistant with a priority on protecting your privacy. See its website for an overview of its features and a few screenshots.

Getting KDE Itinerary

Application

For release packages, see the download links on the website.

For experimental/continuous builds, see the Itinerary README file.

KMail plug-in

Part of kdepim-addons and usually included with any KMail installation already.

Nextcloud Mail integration

Part of Nextcloud Mail itself and included when installing that via the Nextcloud app store.

Browser Integration

Not released yet, see Kai's blog post.

Using KDE Itinerary

Getting data into KDE Itinerary

Importing files

Use Global drawer > Import... in the app to import data from a file directly. This works for the following file types:

  • Supported ticket PDFs.
  • Most Apple Wallet pkpass files.
  • Supported booking emails (in mbox/eml format).
  • .itinerary files exported by another Itinerary instance.
  • Screenshots containing supported ticket barcodes.
  • iCal files with supported event types.

Creating entries from URLs

Opening, pasting or dropping URLs to web sites referring to events, hotels or restaurants opens a pre-filled edit page to create a corresponding entry. This works for web sites containing schema.org semantic annotations, that refer to an ActivityPub event or recognized OSM elements.

Examples:

Importing from online booking systems

It's also possible to import directly from some online booking systems (via Import > Import from <vendor>), typically requiring the input of a name and booking reference, for the following vendors:

  • Deutsche Bahn
  • SCNF

Scanning Barcodes

Ticket barcodes containing at least basic information about the trip can also be imported by scanning the barcode (Import > Scan Barcode). This is supported for:

  • IATA airlines boarding passes
  • ERA-standardized European international railway tickets
  • Some proprietary railway tickets (e.g. MAV)

If you have alternative ways of importing, prefer those over scanning the barcode. Barcodes tend to only have a very minimal set of information due to the limited storage space, and as such often miss full names of the involved locations, or the exact travel times.

Additionally to importing tickets that way, it's also possible to add scanned barcodes to existing or manually added entries via editing those.

Importing from the system calendar

When using Akonadi on Linux as well as on Android, it's possible to import from the system calendar. The following content is supported:

  • Events representing train/bus trips, flights or hotel reservations with corresponding semantic annotations, as added e.g. by Itinerary, the Itinerary KMail plugin as well as some Apple products.
  • Events representing train/bus trips or flights added to the calendar via ics files provided by supported providers.
  • Any calendar entry representing an event.

KMail Itinerary plug-in

For content recognized by the plug-in, there's multiple options:

  • Add data directly to a locally installed Itinerary.
  • Send data via KDE Connect and open it in Itinerary there.
  • Add data to a (shared) calendar. Itinerary can then import from that calendar (see the above section).

Sharing data between multiple instances of Itinerary

Shared Calendar

Itinerary can export to and import from the system calendar. Using a shared calendar (e.g. Nextcloud Calendar + DavDroid on Android) thus gives multiple Itinerary instances access to the same data. There are limitations though:

  • Android's system calendar doesn't support custom properties or attachments. This means Itinerary cannot export all relevant information on Android. Importing works, but only when using DavDroid for syncing (due to support for its special way of persisting custom properties).

Getting involved

New to KDE? See also https://community.kde.org/Get_Involved

Communication

Source Code & Workboard

See https://phabricator.kde.org/project/manage/280/

Donating Sample Data

Samples can be sent to [email protected] and will not be published.

Anything vaguely looking like flight, train, bus, rental car, hotel, event or restaurant bookings/tickets/confirmations/cancellation/etc is relevant. Such documents are even still relevant when they are seemingly already extracted correctly, in many cases there are non-obvious details we don't cover yet correctly.

Preferably in their original unaltered form, for emails the easiest way is "Forward As Attachment".

Switching KDE Itinerary to Development Mode

A number of development or diagnostic features useful for improving KDE Itinerary are available in "Development Mode". To activate that tap the version number in About > Version seven times (same way as the development mode of Android devices is activated).

In development mode a number of additional actions are visible in the menus, the "Development" page accessible from the global menu allows you to disable this again.

Edit Map Styling

Improving the styling of the indoor station maps can be done by editing MapCSS files defining the visual appearance and content of the map, without the need of recompiling the application. For this place a (modified) copy of any of the built-in styles found [here] in the right location.

  • Linux: Place the files in $PREFIX/share/org.kde.kosmindoormap/assets/css or ~/.local/share/org.kde.kosmindoormap/assets/css. If you have a Git checkout of the KPublicTransport repo you can also symlink its src/map/assets folder to one of those places entirely. To revert your modifiations, simply remove the files from those locations again, the built-in styles will then be used again.
  • Flatpak: Copy your modified MapCSS files to ~/.var/app/org.kde.itinerary/data/org.kde.kosmindoormap/assets/css/, symlinks don't work with Flatpak as its isolation system will prevent access to outside data. For removing your modifications again, simply delete those files again.
  • Android: On Android this is a bit more complicated unfortunately, due to the app isolation mechanisms ther. Here you have to use the "Import MapCSS" action in the Development page from the global menu (see above for switching on "Development Mode"). "Reset MapCSS" in the same place allows you to revert your changes.

When Development Mode is enabled, the map page also offers context actions to try different style variants. Toggling between styles can also be useful to trigger a reload of a style on changes.

Troubleshooting

KDE Itinerary isn't importing data from a document

  • Check About > Version in the global menu, this shows the supported formats the app was built with. This should look as follows, in particular missing support for PDF or barcode decoding is a problem here.
Engine version      : 5.13.40
HTML support        : libxml2
PDF support         : poppler (0.83.0)
iCal support        : kcal
Barcode decoder     : zxing
Phone number decoder: libphonenumber
RSA support         : openssl
Extractor scripts   : 53

The KMail Itinerary plug-in isn't finding anything

  • Is the itinerary plug-in installed? Check $LIBDIR/plugins/messageviewer/bodypartformatter/messageviewer_bodypartformatter_semantic.so. If you are missing this, it's in the kdepim-addons repository, and can probably found similarly named distro packages.
  • Is KItinerary built with Poppler and ZXing? Check the output of `$LIBDIR/libexec/kf5/kitinerary-extractor --capabilities` (19.04 or newer). This should show something like this:
HTML support        : libxml2
PDF support         : poppler
iCal support        : kcal
Barcode decoder     : zxing
Phone number decoder: libphonenumber

KDE Itinerary isn't importing data from my calendar?

Importing data from the calendar is done via the global menu action "Check Calendar".

  • Do you have a supported setup? That is:
    • The app is running on Android (calendar access on Linux is currently not implemented)
    • The events were added to the calendar using the KMail plug-in, from 19.08 or newer.
    • Calendar syncing is done using DavDroid, using a version from after Feb 2019.
    • The CalDav server you use does retain custom properties on iCal events. Nextcloud is known to work.
  • Are the events you try to import in the future, but not further away than half a year? (that's a performance optimization on the import code, if that is getting into the way of too many people we can adjust this).
  • Check About > Version in the global menu, check if this shows "kcal" under "iCal support".

Technically, the calendar importing is relying on a custom iCal property "X-KDE-KITINERARY-RESERVATION" containing the JSON-LD representation of the booking. Additionally, the app currently assumes the UID prefix "KIT-" for faster searches.

How to report bugs?

Use https://bugs.kde.org, product "KDE Itinerary". If the bug involves sensitive documents that you don't want to publish there, you can send those directly to [email protected].

Terms

  • KDE Itinerary: the mobile app for showing your itinerary.
  • KItinerary: the library providing the data extraction engine (yes, sub-optimal naming considering the above).
  • KMail Itinerary Plug-in: plugin for KMail running the data extractor on the email you are currently looking at and showing a blue framed box at the top with what it found
  • KItinerary Workbench: diagnostic and development tool for the data extractors.
  • Poppler: PDF parsing library, needed by KItinerary in order to process PDF files.
  • ZXing-C++: Barcode decoding library, needed by KItinerary to decode any form of barcode.
Retrieved from "https://community.kde.org/index.php?title=KDE_PIM/KDE_Itinerary&oldid=101305"