All great software programs, especially free and open source software, share one common feature: You can easily customize and extend the software as you wish. The LibreOffice productivity suite is no exception, thanks to its support for those "saved sequence[s] of commands or keystrokes that are stored for later use" [1], otherwise known as macros.

I like to think of macros as the LibreOffice equivalent of Unix scripts: Whether they are keyboard sequences or code written in a programming language, these simple programs may be created quickly, possibly with very little programming skill, to automate all sorts of tasks.

ScriptForge [2], a LibreOffice library for building scripts, along with the APSO extension needed to run ScriptForge, provides a great tool to learn how to automate LibreOffice because it solves a general, but very important, problem with the LibreOffice macro environment.

In this article, I will provide a brief background of LibreOffice macros, talk about using Python in LibreOffice, and then show you how to use ScriptForge to create portable macros to automate LibreOffice.

LibreOffice Macros

Regardless of the programming language used to write a macro, there are three types of LibreOffice macros: system-wide, user-specific, and document-specific.

A system-wide LibreOffice macro consists of code shipped and installed with LibreOffice. You will find system-wide macros in a system folder (usually /usr/lib/libreoffice/share/Scripts/ on Linux systems), which makes these macros accessible to everyone using that installation. When you select Tools | Macros | Run Macros in LibreOffice, the contents of that system folder show up in the LibreOffice Macros section as shown in Figure 1. As of mid-2022, a standard LibreOffice installation on Ubuntu includes a large number of system-wide macros in four different languages: BeanShell, Java, JavaScript, and Python.

Figure 1: LibreOffice comes with many ready-to-use macros, in several programming languages.

If you install additional macros, depending on their configuration, these macros may be placed in some other section of the /usr/lib/libreoffice hierarchy or even as user-specific macros. For example, the ScriptForge files end up inside several directories under /usr/lib/libreoffice/share/basic/.

In addition to system-wide macros, you can also create user-specific macros, which LibreOffice will display under My Macros (Figure 2). On Linux, the corresponding source files will be placed inside $HOME/.config/libreoffice/4/user/Scripts, which you should remember to add to your backups as soon as you start creating user-specfic macros!

Figure 2: User-specific macros and scripts will be saved in your LibreOffice configuration folder and available under My Macros.

System-wide and user-specific macros can be run on any document that a user opens with LibreOffice using their account on that specific computer.

If you want to make a macro available to any LibreOffice user (who has the right system libraries), you can embed the macro in the document. If a document-specific macro is available for a given document, it will appear in the menus shown in Figures 1 and 2 inside a separate folder named after that file, only when that document is open.

A final note on LibreOffice macros: By default, your LibreOffice installation may refuse to run all the macros you attempt to install (either ones you create or find inside a document). You can change this setting (but think twice before doing it) by going to Tools | Options | LibreOffice | Security, clicking on Macro Security, and then adjusting Security Levels and/or Trusted Sources to meet your requirements.

Macros vs. Scripts

In addition to macros, LibreOffice also uses the term "scripts" for third-party code run from inside LibreOffice to automate a task. You may wonder (as do I) what the real difference between the two categories is, but a single, clear, and simple answer seems hard to find. From personal experience, there seems to be little or no difference between the two concepts for all practical purposes, at least for end users and beginner programmers. The main difference seems to be that a "script" (as opposed to a "macro") might need an extra configuration step or package in order to run it.

Python in LibreOffice

Of the four languages that are "natively" supported by LibreOffice, I prefer to use Python because that is the language I use most frequently, even outside of LibreOffice. As far as LibreOffice automation with Python is concerned, it seems that the only way to easily embed Python code inside a document is to install an extension called Alternative Script Organizer for Python (APSO) [3]. From my understanding, APSO is necessary, at least on Ubuntu and (I assume) most other Linux distributions, because the glue code to run Python scripts is only available as a separate package. In general, with APSO you get an integrated Python interpreter and debugger, which are really useful if you want to do serious LibreOffice programming with Python, with or without ScriptForge.

Even if you just want to run some ScriptForge-based Python script you found online, you will need APSO (or equivalent extensions), at least to embed or extract scripts in the files you manage with LibreOffice (if their format allows it, of course). I will show how to actually use APSO for this purpose later in this article.

To install APSO, just visit the website, download the latest version, select Yes when asked if you would like to open that file with LibreOffice, and follow the instructions. Once APSO is installed, you will find an extra entry in the LibreOffice Macros submenu as shown in Figure 3: a macro organizer, whose default shortcut is Alt+Shift+F11, dedicated to Python scripts.

Figure 3: The APSO extension for LibreOffice adds another interface to execute Python code while running LibreOffice.