Skip to content

Packaging

Allplan Extension Package (Allep) allows you to wrap your PythonParts and all the content related to it (e.g. reports, texture definitions, etc.) in a one, shippable package that end-users can install per drag-and-drop.

  • 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 for your plugin on the Actionbar, provide personalized icons for each of the PythonParts and arrange them in fly-outs and sections.

  • Installed per drag-and-drop

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

  • Managed with plugin manager

    With the help of the plugin manager, the user can manage the plugin: update it by drag-and-dropping the newer version or uninstall it.

Allep file structure

An Allep file is a ZIP container with folders you can also find in the ALLPLAN etc/std/usr directories. What makes a ZIP an Allep package, is the install-config.yml - this is the only required file and must be located in the root. All other files and directories shown below are optional. Click on the to learn more about each asset.

📦 Example package.allep
│
├─🛠️ install-config.yml<!--(1)!-->
├─📋 requirements.in<!--(2)!-->
│
├─📂 Design
│ └─📂 Example Developer
│   └─📄 Surface definition.surf
│
├─📂 Library<!--(3)!-->
│ └─📂 Example Developer<!--(4)!-->
│   ├─🖼️ Tool1.png
│   ├─📄 Tool1.pyp
│   ├─🖼️ Tool2.png
│   ├─📄 Tool2.pyp
│   ├─📄 FolderContent_Example Developer.deu<!--(5)!-->
│   ├─📄 FolderContent_Example Developer.eng
│   ├─📄 Folder_Example Developer.deu<!--(6)!-->
│   ├─📄 Folder_Example Developer.eng
│   └─...
│
├─📂 Prod
│ └─📄 Baz.ini
│
├─📂 PythonPartsActionbar<!--(7)!-->
│ └─📂 example_developer
│   ├─🖼️ Tool1_128.png
│   ├─🖼️ Tool1_128_dark.png
│   ├─🖼️ Tool1_24.png
│   ├─🖼️ Tool1_24_dark.png
│   ├─🖼️ Tool2_128.png
│   └─...
│
├─📂 PythonPartsScripts<!--(8)!-->
│ └─📂 example_developer
│   └─📂 example_package
│     ├─📄 __init__.py
│     └─📄 example_module.py
│
├─📂 Reports<!--(9)!-->
│ ├─📂 eng
│ | └─📂 Example Developer
│ |   └─📄 Example report.rdlc
│ └─📂 deu
│   └─📂 Example Developer
│     └─📄 Beispiel report.rdlc
│
└─📂 VisualScripts<!--(10)!-->
  └─📂 Example Developer
    ├─📄 NodeYourCustomNode.py
    └─📄 NodeYourCustomNode.pypsub

  1. The installation configuration file with all the information about how your plugin should be installed. This is the only required file.

  2. Optional requirements file (the extension doesn't matter) in case your plugin relies on dependency packages. Learn more below .

  3. Assets to be installed in ALLPLAN Library.

    Learn more here about files you can deliver to Library. On top of that, you can deliver content other than PythonParts (.pyp), e.g. symbols (.sym) or smart symbols (.nmk).

  4. We highly recommend you to create one sub-folder with a name you as a developer wants to be identified with (preferably the name of your organization). Because the Library folder is user-facing, provide a user-friendly name, like My Development Company Inc..

  5. You can localize the name of the assets in Library sub-folders by providing a file named like FolderContent_Name of the directory.xyz, where xyz is the language specifier. The file content should look like this:

    Tool1 = Erstes werkzeug
Tool2 = Zweites werkzeug
Tool3 = Drittes werkzeug

  6. You can localize the name of the sub-folders in Library by providing a file named like Folder_Name of the directory.xyz, where xyz is the language specifier. The file content should look like this:

    Example developer = Beispiel Entwickler

  7. Here, you put all the icons needed to show your plugin on the Actionbar. Per PythonPart you need at least two PNGs: 24x24 px and 128x128 px. Ideally, provide a dark mode variant of each, with a suffix _dark (so actually 4 icons per PythonPart).

  8. Here come your python scripts. It's up to you how you organize them. We recommend one sub-directory under the PythonPartsScripts with a slugified, python-friendly name of your organization. This will ensure, that your content does not interfere with the content of other developers.

  9. If you deliver reports, put them under Reports in sub-directories with 3-letter language specifier as name. Also here we recommend to wrap the .rdlc files in a sub-directory with a unique, user-friendly name to avoid conflicts with the content of other developers.

  10. A VisualScripting node consist of two files: NodeNameOfYourNode.py and NodeNameOfYourNode.pypsub. Put them all here, in a sub-directory with a user-friendly name, since it will appear in the tree in Visual Editor.

Note, that only certain folders in combination with certain target location will be considered by the installation and only into certain target locations. Here is the overview of the supported folders names and target locations:

Directory name USR STD
Design
Library
prod
PythonPartsScripts
PythonPartsActionbar
Reports
VisualScripts

Warning

Make sure, that all the assets are located in the root of your zip archive! Do not create any parent directory!

Failure

📦Example package.allep
└─📂MyPlugin
  ├─🛠️ install-config.yml
  ├─📋 requirements.in
  ├─📂Library
  | └─📂Example developer
  |   ├─ 📄 MyTool.pyp
  |   └─ ...
  └─📂PythonPartsScripts
    └─📂example_developer
      ├─ 📄 example_module.py
      └─ ...

Success

📦Example package.allep
├─🛠️ install-config.yml
├─📋 requirements.in
├─📂Library
| └─📂Example developer
|   ├─ 📄 MyTool.pyp
|   └─ ...
└─📂PythonPartsScripts
└─📂example_developer
    ├─ 📄 example_module.py
    └─ ...

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. Simply generate one and don't change it the plugin's entire lifetime.
  3. Version number of the plugin. Make sure to follow the rules of semantic versioning
  4. Your developer id. Ideally, a slugified name of your organization.

  5. The two-letter identifier of the default language. It will be used for the buttons on the Actionbar, if the current ALLPLAN language is not supported by the plugin.

    Info

    If your configuration file contains the section tools, make sure to provide display names for the default language for all entries in that section.

    Refer to the documentation of the documentation of AllplanLocalisationService to see, what languages are supported.

  6. Minimum ALLPLAN version, supported by the plugin.

Installation

This section determines, where your plugin will be installed. Currently, it has only one key target-location:

installation:
  target-location: USR

Choose the target-location 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 the entire office

Info

All the assets of your plugin can be installed to only one target location. And this will stay this way.

For now, you as a developer decide, where the plugin gets installed. In the future, we may offer you the possibility to give this choice to the user.

Warning

Bare in mind that, in a workgroup, only users with administrative privileges are able to install a plugin, that installs into STD.

Tools

This section defines, how your plugin appears in the Actionbar configuration(1). From here, the user can drag-and-drop it on the Actionbar and arrange the tools himself.

  1. To achieve this, the installer creates an .npd file under:

    {target-location}\PythonPartsActionbar\AllepPlugins\{plugin-UUID}.npd

tools: #(1)!
  - id: tool-1 #(2)!
    pyp: Library\Example Developer\Tool1.pyp #(3)!
    display-name: #(4)!
      en: First tool
      de: Erstes Werkzeug
    icons:
      small: PythonPartsActionbar\example_developer\Tool1_24.png #(5)!
      large: PythonPartsActionbar\example_developer\Tool1_128.png #(6)!

  - id: tool-2 #(6)!
    ...

  - id: tool-3
    ...
  1. Each PythonPart in a plugin is a tool
  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. Path to the tool's PYP file, relative to the root of the Allep 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 path to the tool's small (24px×24px) icon in PNG format. Relative to the root of the Allep file.
  6. The path of the tool's large (128px×128px) icon in PNG format. Relative to the root of the Allep file.
  7. Add a new list item (starting with a -) to add a tool to your package.

Actionbar Configuration

Info

The section tools is optional. If you want your tools to be available only in the ALLPLAN Library, you can skip it.

Task area

Task area

Assuming, you defined the tools key, so your PythonParts are visible in the Actionbar configuration, and the user can put them on the Actionbar manually. If you want your PythonParts to appear on the Actionbar right away after the installation, without any action needed from user, follow these steps.

The installer can create one task area per plugin on the Plug-ins tab. You can arrange the PythonParts included in your plugin within this task area using the task-area key. Here's an example:

task-area:
  display-name: #(1)!
    en: Tool set
    de: Werkzeugkiste
  layout:
    - tool-1 #(2)!
    - ---- #(4)!
    - tool-2
    - tool-3
    - "****"
    - tool-4 #(3)!
    - tool-5

  1. Task area title

    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. Each list item represents a tool on the Actionbar. Use id from the tools section to refer to the desired tool.

  3. Hard separator

    This will create a hard separator - a vertical line on the Actionbar.

  4. Soft separator

    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.

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.

Requirements File

When your plugin have some python dependencies on packages from the Python Package Index , they need to be installed when together with your plugin. 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 PIP to install and manage dependency packages. Prepare a file requirements.in containing a list with all the dependency packages according to this documentation . The dependency packages will be installed in the corresponding target location (USR or STD) in PythonParts-site-packages directory.

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, with all the dependency packages. Also those for other plugins. To avoid conflicts, define the requirements as loose as possible.

If your plugin requires a specific version of a dependency package, it is better to include it directly in the Allep file.

Versioning

Both plugin and its PythonParts should be versioned. These versions are independent, but incrementing a PythonPart version should increment the version of the plugin, of which it is part of. Here's an example timeline of a plugin consisting of 3 PythonParts. Note, that the version of the plugin increases as soon as one of the PythonParts becomes a newer version.

timeline
    Plugin v1.0.0   : First PythonPart 1.0
                    : Second PythonPart 1.0
                    : Third PythonPart 1.0
    Plugin v1.1.0   : First PythonPart 1.1
                    : Second PythonPart 1.0
                    : Third PythonPart 1.0
    Plugin v1.2.0   : First PythonPart 1.1
                    : Second PythonPart 1.0
                    : Third PythonPart 1.1
    Plugin v2.0.0   : First PythonPart 1.1
                    : Second PythonPart 2.0
                    : Third PythonPart 1.1

If you want to provide a newer version of your plugin to your end-users, just increment the version number in the plugin section and create a new Allep package. When the user tries to install the package, it will be informed, that he is updating. Also, in case he will try to downgrade, he will be informed about possible unexpected results.

Info

A plugin must be versioned according to the rules of semantic versioning, whereas individual PythonParts should be versioned with a float-like version numbers. (e.g. 1.2).

Bug

When you change the layout of the icons in the task area section and increment the version, the user won't see the changes after the update as long as he does not reset the Actionbar configuration. We're working on it.

Protect your source code

You can encrypt your python source code to protect your copyrights. The encrypted files are unreadable for users, only for the ALLPLAN python interpreter.

The encrypted files are given the extension .pye and work as a regular python module. The interpreter looks for .py file first. If not available, it looks for .pye. So, the Allep package should contain the encrypted files.

The encryption of the source code can be executed by the PythonPart EncryptPythonPartScript, located in \etc\Examples\PythonParts\ToolsAndStartExamples.

Encrypt PythonPart script

You can encrypt a single file or an entire directory. In the second case, the files from the sub directories are also encrypted. You have to specify a target directory, where the encrypted files should be saved.

Testing the PythonPart using the encrypted file(s) can be done as follows:

  • create a directory xxx_Encrypt with xxx is the location of the .py file(s)
  • create the .pye file(s) with the PythonPart EncryptPythonPartScript
  • temporary modify the <Name> tag in the .pyp file by using xxx_Encrypt
  • execute the PythonPart
Placeholder