Package Building¶
If you want to create an OPM package (.opm
) you need to create a spec file (.sopm
) which includes the properties of the package.
Package Spec File¶
The OPM package is XML based. You can create/edit the .sopm
via a text or XML editor. It contains meta data, a file list and database options.
<Name>
*The package name.
<Name>Calendar</Name>
<Version>
*The package version.
<Version>1.2.3</Version>
<Framework>
*The targeted framework version (7.0.x means e.g. 7.0.1 or 7.0.2).
<Framework>7.0.x</Framework>
Can also be used several times.
<Framework>5.0.x</Framework> <Framework>6.0.x</Framework> <Framework>7.0.x</Framework>
<Vendor>
*The package vendor.
<Vendor>Rother OSS GmbH</Vendor>
<URL>
*The vendor URL.
<URL>https://otobo.com/</URL>
<License>
*The license of the package.
<License>GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007</License>
<ChangeLog>
The package change log.
<ChangeLog Version="1.1.2" Date="2018-11-15 18:45:21">Added some feature.</ChangeLog> <ChangeLog Version="1.1.1" Date="2018-11-15 16:17:51">New package.</ChangeLog>
<Description>
*The package description in different languages.
<Description Lang="en">A web calendar.</Description> <Description Lang="de">Ein Web Kalender.</Description>
- Package Actions
The possible actions for the package after installation. If one of these actions is not defined on the package, it will be considered as possible.
<PackageIsVisible>1</PackageIsVisible> <PackageIsDownloadable>0</PackageIsDownloadable> <PackageIsRemovable>1</PackageIsRemovable>
A special package action is
PackageAllowDirectUpdate
. Only if it is defined on the package and set to true, a package can be upgraded from a lower major version (earlier than the last one) to the latest version. (e.g. a package for OTOBO 5 updated to OTOBO 7).<PackageAllowDirectUpdate>1</PackageAllowDirectUpdate>
<BuildHost>
This will be filled in automatically by OPM.
<BuildHost>?</BuildHost>
<BuildDate>
This will be filled in automatically by OPM.
<BuildDate>?</BuildDate>
<PackageRequired>
Packages that must be installed beforehand. If
PackageRequired
is used, a version of the required package must be specified.<PackageRequired Version="1.0.3">SomeOtherPackage</PackageRequired> <PackageRequired Version="5.3.2">SomeotherPackage2</PackageRequired>
<ModuleRequired>
Perl modules that must be installed beforehand.
<ModuleRequired Version="1.03">Encode</ModuleRequired> <ModuleRequired Version="5.32">MIME::Tools</ModuleRequired>
<OS>
Required OS.
<OS>linux</OS> <OS>darwin</OS> <OS>mswin32</OS>
<Filelist>
This is a list of files included in the package.
<Filelist> <File Permission="644" Location="Kernel/Config/Files/Calendar.pm"/> <File Permission="644" Location="Kernel/System/CalendarEvent.pm"/> <File Permission="644" Location="Kernel/Modules/AgentCalendar.pm"/> <File Permission="644" Location="Kernel/Language/de_AgentCalendar.pm"/> </Filelist>
<DatabaseInstall>
Database entries that have to be created when a package is installed.
<DatabaseInstall> <TableCreate Name="calendar_event"> <Column Name="id" Required="true" PrimaryKey="true" AutoIncrement="true" Type="BIGINT"/> <Column Name="title" Required="true" Size="250" Type="VARCHAR"/> <Column Name="content" Required="false" Size="250" Type="VARCHAR"/> <Column Name="start_time" Required="true" Type="DATE"/> <Column Name="end_time" Required="true" Type="DATE"/> <Column Name="owner_id" Required="true" Type="INTEGER"/> <Column Name="event_status" Required="true" Size="50" Type="VARCHAR"/> </TableCreate> <TableAlter Name="calendar_event"> <ColumnChange Name="event_status1" Required="true" Size="50" Type="VARCHAR"/> <ColumnAdd Name="event_status2" Required="true" Size="50" Type="VARCHAR"/> <ColumnDrop Name="event_status2" Required="true" Size="50" Type="VARCHAR"/> </TableAlter> </DatabaseInstall>
You also can choose
<DatabaseInstall Type="post">
or<DatabaseInstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<DatabaseUpgrade>
Information on which actions have to be performed in case of an upgrade.
Example if already installed package version is below 1.3.4 (e. g. 1.2.6), the defined action will be performed:
<DatabaseUpgrade> <TableCreate Name="calendar_event_involved" Version="1.3.4"> <Column Name="event_id" Required="true" Type="BIGINT"/> <Column Name="user_id" Required="true" Type="INTEGER"/> </TableCreate> </DatabaseUpgrade>
You also can choose
<DatabaseUpgrade Type="post">
or<DatabaseUpgrade Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<DatabaseReinstall>
Information on which actions have to be performed if the package is reinstalled.
<DatabaseReinstall></DatabaseReinstall>
You also can choose
<DatabaseReinstall Type="post">
or<DatabaseReinstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<DatabaseUninstall>
Actions to be performed on package uninstall.
<DatabaseUninstall> <TableDrop Name="calendar_event" /> </DatabaseUninstall>
You also can choose
<DatabaseUninstall Type="post">
or<DatabaseUninstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<IntroInstall>
To show a pre or post install introduction in installation dialog.
<IntroInstall Type="post" Lang="en" Title="Some Title"><![CDATA[ Some information formatted in HTML. ]]></IntroInstall>
You can also use the
Format
attribute to define if you want to usehtml
(which is default) orplain
to use automatically a<pre></pre>
tag when intro is shown (to keep the newlines and whitespace of the content).<IntroUninstall>
To show a pre or post uninstall introduction in uninstallation dialog.
<IntroUninstall Type="post" Lang="en" Title="Some Title"><![CDATA[ Some information formatted in HTML. ]]></IntroUninstall>
You can also use the
Format
attribute to define if you want to usehtml
(which is default) orplain
to use automatically a<pre></pre>
tag when intro is shown (to keep the newlines and whitespace of the content).<IntroReinstall>
To show a pre or post reinstall introduction in re-installation dialog.
<IntroReinstall Type="post" Lang="en" Title="Some Title"><![CDATA[ Some information formatted in HTML. ]]></IntroReinstall>
You can also use the
Format
attribute to define if you want to usehtml
(which is default) orplain
to use automatically a<pre></pre>
tag when intro is shown (to keep the newlines and whitespace of the content).<IntroUpgrade>
To show a pre or post upgrade introduction in upgrading dialog.
<IntroUpgrade Type="post" Lang="en" Title="Some Title"><![CDATA[ Some information formatted in HTML. ]]></IntroUpgrade>
You can also use the
Format
attribute to define if you want to usehtml
(which is default) orplain
to use automatically a<pre></pre>
tag when intro is shown (to keep the newlines and whitespace of the content).<CodeInstall>
Perl code to be executed when the package is installed.
<CodeInstall><![CDATA[ # log example $Kernel::OM->Get('Kernel::System::Log')->Log( Priority => 'notice', Message => "Some Message!", ); # database example $Kernel::OM->Get('Kernel::System::DB')->Do(SQL => "SOME SQL"); ]]></CodeInstall>
You also can choose <CodeInstall Type="post">
or <CodeInstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.
<CodeUninstall>
Perl code to be executed when the package is uninstalled. On pre or post time of package uninstallation.
<CodeUninstall><![CDATA[ # Some Perl code. ]]></CodeUninstall>
You also can choose
<CodeUninstall Type="post">
or<CodeUninstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<CodeReinstall>
Perl code to be executed when the package is reinstalled.
<CodeReinstall><![CDATA[ # Some Perl code. ]]></CodeReinstall>
You also can choose
<CodeReinstall Type="post">
or<CodeReinstall Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<CodeUpgrade>
Perl code to be executed when the package is upgraded (subject to
version
tag).Example if already installed package version is below 1.3.4 (e. g. 1.2.6), the defined action will be performed:
<CodeUpgrade Version="1.3.4"><![CDATA[ # Some Perl code. ]]></CodeUpgrade>
You also can choose
<CodeUpgrade Type="post">
or<CodeUpgrade Type="pre">
to define the time of execution separately (post
is default). For more info see Package Life Cycle.<PackageMerge>
This tag signals that a package has been merged into another package. In this case the original package needs to be removed from the file system and the packages database, but all data must be kept.
Let’s assume that
PackageOne
was merged intoPackageTwo
. ThenPackageTwo.sopm
should contain this:<PackageMerge Name="MergeOne" TargetVersion="2.0.0"></PackageMerge>
If
PackageOne
also contained database structures, we need to be sure that it was at the latest available version of the package to have a consistent state in the database after merging the package. The attributeTargetVersion
does just this: it signifies the last known version ofPackageOne
at the timePackageTwo
was created. This is mainly to stop the upgrade process if in the user’s system a version ofPackageOne
was found that is newer than the one specified inTargetVersion
as this could lead to problems.Additionally it is possible to add required database and code upgrade tags for
PackageOne
to make sure that it gets properly upgraded to theTargetVersion
before merging it - to avoid inconsistency problems. Here’s how this could look like:<PackageMerge Name="MergeOne" TargetVersion="2.0.0"> <DatabaseUpgrade Type="merge"> <TableCreate Name="merge_package"> <Column Name="id" Required="true" PrimaryKey="true" AutoIncrement="true" Type="INTEGER"/> <Column Name="description" Required="true" Size="200" Type="VARCHAR"/> </TableCreate> </DatabaseUpgrade> </PackageMerge>
As you can see the attribute
Type="merge"
needs to be set in this case. These sections will only be executed if a package merge is possible.
- Package Conditions
IfPackage
andIfNotPackage
attributes can be added to the regularDatabase*
andCode*
sections. If they are present, the section will only be executed if another package is or is not in the local package repository.<DatabaseInstall IfPackage="AnyPackage"> # ... </DatabaseInstall>
or
<CodeUpgrade IfNotPackage="OtherPackage"> # ... </CodeUpgrade>
These attributes can be also set in the
Database*
andCode*
sections inside thePackageMerge
tags.
Example .sopm¶
This is an example spec file looks with some of the above tags.
<?xml version="1.0" encoding="utf-8" ?>
<otobo_package version="1.0">
<Name>Calendar</Name>
<Version>10.0.1</Version>
<Framework>10.0.x</Framework>
<Vendor>Rother OSS GmbH</Vendor>
<URL>https://otobo.com/</URL>
<License>GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007</License>
<ChangeLog Version="1.1.2" Date="2018-11-15 18:45:21">Added some feature.</ChangeLog>
<ChangeLog Version="1.1.1" Date="2018-11-15 16:17:51">New package.</ChangeLog>
<Description Lang="en">A customer package.</Description>
<Description Lang="de">Ein kundenspezifisches Paket.</Description>
<IntroInstall Type="post" Lang="en" Title="Thank you!">Thank you for choosing the Calendar module.</IntroInstall>
<IntroInstall Type="post" Lang="de" Title="Vielen Dank!">Vielen Dank fuer die Auswahl des Kalender Modules.</IntroInstall>
<BuildDate>?</BuildDate>
<BuildHost>?</BuildHost>
<Filelist>
<File Permission="644" Location="Kernel/Config/Files/Calendar.pm"></File>
<File Permission="644" Location="Kernel/System/CalendarEvent.pm"></File>
<File Permission="644" Location="Kernel/Modules/AgentCalendar.pm"></File>
<File Permission="644" Location="Kernel/Language/de_AgentCalendar.pm"></File>
<File Permission="644" Location="Kernel/Output/HTML/Standard/AgentCalendar.tt"></File>
<File Permission="644" Location="Kernel/Output/HTML/NotificationCalendar.pm"></File>
<File Permission="644" Location="var/httpd/htdocs/images/Standard/calendar.png"></File>
</Filelist>
<DatabaseInstall>
<TableCreate Name="calendar_event">
<Column Name="id" Required="true" PrimaryKey="true" AutoIncrement="true" Type="BIGINT"/>
<Column Name="title" Required="true" Size="250" Type="VARCHAR"/>
<Column Name="content" Required="false" Size="250" Type="VARCHAR"/>
<Column Name="start_time" Required="true" Type="DATE"/>
<Column Name="end_time" Required="true" Type="DATE"/>
<Column Name="owner_id" Required="true" Type="INTEGER"/>
<Column Name="event_status" Required="true" Size="50" Type="VARCHAR"/>
</TableCreate>
</DatabaseInstall>
<DatabaseUninstall>
<TableDrop Name="calendar_event"/>
</DatabaseUninstall>
</otobo_package>
Package Build¶
To build an .opm package from the spec opm.
shell> bin/otobo.Console.pl Dev::Package::Build /path/to/example.sopm /tmp
Building package...
Done.
shell>
Package Life Cycle¶
The following image shows you how the life cycle of a package installation, upgrade and uninstallation works in the back end step by step.
![Package Life Cycle](../../_images/package-life-cycle.png)
Package Life Cycle