Skip to content

Packaging

Work-In-Progress

The Allep installer is still in its early stage. We will gradually improve it for both developers and end users.

Allplan Extension Package (Allep) allows end users to easily install your PythonPart.

  • Quick set up

    You only need to prepare a configuration file with some basic meta data, pack it together with your PY and PYP files into a ZIP archive and change the extension from .zip it to .allep.

  • UI integration

    You can create your own task area within the Actionbar with multiple PythonParts, each with its own icon, organize them in fly-outs and more.

  • Install per drag-and-drop

    The user can install your plugin by simply dragging and dropping the .allep file into ALLPLAN.

  • Easy management

    To update the plugin, the user simply needs to drag-and-drop the .allep file again. Solution for plugin removal1 is planned in the near future.

Prepare Allep File

An Allep file is a zip container with 3 major components:

  1. The installation configuration file with basic data needed for the installation, including entries on the Actionbar.
  2. Folders containing the assets of your plugin.
  3. The optional requirements file with python dependency packages needed for your plugin to work.

Example

The example used in this article to showcase the structure and the content of an Allep file is the PythonPart SDK. It consist of several PythonParts dedicated fo developer and can be downloaded in the getting started section.

The example structure of an .allep file is shown below:

📦PythonPartSDK.allep  
├─📂pyp-actionbar           <!--(1)!-->
| ├─ 🖼️ EncryptPythonPartScript_24.png
| ├─ 🖼️ EncryptPythonPartScript_128.png
| └─ ...
├─📂pyp-library             <!--(2)!-->
| ├─ 🖼️ EncryptPythonPartScript.png
| ├─ 📄 EncryptPythonPartScript.pyp
| ├─ 📄 EncryptPythonPartScript_eng.xml
| └─ ...
├─📂pyp-scripts             <!--(3)!-->
| ├─ 📄 EncryptPythonPartScript.py
| └─ ...
├─🛠️ install-config.yml     <!--(4)!-->
└─📋 requirements.in        <!--(5)!-->

  1. You can provide this directory, if you want to integrate the plugin into the Actionbar. Here, you save all the icons of your tools that should be displayed on the Actionbar. Create two for each PythonPart: one 24px×24px and the other with 128px×128px.

    The name of this directory is customizable in the configuration file in the installation section under the key PythonPartsActionbar

  2. In this directory, you provide assets that should be saved in the Allplan Library, i.e.:

    The name of this directory is customizable in the configuration file in the installation section under the key Library

  3. In this directory, you provide the python scripts for all of your PythonParts.

    The name of this directory is customizable in the configuration file in the installation section under the key PythonPartsScripts

  4. This is the configuration file, the most important file!

    • The name is not customizable!
    • It must be located in the root directory!

  5. You can provide this file, when your plugin uses some site packages from the Python Package Index . Learn more below .

    The name is customizable, but it is a general convention to name it requirements.in

Info

Pay attention, when zipping your files! Make sure, that the install-config.yml file and all other assets are located in the root of your zip archive, and not inside a sub-directory!

Failure

📦MyPlugin.allep  
└─📂MyPlugin <!--(1)!-->
  ├─🛠️ install-config.yml
  ├─📋 requirements.in
  ├─📂pyp-actionbar
  | ├─ 🖼️ MyTool_24.png
  | └─ ...
  ├─📂pyp-library
  | ├─ 📄 MyTool.pyp
  | └─ ...
  └─📂pyp-scripts
    ├─ 📄 MyTool.py
    └─ ...
  1. Some ZIP-software makes a parent directory like this and puts all the content inside it. Avoid this!

Success

📦MyPlugin.allep  
├─🛠️ install-config.yml  <!--(1)!-->
├─📋 requirements.in
├─📂pyp-actionbar
| ├─ 🖼️ MyTool_24.png
| └─ ...
├─📂pyp-library
| ├─ 📄 MyTool.pyp
| └─ ...
└─📂pyp-scripts
  ├─ 📄 MyTool.py
  └─ ...
  1. install-config.yml and all other files and directories should be located directly in the .allep package. No parent directory above it!

Configuration File

The configuration file is a regular YAML file and contains four first-level keys:

Plugin

This section defines the basic meta data of the plugin.

plugin:
  name: PythonPart SDK      #(1)!
  UUID: a6767ff0-a1e7-4e5e-8c07-45722dae763b    #(2)!
  version: 0.2.0            #(3)!
  developer: ALLPLAN GmbH   #(4)!
  default-language: en      #(5)!
  min-allplan-version: 2025 #(6)!
  1. Name of the plugin.
  2. The 128-bits UUID of the plugin. You must generate one for your plug in using a generator of your choice.
  3. Version number of the plugin
  4. The name under which you, as a developer, want to be identified with.
  5. The two-letter identifier of the default plugin language: the language, that should be used, if the current language is not supported by the plugin. Refer to the documentation of the documentation of AllplanLocalisationService to see, what languages are supported
  6. Minimum ALLPLAN version, supported by the plugin

Tip

Make sure to provide all texts for your selected default language for all display texts on the Actionbar for your tools.

Work-In-Progress

In the current state, there is no validation check about default-language and min-allplan-version.

Installation

This section describes how to define what and where should be installed.

installation:
  target-location: USR                  #(1)!
  py-packages: requirements.in          #(2)!
  Library: pyp-library                  #(3)!
  PythonPartsScripts: pyp-scripts       #(4)!
  PythonPartsActionbar: pyp-actionbar   #(5)!

  1. Target location for the plugin installation.

  2. The name of the requirements file. This entry is optional. Learn more below .

  3. The name of the folder with the Library assets.

    Its content will be installed in
    <TargetLocation>\Library\AllepPlugins\<DeveloperName>\<PluginName>\

  4. The name of the folder with python scripts.

    Its content will be installed in
    <TargetLocation>\PythonPartsScripts\AllepPlugins\<DeveloperName>\<PluginName>\

  5. The name of the folder with the Actionbar assets. This entry is optional. You must provide it only if you want to integrate your plugin into the Actionbar. Learn more below .

    The content of this folder will be installed in
    <TargetLocation>\PythonPartsActionbar\AllepPlugins\<DeveloperName>\<PluginName>\

Choose the target-location[^2] depending on who should have access to the plugin once installed:

  • USR will install the plugin for the current user only
  • STD will install the plugin in the directory with office resources and it will be available for every member of the workgroup

Info

The installer can install files only in the following subdirectories of the target-location:

  • \Library
  • \PythonPartsScripts
  • \PythonPartsActionbar

Tools

This section provides the data, that is required for plugin tools to be visible in the Actionbar configuration.

tools:                        #(1)!
  - id: start-python-debug    #(2)!
    pyp: StartPythonDebug.pyp #(3)!
    display-name:
      en: Start Python Debug  #(4)!
      de: Python Debug starten
    icons:
      small: StartPythonDebug_24.png  #(5)!
      large: StartPythonDebug_128.png #(6)!
  - id: install-python-debug
    # ...
  - id: encrypt-python        #(7)!
    # ...
  1. ALLPLAN Extension Package can consist of multiple PythonParts, which we refer to as tools
  2. The ID of a tool used to arrange it on the Actionbar. It is only used inside the configuration file under the key task-area. You won't see it anywhere in ALLPLAN.
  3. The name of the tool's PYP file.
  4. Localized display name of the tool. The key is the two-letter language identifier, followed by the name in this language. Check here for all supported languages.
  5. The filename of the tool's small (24px×24px) icon in PNG format.
  6. The filename of the tool's large (128px×128px) icon in PNG format.
  7. Add a new list item (starting with a -) to add a tool to your package.

Providing these information will make Allep installer to generate a .npd file(1), ensuring the tools appear in the Actionbar configuration:

  1. The file will be created in the following location:
    <TargetLocation>\PythonPartsActionbar\AllepPlugins\<DeveloperName>\<PluginName>\<PluginName>.npd

    Note that any blank spaces in Developer name and Plugin Name will be removed.

Actionbar Configuration

Info

The key tools is optional. If you want your tools to be available only in the ALLPLAN Library, skip it entirely. Also skip the task-area key.

Limitation

Currently, when installing into USR location, no entries in the Actionbar Configuration are created and thus the integration into Actionbar does not work. This will be fixed soon.

Task area

After defining the tools key, your PythonParts are visible in the Actionbar configuration, but not directly in the Actionbar. The user can drag-and-drop them onto the Actionbar manually. If you want to do it for him, define the task-area section in the configuration file.

The installer can create one task area for each plugin inside the Plug-ins tab in ALLPLAN. The layout of this task area is defined as follows:

task-area:
  display-name:
    en: PythonPart SDK      #(1)!
    de: PythonPart SDK
  layout:                   #(2)!
    - start-python-debug    #(3)!
    - "****"                #(4)!
    - create-vscode-workspace
    - ----
    - install-python-package
    - ----                  #(5)!
    - encrypt-pythonpart-script
  1. Localized display name of the task area. The key is the two-letter language identifier, followed by the name in this language. Please check here for all supported languages.
  2. This section defines the tools layout inside the task area.
  3. Each list item (starting with a -) represents a tool on the Actionbar. Use id from the tools section to refer to the desired tool.
  4. This will create a hard separator - a vertical line on the Actionbar.
  5. This will create a soft separator (an invisible vertical line) on the Actionbar. All tools between two soft separators will be put into one flyout.

This makes sure, the tools are visible on the Plug-ins tab on the Actionbar:

Actionbar layout
Task Area with Separator and Flyout on Plug-ins tab

Info

The key task-area is optional. If you don't provide it, your tools will be available in the Allplan Library and in the Actionbar Configuration, but not on the Actionbar.

Assets

You should organize the assets of your plugin in three folders inside an Allep file:

Allep folder Content
Library The PYP file, string resources, library thumbnail image
PythonPartsScripts Files with the python source code
PythonPartsActionbar Icons for the Actionbar

These assets will be copied to the corresponding ALLPLAN folder (STD or USR, depending on the target-location, defined under the key installation), as shown in the overview below.

Allep folder Will be installed in STD or USR\...
Library ...Library\AllepPlugins\<DeveloperName>\<PluginName>\
PythonPartsScripts ...PythonPartsScripts\AllepPlugins\<DeveloperName>\<PluginName>\
PythonPartsActionbar ...PythonPartsActionbar\AllepPlugins\<DeveloperName>\<PluginName>\

Info

The installer installs PY files from PythonPartsScripts directory from the Allep file in the following ALLPLAN directory:
<TargetDirectory>\PythonPartsScripts\AllepPlugins\<DeveloperName>\<PluginName>\.

The path to the PY file defined in your original PYP file will probably not include the AllepPlugins\<DeveloperName>\<PluginName>\ part. To preserve a valid reference, the installer will modify the value in the <Name> tag in the script node in each PYP file accordingly.

For example:
<Name>Foo.py</Name>
will be changed to
<Name>AllepPlugins\DeveloperName\PluginName\Foo.py</Name>

Requirements File

When your plugin uses site packages from the Python Package Index , you have to prepare a requirements file to ensure all the required dependencies are installed together with your plugin on the end user's PC.

Allep installer uses the well known PIP management system to manage dependency packages inside ALLPLAN python environment. You only have to prepare a list with all the packages required by your plugin according to this documentation on the PIP project website. The dependency packages will be installed in (1)\PythonParts-site-packages.

  1. Here comes the directory defined in the installation section of the configuration file (STD or USR).

Example

For example, if your plugin requires numpy and pandas in version no older than 2.0.0, the requirements file can look like this

requirements.in
numpy
pandas >= 2.0.0

Warning

There is only one python environment inside ALLPLAN. All the dependency packages, also for other plugins, will be installed there. To avoid conflicts, define the requirements as loose as possible. E.g. avoid requiring a specific version of a site package, like:
pandas == 2.2.2

Delivery

Here is what the user must do to proceed with your plugin.

Installing

The user can install the plugin either per drag-and-drop or using the Allep Installer.

Simply drag-and-drop the .allep file into ALLPLAN. When everything goes well, the pop-up will inform you about the successful installation.

  1. Go to ALLPLAN library and navigate to
    Default -> AllepPlugins -> AllplanGmbH -> AllepManagement

    Location of AllepInstaller

  2. Start the AllepInstaller PythonPart.

  3. Choose the .allep file to install and press install
  4. A pop-up will inform about a successful installation.

Updating

To updating a plugin is the same as installation. You simply have to install the plugin again. The new files will replace the old one. However, no file will be removed.

Bug

Currently, update doesn't work properly, when the layout of the icons has changed. For this case, we recommend you to prepare a plugin with new UUID and advise your users to uninstall the old plugin before installing the new one.

Uninstalling

You can remove the plugin by removing following files and folders manually1 and restarting ALLPLAN:

  • folder STD_or_USR\PythonPartsActionbar\AllepPlugins\<DeveloperName>\<PluginName>
  • folder STD_or_USR\Library\AllepPlugins\<DeveloperName>\<PluginName>
  • folder STD_or_USR\PythonPartsScripts\AllepPlugins\<DeveloperName>\<PluginName>

  1. The uninstaller is not available yet, but it will be in the near future. ↩↩

Placeholder