Skip to content

Finessensual

A. Synopsis

Finessensual is a python script that allows the conversion of Oracle financial transaction reports into an overview that is useful for research groups (around one or more PIs). Its name is contraction (or you might call it a contraption) of ‘finance’, ‘essential’ and ‘UA’.

B. Package

The script and its auxiliaries have been packaged as a self-extracting executable.

Download Finessensual-2025-3.exe

C. Background

The information available from our finance department is complete, but it is a mess. With the latter I mean that you cannot get a good overview of the situation of a research group, unless you perform manual bookkeeping behind the scenes. Unfortunately, I see that this is the case in almost all faculties and all research groups: either the deacony provides this support, either the PI (or her/his secretary) does it by hand. A lot of person power is burnt in the process. I decided I would not allow myself in that alley. Therefore, I wrote finessensual.

The least I want to claim: the finessensual package solves my problem (at least partly).

Why only partly? The remaining pitfall is that you still have to (manually) download all the excel files from the oracle server, give them proper names and only then you can run the script. The first step (though I am very familiar with it) still takes me half an hour. The latter step takes 10 seconds.

Since I started using the script, my sleep quality improved significantly. I hope it does the same for you.

D. Installation

1. Install the prerequisites

a. GNU/Linux, UNIX or MAC

Install the following software:

  • libreoffice
    • on ubuntu: 
      $ sudo apt-get install libreoffice
``````
      - on arch:
```shell
$ sudo pacman -Syu libreoffice-fresh jre-openjdk'
``````
      - on MAC: you're on your own - don't blame me - you decided to buy a MAC.

  - a python 3 interpreter
      - on ubuntu:
```shell
$ sudo apt-get install python3
``````
      - on arch:
```shell
$ sudo pacman -Syu python-pip python-pipenv
``````
      - on MAC: you're on your own - don't blame me - you decided to buy a MAC.

  Make sure the libreoffice executable and the python3 executable can
  be found based on your PATH environment variable.

#### b. MS-Windows
Install the following software:

  - libreoffice

    Go to the [LibreOffice website](https://libreoffice.org), download the latest version and install it.
    (don't install libreoffice from the microsoft store, or those
    b@s!@rds will charge you for it!)

  - a python interpreter

    Go to [Python website download section](https://www.python.org/downloads) and Download the latest 
    Python package (using the orange button.
    Double click on the python (.exe) installer (in your Downloads folder) 
    and then:

      1. check the box ‘Add python.exe to PATH’
      2. choose “Install Now”

### 2. Install the package itself

The finessensual code can be found on [PyPI](https://pypi.org/project/finessensual).

#### a. GNU/Linux, UNIX or MAC
  If you have a python interpreter installed on a GNU/Linux, BSD-like
  or UNIX-like workstation that is all you need. You can install the
  package from the command line as follows:

```shell
$ pip install –upgrade finessensual

        If your pip complains about not wanting to break the system packages, either setup a virtual environment 
  and activate it:
```shell
$ mkdir my-finessensual-folder
$ cd my-finessensual-folder
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install –upgrade finessensual
``````
  or break the system packages by passing the `--break-system-packages` flag to pip.
  In case you chose the former solution, remember to activate your virtual environment every time before starting finessensial, using:
```shell
$ cd my-finessensual-folder
$ source venv/bin/activate
      ``` If you are on MAC, once again: you're on your own - don't blame me - you decided to buy a MAC.

b. MS-Windows

On this platform, unfortunately, users have unlearnt how to install software and how to use the command line). Therefore, I spent one of my weekends making you a finessensual installer executable that will perform the installation and make a desktop icon for you.

It is called Finessensual-2025-3.exe.

Download it. Double click on the installer executable in your Downloads folder.

E. Usage

Start your oracle java application to consult “Financiële gebruikersrapporten” (below this will be abbreviated as FG) from . If we say ‘download’ below, we mean save in one and the same folder.

1. Download the files from Oracle

  • Download the information on Vlottende Budgetten:

    FG > Werk voor derde en derdengeld > Forfaitaire project, BOF, IOF en activiteiten > Vlottende Budgetten

    Download all ‘vlottende budgetten’ (like: AK, AO, RA, WD, WO) in excel format and name them ‘VBTransacties-’ + nummer + ‘.xls’. As an example: ‘VBTransacties-AK160007.xls’

  • Download ‘Budgets and transactions’ related to the PIs that are part of the financial overview in excel format

    FG > Werk voor derden en derdengeld > Verantwoordingsprojecten > Budgetten en transacties

    • Select the PI you want to cover.

    • Select ‘excel’ as format. This will leave only three buttons active in the rightmost row:

      • Budgetten : download this file and name it UB-.xml
      • Vastleggingen : download this file and name it UV-.xml
      • Uitgaven : download this file and name it UU-.xml

    As an example: UB-DMW.xml, UV-DMW.xml, UU-DMW.xml

  • Download ‘Project transactions’ for FFI and FFP projects, per project (for all accounting years) in excel format

    FG > Tansactierapporten > Transacties meerdere jaren

    Download these as ‘Transacties-\.xls’ As an example: ‘Transacties-FFI230414.xls’

    Remember to set the date range to cover all applicable years! The OZ projects are not needed!

  • Download ‘Budgetboekingen’ for the FFP and FFI projects in excel format (has to be done in the year of the start, or you can select ‘over alle boekjaren heen’)

    FG > Tansactierapporten > Budgetboekingen

    Name these: ‘Budgetboekingen-\.xls

    As an example: ‘Budgetboekingen-FFI230414.xls’

  • Download ‘Transacties lonen’ per PI in excel. Select ‘alle boekjaren t.e.m. boekjaar’.

    FG > Tansactierapporten > Transacties lonen

    Name these: ‘Lonen-Transacties-\.xml’

    As an example: ‘Lonen-transacties-STJ.xml’

2. Complete the 'manual' input files yourself

  • Projects.xlsx : contains an overview of all projects
  • Persons.xlsx : contains an overview of all the employees you want to track
  • Planning.xlsx : contains an overview of the planning as you maintain it

If the first two do not exist in your folder with all oracle files, then the first invocation of finessensual will create empty versions of these files. Finessensual will also complain about missing data in those files. Complete them based on the hints you get.

The latter file is an excel file that you can create by copying the ‘Personnel’ tab blad from the overview that has been generated to a separate file and update that. Remove all the rows prior to the current date.

3. Run finessensual

This can be simply done, by dragging the folder that contains (a) all oracle-generated files and (b) your project, persons and planning files, onto the finessensual icon that the installation procedure has planted on your desktop.

You will see that the script starts running and informs you about its progress.

After the script completed, the result file ‘financial-overview.xlsx’ will be present in the original folder.

Open it, and enjoy!

F. License

Copyright (c) 2025-present Walter Daems walter.daems@uantwerpen.be

finessensual is distributed under the terms of the MIT-license.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.