Set up SAP PI Integration Builder using open-source Java and OpenWebStart

[dylan-drummond]

Some general remarks before starting

A. There are 3 How-To sections - for Ubuntu Desktop, for MacBook, and for Windows. You can scroll down to the relevant section according to your OS preference.

B. There is also - if you prefer - this SAP Note:

https://me.sap.com/notes/2677849

...which advises to use OpenWebStart with sapjvm 8... this advice is of limited use for me personally, since for my own preferred OS choices - modern MacBooks (M1, M2, ...) using arm64 architecture, and arm64 Linux Desktop distros - I haven't seen any arm64-based sapjvm 8 JDKs available for download.  

If you want to download a sapjvm 8, then here is one location (maintained by SAP):

https://tools.hana.ondemand.com/#cloud

In this blog we don't consider this sapjvm option.

C. For Windows, I have also tested successfully with a different variant of openJDK 8 - Eclipse Adoptium 8 - so feel free to try that instead of Azul JDK in the Windows case. For macOS and Linux, Eclipse Adoptium probably only working in x64-architecture cases (for MacBooks that means you need to have an old "Intel" MacBook)... anyway here is the link to Eclipse Adoptium openJDK 8: https://adoptium.net/en-GB/temurin/releases?version=8&os=any&arch=any

D. There is no Helpdesk for this blog, so if you get stuck trying to follow the advice, I am just wishing you good luck in using your own computing skills to get unstuck 🙂

Intro

In an SAP PI (Process Integration) system, it is possible to build new (or modify existing) custom integration content – don’t ask me for the details, I have never done any of this PI content-work and never will 😂. Anyway the tool that is offered for this work is called the SAP PI Integration Builder, so when we logon to a PI system we see it there as one of the main options on the landing page:

<http(s):>//<your.pi.hostname>:<portnumber>/dir/start/index.jsp

When you click the link available from hovering the mouse over the text “Integration Builder”... well, what happens nowadays, is that the browser downloads the .jnlp file, and... that is all:

Yes, it says in the browser that JavaWebStart is starting, but it isn't starting and it cannot even start, because such an app typically does not exist on your machine or on your VM, for the simple reason that you don't typically have a working JDK 8 on your machine. (Also, launching Java programs from a browser is nowadays not considered to be a good practice,  from the security angle).

Anyway, if we look at the contents of the directory.jnlp file, we find some relevant info:

<?xml version="1.0" encoding="UTF-8"?><jnlp spec="1.0+" codebase="<http(s):>//<your.pi.hostname>:<portnumber>/dir/">

[Tells us where the jars are going to be downloaded from, is a reasonable guess].

<application-desc main-class="com.sap.aii.ibdir.gui.appl.ApplicationImpl">
<argument>webstart</argument>
</application-desc>

[Tells us the main class – in Java world, the “start-point” – for getting the whole Integration Builder up and running].

So now our task is to work out how to use the open-source replacement for JavaWebStart, which is called OpenWebStart:

https://openwebstart.com/

...with a suitable open-source JVM (in/via JRE or JDK), so that people can use the PI Integration Builder. Note that this will need to be a JVM 8, as more recent major versions do not generally contain any javaws utility.

We start with Linux, because a Linux VM is a safe place to make mistakes. After that, we solve for macOS, because ahm a MacBook user maself. And then we solve for Windows, which I last used Java on, hmm, in 2015 maybe, but solved it for the PI case anyway (turned out to be easiest case of these three).

Demo on Xubuntu Desktop (Linux)

Although we say “Solution for Linux”, the OpenWebStart site offers only a .deb package for Ubuntu-based distros (may or may not work on other Debian-based desktops). Also, since this OpenWebStart is meant to be GUI-based, we can assume that Ubuntu-based Desktop distros, is the scope. Xubuntu Desktop is such a distro. (My assumption is that sudo-rights are needed, but did not test without sudo so that is just an assumption). If you are using some other distro, well, good luck - generally what works on Xubuntu, works on Ubuntu, that is all I can predict for this Integration Builder case.

Ubuntu: Get OpenWebStart

Download the .deb package from here:

https://openwebstart.com/download/

Open a Terminal and navigate to the directory you downloaded the .deb package to. Then install the app from the .deb package, for example:

sudo dpkg -i OpenWebStart_linux_1_11_0.deb

Ubuntu: Get OpenJDK 8

Next, we need an older version of OpenJDK for Linux (current version on ma' Xubuntu is 11, we need version 8):

sudo apt install openjdk-8-jdk

You can check which JDKs you have available using:

update-java-alternatives --list

If you like (though it’s irrelevant actually, as OpenWebStart decides via its own Settings config, not via reference to default JDK), you can set the machine to use some specific JDK, using sudo and the -s option:

sudo update-java-alternatives -s java-1.8.0-openjdk-arm64

Next step is related to, let’s not call it a bug, to a feature of OpenJDK, that many Java GUI apps will fail to open if they don’t find a file called javafx.properties in the JRE/JDK that is running the app – examples include “OpenWebStart Settings”-app, as well as “SAPGUI for Java for Linux”-app. But don’t worry, this is fixable just by creating an (empty) file called javafx.properties in the appropriate location: in our case where we have two JDKs, then the relevant directories are these or similar to these:

/usr/lib/jvm/java-11-openjdk-arm64/lib

/usr/lib/jvm/java-8-openjdk-arm64/jre/lib 

So to solve this, create the relevant (empty) file in those directories:

sudo touch /usr/lib/jvm/java-11-openjdk-arm64/lib/javafx.properties

sudo touch /usr/lib/jvm/java-8-openjdk-arm64/jre/lib/javafx.properties

Ubuntu: Link OpenJDK 8 to OpenWebStart

Now we can open the GUI app “OpenWebStart Settings”, and go to the JVM Manager tab, and then Add Local... navigate to the relevant JDK, Open. You can remove any other JVMs (typically OpenWebStart has already downloaded its preferred JVM called Eclipse Adoptium, but at least on my arm64 VM this x64 JVM is not going to work (tested), and anyway we are using the OpenJDK 8 that we installed above). Then press Apply to save the changes, and if you like press OK to close the Settings app.

I also recommend going into the JVM Manager -> Settings and changing to option “Do Not Download any version” [of Adoptium JVM], since we are instead using the openJDK 8 from the Ubuntu repos.

Ubuntu: Run Integration Builder

Now we can go to the PI system and click on the link to download the .jnlp:

<http(s):>//<your.pi.hostname>:<portnumber>/dir/start/index.jsp

Ignore the false messaging about non-existent JavaWebStart starting. Instead we go to the folder that contains the downloaded directory.jnlp file, then right-click and choose “Open With” and choose “OpenWebStart” (or, you can go to “Set Default Application...” and then set OpenWebStart as the default, and then you can open with double-click): 

If OpenWebStart offers to download an update of its preferred JVM, I suggest clicking No, as it will then prevent Integration Builder from being run if used. If you get asked to trust the content from publisher SAP, then confirm that this software can be run. And then you logon to the SAP PI system using your SAP user ID and password. 

And then... BANZAI!! ... the Java app called SAP Integration Builder opens and runs ok:

Demo on MacBook M1 Pro

We assume that in 2025 everyone is using an arm64 MacBook (“M-series”). At demo time I had an M1 MacBook at work, since then upgraded to M4 and tested that the instructions work just as well on the newer machine.

[Also I have assumed that the MacBook user has sudo (admin) rights... if you are a developer, it’s generally needed – but good luck if someone wants to try without admin rights; and good luck if you have an old Intel MacBook – in that case, you would want to use x64 packages and apps, not aarch64/arm64 ones].

macOS: Get OpenWebStart

Download the .dmg installer from here:

https://openwebstart.com/download/

So aarch64 means arm64 means our M1 MacBook, so we choose the relevant dmg. Open it and click on the button lower-middle of screen to start the installer:

Because I have sudo rights on the MacBook, even if I choose “Install for current user” the App contents are installed in /Applications i.e. system-wide, I assume it’s the same location if installing for all users of the MacBook, but not tested. Anyway the result of installing successfully for me is: 

We can open “OpenWebStart Settings” and it runs ok, but let’s close it again (by pressing OK in bottom menu) as we still need to do the next step, which is to install OpenJDK 8...

macOS: Get OpenJDK 8 for aarch64/arm64

Usually for MacBook, when we want some specific OpenJDK version, we would go to:

https://adoptium.net/en-GB/temurin/archive/

... and choose Version “8 – LTS” (Long-Term Stable). But the problem here is that for M-series MacBooks, which were launched in 2020, this was after Java 8 had already been sidelined by a more recent major version – so it seems there isn’t any Eclipse Adoptium OpenJDK 8 for macOS on aarch64/arm64 architecture...

Another common method for installing Java on macOS is to use Homebrew, though actually this won’t help us either. (If you don’t already have Homebrew, instructions on installing it are here: https://brew.sh/  ). So this approach doesn’t work for OpenJDK 8:

brew install openjdk@8

[...] openjdk@8: The x86_64 architecture is required for this software.

Error: openjdk@8: An unsatisfied requirement failed this build.

Also checked whether SapMachine (SAP’s version of OpenJDK: https://sap.github.io/SapMachine/ ) has a SapMachine 8 available for macOS – nope, not available. And even downloaded from SAP tools the x64 sapjvm_8 JDK, and tested that it doesn’t work either for the PI Integration Builder case.

So the solution which actually works... is to use a certified, free to use OpenJDK 8 for arm64 macOS from Azul systems.

https://www.azul.com/downloads/?package=jdk#zulu

Scroll down to the filters and enter the relevant data, which corresponds to this URL:

https://www.azul.com/downloads/?version=java-8-lts&os=macos&architecture=arm-64-bit&package=jdk#zulu

Actually let’s download the .zip archive, might be easier to use. Done. Then unzip if needed, and move the whole set of folders and files to somewhere logical, for example I put the stuff in /Users/dylan.drummond/java-generic/ directory (you would obviously use a different directory).

macOS: Link OpenJDK 8 to OpenWebStart

Now we can open the “OpenWebStart Settings”-app again. In the tab JVM Manager, delete any “non-OpenJDK 8” or non-arm64 JVMs. Then Add Local... for example I specified:

/Users/dylan.drummond/java-generic/zulu8.84.0.15-ca-jdk8.0.442-macosx_aarch64/zulu8.jdk/Contents/Home

For some reason 2 JREs added from path...Contents/Home:

We can leave them both there. I also recommend going into the JVM Manager -> Settings and changing to option Do Not Download [Adoptium JVM], since we won’t be able to run Integration Builder with any version of that JVM (since there isn't an arm64 JDK 8 version).

Next step is to test if this works...

macOS: Run Integration Builder

Go to the PI system and click on the Integration Builder link to download the .jnlp:

<http(s):>//<your.pi.hostname>:<portnumber>/dir/start/index.jsp

Ignore the false message about Java Web Start starting. Instead in Finder we right-click on the downloaded directory.jnlp file, ignore the default suggestion (JavaLauncher) and choose Open With... Other... add “OpenWebStart javaws”:

(You can also check the box “Always Open With” to set “OpenWebStart javaws” as the default app to open .jnlp files – that is what I did later as it saves from having to use “Open With” every time). Then we open the file... however, it might not actually open yet, for example I get the error message:

We have no reason to suspect that a file supplied from an SAP system, used to run an SAP product, would have any malware, so here is the procedure to override this warning... Click on the Question-mark icon highlighted in magenta in the above screenshot. Then click on the link “Open an app by overriding security settings”. From the next screen, click on the link “Open Privacy & Security Settings for me”. Scroll down to Security section and click on the button “Open Anyway” next to the reference to the jnlp file:

Then you go back to the popup that said about the error, and click Done. Then open the directory.jnlp file again, this time you get a different popup, and this time you have the option “Open Anyway”:

You might get asked if you want to download latest version of (Adoptium) JVM (if you didn’t turn off that behaviour in Settings app), I clicked No as that JVM favoured by OpenWebStart is not what we want to use - recommend you do the same.

Finally we get one more popup, we click Open:

Now the Java program starts, but before we can get to the main screen of the SAP Integration Builder, still a couple of steps... the first is to accept the SAP SE certificate from the popup – keep “Always trust content from this publisher” checked, and click Run:

Then logon to the PI system using your SAP User ID and password:

...so we logon, and... BANZAI!!

Demo on Windows 11 (works also on Windows 10)

This demo was done on a Windows 11 VM, where I have admin rights to the local machine. This also worked ok on a Windows 10 machine for a user with no local admin rights (i.e. a standard user).

Win11: Get OpenWebStart

[Demo VM is actually running arm64 Windows Insider build, but this should be able to run all the x64 stuff via JIT emulation, so we only consider x64 packages].

Download the x64 .exe installer from here:

https://openwebstart.com/download/

I installed OpenWebStart using the default options, including “For current user only”.

Win11: Get OpenJDK 8

Seems that there is no Microsoft Build of OpenJDK 8 (in January 2025 I found only versions going back to OpenJDK 11), but no problem, we can get a useful and certified OpenJDK 8 from Azul:

https://www.azul.com/downloads/?package=jdk#zulu

Enter the relevant parameters:

https://www.azul.com/downloads/?version=java-8-lts&os=windows&architecture=x86-64-bit&package=jdk#zu...

Download the .zip version from the Download button options. Unzip it and then copy the set of folders and files to some useful location, for example I put the stuff in C:\Users\marmot\Documents\ folder. 

Win11: Link OpenJDK 8 to OpenWebStart

Open OpenWebStart Settings app, from wherever you installed it or using the Search box: 

In the app, go to JVM Manager section. From there, go to Settings button and set Update Strategy to “Do not download any version”, as we don’t want the JVM that OpenWebStart prefers to use, in fact it prevents us from running SAP Integration Builder, so just change the Settings like ah suggested.

Then in JVM Manager section, use “Add local..” button and point it to the OpenJDK folder, in the demo example the path is: C:\Users\marmot\Documents\zulu8.84.0.15-ca-jdk8.0.442-win_x64 ...2 items are added, we can keep them both, then press Apply to save those changes:

Win11: Run Integration Builder

Go to the PI system and click on the Integration Builder link to download the .jnlp:

<http(s):>//<your.pi.hostname>:<portnumber>/dir/start/index.jsp

Ignore the false message about Java Web Start starting. If you get a warning for directory.jnlp about “Insecure download blocked”, recall that this file is coming from your organisation's SAP system, so you should trust it, so you press “Keep” to complete the download.

Then open the directory.jnlp file – when installing OpenWebStart, you should have already chosen in that installation workflow to associate .jnlp files to OpenWebStart, but if not, then you can use “Open With” and choose that  “Launcher for .jnlp applications according to JSR 56”, which should be the OpenWebStart app unless you have other such JavaWebStart replacement apps installed.

There might be a few seconds delay after opening before you get a popup showing progress of the downloads that directory.jnlp invokes, and then you get the security popup, ah suggest keeping checked the option “Always trust content from this publisher” as it is SAP SE, and you probably don’t want to have this popup every time – anyway then press Run:

Depending on your computer’s security settings, you might get asked if you want to allow access to the Zulu (Azul) OpenJDK “app” from public and private networks:

I chose Allow, since after all the data and content handled by the local Integration Builder is mainly located on the SAP PI server which is usually on a network and not on your own local machine. Anyway after logging in with SAP user ID and password, the Integration Builder is now opened: 

Q.E.D.